From 8eb194b6f86d40817d34f5ed77e69c89cfee5945 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carl=20=C3=85stholm?= Date: Mon, 9 Sep 2024 19:15:10 +0200 Subject: [PATCH] stdinc: Document number parsing APIs --- include/SDL3/SDL_stdinc.h | 223 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index 8951b2534..3f2f52548 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/include/SDL3/SDL_stdinc.h @@ -1475,6 +1475,30 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_ */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); +/** + * Parse a `long` from a wide string. + * + * This function makes fewer guarantees than the C runtime `wcstol`: + * + * - 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`. + * + * `str` and `endp` must not overlap. + * + * \param str The null-terminated wide string to read. Must not be NULL and must not overlap with `endp`. + * \param endp If not NULL, the address of the first invalid wide character + * (i.e. the next character after the parsed number) will be written to this pointer. + * Must not overlap with `dst`. + * \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`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_strtol + */ extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base); extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); @@ -1616,12 +1640,211 @@ extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(Sint64 value, char *str, int radix); extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(Uint64 value, char *str, int radix); +/** + * Parse an `int` from a string. + * + * The result of calling `SDL_atoi(str)` is equivalent to `(int)SDL_strtol(str, NULL, 10)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns The parsed `int`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_itoa + */ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); + +/** + * Parse a `double` from a string. + * + * The result of calling `SDL_atoi(str)` is equivalent to `SDL_strtod(str, NULL)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns The parsed `double`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atoi + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + */ 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`: + * + * - 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`. + * + * `str` and `endp` must not overlap. + * + * \param str The null-terminated string to read. Must not be NULL and must not overlap with `endp`. + * \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. + * Must not overlap with `dst`. + * \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`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ltoa + * \sa SDL_wcstol + */ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long` from a string. + * + * This function makes fewer guarantees than the C runtime `strtoul`: + * + * - 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`. + * + * `str` and `endp` must not overlap. + * + * \param str The null-terminated string to read. Must not be NULL and must not overlap with `endp`. + * \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. + * Must not overlap with `dst`. + * \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`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ultoa + */ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base); + +/** + * Parse an Sint64 from a string. + * + * This function makes fewer guarantees than the C runtime `strtoll`: + * + * - 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`. + * + * Also note that unlike the C runtime `strtoll`, this function returns an Sint64, not a `long long`. + * + * `str` and `endp` must not overlap. + * + * \param str The null-terminated string to read. Must not be NULL and must not overlap with `endp`. + * \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. + * Must not overlap with `dst`. + * \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 Sint64. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_lltoa + */ extern SDL_DECLSPEC Sint64 SDLCALL SDL_strtoll(const char *str, char **endp, int base); + +/** + * Parse a Uint64 from a string. + * + * This function makes fewer guarantees than the C runtime `strtoull`: + * + * - 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`. + * + * Also note that unlike the C runtime `strtoull`, this function returns a Uint64, not an `unsigned long long`. + * + * `str` and `endp` must not overlap. + * + * \param str The null-terminated string to read. Must not be NULL and must not overlap with `endp`. + * \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. + * Must not overlap with `dst`. + * \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 Uint64. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtod + * \sa SDL_ulltoa + */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_strtoull(const char *str, char **endp, int base); + +/** + * Parse a `double` from a string. + * + * This function makes fewer guarantees than the C runtime `strtod`: + * + * - Only decimal notation is guaranteed to be supported. + * The handling of scientific and hexadecimal notation is unspecified. + * - Whether or not INF and NAN can be parsed is unspecified. + * - The precision of the result is unspecified. + * + * `str` and `endp` must not overlap. + * + * \param str The null-terminated string to read. Must not be NULL and must not overlap with `endp`. + * \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. + * Must not overlap with `dst`. + * \returns The parsed `double`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtoull + */ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); /**