From b815123cf2ba49d69f0a6d5f75eade6a2b1a9d1c Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Fri, 20 Dec 2024 07:48:16 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
[ci skip]
---
include/SDL3/SDL_stdinc.h | 203 +++++++++++++++++++++-----------------
1 file changed, 111 insertions(+), 92 deletions(-)
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index 46aeea85199d6..55b4b1240034a 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -89,14 +89,15 @@ void *alloca(size_t);
#endif
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
/**
* The largest value that a `size_t` can hold for the target platform.
*
* `size_t` is generally the same size as a pointer in modern times, but this
- * can get weird on very old and very esoteric machines. For example, on
- * a 16-bit Intel 286, you might have a 32-bit "far" pointer (16-bit segment
- * plus 16-bit offset), but `size_t` is 16 bits, because it can only deal
- * with the offset into an individual segment.
+ * can get weird on very old and very esoteric machines. For example, on a
+ * 16-bit Intel 286, you might have a 32-bit "far" pointer (16-bit segment
+ * plus 16-bit offset), but `size_t` is 16 bits, because it can only deal with
+ * the offset into an individual segment.
*
* In modern times, it's generally expected to cover an entire linear address
* space. But be careful!
@@ -480,6 +481,7 @@ typedef Sint64 SDL_Time;
/* @} *//* Floating-point constants */
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
/**
* A printf-formatting string for an Sint64 value.
*
@@ -587,8 +589,8 @@ typedef Sint64 SDL_Time;
/**
* A printf-formatting string prefix for a `long long` value.
*
- * This is just the prefix! You probably actually want SDL_PRILLd,
- * SDL_PRILLu, SDL_PRILLx, or SDL_PRILLX instead.
+ * This is just the prefix! You probably actually want SDL_PRILLd, SDL_PRILLu,
+ * SDL_PRILLx, or SDL_PRILLX instead.
*
* Use it like this:
*
@@ -627,7 +629,8 @@ typedef Sint64 SDL_Time;
#define SDL_PRILLu SDL_PRILL_PREFIX "u"
/**
- * A printf-formatting string for an `unsigned long long` value as lower-case hexadecimal.
+ * A printf-formatting string for an `unsigned long long` value as lower-case
+ * hexadecimal.
*
* Use it like this:
*
@@ -640,7 +643,8 @@ typedef Sint64 SDL_Time;
#define SDL_PRILLx SDL_PRILL_PREFIX "x"
/**
- * A printf-formatting string for an `unsigned long long` value as upper-case hexadecimal.
+ * A printf-formatting string for an `unsigned long long` value as upper-case
+ * hexadecimal.
*
* Use it like this:
*
@@ -899,18 +903,19 @@ extern "C" {
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
/**
* Allocate memory on the stack (maybe).
*
- * If SDL knows how to access alloca() on the current platform, it will use
- * it to stack-allocate memory here. If it doesn't, it will use SDL_malloc()
- * to heap-allocate memory.
+ * If SDL knows how to access alloca() on the current platform, it will use it
+ * to stack-allocate memory here. If it doesn't, it will use SDL_malloc() to
+ * heap-allocate memory.
*
- * Since this might not be stack memory at all, it's important that you
- * check the returned pointer for NULL, and that you call SDL_stack_free
- * on the memory when done with it. Since this might be stack memory, it's
- * important that you don't allocate large amounts of it, or allocate in
- * a loop without returning from the function, so the stack doesn't overflow.
+ * Since this might not be stack memory at all, it's important that you check
+ * the returned pointer for NULL, and that you call SDL_stack_free on the
+ * memory when done with it. Since this might be stack memory, it's important
+ * that you don't allocate large amounts of it, or allocate in a loop without
+ * returning from the function, so the stack doesn't overflow.
*
* \param type the datatype of the memory to allocate.
* \param count the number of `type` objects to allocate.
@@ -1740,9 +1745,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x);
* Return the lesser of two values.
*
* This is a helper macro that might be more clear than writing out the
- * comparisons directly, and works with any type that can be compared with
- * the `<` operator. However, it double-evaluates both its parameters, so do
- * not use expressions with side-effects here.
+ * comparisons directly, and works with any type that can be compared with the
+ * `<` operator. However, it double-evaluates both its parameters, so do not
+ * use expressions with side-effects here.
*
* \param x the first value to compare.
* \param y the second value to compare.
@@ -1758,9 +1763,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x);
* Return the greater of two values.
*
* This is a helper macro that might be more clear than writing out the
- * comparisons directly, and works with any type that can be compared with
- * the `>` operator. However, it double-evaluates both its parameters, so do
- * not use expressions with side-effects here.
+ * comparisons directly, and works with any type that can be compared with the
+ * `>` operator. However, it double-evaluates both its parameters, so do not
+ * use expressions with side-effects here.
*
* \param x the first value to compare.
* \param y the second value to compare.
@@ -1781,9 +1786,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x);
* This macro will produce incorrect results if `b` is less than `a`.
*
* This is a helper macro that might be more clear than writing out the
- * comparisons directly, and works with any type that can be compared with
- * the `<` and `>` operators. However, it double-evaluates all its parameters,
- * so do not use expressions with side-effects here.
+ * comparisons directly, and works with any type that can be compared with the
+ * `<` and `>` operators. However, it double-evaluates all its parameters, so
+ * do not use expressions with side-effects here.
*
* \param x the value to compare.
* \param a the low end value.
@@ -2085,9 +2090,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_
* calculate a hash in chunks; it won't produce the same hash as it would if
* the same data was provided in a single call.
*
- * If you aren't sure what to provide for a seed, zero is fine. Murmur3 is
- * not cryptographically secure, so it shouldn't be used for hashing
- * top-secret data.
+ * If you aren't sure what to provide for a seed, zero is fine. Murmur3 is not
+ * cryptographically secure, so it shouldn't be used for hashing top-secret
+ * data.
*
* \param data the data to be hashed.
* \param len the size of data, in bytes.
@@ -2133,10 +2138,10 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SD
* A macro to copy memory between objects, with basic type checking.
*
* SDL_memcpy and SDL_memmove do not care where you copy memory to and from,
- * which can lead to bugs. This macro aims to avoid most of those bugs
- * by making sure that the source and destination are both pointers to
- * objects that are the same size. It does not check that the objects are
- * the same _type_, just that the copy will not overflow either object.
+ * which can lead to bugs. This macro aims to avoid most of those bugs by
+ * making sure that the source and destination are both pointers to objects
+ * that are the same size. It does not check that the objects are the same
+ * _type_, just that the copy will not overflow either object.
*
* The size check happens at compile time, and the compiler will throw an
* error if the objects are different sizes.
@@ -2273,8 +2278,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwo
/**
* Clear an array's memory to zero.
*
- * This is wrapper over SDL_memset that handles calculating the array size,
- * so there's no chance of copy/paste errors, and the code is cleaner.
+ * This is wrapper over SDL_memset that handles calculating the array size, so
+ * there's no chance of copy/paste errors, and the code is cleaner.
*
* This requires an array, not an object, nor a pointer to an object.
*
@@ -2690,7 +2695,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strlwr(char *str);
*
* \param str the string to search. Must not be NULL.
* \param c the byte value to search for.
- * \returns a pointer to the first instance of `c` in the string, or NULL if not found.
+ * \returns a pointer to the first instance of `c` in the string, or NULL if
+ * not found.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -2708,7 +2714,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strchr(const char *str, int c);
*
* \param str the string to search. Must not be NULL.
* \param c the byte value to search for.
- * \returns a pointer to the last instance of `c` in the string, or NULL if not found.
+ * \returns a pointer to the last instance of `c` in the string, or NULL if
+ * not found.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -2719,15 +2726,16 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c);
/**
* Search a string for the first instance of a specific substring.
*
- * The search ends once it finds the requested substring, or a null
- * terminator byte to end the string.
+ * The search ends once it finds the requested substring, or a null terminator
+ * byte to end the string.
*
* Note that this looks for strings of _bytes_, not _characters_, so it's
* legal to search for malformed and incomplete UTF-8 sequences.
*
* \param haystack the string to search. Must not be NULL.
* \param needle the string to search for. Must not be NULL.
- * \returns a pointer to the first instance of `needle` in the string, or NULL if not found.
+ * \returns a pointer to the first instance of `needle` in the string, or NULL
+ * if not found.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -2736,11 +2744,12 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c);
extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *needle);
/**
- * Search a string, up to n bytes, for the first instance of a specific substring.
+ * Search a string, up to n bytes, for the first instance of a specific
+ * substring.
*
- * The search ends once it finds the requested substring, or a null
- * terminator byte to end the string, or `maxlen` bytes have been examined.
- * It is possible to use this function on a string without a null terminator.
+ * The search ends once it finds the requested substring, or a null terminator
+ * byte to end the string, or `maxlen` bytes have been examined. It is
+ * possible to use this function on a string without a null terminator.
*
* Note that this looks for strings of _bytes_, not _characters_, so it's
* legal to search for malformed and incomplete UTF-8 sequences.
@@ -2748,7 +2757,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *
* \param haystack the string to search. Must not be NULL.
* \param needle the string to search for. Must not be NULL.
* \param maxlen the maximum number of bytes to search in `haystack`.
- * \returns a pointer to the first instance of `needle` in the string, or NULL if not found.
+ * \returns a pointer to the first instance of `needle` in the string, or NULL
+ * if not found.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -2757,7 +2767,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *
extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen);
/**
- * Search a UTF-8 string for the first instance of a specific substring, case-insensitively.
+ * Search a UTF-8 string for the first instance of a specific substring,
+ * case-insensitively.
*
* This will work with Unicode strings, using a technique called
* "case-folding" to handle the vast majority of case-sensitive human
@@ -2774,7 +2785,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char
*
* \param haystack the string to search. Must not be NULL.
* \param needle the string to search for. Must not be NULL.
- * \returns a pointer to the first instance of `needle` in the string, or NULL if not found.
+ * \returns a pointer to the first instance of `needle` in the string, or NULL
+ * if not found.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -2783,21 +2795,22 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char
extern SDL_DECLSPEC char * SDLCALL SDL_strcasestr(const char *haystack, const char *needle);
/**
- * This works exactly like strtok_r() but doesn't require access to a C runtime.
+ * This works exactly like strtok_r() but doesn't require access to a C
+ * runtime.
*
* Break a string up into a series of tokens.
*
* To start tokenizing a new string, `str` should be the non-NULL address of
- * the string to start tokenizing. Future calls to get the next token from
- * the same string should specify a NULL.
+ * the string to start tokenizing. Future calls to get the next token from the
+ * same string should specify a NULL.
*
* Note that this function will overwrite pieces of `str` with null chars to
* split it into tokens. This function cannot be used with const/read-only
* strings!
*
* `saveptr` just needs to point to a `char *` that can be overwritten; SDL
- * will use this to save tokenizing state between calls. It is initialized
- * if `str` is non-NULL, and used to resume tokenizing when `str` is NULL.
+ * will use this to save tokenizing state between calls. It is initialized if
+ * `str` is non-NULL, and used to resume tokenizing when `str` is NULL.
*
* \param str the string to tokenize, or NULL to continue tokenizing.
* \param delim the delimiter string that separates tokens.
@@ -2813,10 +2826,12 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *str, const char *delim, ch
/**
* Count the number of codepoints in a UTF-8 string.
*
- * Counts the _codepoints_, not _bytes_, in `str`, excluding the null terminator.
+ * Counts the _codepoints_, not _bytes_, in `str`, excluding the null
+ * terminator.
+ *
+ * If you need to count the bytes in a string instead, consider using
+ * SDL_strlen().
*
- * If you need to count the bytes in a string instead, consider using SDL_strlen().
-
* Since this handles Unicode, it expects the strings to be well-formed UTF-8
* and not a null-terminated string of arbitrary bytes. Bytes that are not
* valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT
@@ -2824,7 +2839,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *str, const char *delim, ch
* count by several replacement characters.
*
* \param str The null-terminated UTF-8 string to read. Must not be NULL.
- * \returns The length (in codepoints, excluding the null terminator) of `src`.
+ * \returns The length (in codepoints, excluding the null terminator) of
+ * `src`.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -2838,9 +2854,11 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str);
/**
* Count the number of codepoints in a UTF-8 string, up to n bytes.
*
- * Counts the _codepoints_, not _bytes_, in `str`, excluding the null terminator.
+ * Counts the _codepoints_, not _bytes_, in `str`, excluding the null
+ * terminator.
*
- * If you need to count the bytes in a string instead, consider using SDL_strnlen().
+ * If you need to count the bytes in a string instead, consider using
+ * SDL_strnlen().
*
* The counting stops at `bytes` bytes (not codepoints!). This seems
* counterintuitive, but makes it easy to express the total size of the
@@ -2854,8 +2872,8 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str);
*
* \param str The null-terminated UTF-8 string to read. Must not be NULL.
* \param bytes The maximum amount of bytes to count.
- * \returns The length (in codepoints, excluding the null terminator) of `src` but
- * never more than `maxlen`.
+ * \returns The length (in codepoints, excluding the null terminator) of `src`
+ * but never more than `maxlen`.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -2874,10 +2892,10 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes
* to 36.
*
* Note that this function will overflow a buffer if `str` is not large enough
- * to hold the output! It may be safer to use SDL_snprintf to clamp output,
- * or SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to
- * allocate much more space than you expect to use (and don't forget possible
- * negative signs, null terminator bytes, etc).
+ * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
+ * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
+ * much more space than you expect to use (and don't forget possible negative
+ * signs, null terminator bytes, etc).
*
* \param value the integer to convert.
* \param str the buffer to write the string into.
@@ -2902,10 +2920,10 @@ extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix);
* to 36.
*
* Note that this function will overflow a buffer if `str` is not large enough
- * to hold the output! It may be safer to use SDL_snprintf to clamp output,
- * or SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to
- * allocate much more space than you expect to use (and don't forget null
- * terminator bytes, etc).
+ * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
+ * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
+ * much more space than you expect to use (and don't forget null terminator
+ * bytes, etc).
*
* \param value the unsigned integer to convert.
* \param str the buffer to write the string into.
@@ -2930,10 +2948,10 @@ extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int
* to 36.
*
* Note that this function will overflow a buffer if `str` is not large enough
- * to hold the output! It may be safer to use SDL_snprintf to clamp output,
- * or SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to
- * allocate much more space than you expect to use (and don't forget possible
- * negative signs, null terminator bytes, etc).
+ * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
+ * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
+ * much more space than you expect to use (and don't forget possible negative
+ * signs, null terminator bytes, etc).
*
* \param value the long integer to convert.
* \param str the buffer to write the string into.
@@ -2958,10 +2976,10 @@ extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix);
* to 36.
*
* Note that this function will overflow a buffer if `str` is not large enough
- * to hold the output! It may be safer to use SDL_snprintf to clamp output,
- * or SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to
- * allocate much more space than you expect to use (and don't forget null
- * terminator bytes, etc).
+ * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
+ * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
+ * much more space than you expect to use (and don't forget null terminator
+ * bytes, etc).
*
* \param value the unsigned long integer to convert.
* \param str the buffer to write the string into.
@@ -2986,10 +3004,10 @@ extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int
* to 36.
*
* Note that this function will overflow a buffer if `str` is not large enough
- * to hold the output! It may be safer to use SDL_snprintf to clamp output,
- * or SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to
- * allocate much more space than you expect to use (and don't forget possible
- * negative signs, null terminator bytes, etc).
+ * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
+ * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
+ * much more space than you expect to use (and don't forget possible negative
+ * signs, null terminator bytes, etc).
*
* \param value the long long integer to convert.
* \param str the buffer to write the string into.
@@ -3014,10 +3032,10 @@ extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(long long value, char *str, int rad
* to 36.
*
* Note that this function will overflow a buffer if `str` is not large enough
- * to hold the output! It may be safer to use SDL_snprintf to clamp output,
- * or SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to
- * allocate much more space than you expect to use (and don't forget null
- * terminator bytes, etc).
+ * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
+ * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
+ * much more space than you expect to use (and don't forget null terminator
+ * bytes, etc).
*
* \param value the unsigned long long integer to convert.
* \param str the buffer to write the string into.
@@ -5091,7 +5109,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd);
* - inbytesleft will be set to the number of bytes left to convert, which
* will be 0 on success.
* - outbuf will point to the location where to store the next output byte.
- * - outbytesleft will be set to the number of bytes left in the output buffer.
+ * - outbytesleft will be set to the number of bytes left in the output
+ * buffer.
*
* \param cd The character set conversion context, created in
* SDL_iconv_open().
@@ -5154,8 +5173,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode,
* Convert a UTF-8 string to the current locale's character encoding.
*
* This is a helper macro that might be more clear than calling
- * SDL_iconv_string directly. However, it double-evaluates its parameter,
- * so do not use an expression with side-effects here.
+ * SDL_iconv_string directly. However, it double-evaluates its parameter, so
+ * do not use an expression with side-effects here.
*
* \param S the string to convert.
* \returns a new string, converted to the new encoding, or NULL on error.
@@ -5168,8 +5187,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode,
* Convert a UTF-8 string to UCS-2.
*
* This is a helper macro that might be more clear than calling
- * SDL_iconv_string directly. However, it double-evaluates its parameter,
- * so do not use an expression with side-effects here.
+ * SDL_iconv_string directly. However, it double-evaluates its parameter, so
+ * do not use an expression with side-effects here.
*
* \param S the string to convert.
* \returns a new string, converted to the new encoding, or NULL on error.
@@ -5182,8 +5201,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode,
* Convert a UTF-8 string to UCS-4.
*
* This is a helper macro that might be more clear than calling
- * SDL_iconv_string directly. However, it double-evaluates its parameter,
- * so do not use an expression with side-effects here.
+ * SDL_iconv_string directly. However, it double-evaluates its parameter, so
+ * do not use an expression with side-effects here.
*
* \param S the string to convert.
* \returns a new string, converted to the new encoding, or NULL on error.
@@ -5196,8 +5215,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode,
* Convert a wchar_t string to UTF-8.
*
* This is a helper macro that might be more clear than calling
- * SDL_iconv_string directly. However, it double-evaluates its parameter,
- * so do not use an expression with side-effects here.
+ * SDL_iconv_string directly. However, it double-evaluates its parameter, so
+ * do not use an expression with side-effects here.
*
* \param S the string to convert.
* \returns a new string, converted to the new encoding, or NULL on error.