--- a/src/cx/string.h Sun Jan 05 13:19:56 2025 +0100
+++ b/src/cx/string.h Sun Jan 05 13:44:02 2025 +0100
@@ -26,11 +26,11 @@
* POSSIBILITY OF SUCH DAMAGE.
*/
/**
- * \file string.h
- * \brief Strings that know their length.
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @file string.h
+ * @brief Strings that know their length.
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
*/
#ifndef UCX_STRING_H
@@ -50,7 +50,7 @@
struct cx_mutstr_s {
/**
* A pointer to the string.
- * \note The string is not necessarily \c NULL terminated.
+ * @note The string is not necessarily @c NULL terminated.
* Always use the length.
*/
char *ptr;
@@ -69,7 +69,7 @@
struct cx_string_s {
/**
* A pointer to the immutable string.
- * \note The string is not necessarily \c NULL terminated.
+ * @note The string is not necessarily @c NULL terminated.
* Always use the length.
*/
const char *ptr;
@@ -148,7 +148,7 @@
/**
* A literal initializer for an UCX string structure.
*
- * The argument MUST be a string (const char*) \em literal.
+ * The argument MUST be a string (const char*) @em literal.
*
* @param literal the string literal
*/
@@ -160,9 +160,9 @@
/**
* Wraps a mutable string that must be zero-terminated.
*
- * The length is implicitly inferred by using a call to \c strlen().
+ * The length is implicitly inferred by using a call to @c strlen().
*
- * \note the wrapped string will share the specified pointer to the string.
+ * @note the wrapped string will share the specified pointer to the string.
* If you do want a copy, use cx_strdup() on the return value of this function.
*
* If you need to wrap a constant string, use cx_str().
@@ -180,14 +180,14 @@
/**
* Wraps a string that does not need to be zero-terminated.
*
- * The argument may be \c NULL if the length is zero.
+ * The argument may be @c NULL if the length is zero.
*
- * \note the wrapped string will share the specified pointer to the string.
+ * @note the wrapped string will share the specified pointer to the string.
* If you do want a copy, use cx_strdup() on the return value of this function.
*
* If you need to wrap a constant string, use cx_strn().
*
- * @param cstring the string to wrap (or \c NULL, only if the length is zero)
+ * @param cstring the string to wrap (or @c NULL, only if the length is zero)
* @param length the length of the string
* @return the wrapped string
*
@@ -203,9 +203,9 @@
/**
* Wraps a string that must be zero-terminated.
*
- * The length is implicitly inferred by using a call to \c strlen().
+ * The length is implicitly inferred by using a call to @c strlen().
*
- * \note the wrapped string will share the specified pointer to the string.
+ * @note the wrapped string will share the specified pointer to the string.
* If you do want a copy, use cx_strdup() on the return value of this function.
*
* If you need to wrap a non-constant string, use cx_mutstr().
@@ -224,14 +224,14 @@
/**
* Wraps a string that does not need to be zero-terminated.
*
- * The argument may be \c NULL if the length is zero.
+ * The argument may be @c NULL if the length is zero.
*
- * \note the wrapped string will share the specified pointer to the string.
+ * @note the wrapped string will share the specified pointer to the string.
* If you do want a copy, use cx_strdup() on the return value of this function.
*
* If you need to wrap a non-constant string, use cx_mutstrn().
*
- * @param cstring the string to wrap (or \c NULL, only if the length is zero)
+ * @param cstring the string to wrap (or @c NULL, only if the length is zero)
* @param length the length of the string
* @return the wrapped string
*
@@ -282,12 +282,12 @@
*
* Does nothing for already immutable strings.
*
-* \note This is not seriously a cast. Instead, you get a copy
+* @note This is not seriously a cast. Instead, you get a copy
* of the struct with the desired pointer type. Both structs still
* point to the same location, though!
*
-* @param str the mutable string to cast
-* @return an immutable copy of the string pointer
+* @param str (@c cxstring or @c cxmutstr) the string to cast
+* @return (@c cxstring) an immutable copy of the string pointer
*/
#define cx_strcast(str) _Generic((str), \
cxmutstr: cx_strcast_m, \
@@ -296,11 +296,11 @@
#endif
/**
- * Passes the pointer in this string to \c free().
+ * Passes the pointer in this string to @c free().
*
- * The pointer in the struct is set to \c NULL and the length is set to zero.
+ * The pointer in the struct is set to @c NULL and the length is set to zero.
*
- * \note There is no implementation for cxstring, because it is unlikely that
+ * @note There is no implementation for cxstring, because it is unlikely that
* you ever have a <code>const char*</code> you are really supposed to free.
* If you encounter such situation, you should double-check your code.
*
@@ -311,9 +311,9 @@
/**
* Passes the pointer in this string to the allocators free function.
*
- * The pointer in the struct is set to \c NULL and the length is set to zero.
+ * The pointer in the struct is set to @c NULL and the length is set to zero.
*
- * \note There is no implementation for cxstring, because it is unlikely that
+ * @note There is no implementation for cxstring, because it is unlikely that
* you ever have a <code>const char*</code> you are really supposed to free.
* If you encounter such situation, you should double-check your code.
*
@@ -331,7 +331,7 @@
*
* If this sum overflows, errno is set to EOVERFLOW.
*
- * \attention if the count argument is larger than the number of the
+ * @attention if the count argument is larger than the number of the
* specified strings, the behavior is undefined.
*
* @param count the total number of specified strings
@@ -348,22 +348,22 @@
* Concatenates strings.
*
* The resulting string will be allocated by the specified allocator.
- * So developers \em must pass the return value to cx_strfree_a() eventually.
+ * So developers @em must pass the return value to cx_strfree_a() eventually.
*
- * If \p str already contains a string, the memory will be reallocated and
+ * If @p str already contains a string, the memory will be reallocated and
* the other strings are appended. Otherwise, new memory is allocated.
*
* If memory allocation fails, the pointer in the returned string will
- * be \c NULL. Depending on the allocator, \c errno might be set.
+ * be @c NULL. Depending on the allocator, @c errno might be set.
*
- * \note It is guaranteed that there is only one allocation for the
+ * @note It is guaranteed that there is only one allocation for the
* resulting string.
* It is also guaranteed that the returned string is zero-terminated.
*
* @param alloc the allocator to use
* @param str the string the other strings shall be concatenated to
* @param count the number of the other following strings to concatenate
- * @param ... all other strings
+ * @param ... all other UCX strings
* @return the concatenated string
*/
cx_attr_nodiscard
@@ -379,19 +379,19 @@
* Concatenates strings and returns a new string.
*
* The resulting string will be allocated by the specified allocator.
- * So developers \em must pass the return value to cx_strfree_a() eventually.
+ * So developers @em must pass the return value to cx_strfree_a() eventually.
*
* If memory allocation fails, the pointer in the returned string will
- * be \c NULL. Depending on the allocator, \c errno might be set.
+ * be @c NULL. Depending on the allocator, @c errno might be set.
*
- * \note It is guaranteed that there is only one allocation for the
+ * @note It is guaranteed that there is only one allocation for the
* resulting string.
* It is also guaranteed that the returned string is zero-terminated.
*
- * @param alloc the allocator to use
- * @param count the number of the other following strings to concatenate
- * @param ... all other strings
- * @return the concatenated string
+ * @param alloc (@c CxAllocator*) the allocator to use
+ * @param count (@c size_t) the number of the other following strings to concatenate
+ * @param ... all other UCX strings
+ * @return (@c cxmutstr) the concatenated string
*/
#define cx_strcat_a(alloc, count, ...) \
cx_strcat_ma(alloc, cx_mutstrn(NULL, 0), count, __VA_ARGS__)
@@ -399,19 +399,19 @@
/**
* Concatenates strings and returns a new string.
*
- * The resulting string will be allocated by standard \c malloc().
- * So developers \em must pass the return value to cx_strfree() eventually.
+ * The resulting string will be allocated by standard @c malloc().
+ * So developers @em must pass the return value to cx_strfree() eventually.
*
* If memory allocation fails, the pointer in the returned string will
- * be \c NULL and \c errno might be set.
+ * be @c NULL and @c errno might be set.
*
- * \note It is guaranteed that there is only one allocation for the
+ * @note It is guaranteed that there is only one allocation for the
* resulting string.
* It is also guaranteed that the returned string is zero-terminated.
*
- * @param count the number of the other following strings to concatenate
- * @param ... all other strings
- * @return the concatenated string
+ * @param count (@c size_t) the number of the other following strings to concatenate
+ * @param ... all other UCX strings
+ * @return (@c cxmutstr) the concatenated string
*/
#define cx_strcat(count, ...) \
cx_strcat_ma(cxDefaultAllocator, cx_mutstrn(NULL, 0), count, __VA_ARGS__)
@@ -419,23 +419,23 @@
/**
* Concatenates strings.
*
- * The resulting string will be allocated by standard \c malloc().
- * So developers \em must pass the return value to cx_strfree() eventually.
+ * The resulting string will be allocated by standard @c malloc().
+ * So developers @em must pass the return value to cx_strfree() eventually.
*
- * If \p str already contains a string, the memory will be reallocated and
+ * If @p str already contains a string, the memory will be reallocated and
* the other strings are appended. Otherwise, new memory is allocated.
*
* If memory allocation fails, the pointer in the returned string will
- * be \c NULL and \c errno might be set.
+ * be @c NULL and @c errno might be set.
*
- * \note It is guaranteed that there is only one allocation for the
+ * @note It is guaranteed that there is only one allocation for the
* resulting string.
* It is also guaranteed that the returned string is zero-terminated.
*
- * @param str the string the other strings shall be concatenated to
- * @param count the number of the other following strings to concatenate
- * @param ... all other strings
- * @return the concatenated string
+ * @param str (@c cxmutstr) the string the other strings shall be concatenated to
+ * @param count (@c size_t) the number of the other following strings to concatenate
+ * @param ... all other strings
+ * @return (@c cxmutstr) the concatenated string
*/
#define cx_strcat_m(str, count, ...) \
cx_strcat_ma(cxDefaultAllocator, str, count, __VA_ARGS__)
@@ -443,13 +443,13 @@
/**
* Returns a substring starting at the specified location.
*
- * \attention the new string references the same memory area as the
- * input string and is usually \em not zero-terminated.
+ * @attention the new string references the same memory area as the
+ * input string and is usually @em not zero-terminated.
* Use cx_strdup() to get a copy.
*
* @param string input string
* @param start start location of the substring
- * @return a substring of \p string starting at \p start
+ * @return a substring of @p string starting at @p start
*
* @see cx_strsubsl()
* @see cx_strsubs_m()
@@ -464,17 +464,17 @@
/**
* Returns a substring starting at the specified location.
*
- * The returned string will be limited to \p length bytes or the number
- * of bytes available in \p string, whichever is smaller.
+ * The returned string will be limited to @p length bytes or the number
+ * of bytes available in @p string, whichever is smaller.
*
- * \attention the new string references the same memory area as the
- * input string and is usually \em not zero-terminated.
+ * @attention the new string references the same memory area as the
+ * input string and is usually @em not zero-terminated.
* Use cx_strdup() to get a copy.
*
* @param string input string
* @param start start location of the substring
* @param length the maximum length of the returned string
- * @return a substring of \p string starting at \p start
+ * @return a substring of @p string starting at @p start
*
* @see cx_strsubs()
* @see cx_strsubs_m()
@@ -490,13 +490,13 @@
/**
* Returns a substring starting at the specified location.
*
- * \attention the new string references the same memory area as the
- * input string and is usually \em not zero-terminated.
+ * @attention the new string references the same memory area as the
+ * input string and is usually @em not zero-terminated.
* Use cx_strdup() to get a copy.
*
* @param string input string
* @param start start location of the substring
- * @return a substring of \p string starting at \p start
+ * @return a substring of @p string starting at @p start
*
* @see cx_strsubsl_m()
* @see cx_strsubs()
@@ -511,17 +511,17 @@
/**
* Returns a substring starting at the specified location.
*
- * The returned string will be limited to \p length bytes or the number
- * of bytes available in \p string, whichever is smaller.
+ * The returned string will be limited to @p length bytes or the number
+ * of bytes available in @p string, whichever is smaller.
*
- * \attention the new string references the same memory area as the
- * input string and is usually \em not zero-terminated.
+ * @attention the new string references the same memory area as the
+ * input string and is usually @em not zero-terminated.
* Use cx_strdup() to get a copy.
*
* @param string input string
* @param start start location of the substring
* @param length the maximum length of the returned string
- * @return a substring of \p string starting at \p start
+ * @return a substring of @p string starting at @p start
*
* @see cx_strsubs_m()
* @see cx_strsubs()
@@ -542,7 +542,7 @@
*
* @param string the string where to locate the character
* @param chr the character to locate
- * @return a substring starting at the first location of \p chr
+ * @return a substring starting at the first location of @p chr
*
* @see cx_strchr_m()
*/
@@ -560,7 +560,7 @@
*
* @param string the string where to locate the character
* @param chr the character to locate
- * @return a substring starting at the first location of \p chr
+ * @return a substring starting at the first location of @p chr
*
* @see cx_strchr()
*/
@@ -578,7 +578,7 @@
*
* @param string the string where to locate the character
* @param chr the character to locate
- * @return a substring starting at the last location of \p chr
+ * @return a substring starting at the last location of @p chr
*
* @see cx_strrchr_m()
*/
@@ -596,7 +596,7 @@
*
* @param string the string where to locate the character
* @param chr the character to locate
- * @return a substring starting at the last location of \p chr
+ * @return a substring starting at the last location of @p chr
*
* @see cx_strrchr()
*/
@@ -610,15 +610,15 @@
* Returns a substring starting at the location of the first occurrence of the
* specified string.
*
- * If \p haystack does not contain \p needle, an empty string is returned.
+ * If @p haystack does not contain @p needle, an empty string is returned.
*
- * If \p needle is an empty string, the complete \p haystack is
+ * If @p needle is an empty string, the complete @p haystack is
* returned.
*
* @param haystack the string to be scanned
* @param needle string containing the sequence of characters to match
* @return a substring starting at the first occurrence of
- * \p needle, or an empty string, if the sequence is not
+ * @p needle, or an empty string, if the sequence is not
* contained
* @see cx_strstr_m()
*/
@@ -632,15 +632,15 @@
* Returns a substring starting at the location of the first occurrence of the
* specified string.
*
- * If \p haystack does not contain \p needle, an empty string is returned.
+ * If @p haystack does not contain @p needle, an empty string is returned.
*
- * If \p needle is an empty string, the complete \p haystack is
+ * If @p needle is an empty string, the complete @p haystack is
* returned.
*
* @param haystack the string to be scanned
* @param needle string containing the sequence of characters to match
* @return a substring starting at the first occurrence of
- * \p needle, or an empty string, if the sequence is not
+ * @p needle, or an empty string, if the sequence is not
* contained
* @see cx_strstr()
*/
@@ -653,13 +653,13 @@
/**
* Splits a given string using a delimiter string.
*
- * \note The resulting array contains strings that point to the source
- * \p string. Use cx_strdup() to get copies.
+ * @note The resulting array contains strings that point to the source
+ * @p string. Use cx_strdup() to get copies.
*
* @param string the string to split
* @param delim the delimiter
* @param limit the maximum number of split items
- * @param output a pre-allocated array of at least \p limit length
+ * @param output a pre-allocated array of at least @p limit length
* @return the actual number of split items
*/
cx_attr_nodiscard
@@ -675,13 +675,13 @@
/**
* Splits a given string using a delimiter string.
*
- * The array pointed to by \p output will be allocated by \p allocator.
+ * The array pointed to by @p output will be allocated by @p allocator.
*
- * \note The resulting array contains strings that point to the source
- * \p string. Use cx_strdup() to get copies.
+ * @note The resulting array contains strings that point to the source
+ * @p string. Use cx_strdup() to get copies.
*
- * \attention If allocation fails, the \c NULL pointer will be written to
- * \p output and the number returned will be zero.
+ * @attention If allocation fails, the @c NULL pointer will be written to
+ * @p output and the number returned will be zero.
*
* @param allocator the allocator to use for allocating the resulting array
* @param string the string to split
@@ -706,13 +706,13 @@
/**
* Splits a given string using a delimiter string.
*
- * \note The resulting array contains strings that point to the source
- * \p string. Use cx_strdup() to get copies.
+ * @note The resulting array contains strings that point to the source
+ * @p string. Use cx_strdup() to get copies.
*
* @param string the string to split
* @param delim the delimiter
* @param limit the maximum number of split items
- * @param output a pre-allocated array of at least \p limit length
+ * @param output a pre-allocated array of at least @p limit length
* @return the actual number of split items
*/
cx_attr_nodiscard
@@ -728,13 +728,13 @@
/**
* Splits a given string using a delimiter string.
*
- * The array pointed to by \p output will be allocated by \p allocator.
+ * The array pointed to by @p output will be allocated by @p allocator.
*
- * \note The resulting array contains strings that point to the source
- * \p string. Use cx_strdup() to get copies.
+ * @note The resulting array contains strings that point to the source
+ * @p string. Use cx_strdup() to get copies.
*
- * \attention If allocation fails, the \c NULL pointer will be written to
- * \p output and the number returned will be zero.
+ * @attention If allocation fails, the @c NULL pointer will be written to
+ * @p output and the number returned will be zero.
*
* @param allocator the allocator to use for allocating the resulting array
* @param string the string to split
@@ -760,8 +760,8 @@
*
* @param s1 the first string
* @param s2 the second string
- * @return negative if \p s1 is smaller than \p s2, positive if \p s1 is larger
- * than \p s2, zero if both strings equal
+ * @return negative if @p s1 is smaller than @p s2, positive if @p s1 is larger
+ * than @p s2, zero if both strings equal
*/
cx_attr_nodiscard
int cx_strcmp(
@@ -774,8 +774,8 @@
*
* @param s1 the first string
* @param s2 the second string
- * @return negative if \p s1 is smaller than \p s2, positive if \p s1 is larger
- * than \p s2, zero if both strings equal ignoring case
+ * @return negative if @p s1 is smaller than @p s2, positive if @p s1 is larger
+ * than @p s2, zero if both strings equal ignoring case
*/
cx_attr_nodiscard
int cx_strcasecmp(
@@ -790,8 +790,8 @@
*
* @param s1 the first string
* @param s2 the second string
- * @return negative if \p s1 is smaller than \p s2, positive if \p s1 is larger
- * than \p s2, zero if both strings equal
+ * @return negative if @p s1 is smaller than @p s2, positive if @p s1 is larger
+ * than @p s2, zero if both strings equal
*/
cx_attr_nodiscard
cx_attr_nonnull
@@ -807,8 +807,8 @@
*
* @param s1 the first string
* @param s2 the second string
- * @return negative if \p s1 is smaller than \p s2, positive if \p s1 is larger
- * than \p s2, zero if both strings equal ignoring case
+ * @return negative if @p s1 is smaller than @p s2, positive if @p s1 is larger
+ * than @p s2, zero if both strings equal ignoring case
*/
cx_attr_nodiscard
cx_attr_nonnull
@@ -821,9 +821,9 @@
/**
* Creates a duplicate of the specified string.
*
- * The new string will contain a copy allocated by \p allocator.
+ * The new string will contain a copy allocated by @p allocator.
*
- * \note The returned string is guaranteed to be zero-terminated.
+ * @note The returned string is guaranteed to be zero-terminated.
*
* @param allocator the allocator to use
* @param string the string to duplicate
@@ -841,12 +841,12 @@
* Creates a duplicate of the specified string.
*
* The new string will contain a copy allocated by standard
- * \c malloc(). So developers \em must pass the return value to cx_strfree().
+ * @c malloc(). So developers @em must pass the return value to cx_strfree().
*
- * \note The returned string is guaranteed to be zero-terminated.
+ * @note The returned string is guaranteed to be zero-terminated.
*
- * @param string the string to duplicate
- * @return a duplicate of the string
+ * @param string (@c cxstring) the string to duplicate
+ * @return (@c cxmutstr) a duplicate of the string
* @see cx_strdup_a()
*/
#define cx_strdup(string) cx_strdup_a(cxDefaultAllocator, string)
@@ -855,13 +855,13 @@
/**
* Creates a duplicate of the specified string.
*
- * The new string will contain a copy allocated by \p allocator.
+ * The new string will contain a copy allocated by @p allocator.
*
- * \note The returned string is guaranteed to be zero-terminated.
+ * @note The returned string is guaranteed to be zero-terminated.
*
- * @param allocator the allocator to use
- * @param string the string to duplicate
- * @return a duplicate of the string
+ * @param allocator (@c CxAllocator*) the allocator to use
+ * @param string (@c cxmutstr) the string to duplicate
+ * @return (@c cxmutstr) a duplicate of the string
* @see cx_strdup_m()
*/
#define cx_strdup_ma(allocator, string) cx_strdup_a(allocator, cx_strcast(string))
@@ -870,12 +870,12 @@
* Creates a duplicate of the specified string.
*
* The new string will contain a copy allocated by standard
- * \c malloc(). So developers \em must pass the return value to cx_strfree().
+ * @c malloc(). So developers @em must pass the return value to cx_strfree().
*
- * \note The returned string is guaranteed to be zero-terminated.
+ * @note The returned string is guaranteed to be zero-terminated.
*
- * @param string the string to duplicate
- * @return a duplicate of the string
+ * @param string (@c cxmutstr) the string to duplicate
+ * @return (@c cxmutstr) a duplicate of the string
* @see cx_strdup_ma()
*/
#define cx_strdup_m(string) cx_strdup_a(cxDefaultAllocator, cx_strcast(string))
@@ -883,8 +883,8 @@
/**
* Omits leading and trailing spaces.
*
- * \note the returned string references the same memory, thus you
- * must \em not free the returned memory.
+ * @note the returned string references the same memory, thus you
+ * must @em not free the returned memory.
*
* @param string the string that shall be trimmed
* @return the trimmed string
@@ -895,8 +895,8 @@
/**
* Omits leading and trailing spaces.
*
- * \note the returned string references the same memory, thus you
- * must \em not free the returned memory.
+ * @note the returned string references the same memory, thus you
+ * must @em not free the returned memory.
*
* @param string the string that shall be trimmed
* @return the trimmed string
@@ -909,8 +909,8 @@
*
* @param string the string to check
* @param prefix the prefix the string should have
- * @return \c true, if and only if the string has the specified prefix,
- * \c false otherwise
+ * @return @c true, if and only if the string has the specified prefix,
+ * @c false otherwise
*/
cx_attr_nodiscard
bool cx_strprefix(
@@ -923,8 +923,8 @@
*
* @param string the string to check
* @param suffix the suffix the string should have
- * @return \c true, if and only if the string has the specified suffix,
- * \c false otherwise
+ * @return @c true, if and only if the string has the specified suffix,
+ * @c false otherwise
*/
cx_attr_nodiscard
bool cx_strsuffix(
@@ -937,8 +937,8 @@
*
* @param string the string to check
* @param prefix the prefix the string should have
- * @return \c true, if and only if the string has the specified prefix,
- * \c false otherwise
+ * @return @c true, if and only if the string has the specified prefix,
+ * @c false otherwise
*/
cx_attr_nodiscard
bool cx_strcaseprefix(
@@ -951,8 +951,8 @@
*
* @param string the string to check
* @param suffix the suffix the string should have
- * @return \c true, if and only if the string has the specified suffix,
- * \c false otherwise
+ * @return @c true, if and only if the string has the specified suffix,
+ * @c false otherwise
*/
cx_attr_nodiscard
bool cx_strcasesuffix(
@@ -984,9 +984,9 @@
* Replaces a pattern in a string with another string.
*
* The pattern is taken literally and is no regular expression.
- * Replaces at most \p replmax occurrences.
+ * Replaces at most @p replmax occurrences.
*
- * The returned string will be allocated by \p allocator and is guaranteed
+ * The returned string will be allocated by @p allocator and is guaranteed
* to be zero-terminated.
*
* If allocation fails, or the input string is empty,
@@ -1013,19 +1013,19 @@
* Replaces a pattern in a string with another string.
*
* The pattern is taken literally and is no regular expression.
- * Replaces at most \p replmax occurrences.
+ * Replaces at most @p replmax occurrences.
*
- * The returned string will be allocated by \c malloc() and is guaranteed
+ * The returned string will be allocated by @c malloc() and is guaranteed
* to be zero-terminated.
*
* If allocation fails, or the input string is empty,
* the returned string will be empty.
*
- * @param str the string where replacements should be applied
- * @param pattern the pattern to search for
- * @param replacement the replacement string
- * @param replmax maximum number of replacements
- * @return the resulting string after applying the replacements
+ * @param str (@c cxstring) the string where replacements should be applied
+ * @param pattern (@c cxstring) the pattern to search for
+ * @param replacement (@c cxstring) the replacement string
+ * @param replmax (@c size_t) maximum number of replacements
+ * @return (@c cxmutstr) the resulting string after applying the replacements
*/
#define cx_strreplacen(str, pattern, replacement, replmax) \
cx_strreplacen_a(cxDefaultAllocator, str, pattern, replacement, replmax)
@@ -1035,17 +1035,17 @@
*
* The pattern is taken literally and is no regular expression.
*
- * The returned string will be allocated by \p allocator and is guaranteed
+ * The returned string will be allocated by @p allocator and is guaranteed
* to be zero-terminated.
*
* If allocation fails, or the input string is empty,
* the returned string will be empty.
*
- * @param allocator the allocator to use
- * @param str the string where replacements should be applied
- * @param pattern the pattern to search for
- * @param replacement the replacement string
- * @return the resulting string after applying the replacements
+ * @param allocator (@c CxAllocator*) the allocator to use
+ * @param str (@c cxstring) the string where replacements should be applied
+ * @param pattern (@c cxstring) the pattern to search for
+ * @param replacement (@c cxstring) the replacement string
+ * @return (@c cxmutstr) the resulting string after applying the replacements
*/
#define cx_strreplace_a(allocator, str, pattern, replacement) \
cx_strreplacen_a(allocator, str, pattern, replacement, SIZE_MAX)
@@ -1054,18 +1054,18 @@
* Replaces a pattern in a string with another string.
*
* The pattern is taken literally and is no regular expression.
- * Replaces at most \p replmax occurrences.
+ * Replaces at most @p replmax occurrences.
*
- * The returned string will be allocated by \c malloc() and is guaranteed
+ * The returned string will be allocated by @c malloc() and is guaranteed
* to be zero-terminated.
*
* If allocation fails, or the input string is empty,
* the returned string will be empty.
*
- * @param str the string where replacements should be applied
- * @param pattern the pattern to search for
- * @param replacement the replacement string
- * @return the resulting string after applying the replacements
+ * @param str (@c cxstring) the string where replacements should be applied
+ * @param pattern (@c cxstring) the pattern to search for
+ * @param replacement (@c cxstring) the replacement string
+ * @return (@c cxmutstr) the resulting string after applying the replacements
*/
#define cx_strreplace(str, pattern, replacement) \
cx_strreplacen_a(cxDefaultAllocator, str, pattern, replacement, SIZE_MAX)
@@ -1158,87 +1158,87 @@
* ------------------------------------------------------------------------- */
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtos_lc(cxstring str, short *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtoi_lc(cxstring str, int *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtol_lc(cxstring str, long *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtoll_lc(cxstring str, long long *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtoi8_lc(cxstring str, int8_t *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtoi16_lc(cxstring str, int16_t *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtoi32_lc(cxstring str, int32_t *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtoi64_lc(cxstring str, int64_t *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtoz_lc(cxstring str, ssize_t *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtous_lc(cxstring str, unsigned short *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtou_lc(cxstring str, unsigned int *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtoul_lc(cxstring str, unsigned long *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtoull_lc(cxstring str, unsigned long long *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtou8_lc(cxstring str, uint8_t *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtou16_lc(cxstring str, uint16_t *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtou32_lc(cxstring str, uint32_t *output, int base, const char *groupsep);
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtou64_lc(cxstring str, uint64_t *output, int base, const char *groupsep);
@@ -1254,7 +1254,8 @@
* @param output a pointer to the integer variable where the result shall be stored
* @param base 2, 8, 10, or 16
* @param groupsep each character in this string is treated as group separator and ignored during conversion
- * @return zero on success, non-zero if conversion was not possible
+ * @retval zero success
+ * @retval non-zero conversion was not possible
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtouz_lc(cxstring str, size_t *output, int base, const char *groupsep);
@@ -1274,7 +1275,8 @@
* @param output a pointer to the float variable where the result shall be stored
* @param decsep the decimal separator
* @param groupsep each character in this string is treated as group separator and ignored during conversion
- * @return zero on success, non-zero if conversion was not possible
+ * @retval zero success
+ * @retval non-zero conversion was not possible
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtof_lc(cxstring str, float *output, char decsep, const char *groupsep);
@@ -1294,78 +1296,79 @@
* @param output a pointer to the float variable where the result shall be stored
* @param decsep the decimal separator
* @param groupsep each character in this string is treated as group separator and ignored during conversion
- * @return zero on success, non-zero if conversion was not possible
+ * @retval zero success
+ * @retval non-zero conversion was not possible
*/
cx_attr_access_w(2) cx_attr_nonnull_arg(2)
int cx_strtod_lc(cxstring str, double *output, char decsep, const char *groupsep);
#ifndef CX_STR_IMPLEMENTATION
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtos_lc(str, output, base, groupsep) cx_strtos_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtoi_lc(str, output, base, groupsep) cx_strtoi_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtol_lc(str, output, base, groupsep) cx_strtol_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtoll_lc(str, output, base, groupsep) cx_strtoll_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtoi8_lc(str, output, base, groupsep) cx_strtoi8_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtoi16_lc(str, output, base, groupsep) cx_strtoi16_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtoi32_lc(str, output, base, groupsep) cx_strtoi32_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtoi64_lc(str, output, base, groupsep) cx_strtoi64_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtoz_lc(str, output, base, groupsep) cx_strtoz_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtous_lc(str, output, base, groupsep) cx_strtous_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtou_lc(str, output, base, groupsep) cx_strtou_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtoul_lc(str, output, base, groupsep) cx_strtoul_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtoull_lc(str, output, base, groupsep) cx_strtoull_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtou8_lc(str, output, base, groupsep) cx_strtou8_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtou16_lc(str, output, base, groupsep) cx_strtou16_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtou32_lc(str, output, base, groupsep) cx_strtou32_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz_lc()
+ * @copydoc cx_strtouz_lc()
*/
#define cx_strtou64_lc(str, output, base, groupsep) cx_strtou64_lc(cx_strcast(str), output, base, groupsep)
/**
@@ -1379,76 +1382,77 @@
* @param output a pointer to the integer variable where the result shall be stored
* @param base 2, 8, 10, or 16
* @param groupsep each character in this string is treated as group separator and ignored during conversion
- * @return zero on success, non-zero if conversion was not possible
+ * @retval zero success
+ * @retval non-zero conversion was not possible
*/
#define cx_strtouz_lc(str, output, base, groupsep) cx_strtouz_lc(cx_strcast(str), output, base, groupsep)
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtos(str, output, base) cx_strtos_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtoi(str, output, base) cx_strtoi_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtol(str, output, base) cx_strtol_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtoll(str, output, base) cx_strtoll_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtoi8(str, output, base) cx_strtoi8_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtoi16(str, output, base) cx_strtoi16_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtoi32(str, output, base) cx_strtoi32_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtoi64(str, output, base) cx_strtoi64_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtoz(str, output, base) cx_strtoz_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtous(str, output, base) cx_strtous_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtou(str, output, base) cx_strtou_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtoul(str, output, base) cx_strtoul_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtoull(str, output, base) cx_strtoull_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtou8(str, output, base) cx_strtou8_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtou16(str, output, base) cx_strtou16_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtou32(str, output, base) cx_strtou32_lc(str, output, base, ",")
/**
- * \copydoc cx_strtouz()
+ * @copydoc cx_strtouz()
*/
#define cx_strtou64(str, output, base) cx_strtou64_lc(str, output, base, ",")
/**
@@ -1459,12 +1463,13 @@
* It sets errno to ERANGE when the target datatype is too small.
*
* The comma character is treated as group separator and ignored during parsing.
- * If you want to choose the set of group separators, use the \c _lc variant of this function (e.g. cx_strtouz_lc()).
+ * If you want to choose the set of group separators, use the @c _lc variant of this function (e.g. cx_strtouz_lc()).
*
* @param str the string to convert
* @param output a pointer to the integer variable where the result shall be stored
* @param base 2, 8, 10, or 16
- * @return zero on success, non-zero if conversion was not possible
+ * @retval zero success
+ * @retval non-zero conversion was not possible
*/
#define cx_strtouz(str, output, base) cx_strtouz_lc(str, output, base, ",")
@@ -1483,7 +1488,8 @@
* @param output a pointer to the float variable where the result shall be stored
* @param decsep the decimal separator
* @param groupsep each character in this string is treated as group separator and ignored during conversion
- * @return zero on success, non-zero if conversion was not possible
+ * @retval zero success
+ * @retval non-zero conversion was not possible
*/
#define cx_strtof_lc(str, output, decsep, groupsep) cx_strtof_lc(cx_strcast(str), output, decsep, groupsep)
/**
@@ -1491,17 +1497,17 @@
*
* The function returns non-zero when conversion is not possible.
* In that case the function sets errno to EINVAL when the reason is an invalid character.
- * It sets errno to ERANGE when the necessary representation would exceed the limits defined in libc's float.h.
*
* The decimal separator is assumed to be a dot character.
* The comma character is treated as group separator and ignored during parsing.
* If you want to choose a different format, use cx_strtof_lc().
*
* @param str the string to convert
- * @param output a pointer to the float variable where the result shall be stored
+ * @param output a pointer to the double variable where the result shall be stored
* @param decsep the decimal separator
* @param groupsep each character in this string is treated as group separator and ignored during conversion
- * @return zero on success, non-zero if conversion was not possible
+ * @retval zero success
+ * @retval non-zero conversion was not possible
*/
#define cx_strtod_lc(str, output, decsep, groupsep) cx_strtod_lc(cx_strcast(str), output, decsep, groupsep)
@@ -1518,7 +1524,8 @@
*
* @param str the string to convert
* @param output a pointer to the float variable where the result shall be stored
- * @return zero on success, non-zero if conversion was not possible
+ * @retval zero success
+ * @retval non-zero conversion was not possible
*/
#define cx_strtof(str, output) cx_strtof_lc(str, output, '.', ",")
/**
@@ -1526,15 +1533,15 @@
*
* The function returns non-zero when conversion is not possible.
* In that case the function sets errno to EINVAL when the reason is an invalid character.
- * It sets errno to ERANGE when the necessary representation would exceed the limits defined in libc's float.h.
*
* The decimal separator is assumed to be a dot character.
* The comma character is treated as group separator and ignored during parsing.
* If you want to choose a different format, use cx_strtof_lc().
*
* @param str the string to convert
- * @param output a pointer to the float variable where the result shall be stored
- * @return zero on success, non-zero if conversion was not possible
+ * @param output a pointer to the double variable where the result shall be stored
+ * @retval zero success
+ * @retval non-zero conversion was not possible
*/
#define cx_strtod(str, output) cx_strtod_lc(str, output, '.', ",")
