#ifndef __ETK_STRING_H__
#define __ETK_STRING_H__
#include <string.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C"
{
#endif

/**
 * @brief Safe string copy function that improves upon standard strncpy
 * 
 * @param dest Destination buffer where the content is to be copied
 * @param src Source string to be copied
 * @param dest_size Size of the destination buffer (including null terminator)
 * @return char* Pointer to the destination buffer
 * 
 * Improvements over standard strncpy:
 * 1. Guarantees destination string is always null-terminated
 * 2. When source string length exceeds dest_size-1, only copies dest_size-1 characters
 * 3. Handles NULL pointer inputs to prevent crashes
 * 4. When dest_size is 0, performs no operation
 */
char *etk_strncpy(char *dest, const char *src, size_t dest_size);

/**
 * @brief Safe string copy function that replaces dangerous strcpy
 * 
 * @param dest Destination buffer where the content is to be copied
 * @param src Source string to be copied
 * @param dest_size Size of the destination buffer (including null terminator)
 * @return char* Pointer to the destination buffer
 * 
 * Improvements over standard strcpy:
 * 1. Checks destination buffer size to prevent overflow
 * 2. Handles NULL pointer inputs gracefully
 * 3. Guarantees null-termination
 * 4. Returns NULL if destination is too small or inputs are invalid
 */
char *etk_strcpy(char *dest, const char *src, size_t dest_size);

/**
 * @brief Safe string concatenation function that replaces dangerous strcat
 * 
 * @param dest Destination buffer to append to
 * @param src Source string to append
 * @param dest_size Total size of destination buffer (including null terminator)
 * @return char* Pointer to the destination buffer
 * 
 * Improvements over standard strcat:
 * 1. Checks remaining space in destination buffer
 * 2. Handles NULL pointer inputs safely
 * 3. Guarantees null-termination
 * 4. Returns NULL if insufficient space or invalid inputs
 */
char *etk_strcat(char *dest, const char *src, size_t dest_size);

/**
 * @brief Safe string length function with maximum length limit
 * 
 * @param str String to measure
 * @param max_len Maximum length to check (prevents infinite loops on non-null-terminated strings)
 * @return size_t Length of string, or max_len if string is longer or not null-terminated
 * 
 * Improvements over standard strlen:
 * 1. Prevents infinite loops on malformed strings
 * 2. Handles NULL pointer input safely
 * 3. Provides bounded operation for security
 */
size_t etk_strlen(const char *str, size_t max_len);

/**
 * @brief Improved string concatenation function with better buffer management
 * 
 * @param dest Destination buffer to append to
 * @param src Source string to append
 * @param dest_size Total size of destination buffer (including null terminator)
 * @param n Maximum number of characters to append from source
 * @return char* Pointer to the destination buffer, or NULL if error
 * 
 * Improvements over standard strncat:
 * 1. More intuitive buffer size parameter (total size vs remaining space)
 * 2. Better error handling and NULL pointer checks
 * 3. Guarantees null-termination even when n is 0
 * 4. Returns NULL on insufficient space or invalid inputs
 */
char *etk_strncat(char *dest, const char *src, size_t dest_size, size_t n);

/**
 * @brief Optimized string search function with better performance
 * 
 * @param haystack String to search in
 * @param needle String to search for
 * @param max_len Maximum length to search in haystack (for safety)
 * @return char* Pointer to first occurrence of needle in haystack, or NULL if not found
 * 
 * Improvements over standard strstr:
 * 1. Added max_len parameter for safety with non-null-terminated strings
 * 2. Better performance for long strings (can be optimized with better algorithms)
 * 3. Handles NULL pointer inputs safely
 * 4. More predictable behavior with edge cases
 */
char *etk_strstr(const char *haystack, const char *needle, size_t max_len);

/**
 * @brief Safe string to integer conversion with error handling
 * 
 * @param str String to convert
 * @param result Pointer to store the converted integer value
 * @return int 1 on success, 0 on failure
 * 
 * Improvements over standard atoi:
 * 1. Proper error handling (returns success/failure status)
 * 2. Handles NULL pointer input safely
 * 3. Better validation of input string format
 * 4. Prevents integer overflow
 */
int etk_atoi(const char *str, int *result);

/**
 * @brief Safe string to long integer conversion with error handling
 * 
 * @param str String to convert
 * @param result Pointer to store the converted long value
 * @return int 1 on success, 0 on failure
 * 
 * Improvements over standard atol:
 * 1. Proper error handling (returns success/failure status)
 * 2. Handles NULL pointer input safely
 * 3. Better validation of input string format
 * 4. Prevents integer overflow
 */
int etk_atol(const char *str, long *result);

/**
 * @brief Safe string to double conversion with error handling
 * 
 * @param str String to convert
 * @param result Pointer to store the converted double value
 * @return int 1 on success, 0 on failure
 * 
 * Improvements over standard atof:
 * 1. Proper error handling (returns success/failure status)
 * 2. Handles NULL pointer input safely
 * 3. Better validation of input string format
 * 4. More precise error detection
 */
int etk_atof(const char *str, double *result);

/**
 * @brief String comparison with length limit and safety checks
 * 
 * @param str1 First string to compare
 * @param str2 Second string to compare
 * @param max_len Maximum length to compare (for safety)
 * @return int 0 if equal, negative if str1 < str2, positive if str1 > str2
 * 
 * Improvements over standard strcmp:
 * 1. Added max_len parameter for safety with non-null-terminated strings
 * 2. Handles NULL pointer inputs safely
 * 3. Bounded operation prevents infinite loops
 * 4. More predictable behavior with malformed strings
 */
int etk_strcmp_len(const char *str1, const char *str2, size_t max_len);

/**
 * @brief Safe memory copy function with better error handling
 * 
 * @param dest Destination buffer
 * @param src Source buffer
 * @param n Number of bytes to copy
 * @return void* Pointer to destination buffer, or NULL if error
 * 
 * Improvements over standard memcpy:
 * 1. Handles NULL pointer inputs safely
 * 2. Better error detection and reporting
 * 3. More robust behavior with edge cases
 * 4. Returns NULL on invalid inputs
 */
void *etk_memcpy(void *dest, const void *src, size_t n);

/**
 * @brief Safe memory set function with better error handling
 * 
 * @param dest Destination buffer
 * @param c Value to set (converted to unsigned char)
 * @param n Number of bytes to set
 * @return void* Pointer to destination buffer, or NULL if error
 * 
 * Improvements over standard memset:
 * 1. Handles NULL pointer input safely
 * 2. Better error detection and reporting
 * 3. More robust behavior with edge cases
 * 4. Returns NULL on invalid inputs
 */
void *etk_memset(void *dest, int c, size_t n);

/**
 * @brief Safe memory comparison function with better error handling
 * 
 * @param ptr1 First memory block
 * @param ptr2 Second memory block
 * @param n Number of bytes to compare
 * @return int 0 if equal, negative if ptr1 < ptr2, positive if ptr1 > ptr2
 * 
 * Improvements over standard memcmp:
 * 1. Handles NULL pointer inputs safely
 * 2. Better error detection and reporting
 * 3. More robust behavior with edge cases
 * 4. Returns 0 on invalid inputs (consistent behavior)
 */
int etk_memcmp(const void *ptr1, const void *ptr2, size_t n);

#ifdef __cplusplus
}
#endif

#endif
