drop math library

string/mystring.h

@@ -5,69 +5,68 @@
 #include <stddef.h>
 
 /**
- * @brief Thread-safe dynamic string structure
+ * @brief Thread-safe dynamic string structure.
  */
 typedef struct mcl_string_t {
 	size_t size;		  /**< Current length of the string (excluding null terminator) */
-	size_t capacity;	  /**< Allocated capacity */
-	char *data;			  /**< Pointer to string data */
+	size_t capacity;	  /**< Allocated capacity including null terminator */
+	char *data;			  /**< Pointer to string data (null-terminated) */
 	pthread_mutex_t lock; /**< Mutex for thread safety */
 } mcl_string;
 
 /**
- * @brief Create a new string initialized with given text
+ * @brief Create a new string initialized with the given text.
  *
- * @param text Initial text (cannot be NULL)
- * @param initial_capacity Initial buffer capacity; pass -1 to auto-calculate
- * @return Pointer to new string, or NULL on failure
+ * @param text Initial text (must not be NULL)
+ * @param initial_capacity Initial buffer capacity (0 to auto-calculate)
+ * @return Pointer to new string on success, or NULL on failure.
  *
- * @note Caller must free the string with mcl_string_free()
+ * @note Caller must release the string using mcl_string_free().
  */
-mcl_string *mcl_string_new(const char *text, long initial_capacity);
+mcl_string *mcl_string_new(const char *text, size_t initial_capacity);
 
 /**
- * @brief Append text to an existing string
+ * @brief Append text to the string.
  *
- * @param string The string to append to
- * @param text Text to append (can be empty)
+ * @param string String to modify
+ * @param text Text to append (must not be NULL, can be empty)
  * @return 0 on success, -1 on failure
  *
- * @note Original string remains unchanged if append fails
+ * @note On failure, the original string remains unchanged.
  */
 int mcl_string_append(mcl_string *string, const char *text);
 
 /**
- * @brief Free a string and its resources
+ * @brief Free the string and its resources.
  *
- * @param string String to free (NULL is safe)
+ * @param string String to free (safe to call with NULL)
  */
 void mcl_string_free(mcl_string *string);
 
 /**
- * @brief Get the current length of the string
+ * @brief Get the current length of the string.
  *
  * @param string String to query
- * @return Length of string, or 0 if NULL
+ * @return Length of the string (excluding null terminator), or 0 if NULL
  */
 size_t mcl_string_length(mcl_string *string);
 
 /**
- * @brief Get the current capacity of the string buffer
+ * @brief Get the total allocated capacity of the string buffer.
  *
  * @param string String to query
- * @return Capacity, or 0 if NULL
+ * @return Capacity (in bytes, including null terminator), or 0 if NULL
  */
 size_t mcl_string_capacity(mcl_string *string);
 
 /**
- * @brief Get a read-only C-string pointer
+ * @brief Get a copy of the string as a null-terminated C-string.
  *
- * @param string String to access
- * @return Null-terminated string pointer, or "" if NULL
+ * @param string String to copy
+ * @return Newly allocated copy of the string, or NULL on failure
  *
- * @warning Do not modify returned pointer.
- *          Pointer may become invalid after string modifications.
+ * @warning Caller is responsible for freeing the returned pointer.
  */
-const char *mcl_string_cstr(mcl_string *string);
+char *mcl_string_cstr(mcl_string *string);
 
 #endif /* MYCLIB_STRING_H */