Mercurial > hg > ucx / changeset

--- a/src/cx/string.h	Sun Dec 22 11:34:05 2024 +0100
+++ b/src/cx/string.h	Sun Dec 22 21:33:10 2024 +0100
@@ -1120,70 +1120,364 @@
  * ------------------------------------------------------------------------- */
 
 
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtos_lc(cxstring str, short *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtoi_lc(cxstring str, int *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtol_lc(cxstring str, long *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtoll_lc(cxstring str, long int *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtoi8_lc(cxstring str, int8_t *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtoi16_lc(cxstring str, int16_t *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtoi32_lc(cxstring str, int32_t *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtoi64_lc(cxstring str, int64_t *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtoz_lc(cxstring str, ssize_t *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtous_lc(cxstring str, unsigned short *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtou_lc(cxstring str, unsigned int *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtoul_lc(cxstring str, unsigned long *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtoull_lc(cxstring str, unsigned long int *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtou8_lc(cxstring str, uint8_t *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtou16_lc(cxstring str, uint16_t *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtou32_lc(cxstring str, uint32_t *output, int base, const char *groupsep);
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 int cx_strtou64_lc(cxstring str, uint64_t *output, int base, const char *groupsep);
+
+/**
+ * Converts a string to a number.
+ *
+ * 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 or an unsupported base.
+ * It sets errno to ERANGE when the target datatype is too small.
+ *
+ * @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
+ * @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
+ */
 int cx_strtouz_lc(cxstring str, size_t *output, int base, const char *groupsep);
 
+/**
+ * \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()
+ */
 #define cx_strtoi_lc(str, output, base, groupsep) cx_strtoi_lc(cx_strcast(str), output, base, groupsep)
+/**
+ * \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()
+ */
 #define cx_strtoll_lc(str, output, base, groupsep) cx_strtoll_lc(cx_strcast(str), output, base, groupsep)
+/**
+ * \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()
+ */
 #define cx_strtoi16_lc(str, output, base, groupsep) cx_strtoi16_lc(cx_strcast(str), output, base, groupsep)
+/**
+ * \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()
+ */
 #define cx_strtoi64_lc(str, output, base, groupsep) cx_strtoi64_lc(cx_strcast(str), output, base, groupsep)
+/**
+ * \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()
+ */
 #define cx_strtous_lc(str, output, base, groupsep) cx_strtous_lc(cx_strcast(str), output, base, groupsep)
+/**
+ * \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()
+ */
 #define cx_strtoul_lc(str, output, base, groupsep) cx_strtoul_lc(cx_strcast(str), output, base, groupsep)
+/**
+ * \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()
+ */
 #define cx_strtou8_lc(str, output, base, groupsep) cx_strtou8_lc(cx_strcast(str), output, base, groupsep)
+/**
+ * \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()
+ */
 #define cx_strtou32_lc(str, output, base, groupsep) cx_strtou32_lc(cx_strcast(str), output, base, groupsep)
+/**
+ * \copydoc cx_strtouz_lc()
+ */
 #define cx_strtou64_lc(str, output, base, groupsep) cx_strtou64_lc(cx_strcast(str), output, base, groupsep)
+/**
+ * Converts a string to a number.
+ *
+ * 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 or an unsupported base.
+ * It sets errno to ERANGE when the target datatype is too small.
+ *
+ * @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
+ * @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
+ */
 #define cx_strtouz_lc(str, output, base, groupsep) cx_strtouz_lc(cx_strcast(str), output, base, groupsep)
 
+
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtos(str, output, base) cx_strtos_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtoi(str, output, base) cx_strtoi_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtol(str, output, base) cx_strtol_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtoll(str, output, base) cx_strtoll_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtoi8(str, output, base) cx_strtoi8_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtoi16(str, output, base) cx_strtoi16_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtoi32(str, output, base) cx_strtoi32_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtoi64(str, output, base) cx_strtoi64_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtoz(str, output, base) cx_strtoz_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtous(str, output, base) cx_strtous_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtou(str, output, base) cx_strtou_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtoul(str, output, base) cx_strtoul_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtoull(str, output, base) cx_strtoull_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtou8(str, output, base) cx_strtou8_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtou16(str, output, base) cx_strtou16_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtou32(str, output, base) cx_strtou32_lc(str, output, base, ",")
+/**
+ * \copydoc cx_strtouz()
+ */
 #define cx_strtou64(str, output, base) cx_strtou64_lc(str, output, base, ",")
+/**
+ * Converts a string to a number.
+ *
+ * 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 or an unsupported base.
+ * 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()).
+ *
+ * @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
+ */
 #define cx_strtouz(str, output, base) cx_strtouz_lc(str, output, base, ",")
 
+/**
+ * Converts a string to a single precision floating point number.
+ *
+ * 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 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
+ */
 int cx_strtof_lc(cxstring str, float *output, char decsep, const char *groupsep);
+/**
+ * Converts a string to a double precision floating point number.
+ *
+ * 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 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
+ */
 int cx_strtod_lc(cxstring str, double *output, char decsep, const char *groupsep);
 
+/**
+ * Converts a string to a single precision floating point number.
+ *
+ * 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 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
+ */
 #define cx_strtof_lc(str, output, decsep, groupsep) cx_strtof_lc(cx_strcast(str), output, decsep, groupsep)
+/**
+ * Converts a string to a double precision floating point number.
+ *
+ * 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 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
+ */
 #define cx_strtod_lc(str, output, decsep, groupsep) cx_strtod_lc(cx_strcast(str), output, decsep, groupsep)
 
+/**
+ * Converts a string to a single precision floating point number.
+ *
+ * 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
+ */
 #define cx_strtof(str, output) cx_strtof_lc(str, output, '.', ",")
+/**
+ * Converts a string to a double precision floating point number.
+ *
+ * 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
+ */
 #define cx_strtod(str, output) cx_strtod_lc(str, output, '.', ",")
 
 #ifdef __cplusplus