From b815123cf2ba49d69f0a6d5f75eade6a2b1a9d1c Mon Sep 17 00:00:00 2001 From: SDL Wiki Bot 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 46aeea8519..55b4b12400 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.