/**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

#pragma once
#include "dusk.h"

/**
 * Determines if a character is whitespace.
 * 
 * @param c The character to check.
 * @return TRUE if the character is whitespace, FALSE otherwise.
 */
bool_t stringIsWhitespace(const char_t c);

/**
 * Copies a string from src to dest, ensuring the dest string is null-terminated
 * and does not exceed the specified size.
 * 
 * @param dest The destination string.
 * @param src The source string.
 * @param destSize The size of the destination string exc. null terminator.
 */ 
void stringCopy(char_t *dest, const char_t *src, const size_t destSize);

/**
 * Compares two strings.
 * 
 * @param str1 The first string.
 * @param str2 The second string.
 * @return 0 if the strings are equal, -1 if str1 is less than str2, 1 if str1
 * is greater than str2.
 */
int stringCompare(const char_t *str1, const char_t *str2);

/**
 * Compares two strings, ignoring case.
 * 
 * @param str1 The first string.
 * @param str2 The second string.
 * @return 0 if the strings are equal, -1 if str1 is less than str2, 1 if str1
 * is greater than str2.
 */
int stringCompareInsensitive(const char_t *str1, const char_t *str2);

/**
 * Trims whitespace from the beginning and end of a string.
 * 
 * @param str The string to trim.
 */
void stringTrim(char_t *str);

/**
 * Gets the next token in a string using a delimiter.
 * e.g. input: "Hello, World, Happy Monday!" with stringToken(input, ",") will
 * return "Hello" then " World" then " Happy Monday!" on each subsequent call.
 * 
 * @param str The string to split.
 * @param delim The delimiter to split by.
 * @return A pointer to the next token in the string.
 */
char_t * stringToken(char_t *str, const char_t *delim);

/**
 * Formats a string.
 * 
 * @param dest The destination string, or NULL to get the length of the
 * formatted string.
 * @param destSize The size of the destination string exc. null terminator, can
 * be anything if dest is NULL.
 * @param format The format string.
 * @param ... The arguments to format.
 * @return The number of characters written.
 */
int32_t stringFormat(
  char_t *dest,
  const size_t destSize,
  const char_t *format,
  ...
);

/**
 * Formats a string using a va_list.
 * 
 * @param dest The destination string, or NULL to get the length of the
 * formatted string.
 * @param destSize The size of the destination string exc. null terminator, can
 * be anything if dest is NULL.
 * @param format The format string.
 * @param args The va_list of arguments.
 * @return The number of characters written.
 */
int32_t stringFormatVA(
  char_t *dest,
  const size_t destSize,
  const char_t *format,
  va_list args
);

/**
 * Converts a string to an integer.
 * 
 * @param str The string to convert.
 * @param out The output integer.
 * @return TRUE if the conversion was successful, FALSE otherwise.
 */
bool_t stringToI32(const char_t *str, int32_t *out);

/**
 * Converts a string to a signed 16-bit integer.
 * 
 * @param str The string to convert.
 * @param out The output signed integer.
 * @return TRUE if the conversion was successful, FALSE otherwise.
 */
bool_t stringToI16(const char_t *str, int16_t *out);

/**
 * Converts a string to an unsigned 16-bit integer.
 * 
 * @param str The string to convert.
 * @param out The output unsigned integer.
 * @return TRUE if the conversion was successful, FALSE otherwise.
 */
bool_t stringToU16(const char_t *str, uint16_t *out);

/**
 * Converts a string to a float.
 * 
 * @param str The string to convert.
 * @param out The output float.
 * @return TRUE if the conversion was successful, FALSE otherwise.
 */
bool_t stringToF32(const char_t *str, float_t *out);

/**
 * Determines if a string ends with a specified suffix.
 * 
 * @param str The string to check.
 * @param suffix The suffix to check for.
 * @return TRUE if the string ends with the suffix, FALSE otherwise.
 */
bool_t stringEndsWith(const char_t *str, const char_t *suffix);

/**
 * Determines if a string ends with a specified suffix, ignoring case.
 * 
 * @param str The string to check.
 * @param suffix The suffix to check for.
 * @return TRUE if the string ends with the suffix, FALSE otherwise.
 */
bool_t stringEndsWithCaseInsensitive(const char_t *str, const char_t *suffix);