From 7d1bbae6b256590d65f24c567ecdc99668a431cb Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Mon, 9 Sep 2024 20:51:57 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
---
include/SDL3/SDL_stdinc.h | 252 +++++++++++++++++++++++---------------
1 file changed, 156 insertions(+), 96 deletions(-)
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index 8258f57882895..f2e58a1960fc7 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -23,10 +23,10 @@
* # CategoryStdinc
*
* This is a general header that includes C language support. It implements a
- * subset of the C runtime APIs, but with an `SDL_` prefix.
- * For most common use cases, these should behave the same way as their C
- * runtime equivalents, but they may differ in how or whether they handle certain edge cases.
- * When in doubt, consult the documentation for details.
+ * subset of the C runtime APIs, but with an `SDL_` prefix. For most common
+ * use cases, these should behave the same way as their C runtime equivalents,
+ * but they may differ in how or whether they handle certain edge cases. When
+ * in doubt, consult the documentation for details.
*/
#ifndef SDL_stdinc_h_
@@ -670,11 +670,13 @@ extern "C" {
/**
* Allocate uninitialized memory.
*
- * The allocated memory returned by this function must be freed with SDL_free().
+ * The allocated memory returned by this function must be freed with
+ * SDL_free().
*
* If `size` is 0, it will be set to 1.
*
- * If you want to allocate memory aligned to a specific alignment, consider using SDL_aligned_alloc().
+ * If you want to allocate memory aligned to a specific alignment, consider
+ * using SDL_aligned_alloc().
*
* \param size the size to allocate.
* \returns a pointer to the allocated memory, or NULL if allocation failed.
@@ -716,23 +718,25 @@ extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(s
*
* The memory returned by this function must be freed with SDL_free().
*
- * If `size` is 0, it will be set to 1.
- * Note that this is unlike some other C runtime `realloc` implementations,
- * which may treat `realloc(mem, 0)` the same way as `free(mem)`.
+ * If `size` is 0, it will be set to 1. Note that this is unlike some other C
+ * runtime `realloc` implementations, which may treat `realloc(mem, 0)` the
+ * same way as `free(mem)`.
*
- * If `mem` is NULL, the behavior of this function is equivalent to SDL_malloc().
- * Otherwise, the function can have one of three possible outcomes:
+ * If `mem` is NULL, the behavior of this function is equivalent to
+ * SDL_malloc(). Otherwise, the function can have one of three possible
+ * outcomes:
*
- * - If it returns the same pointer as `mem`,
- * it means that `mem` was resized in place without freeing.
- * - If it returns a different non-NULL pointer,
- * it means that `mem` was freed and cannot be dereferenced anymore.
- * - If it returns NULL (indicating failure),
- * then `mem` will remain valid and must still be freed with SDL_free().
+ * - If it returns the same pointer as `mem`, it means that `mem` was resized
+ * in place without freeing.
+ * - If it returns a different non-NULL pointer, it means that `mem` was freed
+ * and cannot be dereferenced anymore.
+ * - If it returns NULL (indicating failure), then `mem` will remain valid and
+ * must still be freed with SDL_free().
*
* \param mem a pointer to allocated memory to reallocate, or NULL.
* \param size the new size of the memory.
- * \returns a pointer to the newly allocated memory, or NULL if allocation failed.
+ * \returns a pointer to the newly allocated memory, or NULL if allocation
+ * failed.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -786,7 +790,8 @@ typedef void *(SDLCALL *SDL_malloc_func)(size_t size);
/**
* A callback used to implement SDL_calloc().
*
- * SDL will always ensure that the passed `nmemb` and `size` are both greater than 0.
+ * SDL will always ensure that the passed `nmemb` and `size` are both greater
+ * than 0.
*
* \param nmemb the number of elements in the array.
* \param size the size of each element of the array.
@@ -810,7 +815,8 @@ typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size);
*
* \param mem a pointer to allocated memory to reallocate, or NULL.
* \param size the new size of the memory.
- * \returns a pointer to the newly allocated memory, or NULL if allocation failed.
+ * \returns a pointer to the newly allocated memory, or NULL if allocation
+ * failed.
*
* \threadsafety It should be safe to call this callback from any thread.
*
@@ -922,8 +928,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func mall
* The memory returned by this function must be freed with SDL_aligned_free(),
* _not_ SDL_free().
*
- * If `alignment` is less than the size of `void *`, it will be increased
- * to match that.
+ * If `alignment` is less than the size of `void *`, it will be increased to
+ * match that.
*
* The returned memory address will be a multiple of the alignment value, and
* the size of the memory allocated will be a multiple of the alignment value.
@@ -1232,8 +1238,10 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_
*
* The memory regions must not overlap. If they do, use SDL_memmove() instead.
*
- * \param dst The destination memory region. Must not be NULL, and must not overlap with `src`.
- * \param src The source memory region. Must not be NULL, and must not overlap with `dst`.
+ * \param dst The destination memory region. Must not be NULL, and must not
+ * overlap with `src`.
+ * \param src The source memory region. Must not be NULL, and must not overlap
+ * with `dst`.
* \param len The length in bytes of both `dst` and `src`.
* \returns `dst`.
*
@@ -1260,8 +1268,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SD
/**
* Copy memory.
*
- * It is okay for the memory regions to overlap.
- * If you are confident that the regions never overlap, using SDL_memcpy() may improve performance.
+ * It is okay for the memory regions to overlap. If you are confident that the
+ * regions never overlap, using SDL_memcpy() may improve performance.
*
* \param dst The destination memory region. Must not be NULL.
* \param src The source memory region. Must not be NULL.
@@ -1307,16 +1315,21 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxle
/**
* Copy a wide string.
*
- * This function copies `maxlen` - 1 wide characters from `src` to `dst`, then appends a null terminator.
+ * This function copies `maxlen` - 1 wide characters from `src` to `dst`, then
+ * appends a null terminator.
*
* `src` and `dst` must not overlap.
*
- * If `maxlen` is 0, no wide characters are copied and no null terminator is written.
+ * If `maxlen` is 0, no wide characters are copied and no null terminator is
+ * written.
*
- * \param dst The destination buffer. Must not be NULL, and must not overlap with `src`.
- * \param src The null-terminated wide string to copy. Must not be NULL, and must not overlap with `dst`.
+ * \param dst The destination buffer. Must not be NULL, and must not overlap
+ * with `src`.
+ * \param src The null-terminated wide string to copy. Must not be NULL, and
+ * must not overlap with `dst`.
* \param maxlen The length (in wide characters) of the destination buffer.
- * \returns The length (in wide characters, excluding the null terminator) of `src`.
+ * \returns The length (in wide characters, excluding the null terminator) of
+ * `src`.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1329,17 +1342,23 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *ds
/**
* Concatenate wide strings.
*
- * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters from `src`
- * to the end of the wide string in `dst`, then appends a null terminator.
+ * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters
+ * from `src` to the end of the wide string in `dst`, then appends a null
+ * terminator.
*
* `src` and `dst` must not overlap.
*
- * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is unmodified.
+ * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is
+ * unmodified.
*
- * \param dst The destination buffer already containing the first null-terminated wide string. Must not be NULL and must not overlap with `src`.
- * \param src The second null-terminated wide string. Must not be NULL, and must not overlap with `dst`.
+ * \param dst The destination buffer already containing the first
+ * null-terminated wide string. Must not be NULL and must not
+ * overlap with `src`.
+ * \param src The second null-terminated wide string. Must not be NULL, and
+ * must not overlap with `dst`.
* \param maxlen The length (in wide characters) of the destination buffer.
- * \returns The length (in wide characters, excluding the null terminator) of the string in `dst` plus the length of `src`.
+ * \returns The length (in wide characters, excluding the null terminator) of
+ * the string in `dst` plus the length of `src`.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1480,14 +1499,18 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar
*
* 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`.
+ * - 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`.
*
* \param str The null-terminated wide string to read. Must not be NULL.
* \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.
- * \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.
+ * (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`.
*
* \threadsafety It is safe to call this function from any thread.
@@ -1504,17 +1527,22 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen);
/**
* Copy a string.
*
- * This function copies up to `maxlen` - 1 characters from `src` to `dst`, then appends a null terminator.
+ * This function copies up to `maxlen` - 1 characters from `src` to `dst`,
+ * then appends a null terminator.
*
- * If `maxlen` is 0, no characters are copied and no null terminator is written.
+ * If `maxlen` is 0, no characters are copied and no null terminator is
+ * written.
*
- * If you want to copy an UTF-8 string but need to ensure that multi-byte sequences are not truncated,
- * consider using SDL_utf8strlcpy().
+ * If you want to copy an UTF-8 string but need to ensure that multi-byte
+ * sequences are not truncated, consider using SDL_utf8strlcpy().
*
- * \param dst The destination buffer. Must not be NULL, and must not overlap with `src`.
- * \param src The null-terminated string to copy. Must not be NULL, and must not overlap with `dst`.
+ * \param dst The destination buffer. Must not be NULL, and must not overlap
+ * with `src`.
+ * \param src The null-terminated string to copy. Must not be NULL, and must
+ * not overlap with `dst`.
* \param maxlen The length (in characters) of the destination buffer.
- * \returns The length (in characters, excluding the null terminator) of `src`.
+ * \returns The length (in characters, excluding the null terminator) of
+ * `src`.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1528,17 +1556,21 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst,
/**
* Copy an UTF-8 string.
*
- * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst`
- * while also ensuring that the string written to `dst`
- * does not end in a truncated multi-byte sequence. Finally, it appends a null terminator.
+ * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst` while
+ * also ensuring that the string written to `dst` does not end in a truncated
+ * multi-byte sequence. Finally, it appends a null terminator.
*
* `src` and `dst` must not overlap.
*
- * Note that unlike SDL_strlcpy(), this function returns the number of bytes written, not the length of `src`.
+ * Note that unlike SDL_strlcpy(), this function returns the number of bytes
+ * written, not the length of `src`.
*
- * \param dst The destination buffer. Must not be NULL, and must not overlap with `src`.
- * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and must not overlap with `dst`.
- * \param dst_bytes The length (in bytes) of the destination buffer. Must not be 0.
+ * \param dst The destination buffer. Must not be NULL, and must not overlap
+ * with `src`.
+ * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and
+ * must not overlap with `dst`.
+ * \param dst_bytes The length (in bytes) of the destination buffer. Must not
+ * be 0.
* \returns The number of bytes written, excluding the null terminator.
*
* \threadsafety It is safe to call this function from any thread.
@@ -1552,17 +1584,22 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char
/**
* Concatenate strings.
*
- * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from `src`
- * to the end of the string in `dst`, then appends a null terminator.
+ * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from
+ * `src` to the end of the string in `dst`, then appends a null terminator.
*
* `src` and `dst` must not overlap.
*
- * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is unmodified.
+ * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is
+ * unmodified.
*
- * \param dst The destination buffer already containing the first null-terminated string. Must not be NULL and must not overlap with `src`.
- * \param src The second null-terminated string. Must not be NULL, and must not overlap with `dst`.
+ * \param dst The destination buffer already containing the first
+ * null-terminated string. Must not be NULL and must not overlap
+ * with `src`.
+ * \param src The second null-terminated string. Must not be NULL, and must
+ * not overlap with `dst`.
* \param maxlen The length (in characters) of the destination buffer.
- * \returns The length (in characters, excluding the null terminator) of the string in `dst` plus the length of `src`.
+ * \returns The length (in characters, excluding the null terminator) of the
+ * string in `dst` plus the length of `src`.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1637,7 +1674,8 @@ 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)`.
+ * 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`.
@@ -1659,7 +1697,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str);
/**
* Parse a `double` from a string.
*
- * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str, NULL)`.
+ * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str,
+ * NULL)`.
*
* \param str The null-terminated string to read. Must not be NULL.
* \returns The parsed `double`.
@@ -1682,14 +1721,18 @@ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str);
*
* 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`.
+ * - 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`.
*
* \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.
+ * \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`.
*
* \threadsafety It is safe to call this function from any thread.
@@ -1712,14 +1755,18 @@ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int ba
*
* 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`.
+ * - 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`.
*
* \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.
+ * \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`.
*
* \threadsafety It is safe to call this function from any thread.
@@ -1741,16 +1788,21 @@ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **en
*
* 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`.
+ * - 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`.
+ * Also note that unlike the C runtime `strtoll`, this function returns an
+ * Sint64, not a `long long`.
*
* \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.
+ * \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 Sint64.
*
* \threadsafety It is safe to call this function from any thread.
@@ -1772,16 +1824,21 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_strtoll(const char *str, char **endp, int
*
* 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`.
+ * - 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`.
+ * Also note that unlike the C runtime `strtoull`, this function returns a
+ * Uint64, not an `unsigned long long`.
*
* \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.
+ * \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 Uint64.
*
* \threadsafety It is safe to call this function from any thread.
@@ -1803,14 +1860,15 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_strtoull(const char *str, char **endp, in
*
* 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.
+ * - 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.
*
* \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 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`.
*
* \threadsafety It is safe to call this function from any thread.
@@ -1948,9 +2006,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *st
* Searches a string for the first occurence of any character contained in a
* breakset, and returns a pointer from the string to that character.
*
- * \param str The null-terminated string to be searched. Must not be NULL, and must not overlap with `breakset`.
+ * \param str The null-terminated string to be searched. Must not be NULL, and
+ * must not overlap with `breakset`.
* \param breakset A null-terminated string containing the list of characters
- * to look for. Must not be NULL, and must not overlap with `str`.
+ * to look for. Must not be NULL, and must not overlap with
+ * `str`.
* \returns A pointer to the location, in str, of the first occurence of a
* character present in the breakset, or NULL if none is found.
*