From 7d94bf528dbc33bee0bf37d09d646d2b42f2531f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carl=20=C3=85stholm?= Date: Thu, 12 Sep 2024 23:24:09 +0200 Subject: [PATCH] stdlib: Document SDL_strtox functions --- include/SDL3/SDL_stdinc.h | 50 ++++++++++++++++----------------------- 1 file changed, 21 insertions(+), 29 deletions(-) diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index f444104811..17ff636c35 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/include/SDL3/SDL_stdinc.h @@ -1719,21 +1719,18 @@ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); /** * Parse a `long` from a string. * - * This function makes fewer guarantees than the C runtime `strtol`: + * If `str` starts with whitespace, then those whitespace characters are skipped before attempting to parse the number. * - * - Only the bases 10 and 16 are guaranteed to be supported. The behavior for - * other bases is unspecified. - * - It is unspecified what this function returns when the parsed integer does - * not fit inside a `long`. + * If the parsed number does not fit inside a `long`, the result is clamped to the minimum and maximum representable `long` values. * * \param str The null-terminated string to read. Must not be NULL. * \param endp If not NULL, the address of the first invalid character (i.e. * the next character after the parsed number) will be written to * this pointer. - * \param base The base of the integer to read. The values 0, 10 and 16 are - * supported. If 0, the base will be inferred from the integer's - * prefix. - * \returns The parsed `long`. + * \param base The base of the integer to read. Supported values are 0 and 2 to 36 inclusive. + * If 0, the base will be inferred from the number's + * prefix (0x for hexadecimal, 0 for octal, decimal otherwise). + * \returns The parsed `long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -1753,21 +1750,19 @@ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int ba /** * Parse an `unsigned long` from a string. * - * This function makes fewer guarantees than the C runtime `strtoul`: + * If `str` starts with whitespace, then those whitespace characters are skipped before attempting to parse the number. * - * - Only the bases 10 and 16 are guaranteed to be supported. The behavior for - * other bases is unspecified. - * - It is unspecified what this function returns when the parsed integer does - * not fit inside an `unsigned long`. + * If the parsed number does not fit inside an `unsigned long`, + * the result is clamped to the maximum representable `unsigned long` value. * * \param str The null-terminated string to read. Must not be NULL. * \param endp If not NULL, the address of the first invalid character (i.e. * the next character after the parsed number) will be written to * this pointer. - * \param base The base of the integer to read. The values 0, 10 and 16 are - * supported. If 0, the base will be inferred from the integer's - * prefix. - * \returns The parsed `unsigned long`. + * \param base The base of the integer to read. Supported values are 0 and 2 to 36 inclusive. + * If 0, the base will be inferred from the number's + * prefix (0x for hexadecimal, 0 for octal, decimal otherwise). + * \returns The parsed `unsigned long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -1786,21 +1781,18 @@ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **en /** * Parse a `long long` from a string. * - * This function makes fewer guarantees than the C runtime `strtoll`: + * If `str` starts with whitespace, then those whitespace characters are skipped before attempting to parse the number. * - * - Only the bases 10 and 16 are guaranteed to be supported. The behavior for - * other bases is unspecified. - * - It is unspecified what this function returns when the parsed integer does - * not fit inside a `long long`. + * If the parsed number does not fit inside a `long long`, the result is clamped to the minimum and maximum representable `long long` values. * * \param str The null-terminated string to read. Must not be NULL. * \param endp If not NULL, the address of the first invalid character (i.e. * the next character after the parsed number) will be written to * this pointer. - * \param base The base of the integer to read. The values 0, 10 and 16 are - * supported. If 0, the base will be inferred from the integer's - * prefix. - * \returns The parsed `long long`. + * \param base The base of the integer to read. Supported values are 0 and 2 to 36 inclusive. + * If 0, the base will be inferred from the number's + * prefix (0x for hexadecimal, 0 for octal, decimal otherwise). + * \returns The parsed `long long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -1831,7 +1823,7 @@ extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, * \param base The base of the integer to read. Supported values are 0 and 2 to 36 inclusive. * If 0, the base will be inferred from the number's * prefix (0x for hexadecimal, 0 for octal, decimal otherwise). - * \returns The parsed `unsigned long long`. + * \returns The parsed `unsigned long long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -1861,7 +1853,7 @@ extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, cha * \param endp If not NULL, the address of the first invalid character (i.e. * the next character after the parsed number) will be written to * this pointer. - * \returns The parsed `double`. + * \returns The parsed `double`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. *