SDL 3.0
SDL_stdinc.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * # CategoryStdinc
24 *
25 * This is a general header that includes C language support. It implements a
26 * subset of the C runtime APIs, but with an `SDL_` prefix. For most common
27 * use cases, these should behave the same way as their C runtime equivalents,
28 * but they may differ in how or whether they handle certain edge cases. When
29 * in doubt, consult the documentation for details.
30 */
31
32#ifndef SDL_stdinc_h_
33#define SDL_stdinc_h_
34
36
37#include <stdarg.h>
38#include <stdint.h>
39#include <string.h>
40#include <wchar.h>
41
42#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \
43 defined(SDL_INCLUDE_INTTYPES_H)
44#include <inttypes.h>
45#endif
46
47#ifndef __cplusplus
48#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \
49 (defined(_MSC_VER) && (_MSC_VER >= 1910 /* Visual Studio 2017 */)) || \
50 defined(SDL_INCLUDE_STDBOOL_H)
51#include <stdbool.h>
52#elif !defined(__bool_true_false_are_defined) && !defined(bool)
53#define bool unsigned char
54#define false 0
55#define true 1
56#define __bool_true_false_are_defined 1
57#endif
58#endif /* !__cplusplus */
59
60#ifndef SDL_DISABLE_ALLOCA
61# ifndef alloca
62# ifdef HAVE_ALLOCA_H
63# include <alloca.h>
64# elif defined(SDL_PLATFORM_NETBSD)
65# if defined(__STRICT_ANSI__)
66# define SDL_DISABLE_ALLOCA
67# else
68# include <stdlib.h>
69# endif
70# elif defined(__GNUC__)
71# define alloca __builtin_alloca
72# elif defined(_MSC_VER)
73# include <malloc.h>
74# define alloca _alloca
75# elif defined(__WATCOMC__)
76# include <malloc.h>
77# elif defined(__BORLANDC__)
78# include <malloc.h>
79# elif defined(__DMC__)
80# include <stdlib.h>
81# elif defined(SDL_PLATFORM_AIX)
82# pragma alloca
83# elif defined(__MRC__)
84void *alloca(unsigned);
85# else
86void *alloca(size_t);
87# endif
88# endif
89#endif
90
91#ifdef SIZE_MAX
92# define SDL_SIZE_MAX SIZE_MAX
93#else
94# define SDL_SIZE_MAX ((size_t) -1)
95#endif
96
97#ifndef SDL_COMPILE_TIME_ASSERT
98#if defined(__cplusplus)
99/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */
100#if (__cplusplus >= 201103L)
101#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x)
102#endif
103#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L)
104#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x)
105#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L)
106#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x)
107#endif
108#endif /* !SDL_COMPILE_TIME_ASSERT */
109
110#ifndef SDL_COMPILE_TIME_ASSERT
111/* universal, but may trigger -Wunused-local-typedefs */
112#define SDL_COMPILE_TIME_ASSERT(name, x) \
113 typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1]
114#endif
115
116/**
117 * Check if the compiler supports a given builtin.
118 * Supported by virtually all clang versions and recent gcc. Use this
119 * instead of checking the clang version if possible.
120 */
121#ifdef __has_builtin
122#define SDL_HAS_BUILTIN(x) __has_builtin(x)
123#else
124#define SDL_HAS_BUILTIN(x) 0
125#endif
126
127/**
128 * The number of elements in an array.
129 *
130 * This macro looks like it double-evaluates the argument, but it does so
131 * inside of `sizeof`, so there are no side-effects here, as expressions do
132 * not actually run any code in these cases.
133 *
134 * \since This macro is available since SDL 3.0.0.
135 */
136#define SDL_arraysize(array) (sizeof(array)/sizeof(array[0]))
137
138/**
139 * Macro useful for building other macros with strings in them.
140 *
141 * For example:
142 *
143 * ```c
144 * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")`
145 * ```
146 *
147 * \since This macro is available since SDL 3.0.0.
148 */
149#define SDL_STRINGIFY_ARG(arg) #arg
150
151/**
152 * \name Cast operators
153 *
154 * Use proper C++ casts when compiled as C++ to be compatible with the option
155 * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above).
156 */
157/* @{ */
158
159#ifdef SDL_WIKI_DOCUMENTATION_SECTION
160
161/**
162 * Handle a Reinterpret Cast properly whether using C or C++.
163 *
164 * If compiled as C++, this macro offers a proper C++ reinterpret_cast<>.
165 *
166 * If compiled as C, this macro does a normal C-style cast.
167 *
168 * This is helpful to avoid compiler warnings in C++.
169 *
170 * \param type the type to cast the expression to.
171 * \param expression the expression to cast to a different type.
172 * \returns `expression`, cast to `type`.
173 *
174 * \threadsafety It is safe to call this macro from any thread.
175 *
176 * \since This macro is available since SDL 3.0.0.
177 *
178 * \sa SDL_static_cast
179 * \sa SDL_const_cast
180 */
181#define SDL_reinterpret_cast(type, expression) reinterpret_cast<type>(expression) /* or `((type)(expression))` in C */
182
183/**
184 * Handle a Static Cast properly whether using C or C++.
185 *
186 * If compiled as C++, this macro offers a proper C++ static_cast<>.
187 *
188 * If compiled as C, this macro does a normal C-style cast.
189 *
190 * This is helpful to avoid compiler warnings in C++.
191 *
192 * \param type the type to cast the expression to.
193 * \param expression the expression to cast to a different type.
194 * \returns `expression`, cast to `type`.
195 *
196 * \threadsafety It is safe to call this macro from any thread.
197 *
198 * \since This macro is available since SDL 3.0.0.
199 *
200 * \sa SDL_reinterpret_cast
201 * \sa SDL_const_cast
202 */
203#define SDL_static_cast(type, expression) static_cast<type>(expression) /* or `((type)(expression))` in C */
204
205/**
206 * Handle a Const Cast properly whether using C or C++.
207 *
208 * If compiled as C++, this macro offers a proper C++ const_cast<>.
209 *
210 * If compiled as C, this macro does a normal C-style cast.
211 *
212 * This is helpful to avoid compiler warnings in C++.
213 *
214 * \param type the type to cast the expression to.
215 * \param expression the expression to cast to a different type.
216 * \returns `expression`, cast to `type`.
217 *
218 * \threadsafety It is safe to call this macro from any thread.
219 *
220 * \since This macro is available since SDL 3.0.0.
221 *
222 * \sa SDL_reinterpret_cast
223 * \sa SDL_static_cast
224 */
225#define SDL_const_cast(type, expression) const_cast<type>(expression) /* or `((type)(expression))` in C */
226
227#elif defined(__cplusplus)
228#define SDL_reinterpret_cast(type, expression) reinterpret_cast<type>(expression)
229#define SDL_static_cast(type, expression) static_cast<type>(expression)
230#define SDL_const_cast(type, expression) const_cast<type>(expression)
231#else
232#define SDL_reinterpret_cast(type, expression) ((type)(expression))
233#define SDL_static_cast(type, expression) ((type)(expression))
234#define SDL_const_cast(type, expression) ((type)(expression))
235#endif
236
237/* @} *//* Cast operators */
238
239/**
240 * Define a four character code as a Uint32.
241 *
242 * \param A the first ASCII character.
243 * \param B the second ASCII character.
244 * \param C the third ASCII character.
245 * \param D the fourth ASCII character.
246 * \returns the four characters converted into a Uint32, one character
247 * per-byte.
248 *
249 * \threadsafety It is safe to call this macro from any thread.
250 *
251 * \since This macro is available since SDL 3.0.0.
252 */
253#define SDL_FOURCC(A, B, C, D) \
254 ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \
255 (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \
256 (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (C))) << 16) | \
257 (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (D))) << 24))
258
259#ifdef SDL_WIKI_DOCUMENTATION_SECTION
260
261/**
262 * Append the 64 bit integer suffix to a signed integer literal.
263 *
264 * This helps compilers that might believe a integer literal larger than
265 * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_SINT64_C(0xFFFFFFFF1)`
266 * instead of `0xFFFFFFFF1` by itself.
267 *
268 * \since This macro is available since SDL 3.0.0.
269 *
270 * \sa SDL_UINT64_C
271 */
272#define SDL_SINT64_C(c) c ## LL /* or whatever the current compiler uses. */
273
274/**
275 * Append the 64 bit integer suffix to an unsigned integer literal.
276 *
277 * This helps compilers that might believe a integer literal larger than
278 * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_UINT64_C(0xFFFFFFFF1)`
279 * instead of `0xFFFFFFFF1` by itself.
280 *
281 * \since This macro is available since SDL 3.0.0.
282 *
283 * \sa SDL_SINT64_C
284 */
285#define SDL_UINT64_C(c) c ## ULL /* or whatever the current compiler uses. */
286
287#elif defined(INT64_C)
288#define SDL_SINT64_C(c) INT64_C(c)
289#define SDL_UINT64_C(c) UINT64_C(c)
290#elif defined(_MSC_VER)
291#define SDL_SINT64_C(c) c ## i64
292#define SDL_UINT64_C(c) c ## ui64
293#elif defined(__LP64__) || defined(_LP64)
294#define SDL_SINT64_C(c) c ## L
295#define SDL_UINT64_C(c) c ## UL
296#else
297#define SDL_SINT64_C(c) c ## LL
298#define SDL_UINT64_C(c) c ## ULL
299#endif
300
301/**
302 * \name Basic data types
303 */
304/* @{ */
305
306/**
307 * A signed 8-bit integer type.
308 *
309 * \since This macro is available since SDL 3.0.0.
310 */
311typedef int8_t Sint8;
312#define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */
313#define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */
314
315/**
316 * An unsigned 8-bit integer type.
317 *
318 * \since This macro is available since SDL 3.0.0.
319 */
320typedef uint8_t Uint8;
321#define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */
322#define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */
323
324/**
325 * A signed 16-bit integer type.
326 *
327 * \since This macro is available since SDL 3.0.0.
328 */
329typedef int16_t Sint16;
330#define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */
331#define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */
332
333/**
334 * An unsigned 16-bit integer type.
335 *
336 * \since This macro is available since SDL 3.0.0.
337 */
338typedef uint16_t Uint16;
339#define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */
340#define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */
341
342/**
343 * A signed 32-bit integer type.
344 *
345 * \since This macro is available since SDL 3.0.0.
346 */
347typedef int32_t Sint32;
348#define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */
349#define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */
350
351/**
352 * An unsigned 32-bit integer type.
353 *
354 * \since This macro is available since SDL 3.0.0.
355 */
356typedef uint32_t Uint32;
357#define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */
358#define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */
359
360/**
361 * A signed 64-bit integer type.
362 *
363 * \since This macro is available since SDL 3.0.0.
364 *
365 * \sa SDL_SINT64_C
366 */
367typedef int64_t Sint64;
368#define SDL_MAX_SINT64 SDL_SINT64_C(0x7FFFFFFFFFFFFFFF) /* 9223372036854775807 */
369#define SDL_MIN_SINT64 ~SDL_SINT64_C(0x7FFFFFFFFFFFFFFF) /* -9223372036854775808 */
370
371/**
372 * An unsigned 64-bit integer type.
373 *
374 * \since This macro is available since SDL 3.0.0.
375 *
376 * \sa SDL_UINT64_C
377 */
378typedef uint64_t Uint64;
379#define SDL_MAX_UINT64 SDL_UINT64_C(0xFFFFFFFFFFFFFFFF) /* 18446744073709551615 */
380#define SDL_MIN_UINT64 SDL_UINT64_C(0x0000000000000000) /* 0 */
381
382/**
383 * SDL times are signed, 64-bit integers representing nanoseconds since the
384 * Unix epoch (Jan 1, 1970).
385 *
386 * They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS()
387 * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with
388 * SDL_TimeToWindows() and SDL_TimeFromWindows().
389 *
390 * \since This macro is available since SDL 3.0.0.
391 *
392 * \sa SDL_MAX_SINT64
393 * \sa SDL_MIN_SINT64
394 */
396#define SDL_MAX_TIME SDL_MAX_SINT64
397#define SDL_MIN_TIME SDL_MIN_SINT64
398
399/* @} *//* Basic data types */
400
401/**
402 * \name Floating-point constants
403 */
404/* @{ */
405
406#ifdef FLT_EPSILON
407#define SDL_FLT_EPSILON FLT_EPSILON
408#else
409
410/**
411 * Epsilon constant, used for comparing floating-point numbers.
412 *
413 * Equals by default to platform-defined `FLT_EPSILON`, or
414 * `1.1920928955078125e-07F` if that's not available.
415 *
416 * \since This macro is available since SDL 3.0.0.
417 */
418#define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */
419#endif
420
421/* @} *//* Floating-point constants */
422
423/* Make sure we have macros for printing width-based integers.
424 * <inttypes.h> should define these but this is not true all platforms.
425 * (for example win32) */
426#ifndef SDL_PRIs64
427#if defined(SDL_PLATFORM_WINDOWS)
428#define SDL_PRIs64 "I64d"
429#elif defined(PRIs64)
430#define SDL_PRIs64 PRIs64
431#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE)
432#define SDL_PRIs64 "ld"
433#else
434#define SDL_PRIs64 "lld"
435#endif
436#endif
437#ifndef SDL_PRIu64
438#if defined(SDL_PLATFORM_WINDOWS)
439#define SDL_PRIu64 "I64u"
440#elif defined(PRIu64)
441#define SDL_PRIu64 PRIu64
442#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE)
443#define SDL_PRIu64 "lu"
444#else
445#define SDL_PRIu64 "llu"
446#endif
447#endif
448#ifndef SDL_PRIx64
449#if defined(SDL_PLATFORM_WINDOWS)
450#define SDL_PRIx64 "I64x"
451#elif defined(PRIx64)
452#define SDL_PRIx64 PRIx64
453#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE)
454#define SDL_PRIx64 "lx"
455#else
456#define SDL_PRIx64 "llx"
457#endif
458#endif
459#ifndef SDL_PRIX64
460#if defined(SDL_PLATFORM_WINDOWS)
461#define SDL_PRIX64 "I64X"
462#elif defined(PRIX64)
463#define SDL_PRIX64 PRIX64
464#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE)
465#define SDL_PRIX64 "lX"
466#else
467#define SDL_PRIX64 "llX"
468#endif
469#endif
470#ifndef SDL_PRIs32
471#ifdef PRId32
472#define SDL_PRIs32 PRId32
473#else
474#define SDL_PRIs32 "d"
475#endif
476#endif
477#ifndef SDL_PRIu32
478#ifdef PRIu32
479#define SDL_PRIu32 PRIu32
480#else
481#define SDL_PRIu32 "u"
482#endif
483#endif
484#ifndef SDL_PRIx32
485#ifdef PRIx32
486#define SDL_PRIx32 PRIx32
487#else
488#define SDL_PRIx32 "x"
489#endif
490#endif
491#ifndef SDL_PRIX32
492#ifdef PRIX32
493#define SDL_PRIX32 PRIX32
494#else
495#define SDL_PRIX32 "X"
496#endif
497#endif
498/* Specifically for the `long long` -- SDL-specific. */
499#ifdef SDL_PLATFORM_WINDOWS
500SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 for windows - make sure `long long` is 64 bits. */
501#define SDL_PRILL_PREFIX "I64"
502#else
503#define SDL_PRILL_PREFIX "ll"
504#endif
505#ifndef SDL_PRILLd
506#define SDL_PRILLd SDL_PRILL_PREFIX "d"
507#endif
508#ifndef SDL_PRILLu
509#define SDL_PRILLu SDL_PRILL_PREFIX "u"
510#endif
511#ifndef SDL_PRILLx
512#define SDL_PRILLx SDL_PRILL_PREFIX "x"
513#endif
514#ifndef SDL_PRILLX
515#define SDL_PRILLX SDL_PRILL_PREFIX "X"
516#endif
517
518/* Annotations to help code analysis tools */
519#ifdef SDL_DISABLE_ANALYZE_MACROS
520#define SDL_IN_BYTECAP(x)
521#define SDL_INOUT_Z_CAP(x)
522#define SDL_OUT_Z_CAP(x)
523#define SDL_OUT_CAP(x)
524#define SDL_OUT_BYTECAP(x)
525#define SDL_OUT_Z_BYTECAP(x)
526#define SDL_PRINTF_FORMAT_STRING
527#define SDL_SCANF_FORMAT_STRING
528#define SDL_PRINTF_VARARG_FUNC( fmtargnumber )
529#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber )
530#define SDL_SCANF_VARARG_FUNC( fmtargnumber )
531#define SDL_SCANF_VARARG_FUNCV( fmtargnumber )
532#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber )
533#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber )
534#else
535#if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */
536#include <sal.h>
537
538#define SDL_IN_BYTECAP(x) _In_bytecount_(x)
539#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x)
540#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x)
541#define SDL_OUT_CAP(x) _Out_cap_(x)
542#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x)
543#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x)
544
545#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_
546#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_
547#else
548#define SDL_IN_BYTECAP(x)
549#define SDL_INOUT_Z_CAP(x)
550#define SDL_OUT_Z_CAP(x)
551#define SDL_OUT_CAP(x)
552#define SDL_OUT_BYTECAP(x)
553#define SDL_OUT_Z_BYTECAP(x)
554#define SDL_PRINTF_FORMAT_STRING
555#define SDL_SCANF_FORMAT_STRING
556#endif
557#if defined(__GNUC__) || defined(__clang__)
558#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 )))
559#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 )))
560#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 )))
561#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 )))
562#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */
563#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */
564#else
565#define SDL_PRINTF_VARARG_FUNC( fmtargnumber )
566#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber )
567#define SDL_SCANF_VARARG_FUNC( fmtargnumber )
568#define SDL_SCANF_VARARG_FUNCV( fmtargnumber )
569#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber )
570#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber )
571#endif
572#endif /* SDL_DISABLE_ANALYZE_MACROS */
573
574/** \cond */
575#ifndef DOXYGEN_SHOULD_IGNORE_THIS
576SDL_COMPILE_TIME_ASSERT(bool_size, sizeof(bool) == 1);
577SDL_COMPILE_TIME_ASSERT(uint8_size, sizeof(Uint8) == 1);
578SDL_COMPILE_TIME_ASSERT(sint8_size, sizeof(Sint8) == 1);
579SDL_COMPILE_TIME_ASSERT(uint16_size, sizeof(Uint16) == 2);
580SDL_COMPILE_TIME_ASSERT(sint16_size, sizeof(Sint16) == 2);
581SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4);
582SDL_COMPILE_TIME_ASSERT(sint32_size, sizeof(Sint32) == 4);
583SDL_COMPILE_TIME_ASSERT(uint64_size, sizeof(Uint64) == 8);
584SDL_COMPILE_TIME_ASSERT(sint64_size, sizeof(Sint64) == 8);
585SDL_COMPILE_TIME_ASSERT(uint64_longlong, sizeof(Uint64) <= sizeof(unsigned long long));
586SDL_COMPILE_TIME_ASSERT(size_t_longlong, sizeof(size_t) <= sizeof(unsigned long long));
587typedef struct SDL_alignment_test
588{
589 Uint8 a;
590 void *b;
591} SDL_alignment_test;
592SDL_COMPILE_TIME_ASSERT(struct_alignment, sizeof(SDL_alignment_test) == (2 * sizeof(void *)));
593SDL_COMPILE_TIME_ASSERT(two_s_complement, (int)~(int)0 == (int)(-1));
594#endif /* DOXYGEN_SHOULD_IGNORE_THIS */
595/** \endcond */
596
597/* Check to make sure enums are the size of ints, for structure packing.
598 For both Watcom C/C++ and Borland C/C++ the compiler option that makes
599 enums having the size of an int must be enabled.
600 This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11).
601*/
602
603/** \cond */
604#ifndef DOXYGEN_SHOULD_IGNORE_THIS
605#if !defined(SDL_PLATFORM_VITA) && !defined(SDL_PLATFORM_3DS)
606/* TODO: include/SDL_stdinc.h:390: error: size of array 'SDL_dummy_enum' is negative */
607typedef enum SDL_DUMMY_ENUM
608{
609 DUMMY_ENUM_VALUE
610} SDL_DUMMY_ENUM;
611
612SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int));
613#endif
614#endif /* DOXYGEN_SHOULD_IGNORE_THIS */
615/** \endcond */
616
617#include <SDL3/SDL_begin_code.h>
618/* Set up for C function definitions, even when using C++ */
619#ifdef __cplusplus
620extern "C" {
621#endif
622
623/**
624 * A macro to initialize an SDL interface.
625 *
626 * This macro will initialize an SDL interface structure and should be called
627 * before you fill out the fields with your implementation.
628 *
629 * You can use it like this:
630 *
631 * ```c
632 * SDL_IOStreamInterface iface;
633 *
634 * SDL_INIT_INTERFACE(&iface);
635 *
636 * // Fill in the interface function pointers with your implementation
637 * iface.seek = ...
638 *
639 * stream = SDL_OpenIO(&iface, NULL);
640 * ```
641 *
642 * If you are using designated initializers, you can use the size of the
643 * interface as the version, e.g.
644 *
645 * ```c
646 * SDL_IOStreamInterface iface = {
647 * .version = sizeof(iface),
648 * .seek = ...
649 * };
650 * stream = SDL_OpenIO(&iface, NULL);
651 * ```
652 *
653 * \threadsafety It is safe to call this macro from any thread.
654 *
655 * \since This macro is available since SDL 3.0.0.
656 *
657 * \sa SDL_IOStreamInterface
658 * \sa SDL_StorageInterface
659 * \sa SDL_VirtualJoystickDesc
660 */
661#define SDL_INIT_INTERFACE(iface) \
662 do { \
663 SDL_zerop(iface); \
664 (iface)->version = sizeof(*(iface)); \
665 } while (0)
666
667
668#ifndef SDL_DISABLE_ALLOCA
669#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count))
670#define SDL_stack_free(data)
671#else
672#define SDL_stack_alloc(type, count) (type*)SDL_malloc(sizeof(type)*(count))
673#define SDL_stack_free(data) SDL_free(data)
674#endif
675
676/**
677 * Allocate uninitialized memory.
678 *
679 * The allocated memory returned by this function must be freed with
680 * SDL_free().
681 *
682 * If `size` is 0, it will be set to 1.
683 *
684 * If you want to allocate memory aligned to a specific alignment, consider
685 * using SDL_aligned_alloc().
686 *
687 * \param size the size to allocate.
688 * \returns a pointer to the allocated memory, or NULL if allocation failed.
689 *
690 * \threadsafety It is safe to call this function from any thread.
691 *
692 * \since This function is available since SDL 3.0.0.
693 *
694 * \sa SDL_free
695 * \sa SDL_calloc
696 * \sa SDL_realloc
697 * \sa SDL_aligned_alloc
698 */
699extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size);
700
701/**
702 * Allocate a zero-initialized array.
703 *
704 * The memory returned by this function must be freed with SDL_free().
705 *
706 * If either of `nmemb` or `size` is 0, they will both be set to 1.
707 *
708 * \param nmemb the number of elements in the array.
709 * \param size the size of each element of the array.
710 * \returns a pointer to the allocated array, or NULL if allocation failed.
711 *
712 * \threadsafety It is safe to call this function from any thread.
713 *
714 * \since This function is available since SDL 3.0.0.
715 *
716 * \sa SDL_free
717 * \sa SDL_malloc
718 * \sa SDL_realloc
719 */
720extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(size_t nmemb, size_t size);
721
722/**
723 * Change the size of allocated memory.
724 *
725 * The memory returned by this function must be freed with SDL_free().
726 *
727 * If `size` is 0, it will be set to 1. Note that this is unlike some other C
728 * runtime `realloc` implementations, which may treat `realloc(mem, 0)` the
729 * same way as `free(mem)`.
730 *
731 * If `mem` is NULL, the behavior of this function is equivalent to
732 * SDL_malloc(). Otherwise, the function can have one of three possible
733 * outcomes:
734 *
735 * - If it returns the same pointer as `mem`, it means that `mem` was resized
736 * in place without freeing.
737 * - If it returns a different non-NULL pointer, it means that `mem` was freed
738 * and cannot be dereferenced anymore.
739 * - If it returns NULL (indicating failure), then `mem` will remain valid and
740 * must still be freed with SDL_free().
741 *
742 * \param mem a pointer to allocated memory to reallocate, or NULL.
743 * \param size the new size of the memory.
744 * \returns a pointer to the newly allocated memory, or NULL if allocation
745 * failed.
746 *
747 * \threadsafety It is safe to call this function from any thread.
748 *
749 * \since This function is available since SDL 3.0.0.
750 *
751 * \sa SDL_free
752 * \sa SDL_malloc
753 * \sa SDL_calloc
754 */
755extern SDL_DECLSPEC SDL_ALLOC_SIZE(2) void * SDLCALL SDL_realloc(void *mem, size_t size);
756
757/**
758 * Free allocated memory.
759 *
760 * The pointer is no longer valid after this call and cannot be dereferenced
761 * anymore.
762 *
763 * If `mem` is NULL, this function does nothing.
764 *
765 * \param mem a pointer to allocated memory, or NULL.
766 *
767 * \threadsafety It is safe to call this function from any thread.
768 *
769 * \since This function is available since SDL 3.0.0.
770 *
771 * \sa SDL_malloc
772 * \sa SDL_calloc
773 * \sa SDL_realloc
774 */
775extern SDL_DECLSPEC void SDLCALL SDL_free(void *mem);
776
777/**
778 * A callback used to implement SDL_malloc().
779 *
780 * SDL will always ensure that the passed `size` is greater than 0.
781 *
782 * \param size the size to allocate.
783 * \returns a pointer to the allocated memory, or NULL if allocation failed.
784 *
785 * \threadsafety It should be safe to call this callback from any thread.
786 *
787 * \since This datatype is available since SDL 3.0.0.
788 *
789 * \sa SDL_malloc
790 * \sa SDL_GetOriginalMemoryFunctions
791 * \sa SDL_GetMemoryFunctions
792 * \sa SDL_SetMemoryFunctions
793 */
794typedef void *(SDLCALL *SDL_malloc_func)(size_t size);
795
796/**
797 * A callback used to implement SDL_calloc().
798 *
799 * SDL will always ensure that the passed `nmemb` and `size` are both greater
800 * than 0.
801 *
802 * \param nmemb the number of elements in the array.
803 * \param size the size of each element of the array.
804 * \returns a pointer to the allocated array, or NULL if allocation failed.
805 *
806 * \threadsafety It should be safe to call this callback from any thread.
807 *
808 * \since This datatype is available since SDL 3.0.0.
809 *
810 * \sa SDL_calloc
811 * \sa SDL_GetOriginalMemoryFunctions
812 * \sa SDL_GetMemoryFunctions
813 * \sa SDL_SetMemoryFunctions
814 */
815typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size);
816
817/**
818 * A callback used to implement SDL_realloc().
819 *
820 * SDL will always ensure that the passed `size` is greater than 0.
821 *
822 * \param mem a pointer to allocated memory to reallocate, or NULL.
823 * \param size the new size of the memory.
824 * \returns a pointer to the newly allocated memory, or NULL if allocation
825 * failed.
826 *
827 * \threadsafety It should be safe to call this callback from any thread.
828 *
829 * \since This datatype is available since SDL 3.0.0.
830 *
831 * \sa SDL_realloc
832 * \sa SDL_GetOriginalMemoryFunctions
833 * \sa SDL_GetMemoryFunctions
834 * \sa SDL_SetMemoryFunctions
835 */
836typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size);
837
838/**
839 * A callback used to implement SDL_free().
840 *
841 * SDL will always ensure that the passed `mem` is a non-NULL pointer.
842 *
843 * \param mem a pointer to allocated memory.
844 *
845 * \threadsafety It should be safe to call this callback from any thread.
846 *
847 * \since This datatype is available since SDL 3.0.0.
848 *
849 * \sa SDL_free
850 * \sa SDL_GetOriginalMemoryFunctions
851 * \sa SDL_GetMemoryFunctions
852 * \sa SDL_SetMemoryFunctions
853 */
854typedef void (SDLCALL *SDL_free_func)(void *mem);
855
856/**
857 * Get the original set of SDL memory functions.
858 *
859 * This is what SDL_malloc and friends will use by default, if there has been
860 * no call to SDL_SetMemoryFunctions. This is not necessarily using the C
861 * runtime's `malloc` functions behind the scenes! Different platforms and
862 * build configurations might do any number of unexpected things.
863 *
864 * \param malloc_func filled with malloc function.
865 * \param calloc_func filled with calloc function.
866 * \param realloc_func filled with realloc function.
867 * \param free_func filled with free function.
868 *
869 * \threadsafety It is safe to call this function from any thread.
870 *
871 * \since This function is available since SDL 3.0.0.
872 */
873extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func,
874 SDL_calloc_func *calloc_func,
875 SDL_realloc_func *realloc_func,
876 SDL_free_func *free_func);
877
878/**
879 * Get the current set of SDL memory functions.
880 *
881 * \param malloc_func filled with malloc function.
882 * \param calloc_func filled with calloc function.
883 * \param realloc_func filled with realloc function.
884 * \param free_func filled with free function.
885 *
886 * \threadsafety This does not hold a lock, so do not call this in the
887 * unlikely event of a background thread calling
888 * SDL_SetMemoryFunctions simultaneously.
889 *
890 * \since This function is available since SDL 3.0.0.
891 *
892 * \sa SDL_SetMemoryFunctions
893 * \sa SDL_GetOriginalMemoryFunctions
894 */
895extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func,
896 SDL_calloc_func *calloc_func,
897 SDL_realloc_func *realloc_func,
898 SDL_free_func *free_func);
899
900/**
901 * Replace SDL's memory allocation functions with a custom set.
902 *
903 * It is not safe to call this function once any allocations have been made,
904 * as future calls to SDL_free will use the new allocator, even if they came
905 * from an SDL_malloc made with the old one!
906 *
907 * If used, usually this needs to be the first call made into the SDL library,
908 * if not the very first thing done at program startup time.
909 *
910 * \param malloc_func custom malloc function.
911 * \param calloc_func custom calloc function.
912 * \param realloc_func custom realloc function.
913 * \param free_func custom free function.
914 * \returns true on success or false on failure; call SDL_GetError() for more
915 * information.
916 *
917 * \threadsafety It is safe to call this function from any thread, but one
918 * should not replace the memory functions once any allocations
919 * are made!
920 *
921 * \since This function is available since SDL 3.0.0.
922 *
923 * \sa SDL_GetMemoryFunctions
924 * \sa SDL_GetOriginalMemoryFunctions
925 */
926extern SDL_DECLSPEC bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
927 SDL_calloc_func calloc_func,
928 SDL_realloc_func realloc_func,
929 SDL_free_func free_func);
930
931/**
932 * Allocate memory aligned to a specific alignment.
933 *
934 * The memory returned by this function must be freed with SDL_aligned_free(),
935 * _not_ SDL_free().
936 *
937 * If `alignment` is less than the size of `void *`, it will be increased to
938 * match that.
939 *
940 * The returned memory address will be a multiple of the alignment value, and
941 * the size of the memory allocated will be a multiple of the alignment value.
942 *
943 * \param alignment the alignment of the memory.
944 * \param size the size to allocate.
945 * \returns a pointer to the aligned memory, or NULL if allocation failed.
946 *
947 * \threadsafety It is safe to call this function from any thread.
948 *
949 * \since This function is available since SDL 3.0.0.
950 *
951 * \sa SDL_aligned_free
952 */
953extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_aligned_alloc(size_t alignment, size_t size);
954
955/**
956 * Free memory allocated by SDL_aligned_alloc().
957 *
958 * The pointer is no longer valid after this call and cannot be dereferenced
959 * anymore.
960 *
961 * If `mem` is NULL, this function does nothing.
962 *
963 * \param mem a pointer previously returned by SDL_aligned_alloc(), or NULL.
964 *
965 * \threadsafety It is safe to call this function from any thread.
966 *
967 * \since This function is available since SDL 3.0.0.
968 *
969 * \sa SDL_aligned_alloc
970 */
971extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem);
972
973/**
974 * Get the number of outstanding (unfreed) allocations.
975 *
976 * \returns the number of allocations.
977 *
978 * \threadsafety It is safe to call this function from any thread.
979 *
980 * \since This function is available since SDL 3.0.0.
981 */
982extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void);
983
984/**
985 * A thread-safe set of environment variables
986 *
987 * \since This struct is available since SDL 3.0.0.
988 *
989 * \sa SDL_GetEnvironment
990 * \sa SDL_CreateEnvironment
991 * \sa SDL_GetEnvironmentVariable
992 * \sa SDL_GetEnvironmentVariables
993 * \sa SDL_SetEnvironmentVariable
994 * \sa SDL_UnsetEnvironmentVariable
995 * \sa SDL_DestroyEnvironment
996 */
998
999/**
1000 * Get the process environment.
1001 *
1002 * This is initialized at application start and is not affected by setenv()
1003 * and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and
1004 * SDL_UnsetEnvironmentVariable() if you want to modify this environment, or
1005 * SDL_setenv_unsafe() or SDL_unsetenv_unsafe() if you want changes to persist
1006 * in the C runtime environment after SDL_Quit().
1007 *
1008 * \returns a pointer to the environment for the process or NULL on failure;
1009 * call SDL_GetError() for more information.
1010 *
1011 * \threadsafety It is safe to call this function from any thread.
1012 *
1013 * \since This function is available since SDL 3.0.0.
1014 *
1015 * \sa SDL_GetEnvironmentVariable
1016 * \sa SDL_GetEnvironmentVariables
1017 * \sa SDL_SetEnvironmentVariable
1018 * \sa SDL_UnsetEnvironmentVariable
1019 */
1020extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_GetEnvironment(void);
1021
1022/**
1023 * Create a set of environment variables
1024 *
1025 * \param populated true to initialize it from the C runtime environment,
1026 * false to create an empty environment.
1027 * \returns a pointer to the new environment or NULL on failure; call
1028 * SDL_GetError() for more information.
1029 *
1030 * \threadsafety If `populated` is false, it is safe to call this function
1031 * from any thread, otherwise it is safe if no other threads are
1032 * calling setenv() or unsetenv()
1033 *
1034 * \since This function is available since SDL 3.0.0.
1035 *
1036 * \sa SDL_GetEnvironmentVariable
1037 * \sa SDL_GetEnvironmentVariables
1038 * \sa SDL_SetEnvironmentVariable
1039 * \sa SDL_UnsetEnvironmentVariable
1040 * \sa SDL_DestroyEnvironment
1041 */
1042extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_CreateEnvironment(bool populated);
1043
1044/**
1045 * Get the value of a variable in the environment.
1046 *
1047 * \param env the environment to query.
1048 * \param name the name of the variable to get.
1049 * \returns a pointer to the value of the variable or NULL if it can't be
1050 * found.
1051 *
1052 * \threadsafety It is safe to call this function from any thread.
1053 *
1054 * \since This function is available since SDL 3.0.0.
1055 *
1056 * \sa SDL_GetEnvironment
1057 * \sa SDL_CreateEnvironment
1058 * \sa SDL_GetEnvironmentVariables
1059 * \sa SDL_SetEnvironmentVariable
1060 * \sa SDL_UnsetEnvironmentVariable
1061 */
1062extern SDL_DECLSPEC const char * SDLCALL SDL_GetEnvironmentVariable(SDL_Environment *env, const char *name);
1063
1064/**
1065 * Get all variables in the environment.
1066 *
1067 * \param env the environment to query.
1068 * \returns a NULL terminated array of pointers to environment variables in
1069 * the form "variable=value" or NULL on failure; call SDL_GetError()
1070 * for more information. This is a single allocation that should be
1071 * freed with SDL_free() when it is no longer needed.
1072 *
1073 * \threadsafety It is safe to call this function from any thread.
1074 *
1075 * \since This function is available since SDL 3.0.0.
1076 *
1077 * \sa SDL_GetEnvironment
1078 * \sa SDL_CreateEnvironment
1079 * \sa SDL_GetEnvironmentVariables
1080 * \sa SDL_SetEnvironmentVariable
1081 * \sa SDL_UnsetEnvironmentVariable
1082 */
1083extern SDL_DECLSPEC char ** SDLCALL SDL_GetEnvironmentVariables(SDL_Environment *env);
1084
1085/**
1086 * Set the value of a variable in the environment.
1087 *
1088 * \param env the environment to modify.
1089 * \param name the name of the variable to set.
1090 * \param value the value of the variable to set.
1091 * \param overwrite true to overwrite the variable if it exists, false to
1092 * return success without setting the variable if it already
1093 * exists.
1094 * \returns true on success or false on failure; call SDL_GetError() for more
1095 * information.
1096 *
1097 * \threadsafety It is safe to call this function from any thread.
1098 *
1099 * \since This function is available since SDL 3.0.0.
1100 *
1101 * \sa SDL_GetEnvironment
1102 * \sa SDL_CreateEnvironment
1103 * \sa SDL_GetEnvironmentVariable
1104 * \sa SDL_GetEnvironmentVariables
1105 * \sa SDL_UnsetEnvironmentVariable
1106 */
1107extern SDL_DECLSPEC bool SDLCALL SDL_SetEnvironmentVariable(SDL_Environment *env, const char *name, const char *value, bool overwrite);
1108
1109/**
1110 * Clear a variable from the environment.
1111 *
1112 * \param env the environment to modify.
1113 * \param name the name of the variable to unset.
1114 * \returns true on success or false on failure; call SDL_GetError() for more
1115 * information.
1116 *
1117 * \threadsafety It is safe to call this function from any thread.
1118 *
1119 * \since This function is available since SDL 3.0.0.
1120 *
1121 * \sa SDL_GetEnvironment
1122 * \sa SDL_CreateEnvironment
1123 * \sa SDL_GetEnvironmentVariable
1124 * \sa SDL_GetEnvironmentVariables
1125 * \sa SDL_SetEnvironmentVariable
1126 * \sa SDL_UnsetEnvironmentVariable
1127 */
1128extern SDL_DECLSPEC bool SDLCALL SDL_UnsetEnvironmentVariable(SDL_Environment *env, const char *name);
1129
1130/**
1131 * Destroy a set of environment variables.
1132 *
1133 * \param env the environment to destroy.
1134 *
1135 * \threadsafety It is safe to call this function from any thread, as long as
1136 * the environment is no longer in use.
1137 *
1138 * \since This function is available since SDL 3.0.0.
1139 *
1140 * \sa SDL_CreateEnvironment
1141 */
1142extern SDL_DECLSPEC void SDLCALL SDL_DestroyEnvironment(SDL_Environment *env);
1143
1144/**
1145 * Get the value of a variable in the environment.
1146 *
1147 * This function uses SDL's cached copy of the environment and is thread-safe.
1148 *
1149 * \param name the name of the variable to get.
1150 * \returns a pointer to the value of the variable or NULL if it can't be
1151 * found.
1152 *
1153 * \threadsafety It is safe to call this function from any thread.
1154 *
1155 * \since This function is available since SDL 3.0.0.
1156 */
1157extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name);
1158
1159/**
1160 * Get the value of a variable in the environment.
1161 *
1162 * This function bypasses SDL's cached copy of the environment and is not
1163 * thread-safe.
1164 *
1165 * \param name the name of the variable to get.
1166 * \returns a pointer to the value of the variable or NULL if it can't be
1167 * found.
1168 *
1169 * \threadsafety This function is not thread safe, consider using SDL_getenv()
1170 * instead.
1171 *
1172 * \since This function is available since SDL 3.0.0.
1173 *
1174 * \sa SDL_getenv
1175 */
1176extern SDL_DECLSPEC const char * SDLCALL SDL_getenv_unsafe(const char *name);
1177
1178/**
1179 * Set the value of a variable in the environment.
1180 *
1181 * \param name the name of the variable to set.
1182 * \param value the value of the variable to set.
1183 * \param overwrite 1 to overwrite the variable if it exists, 0 to return
1184 * success without setting the variable if it already exists.
1185 * \returns 0 on success, -1 on error.
1186 *
1187 * \threadsafety This function is not thread safe, consider using
1188 * SDL_SetEnvironmentVariable() instead.
1189 *
1190 * \since This function is available since SDL 3.0.0.
1191 *
1192 * \sa SDL_SetEnvironmentVariable
1193 */
1194extern SDL_DECLSPEC int SDLCALL SDL_setenv_unsafe(const char *name, const char *value, int overwrite);
1195
1196/**
1197 * Clear a variable from the environment.
1198 *
1199 * \param name the name of the variable to unset.
1200 * \returns 0 on success, -1 on error.
1201 *
1202 * \threadsafety This function is not thread safe, consider using
1203 * SDL_UnsetEnvironmentVariable() instead.
1204 *
1205 * \since This function is available since SDL 3.0.0.
1206 *
1207 * \sa SDL_UnsetEnvironmentVariable
1208 */
1209extern SDL_DECLSPEC int SDLCALL SDL_unsetenv_unsafe(const char *name);
1210
1211/**
1212 * A callback used with SDL sorting and binary search functions.
1213 *
1214 * \param a a pointer to the first element being compared.
1215 * \param b a pointer to the second element being compared.
1216 * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted
1217 * before `a`, 0 if they are equal. If two elements are equal, their
1218 * order in the sorted array is undefined.
1219 *
1220 * \since This callback is available since SDL 3.0.0.
1221 *
1222 * \sa SDL_bsearch
1223 * \sa SDL_qsort
1224 */
1225typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b);
1226
1227/**
1228 * Sort an array.
1229 *
1230 * For example:
1231 *
1232 * ```c
1233 * typedef struct {
1234 * int key;
1235 * const char *string;
1236 * } data;
1237 *
1238 * int SDLCALL compare(const void *a, const void *b)
1239 * {
1240 * const data *A = (const data *)a;
1241 * const data *B = (const data *)b;
1242 *
1243 * if (A->n < B->n) {
1244 * return -1;
1245 * } else if (B->n < A->n) {
1246 * return 1;
1247 * } else {
1248 * return 0;
1249 * }
1250 * }
1251 *
1252 * data values[] = {
1253 * { 3, "third" }, { 1, "first" }, { 2, "second" }
1254 * };
1255 *
1256 * SDL_qsort(values, SDL_arraysize(values), sizeof(values[0]), compare);
1257 * ```
1258 *
1259 * \param base a pointer to the start of the array.
1260 * \param nmemb the number of elements in the array.
1261 * \param size the size of the elements in the array.
1262 * \param compare a function used to compare elements in the array.
1263 *
1264 * \since This function is available since SDL 3.0.0.
1265 *
1266 * \sa SDL_bsearch
1267 * \sa SDL_qsort_r
1268 */
1269extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare);
1270
1271/**
1272 * Perform a binary search on a previously sorted array.
1273 *
1274 * For example:
1275 *
1276 * ```c
1277 * typedef struct {
1278 * int key;
1279 * const char *string;
1280 * } data;
1281 *
1282 * int SDLCALL compare(const void *a, const void *b)
1283 * {
1284 * const data *A = (const data *)a;
1285 * const data *B = (const data *)b;
1286 *
1287 * if (A->n < B->n) {
1288 * return -1;
1289 * } else if (B->n < A->n) {
1290 * return 1;
1291 * } else {
1292 * return 0;
1293 * }
1294 * }
1295 *
1296 * data values[] = {
1297 * { 1, "first" }, { 2, "second" }, { 3, "third" }
1298 * };
1299 * data key = { 2, NULL };
1300 *
1301 * data *result = SDL_bsearch(&key, values, SDL_arraysize(values), sizeof(values[0]), compare);
1302 * ```
1303 *
1304 * \param key a pointer to a key equal to the element being searched for.
1305 * \param base a pointer to the start of the array.
1306 * \param nmemb the number of elements in the array.
1307 * \param size the size of the elements in the array.
1308 * \param compare a function used to compare elements in the array.
1309 * \returns a pointer to the matching element in the array, or NULL if not
1310 * found.
1311 *
1312 * \since This function is available since SDL 3.0.0.
1313 *
1314 * \sa SDL_bsearch_r
1315 * \sa SDL_qsort
1316 */
1317extern SDL_DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare);
1318
1319/**
1320 * A callback used with SDL sorting and binary search functions.
1321 *
1322 * \param userdata the `userdata` pointer passed to the sort function.
1323 * \param a a pointer to the first element being compared.
1324 * \param b a pointer to the second element being compared.
1325 * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted
1326 * before `a`, 0 if they are equal. If two elements are equal, their
1327 * order in the sorted array is undefined.
1328 *
1329 * \since This callback is available since SDL 3.0.0.
1330 *
1331 * \sa SDL_qsort_r
1332 * \sa SDL_bsearch_r
1333 */
1334typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, const void *b);
1335
1336/**
1337 * Sort an array, passing a userdata pointer to the compare function.
1338 *
1339 * For example:
1340 *
1341 * ```c
1342 * typedef enum {
1343 * sort_increasing,
1344 * sort_decreasing,
1345 * } sort_method;
1346 *
1347 * typedef struct {
1348 * int key;
1349 * const char *string;
1350 * } data;
1351 *
1352 * int SDLCALL compare(const void *userdata, const void *a, const void *b)
1353 * {
1354 * sort_method method = (sort_method)(uintptr_t)userdata;
1355 * const data *A = (const data *)a;
1356 * const data *B = (const data *)b;
1357 *
1358 * if (A->n < B->n) {
1359 * return (method == sort_increasing) ? -1 : 1;
1360 * } else if (B->n < A->n) {
1361 * return (method == sort_increasing) ? 1 : -1;
1362 * } else {
1363 * return 0;
1364 * }
1365 * }
1366 *
1367 * data values[] = {
1368 * { 3, "third" }, { 1, "first" }, { 2, "second" }
1369 * };
1370 *
1371 * SDL_qsort_r(values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing);
1372 * ```
1373 *
1374 * \param base a pointer to the start of the array.
1375 * \param nmemb the number of elements in the array.
1376 * \param size the size of the elements in the array.
1377 * \param compare a function used to compare elements in the array.
1378 * \param userdata a pointer to pass to the compare function.
1379 *
1380 * \since This function is available since SDL 3.0.0.
1381 *
1382 * \sa SDL_bsearch_r
1383 * \sa SDL_qsort
1384 */
1385extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata);
1386
1387/**
1388 * Perform a binary search on a previously sorted array, passing a userdata
1389 * pointer to the compare function.
1390 *
1391 * For example:
1392 *
1393 * ```c
1394 * typedef enum {
1395 * sort_increasing,
1396 * sort_decreasing,
1397 * } sort_method;
1398 *
1399 * typedef struct {
1400 * int key;
1401 * const char *string;
1402 * } data;
1403 *
1404 * int SDLCALL compare(const void *userdata, const void *a, const void *b)
1405 * {
1406 * sort_method method = (sort_method)(uintptr_t)userdata;
1407 * const data *A = (const data *)a;
1408 * const data *B = (const data *)b;
1409 *
1410 * if (A->n < B->n) {
1411 * return (method == sort_increasing) ? -1 : 1;
1412 * } else if (B->n < A->n) {
1413 * return (method == sort_increasing) ? 1 : -1;
1414 * } else {
1415 * return 0;
1416 * }
1417 * }
1418 *
1419 * data values[] = {
1420 * { 1, "first" }, { 2, "second" }, { 3, "third" }
1421 * };
1422 * data key = { 2, NULL };
1423 *
1424 * data *result = SDL_bsearch_r(&key, values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing);
1425 * ```
1426 *
1427 * \param key a pointer to a key equal to the element being searched for.
1428 * \param base a pointer to the start of the array.
1429 * \param nmemb the number of elements in the array.
1430 * \param size the size of the elements in the array.
1431 * \param compare a function used to compare elements in the array.
1432 * \param userdata a pointer to pass to the compare function.
1433 * \returns a pointer to the matching element in the array, or NULL if not
1434 * found.
1435 *
1436 * \since This function is available since SDL 3.0.0.
1437 *
1438 * \sa SDL_bsearch
1439 * \sa SDL_qsort_r
1440 */
1441extern SDL_DECLSPEC void * SDLCALL SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata);
1442
1443extern SDL_DECLSPEC int SDLCALL SDL_abs(int x);
1444
1445/* NOTE: these double-evaluate their arguments, so you should never have side effects in the parameters */
1446#define SDL_min(x, y) (((x) < (y)) ? (x) : (y))
1447#define SDL_max(x, y) (((x) > (y)) ? (x) : (y))
1448#define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x)))
1449
1450/**
1451 * Query if a character is alphabetic (a letter).
1452 *
1453 * **WARNING**: Regardless of system locale, this will only treat ASCII values
1454 * for English 'a-z' and 'A-Z' as true.
1455 *
1456 * \param x character value to check.
1457 * \returns non-zero if x falls within the character class, zero otherwise.
1458 *
1459 * \threadsafety It is safe to call this function from any thread.
1460 *
1461 * \since This function is available since SDL 3.0.0.
1462 */
1463extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x);
1464
1465/**
1466 * Query if a character is alphabetic (a letter) or a number.
1467 *
1468 * **WARNING**: Regardless of system locale, this will only treat ASCII values
1469 * for English 'a-z', 'A-Z', and '0-9' as true.
1470 *
1471 * \param x character value to check.
1472 * \returns non-zero if x falls within the character class, zero otherwise.
1473 *
1474 * \threadsafety It is safe to call this function from any thread.
1475 *
1476 * \since This function is available since SDL 3.0.0.
1477 */
1478extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x);
1479
1480/**
1481 * Report if a character is blank (a space or tab).
1482 *
1483 * **WARNING**: Regardless of system locale, this will only treat ASCII values
1484 * 0x20 (space) or 0x9 (tab) as true.
1485 *
1486 * \param x character value to check.
1487 * \returns non-zero if x falls within the character class, zero otherwise.
1488 *
1489 * \threadsafety It is safe to call this function from any thread.
1490 *
1491 * \since This function is available since SDL 3.0.0.
1492 */
1493extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x);
1494
1495/**
1496 * Report if a character is a control character.
1497 *
1498 * **WARNING**: Regardless of system locale, this will only treat ASCII values
1499 * 0 through 0x1F, and 0x7F, as true.
1500 *
1501 * \param x character value to check.
1502 * \returns non-zero if x falls within the character class, zero otherwise.
1503 *
1504 * \threadsafety It is safe to call this function from any thread.
1505 *
1506 * \since This function is available since SDL 3.0.0.
1507 */
1508extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x);
1509
1510/**
1511 * Report if a character is a numeric digit.
1512 *
1513 * **WARNING**: Regardless of system locale, this will only treat ASCII values
1514 * '0' (0x30) through '9' (0x39), as true.
1515 *
1516 * \param x character value to check.
1517 * \returns non-zero if x falls within the character class, zero otherwise.
1518 *
1519 * \threadsafety It is safe to call this function from any thread.
1520 *
1521 * \since This function is available since SDL 3.0.0.
1522 */
1523extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x);
1524
1525/**
1526 * Report if a character is a hexadecimal digit.
1527 *
1528 * **WARNING**: Regardless of system locale, this will only treat ASCII values
1529 * 'A' through 'F', 'a' through 'f', and '0' through '9', as true.
1530 *
1531 * \param x character value to check.
1532 * \returns non-zero if x falls within the character class, zero otherwise.
1533 *
1534 * \threadsafety It is safe to call this function from any thread.
1535 *
1536 * \since This function is available since SDL 3.0.0.
1537 */
1538extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x);
1539
1540/**
1541 * Report if a character is a punctuation mark.
1542 *
1543 * **WARNING**: Regardless of system locale, this is equivalent to
1544 * `((SDL_isgraph(x)) && (!SDL_isalnum(x)))`.
1545 *
1546 * \param x character value to check.
1547 * \returns non-zero if x falls within the character class, zero otherwise.
1548 *
1549 * \threadsafety It is safe to call this function from any thread.
1550 *
1551 * \since This function is available since SDL 3.0.0.
1552 *
1553 * \sa SDL_isgraph
1554 * \sa SDL_isalnum
1555 */
1556extern SDL_DECLSPEC int SDLCALL SDL_ispunct(int x);
1557
1558/**
1559 * Report if a character is whitespace.
1560 *
1561 * **WARNING**: Regardless of system locale, this will only treat the
1562 * following ASCII values as true:
1563 *
1564 * - space (0x20)
1565 * - tab (0x09)
1566 * - newline (0x0A)
1567 * - vertical tab (0x0B)
1568 * - form feed (0x0C)
1569 * - return (0x0D)
1570 *
1571 * \param x character value to check.
1572 * \returns non-zero if x falls within the character class, zero otherwise.
1573 *
1574 * \threadsafety It is safe to call this function from any thread.
1575 *
1576 * \since This function is available since SDL 3.0.0.
1577 */
1578extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x);
1579
1580/**
1581 * Report if a character is upper case.
1582 *
1583 * **WARNING**: Regardless of system locale, this will only treat ASCII values
1584 * 'A' through 'Z' as true.
1585 *
1586 * \param x character value to check.
1587 * \returns non-zero if x falls within the character class, zero otherwise.
1588 *
1589 * \threadsafety It is safe to call this function from any thread.
1590 *
1591 * \since This function is available since SDL 3.0.0.
1592 */
1593extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x);
1594
1595/**
1596 * Report if a character is lower case.
1597 *
1598 * **WARNING**: Regardless of system locale, this will only treat ASCII values
1599 * 'a' through 'z' as true.
1600 *
1601 * \param x character value to check.
1602 * \returns non-zero if x falls within the character class, zero otherwise.
1603 *
1604 * \threadsafety It is safe to call this function from any thread.
1605 *
1606 * \since This function is available since SDL 3.0.0.
1607 */
1608extern SDL_DECLSPEC int SDLCALL SDL_islower(int x);
1609
1610/**
1611 * Report if a character is "printable".
1612 *
1613 * Be advised that "printable" has a definition that goes back to text
1614 * terminals from the dawn of computing, making this a sort of special case
1615 * function that is not suitable for Unicode (or most any) text management.
1616 *
1617 * **WARNING**: Regardless of system locale, this will only treat ASCII values
1618 * ' ' (0x20) through '~' (0x7E) as true.
1619 *
1620 * \param x character value to check.
1621 * \returns non-zero if x falls within the character class, zero otherwise.
1622 *
1623 * \threadsafety It is safe to call this function from any thread.
1624 *
1625 * \since This function is available since SDL 3.0.0.
1626 */
1627extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x);
1628
1629/**
1630 * Report if a character is any "printable" except space.
1631 *
1632 * Be advised that "printable" has a definition that goes back to text
1633 * terminals from the dawn of computing, making this a sort of special case
1634 * function that is not suitable for Unicode (or most any) text management.
1635 *
1636 * **WARNING**: Regardless of system locale, this is equivalent to
1637 * `(SDL_isprint(x)) && ((x) != ' ')`.
1638 *
1639 * \param x character value to check.
1640 * \returns non-zero if x falls within the character class, zero otherwise.
1641 *
1642 * \threadsafety It is safe to call this function from any thread.
1643 *
1644 * \since This function is available since SDL 3.0.0.
1645 *
1646 * \sa SDL_isprint
1647 */
1648extern SDL_DECLSPEC int SDLCALL SDL_isgraph(int x);
1649
1650/**
1651 * Convert low-ASCII English letters to uppercase.
1652 *
1653 * **WARNING**: Regardless of system locale, this will only convert ASCII
1654 * values 'a' through 'z' to uppercase.
1655 *
1656 * This function returns the uppercase equivalent of `x`. If a character
1657 * cannot be converted, or is already uppercase, this function returns `x`.
1658 *
1659 * \param x character value to check.
1660 * \returns capitalized version of x, or x if no conversion available.
1661 *
1662 * \threadsafety It is safe to call this function from any thread.
1663 *
1664 * \since This function is available since SDL 3.0.0.
1665 */
1666extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x);
1667
1668/**
1669 * Convert low-ASCII English letters to lowercase.
1670 *
1671 * **WARNING**: Regardless of system locale, this will only convert ASCII
1672 * values 'A' through 'Z' to lowercase.
1673 *
1674 * This function returns the lowercase equivalent of `x`. If a character
1675 * cannot be converted, or is already lowercase, this function returns `x`.
1676 *
1677 * \param x character value to check.
1678 * \returns lowercase version of x, or x if no conversion available.
1679 *
1680 * \threadsafety It is safe to call this function from any thread.
1681 *
1682 * \since This function is available since SDL 3.0.0.
1683 */
1684extern SDL_DECLSPEC int SDLCALL SDL_tolower(int x);
1685
1686extern SDL_DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len);
1687extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len);
1688extern SDL_DECLSPEC Uint32 SDLCALL SDL_murmur3_32(const void *data, size_t len, Uint32 seed);
1689
1690/**
1691 * Copy non-overlapping memory.
1692 *
1693 * The memory regions must not overlap. If they do, use SDL_memmove() instead.
1694 *
1695 * \param dst The destination memory region. Must not be NULL, and must not
1696 * overlap with `src`.
1697 * \param src The source memory region. Must not be NULL, and must not overlap
1698 * with `dst`.
1699 * \param len The length in bytes of both `dst` and `src`.
1700 * \returns `dst`.
1701 *
1702 * \threadsafety It is safe to call this function from any thread.
1703 *
1704 * \since This function is available since SDL 3.0.0.
1705 *
1706 * \sa SDL_memmove
1707 */
1708extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len);
1709
1710/* Take advantage of compiler optimizations for memcpy */
1711#ifndef SDL_SLOW_MEMCPY
1712#ifdef SDL_memcpy
1713#undef SDL_memcpy
1714#endif
1715#define SDL_memcpy memcpy
1716#endif
1717
1718#define SDL_copyp(dst, src) \
1719 { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \
1720 SDL_memcpy((dst), (src), sizeof(*(src)))
1721
1722/**
1723 * Copy memory.
1724 *
1725 * It is okay for the memory regions to overlap. If you are confident that the
1726 * regions never overlap, using SDL_memcpy() may improve performance.
1727 *
1728 * \param dst The destination memory region. Must not be NULL.
1729 * \param src The source memory region. Must not be NULL.
1730 * \param len The length in bytes of both `dst` and `src`.
1731 * \returns `dst`.
1732 *
1733 * \threadsafety It is safe to call this function from any thread.
1734 *
1735 * \since This function is available since SDL 3.0.0.
1736 *
1737 * \sa SDL_memcpy
1738 */
1739extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len);
1740
1741/* Take advantage of compiler optimizations for memmove */
1742#ifndef SDL_SLOW_MEMMOVE
1743#ifdef SDL_memmove
1744#undef SDL_memmove
1745#endif
1746#define SDL_memmove memmove
1747#endif
1748
1749extern SDL_DECLSPEC void * SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len);
1750extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwords);
1751
1752/* Take advantage of compiler optimizations for memset */
1753#ifndef SDL_SLOW_MEMSET
1754#ifdef SDL_memset
1755#undef SDL_memset
1756#endif
1757#define SDL_memset memset
1758#endif
1759
1760#define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x)))
1761#define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x)))
1762#define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x)))
1763
1764extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len);
1765
1766extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr);
1767extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen);
1768
1769/**
1770 * Copy a wide string.
1771 *
1772 * This function copies `maxlen` - 1 wide characters from `src` to `dst`, then
1773 * appends a null terminator.
1774 *
1775 * `src` and `dst` must not overlap.
1776 *
1777 * If `maxlen` is 0, no wide characters are copied and no null terminator is
1778 * written.
1779 *
1780 * \param dst The destination buffer. Must not be NULL, and must not overlap
1781 * with `src`.
1782 * \param src The null-terminated wide string to copy. Must not be NULL, and
1783 * must not overlap with `dst`.
1784 * \param maxlen The length (in wide characters) of the destination buffer.
1785 * \returns The length (in wide characters, excluding the null terminator) of
1786 * `src`.
1787 *
1788 * \threadsafety It is safe to call this function from any thread.
1789 *
1790 * \since This function is available since SDL 3.0.0.
1791 *
1792 * \sa SDL_wcslcat
1793 */
1794extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen);
1795
1796/**
1797 * Concatenate wide strings.
1798 *
1799 * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters
1800 * from `src` to the end of the wide string in `dst`, then appends a null
1801 * terminator.
1802 *
1803 * `src` and `dst` must not overlap.
1804 *
1805 * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is
1806 * unmodified.
1807 *
1808 * \param dst The destination buffer already containing the first
1809 * null-terminated wide string. Must not be NULL and must not
1810 * overlap with `src`.
1811 * \param src The second null-terminated wide string. Must not be NULL, and
1812 * must not overlap with `dst`.
1813 * \param maxlen The length (in wide characters) of the destination buffer.
1814 * \returns The length (in wide characters, excluding the null terminator) of
1815 * the string in `dst` plus the length of `src`.
1816 *
1817 * \threadsafety It is safe to call this function from any thread.
1818 *
1819 * \since This function is available since SDL 3.0.0.
1820 *
1821 * \sa SDL_wcslcpy
1822 */
1823extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen);
1824
1825extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr);
1826extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle);
1827extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen);
1828
1829/**
1830 * Compare two null-terminated wide strings.
1831 *
1832 * This only compares wchar_t values until it hits a null-terminating
1833 * character; it does not care if the string is well-formed UTF-16 (or UTF-32,
1834 * depending on your platform's wchar_t size), or uses valid Unicode values.
1835 *
1836 * \param str1 the first string to compare. NULL is not permitted!
1837 * \param str2 the second string to compare. NULL is not permitted!
1838 * \returns less than zero if str1 is "less than" str2, greater than zero if
1839 * str1 is "greater than" str2, and zero if the strings match
1840 * exactly.
1841 *
1842 * \threadsafety It is safe to call this function from any thread.
1843 *
1844 * \since This function is available since SDL 3.0.0.
1845 */
1846extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2);
1847
1848/**
1849 * Compare two wide strings up to a number of wchar_t values.
1850 *
1851 * This only compares wchar_t values; it does not care if the string is
1852 * well-formed UTF-16 (or UTF-32, depending on your platform's wchar_t size),
1853 * or uses valid Unicode values.
1854 *
1855 * Note that while this function is intended to be used with UTF-16 (or
1856 * UTF-32, depending on your platform's definition of wchar_t), it is
1857 * comparing raw wchar_t values and not Unicode codepoints: `maxlen` specifies
1858 * a wchar_t limit! If the limit lands in the middle of a multi-wchar UTF-16
1859 * sequence, it will only compare a portion of the final character.
1860 *
1861 * `maxlen` specifies a maximum number of wchar_t to compare; if the strings
1862 * match to this number of wide chars (or both have matched to a
1863 * null-terminator character before this count), they will be considered
1864 * equal.
1865 *
1866 * \param str1 the first string to compare. NULL is not permitted!
1867 * \param str2 the second string to compare. NULL is not permitted!
1868 * \param maxlen the maximum number of wchar_t to compare.
1869 * \returns less than zero if str1 is "less than" str2, greater than zero if
1870 * str1 is "greater than" str2, and zero if the strings match
1871 * exactly.
1872 *
1873 * \threadsafety It is safe to call this function from any thread.
1874 *
1875 * \since This function is available since SDL 3.0.0.
1876 */
1877extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen);
1878
1879/**
1880 * Compare two null-terminated wide strings, case-insensitively.
1881 *
1882 * This will work with Unicode strings, using a technique called
1883 * "case-folding" to handle the vast majority of case-sensitive human
1884 * languages regardless of system locale. It can deal with expanding values: a
1885 * German Eszett character can compare against two ASCII 's' chars and be
1886 * considered a match, for example. A notable exception: it does not handle
1887 * the Turkish 'i' character; human language is complicated!
1888 *
1889 * Depending on your platform, "wchar_t" might be 2 bytes, and expected to be
1890 * UTF-16 encoded (like Windows), or 4 bytes in UTF-32 format. Since this
1891 * handles Unicode, it expects the string to be well-formed and not a
1892 * null-terminated string of arbitrary bytes. Characters that are not valid
1893 * UTF-16 (or UTF-32) are treated as Unicode character U+FFFD (REPLACEMENT
1894 * CHARACTER), which is to say two strings of random bits may turn out to
1895 * match if they convert to the same amount of replacement characters.
1896 *
1897 * \param str1 the first string to compare. NULL is not permitted!
1898 * \param str2 the second string to compare. NULL is not permitted!
1899 * \returns less than zero if str1 is "less than" str2, greater than zero if
1900 * str1 is "greater than" str2, and zero if the strings match
1901 * exactly.
1902 *
1903 * \threadsafety It is safe to call this function from any thread.
1904 *
1905 * \since This function is available since SDL 3.0.0.
1906 */
1907extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2);
1908
1909/**
1910 * Compare two wide strings, case-insensitively, up to a number of wchar_t.
1911 *
1912 * This will work with Unicode strings, using a technique called
1913 * "case-folding" to handle the vast majority of case-sensitive human
1914 * languages regardless of system locale. It can deal with expanding values: a
1915 * German Eszett character can compare against two ASCII 's' chars and be
1916 * considered a match, for example. A notable exception: it does not handle
1917 * the Turkish 'i' character; human language is complicated!
1918 *
1919 * Depending on your platform, "wchar_t" might be 2 bytes, and expected to be
1920 * UTF-16 encoded (like Windows), or 4 bytes in UTF-32 format. Since this
1921 * handles Unicode, it expects the string to be well-formed and not a
1922 * null-terminated string of arbitrary bytes. Characters that are not valid
1923 * UTF-16 (or UTF-32) are treated as Unicode character U+FFFD (REPLACEMENT
1924 * CHARACTER), which is to say two strings of random bits may turn out to
1925 * match if they convert to the same amount of replacement characters.
1926 *
1927 * Note that while this function might deal with variable-sized characters,
1928 * `maxlen` specifies a _wchar_ limit! If the limit lands in the middle of a
1929 * multi-byte UTF-16 sequence, it may convert a portion of the final character
1930 * to one or more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not
1931 * to overflow a buffer.
1932 *
1933 * `maxlen` specifies a maximum number of wchar_t values to compare; if the
1934 * strings match to this number of wchar_t (or both have matched to a
1935 * null-terminator character before this number of bytes), they will be
1936 * considered equal.
1937 *
1938 * \param str1 the first string to compare. NULL is not permitted!
1939 * \param str2 the second string to compare. NULL is not permitted!
1940 * \param maxlen the maximum number of wchar_t values to compare.
1941 * \returns less than zero if str1 is "less than" str2, greater than zero if
1942 * str1 is "greater than" str2, and zero if the strings match
1943 * exactly.
1944 *
1945 * \threadsafety It is safe to call this function from any thread.
1946 *
1947 * \since This function is available since SDL 3.0.0.
1948 */
1949extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen);
1950
1951/**
1952 * Parse a `long` from a wide string.
1953 *
1954 * If `str` starts with whitespace, then those whitespace characters are
1955 * skipped before attempting to parse the number.
1956 *
1957 * If the parsed number does not fit inside a `long`, the result is clamped to
1958 * the minimum and maximum representable `long` values.
1959 *
1960 * \param str The null-terminated wide string to read. Must not be NULL.
1961 * \param endp If not NULL, the address of the first invalid wide character
1962 * (i.e. the next character after the parsed number) will be
1963 * written to this pointer.
1964 * \param base The base of the integer to read. Supported values are 0 and 2
1965 * to 36 inclusive. If 0, the base will be inferred from the
1966 * number's prefix (0x for hexadecimal, 0 for octal, decimal
1967 * otherwise).
1968 * \returns The parsed `long`, or 0 if no number could be parsed.
1969 *
1970 * \threadsafety It is safe to call this function from any thread.
1971 *
1972 * \since This function is available since SDL 3.0.0.
1973 *
1974 * \sa SDL_strtol
1975 */
1976extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base);
1977
1978extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str);
1979extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen);
1980
1981/**
1982 * Copy a string.
1983 *
1984 * This function copies up to `maxlen` - 1 characters from `src` to `dst`,
1985 * then appends a null terminator.
1986 *
1987 * If `maxlen` is 0, no characters are copied and no null terminator is
1988 * written.
1989 *
1990 * If you want to copy an UTF-8 string but need to ensure that multi-byte
1991 * sequences are not truncated, consider using SDL_utf8strlcpy().
1992 *
1993 * \param dst The destination buffer. Must not be NULL, and must not overlap
1994 * with `src`.
1995 * \param src The null-terminated string to copy. Must not be NULL, and must
1996 * not overlap with `dst`.
1997 * \param maxlen The length (in characters) of the destination buffer.
1998 * \returns The length (in characters, excluding the null terminator) of
1999 * `src`.
2000 *
2001 * \threadsafety It is safe to call this function from any thread.
2002 *
2003 * \since This function is available since SDL 3.0.0.
2004 *
2005 * \sa SDL_strlcat
2006 * \sa SDL_utf8strlcpy
2007 */
2008extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);
2009
2010/**
2011 * Copy an UTF-8 string.
2012 *
2013 * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst` while
2014 * also ensuring that the string written to `dst` does not end in a truncated
2015 * multi-byte sequence. Finally, it appends a null terminator.
2016 *
2017 * `src` and `dst` must not overlap.
2018 *
2019 * Note that unlike SDL_strlcpy(), this function returns the number of bytes
2020 * written, not the length of `src`.
2021 *
2022 * \param dst The destination buffer. Must not be NULL, and must not overlap
2023 * with `src`.
2024 * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and
2025 * must not overlap with `dst`.
2026 * \param dst_bytes The length (in bytes) of the destination buffer. Must not
2027 * be 0.
2028 * \returns The number of bytes written, excluding the null terminator.
2029 *
2030 * \threadsafety It is safe to call this function from any thread.
2031 *
2032 * \since This function is available since SDL 3.0.0.
2033 *
2034 * \sa SDL_strlcpy
2035 */
2036extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes);
2037
2038/**
2039 * Concatenate strings.
2040 *
2041 * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from
2042 * `src` to the end of the string in `dst`, then appends a null terminator.
2043 *
2044 * `src` and `dst` must not overlap.
2045 *
2046 * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is
2047 * unmodified.
2048 *
2049 * \param dst The destination buffer already containing the first
2050 * null-terminated string. Must not be NULL and must not overlap
2051 * with `src`.
2052 * \param src The second null-terminated string. Must not be NULL, and must
2053 * not overlap with `dst`.
2054 * \param maxlen The length (in characters) of the destination buffer.
2055 * \returns The length (in characters, excluding the null terminator) of the
2056 * string in `dst` plus the length of `src`.
2057 *
2058 * \threadsafety It is safe to call this function from any thread.
2059 *
2060 * \since This function is available since SDL 3.0.0.
2061 *
2062 * \sa SDL_strlcpy
2063 */
2064extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);
2065
2066extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str);
2067extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen);
2068extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str);
2069
2070/**
2071 * Convert a string to uppercase.
2072 *
2073 * **WARNING**: Regardless of system locale, this will only convert ASCII
2074 * values 'A' through 'Z' to uppercase.
2075 *
2076 * This function operates on a null-terminated string of bytes--even if it is
2077 * malformed UTF-8!--and converts ASCII characters 'a' through 'z' to their
2078 * uppercase equivalents in-place, returning the original `str` pointer.
2079 *
2080 * \param str the string to convert in-place. Can not be NULL.
2081 * \returns the `str` pointer passed into this function.
2082 *
2083 * \threadsafety It is safe to call this function from any thread.
2084 *
2085 * \since This function is available since SDL 3.0.0.
2086 *
2087 * \sa SDL_strlwr
2088 */
2089extern SDL_DECLSPEC char * SDLCALL SDL_strupr(char *str);
2090
2091/**
2092 * Convert a string to lowercase.
2093 *
2094 * **WARNING**: Regardless of system locale, this will only convert ASCII
2095 * values 'A' through 'Z' to lowercase.
2096 *
2097 * This function operates on a null-terminated string of bytes--even if it is
2098 * malformed UTF-8!--and converts ASCII characters 'A' through 'Z' to their
2099 * lowercase equivalents in-place, returning the original `str` pointer.
2100 *
2101 * \param str the string to convert in-place. Can not be NULL.
2102 * \returns the `str` pointer passed into this function.
2103 *
2104 * \threadsafety It is safe to call this function from any thread.
2105 *
2106 * \since This function is available since SDL 3.0.0.
2107 *
2108 * \sa SDL_strupr
2109 */
2110extern SDL_DECLSPEC char * SDLCALL SDL_strlwr(char *str);
2111
2112extern SDL_DECLSPEC char * SDLCALL SDL_strchr(const char *str, int c);
2113extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c);
2114extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *needle);
2115extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen);
2116extern SDL_DECLSPEC char * SDLCALL SDL_strcasestr(const char *haystack, const char *needle);
2117extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *s1, const char *s2, char **saveptr);
2118extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str);
2119extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes);
2120
2121extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix);
2122extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix);
2123extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix);
2124extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix);
2125extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(long long value, char *str, int radix);
2126extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *str, int radix);
2127
2128/**
2129 * Parse an `int` from a string.
2130 *
2131 * The result of calling `SDL_atoi(str)` is equivalent to
2132 * `(int)SDL_strtol(str, NULL, 10)`.
2133 *
2134 * \param str The null-terminated string to read. Must not be NULL.
2135 * \returns The parsed `int`.
2136 *
2137 * \threadsafety It is safe to call this function from any thread.
2138 *
2139 * \since This function is available since SDL 3.0.0.
2140 *
2141 * \sa SDL_atof
2142 * \sa SDL_strtol
2143 * \sa SDL_strtoul
2144 * \sa SDL_strtoll
2145 * \sa SDL_strtoull
2146 * \sa SDL_strtod
2147 * \sa SDL_itoa
2148 */
2149extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str);
2150
2151/**
2152 * Parse a `double` from a string.
2153 *
2154 * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str,
2155 * NULL)`.
2156 *
2157 * \param str The null-terminated string to read. Must not be NULL.
2158 * \returns The parsed `double`.
2159 *
2160 * \threadsafety It is safe to call this function from any thread.
2161 *
2162 * \since This function is available since SDL 3.0.0.
2163 *
2164 * \sa SDL_atoi
2165 * \sa SDL_strtol
2166 * \sa SDL_strtoul
2167 * \sa SDL_strtoll
2168 * \sa SDL_strtoull
2169 * \sa SDL_strtod
2170 */
2171extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str);
2172
2173/**
2174 * Parse a `long` from a string.
2175 *
2176 * If `str` starts with whitespace, then those whitespace characters are
2177 * skipped before attempting to parse the number.
2178 *
2179 * If the parsed number does not fit inside a `long`, the result is clamped to
2180 * the minimum and maximum representable `long` values.
2181 *
2182 * \param str The null-terminated string to read. Must not be NULL.
2183 * \param endp If not NULL, the address of the first invalid character (i.e.
2184 * the next character after the parsed number) will be written to
2185 * this pointer.
2186 * \param base The base of the integer to read. Supported values are 0 and 2
2187 * to 36 inclusive. If 0, the base will be inferred from the
2188 * number's prefix (0x for hexadecimal, 0 for octal, decimal
2189 * otherwise).
2190 * \returns The parsed `long`, or 0 if no number could be parsed.
2191 *
2192 * \threadsafety It is safe to call this function from any thread.
2193 *
2194 * \since This function is available since SDL 3.0.0.
2195 *
2196 * \sa SDL_atoi
2197 * \sa SDL_atof
2198 * \sa SDL_strtoul
2199 * \sa SDL_strtoll
2200 * \sa SDL_strtoull
2201 * \sa SDL_strtod
2202 * \sa SDL_ltoa
2203 * \sa SDL_wcstol
2204 */
2205extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base);
2206
2207/**
2208 * Parse an `unsigned long` from a string.
2209 *
2210 * If `str` starts with whitespace, then those whitespace characters are
2211 * skipped before attempting to parse the number.
2212 *
2213 * If the parsed number does not fit inside an `unsigned long`, the result is
2214 * clamped to the maximum representable `unsigned long` value.
2215 *
2216 * \param str The null-terminated string to read. Must not be NULL.
2217 * \param endp If not NULL, the address of the first invalid character (i.e.
2218 * the next character after the parsed number) will be written to
2219 * this pointer.
2220 * \param base The base of the integer to read. Supported values are 0 and 2
2221 * to 36 inclusive. If 0, the base will be inferred from the
2222 * number's prefix (0x for hexadecimal, 0 for octal, decimal
2223 * otherwise).
2224 * \returns The parsed `unsigned long`, or 0 if no number could be parsed.
2225 *
2226 * \threadsafety It is safe to call this function from any thread.
2227 *
2228 * \since This function is available since SDL 3.0.0.
2229 *
2230 * \sa SDL_atoi
2231 * \sa SDL_atof
2232 * \sa SDL_strtol
2233 * \sa SDL_strtoll
2234 * \sa SDL_strtoull
2235 * \sa SDL_strtod
2236 * \sa SDL_ultoa
2237 */
2238extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base);
2239
2240/**
2241 * Parse a `long long` from a string.
2242 *
2243 * If `str` starts with whitespace, then those whitespace characters are
2244 * skipped before attempting to parse the number.
2245 *
2246 * If the parsed number does not fit inside a `long long`, the result is
2247 * clamped to the minimum and maximum representable `long long` values.
2248 *
2249 * \param str The null-terminated string to read. Must not be NULL.
2250 * \param endp If not NULL, the address of the first invalid character (i.e.
2251 * the next character after the parsed number) will be written to
2252 * this pointer.
2253 * \param base The base of the integer to read. Supported values are 0 and 2
2254 * to 36 inclusive. If 0, the base will be inferred from the
2255 * number's prefix (0x for hexadecimal, 0 for octal, decimal
2256 * otherwise).
2257 * \returns The parsed `long long`, or 0 if no number could be parsed.
2258 *
2259 * \threadsafety It is safe to call this function from any thread.
2260 *
2261 * \since This function is available since SDL 3.0.0.
2262 *
2263 * \sa SDL_atoi
2264 * \sa SDL_atof
2265 * \sa SDL_strtol
2266 * \sa SDL_strtoul
2267 * \sa SDL_strtoull
2268 * \sa SDL_strtod
2269 * \sa SDL_lltoa
2270 */
2271extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, int base);
2272
2273/**
2274 * Parse an `unsigned long long` from a string.
2275 *
2276 * If `str` starts with whitespace, then those whitespace characters are
2277 * skipped before attempting to parse the number.
2278 *
2279 * If the parsed number does not fit inside an `unsigned long long`, the
2280 * result is clamped to the maximum representable `unsigned long long` value.
2281 *
2282 * \param str The null-terminated string to read. Must not be NULL.
2283 * \param endp If not NULL, the address of the first invalid character (i.e.
2284 * the next character after the parsed number) will be written to
2285 * this pointer.
2286 * \param base The base of the integer to read. Supported values are 0 and 2
2287 * to 36 inclusive. If 0, the base will be inferred from the
2288 * number's prefix (0x for hexadecimal, 0 for octal, decimal
2289 * otherwise).
2290 * \returns The parsed `unsigned long long`, or 0 if no number could be
2291 * parsed.
2292 *
2293 * \threadsafety It is safe to call this function from any thread.
2294 *
2295 * \since This function is available since SDL 3.0.0.
2296 *
2297 * \sa SDL_atoi
2298 * \sa SDL_atof
2299 * \sa SDL_strtol
2300 * \sa SDL_strtoll
2301 * \sa SDL_strtoul
2302 * \sa SDL_strtod
2303 * \sa SDL_ulltoa
2304 */
2305extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, char **endp, int base);
2306
2307/**
2308 * Parse a `double` from a string.
2309 *
2310 * This function makes fewer guarantees than the C runtime `strtod`:
2311 *
2312 * - Only decimal notation is guaranteed to be supported. The handling of
2313 * scientific and hexadecimal notation is unspecified.
2314 * - Whether or not INF and NAN can be parsed is unspecified.
2315 * - The precision of the result is unspecified.
2316 *
2317 * \param str The null-terminated string to read. Must not be NULL.
2318 * \param endp If not NULL, the address of the first invalid character (i.e.
2319 * the next character after the parsed number) will be written to
2320 * this pointer.
2321 * \returns The parsed `double`, or 0 if no number could be parsed.
2322 *
2323 * \threadsafety It is safe to call this function from any thread.
2324 *
2325 * \since This function is available since SDL 3.0.0.
2326 *
2327 * \sa SDL_atoi
2328 * \sa SDL_atof
2329 * \sa SDL_strtol
2330 * \sa SDL_strtoll
2331 * \sa SDL_strtoul
2332 * \sa SDL_strtoull
2333 */
2334extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp);
2335
2336/**
2337 * Compare two null-terminated UTF-8 strings.
2338 *
2339 * Due to the nature of UTF-8 encoding, this will work with Unicode strings,
2340 * since effectively this function just compares bytes until it hits a
2341 * null-terminating character. Also due to the nature of UTF-8, this can be
2342 * used with SDL_qsort() to put strings in (roughly) alphabetical order.
2343 *
2344 * \param str1 the first string to compare. NULL is not permitted!
2345 * \param str2 the second string to compare. NULL is not permitted!
2346 * \returns less than zero if str1 is "less than" str2, greater than zero if
2347 * str1 is "greater than" str2, and zero if the strings match
2348 * exactly.
2349 *
2350 * \threadsafety It is safe to call this function from any thread.
2351 *
2352 * \since This function is available since SDL 3.0.0.
2353 */
2354extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2);
2355
2356/**
2357 * Compare two UTF-8 strings up to a number of bytes.
2358 *
2359 * Due to the nature of UTF-8 encoding, this will work with Unicode strings,
2360 * since effectively this function just compares bytes until it hits a
2361 * null-terminating character. Also due to the nature of UTF-8, this can be
2362 * used with SDL_qsort() to put strings in (roughly) alphabetical order.
2363 *
2364 * Note that while this function is intended to be used with UTF-8, it is
2365 * doing a bytewise comparison, and `maxlen` specifies a _byte_ limit! If the
2366 * limit lands in the middle of a multi-byte UTF-8 sequence, it will only
2367 * compare a portion of the final character.
2368 *
2369 * `maxlen` specifies a maximum number of bytes to compare; if the strings
2370 * match to this number of bytes (or both have matched to a null-terminator
2371 * character before this number of bytes), they will be considered equal.
2372 *
2373 * \param str1 the first string to compare. NULL is not permitted!
2374 * \param str2 the second string to compare. NULL is not permitted!
2375 * \param maxlen the maximum number of _bytes_ to compare.
2376 * \returns less than zero if str1 is "less than" str2, greater than zero if
2377 * str1 is "greater than" str2, and zero if the strings match
2378 * exactly.
2379 *
2380 * \threadsafety It is safe to call this function from any thread.
2381 *
2382 * \since This function is available since SDL 3.0.0.
2383 */
2384extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, size_t maxlen);
2385
2386/**
2387 * Compare two null-terminated UTF-8 strings, case-insensitively.
2388 *
2389 * This will work with Unicode strings, using a technique called
2390 * "case-folding" to handle the vast majority of case-sensitive human
2391 * languages regardless of system locale. It can deal with expanding values: a
2392 * German Eszett character can compare against two ASCII 's' chars and be
2393 * considered a match, for example. A notable exception: it does not handle
2394 * the Turkish 'i' character; human language is complicated!
2395 *
2396 * Since this handles Unicode, it expects the string to be well-formed UTF-8
2397 * and not a null-terminated string of arbitrary bytes. Bytes that are not
2398 * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT
2399 * CHARACTER), which is to say two strings of random bits may turn out to
2400 * match if they convert to the same amount of replacement characters.
2401 *
2402 * \param str1 the first string to compare. NULL is not permitted!
2403 * \param str2 the second string to compare. NULL is not permitted!
2404 * \returns less than zero if str1 is "less than" str2, greater than zero if
2405 * str1 is "greater than" str2, and zero if the strings match
2406 * exactly.
2407 *
2408 * \threadsafety It is safe to call this function from any thread.
2409 *
2410 * \since This function is available since SDL 3.0.0.
2411 */
2412extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2);
2413
2414
2415/**
2416 * Compare two UTF-8 strings, case-insensitively, up to a number of bytes.
2417 *
2418 * This will work with Unicode strings, using a technique called
2419 * "case-folding" to handle the vast majority of case-sensitive human
2420 * languages regardless of system locale. It can deal with expanding values: a
2421 * German Eszett character can compare against two ASCII 's' chars and be
2422 * considered a match, for example. A notable exception: it does not handle
2423 * the Turkish 'i' character; human language is complicated!
2424 *
2425 * Since this handles Unicode, it expects the string to be well-formed UTF-8
2426 * and not a null-terminated string of arbitrary bytes. Bytes that are not
2427 * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT
2428 * CHARACTER), which is to say two strings of random bits may turn out to
2429 * match if they convert to the same amount of replacement characters.
2430 *
2431 * Note that while this function is intended to be used with UTF-8, `maxlen`
2432 * specifies a _byte_ limit! If the limit lands in the middle of a multi-byte
2433 * UTF-8 sequence, it may convert a portion of the final character to one or
2434 * more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not to overflow
2435 * a buffer.
2436 *
2437 * `maxlen` specifies a maximum number of bytes to compare; if the strings
2438 * match to this number of bytes (or both have matched to a null-terminator
2439 * character before this number of bytes), they will be considered equal.
2440 *
2441 * \param str1 the first string to compare. NULL is not permitted!
2442 * \param str2 the second string to compare. NULL is not permitted!
2443 * \param maxlen the maximum number of bytes to compare.
2444 * \returns less than zero if str1 is "less than" str2, greater than zero if
2445 * str1 is "greater than" str2, and zero if the strings match
2446 * exactly.
2447 *
2448 * \threadsafety It is safe to call this function from any thread.
2449 *
2450 * \since This function is available since SDL 3.0.0.
2451 */
2452extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen);
2453
2454/**
2455 * Searches a string for the first occurence of any character contained in a
2456 * breakset, and returns a pointer from the string to that character.
2457 *
2458 * \param str The null-terminated string to be searched. Must not be NULL, and
2459 * must not overlap with `breakset`.
2460 * \param breakset A null-terminated string containing the list of characters
2461 * to look for. Must not be NULL, and must not overlap with
2462 * `str`.
2463 * \returns A pointer to the location, in str, of the first occurence of a
2464 * character present in the breakset, or NULL if none is found.
2465 *
2466 * \threadsafety It is safe to call this function from any thread.
2467 *
2468 * \since This function is available since SDL 3.0.0.
2469 */
2470extern SDL_DECLSPEC char * SDLCALL SDL_strpbrk(const char *str, const char *breakset);
2471
2472/**
2473 * The Unicode REPLACEMENT CHARACTER codepoint.
2474 *
2475 * SDL_StepUTF8() reports this codepoint when it encounters a UTF-8 string
2476 * with encoding errors.
2477 *
2478 * This tends to render as something like a question mark in most places.
2479 *
2480 * \since This macro is available since SDL 3.0.0.
2481 *
2482 * \sa SDL_StepUTF8
2483 */
2484#define SDL_INVALID_UNICODE_CODEPOINT 0xFFFD
2485
2486/**
2487 * Decode a UTF-8 string, one Unicode codepoint at a time.
2488 *
2489 * This will return the first Unicode codepoint in the UTF-8 encoded string in
2490 * `*pstr`, and then advance `*pstr` past any consumed bytes before returning.
2491 *
2492 * It will not access more than `*pslen` bytes from the string. `*pslen` will
2493 * be adjusted, as well, subtracting the number of bytes consumed.
2494 *
2495 * `pslen` is allowed to be NULL, in which case the string _must_ be
2496 * NULL-terminated, as the function will blindly read until it sees the NULL
2497 * char.
2498 *
2499 * if `*pslen` is zero, it assumes the end of string is reached and returns a
2500 * zero codepoint regardless of the contents of the string buffer.
2501 *
2502 * If the resulting codepoint is zero (a NULL terminator), or `*pslen` is
2503 * zero, it will not advance `*pstr` or `*pslen` at all.
2504 *
2505 * Generally this function is called in a loop until it returns zero,
2506 * adjusting its parameters each iteration.
2507 *
2508 * If an invalid UTF-8 sequence is encountered, this function returns
2509 * SDL_INVALID_UNICODE_CODEPOINT and advances the string/length by one byte
2510 * (which is to say, a multibyte sequence might produce several
2511 * SDL_INVALID_UNICODE_CODEPOINT returns before it syncs to the next valid
2512 * UTF-8 sequence).
2513 *
2514 * Several things can generate invalid UTF-8 sequences, including overlong
2515 * encodings, the use of UTF-16 surrogate values, and truncated data. Please
2516 * refer to
2517 * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt)
2518 * for details.
2519 *
2520 * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted.
2521 * \param pslen a pointer to the number of bytes in the string, to be read and
2522 * adjusted. NULL is allowed.
2523 * \returns the first Unicode codepoint in the string.
2524 *
2525 * \threadsafety It is safe to call this function from any thread.
2526 *
2527 * \since This function is available since SDL 3.0.0.
2528 */
2529extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen);
2530
2531/**
2532 * Convert a single Unicode codepoint to UTF-8.
2533 *
2534 * The buffer pointed to by `dst` must be at least 4 bytes long, as this
2535 * function may generate between 1 and 4 bytes of output.
2536 *
2537 * This function returns the first byte _after_ the newly-written UTF-8
2538 * sequence, which is useful for encoding multiple codepoints in a loop, or
2539 * knowing where to write a NULL-terminator character to end the string (in
2540 * either case, plan to have a buffer of _more_ than 4 bytes!).
2541 *
2542 * If `codepoint` is an invalid value (outside the Unicode range, or a UTF-16
2543 * surrogate value, etc), this will use U+FFFD (REPLACEMENT CHARACTER) for the
2544 * codepoint instead, and not set an error.
2545 *
2546 * If `dst` is NULL, this returns NULL immediately without writing to the
2547 * pointer and without setting an error.
2548 *
2549 * \param codepoint a Unicode codepoint to convert to UTF-8.
2550 * \param dst the location to write the encoded UTF-8. Must point to at least
2551 * 4 bytes!
2552 * \returns the first byte past the newly-written UTF-8 sequence.
2553 *
2554 * \threadsafety It is safe to call this function from any thread.
2555 *
2556 * \since This function is available since SDL 3.0.0.
2557 */
2558extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst);
2559
2560
2561extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2);
2562extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2);
2563extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
2564extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(3);
2565extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3);
2566extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3);
2567extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
2568extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
2569
2570/**
2571 * Seeds the pseudo-random number generator.
2572 *
2573 * Reusing the seed number will cause SDL_rand_*() to repeat the same stream
2574 * of 'random' numbers.
2575 *
2576 * \param seed the value to use as a random number seed, or 0 to use
2577 * SDL_GetPerformanceCounter().
2578 *
2579 * \threadsafety This should be called on the same thread that calls
2580 * SDL_rand*()
2581 *
2582 * \since This function is available since SDL 3.0.0.
2583 *
2584 * \sa SDL_rand
2585 * \sa SDL_rand_bits
2586 * \sa SDL_randf
2587 */
2588extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed);
2589
2590/**
2591 * Generate a pseudo-random number less than n for positive n
2592 *
2593 * The method used is faster and of better quality than `rand() % n`. Odds are
2594 * roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and
2595 * much worse as n gets bigger.
2596 *
2597 * Example: to simulate a d6 use `SDL_rand(6) + 1` The +1 converts 0..5 to
2598 * 1..6
2599 *
2600 * If you want to generate a pseudo-random number in the full range of Sint32,
2601 * you should use: (Sint32)SDL_rand_bits()
2602 *
2603 * If you want reproducible output, be sure to initialize with SDL_srand()
2604 * first.
2605 *
2606 * There are no guarantees as to the quality of the random sequence produced,
2607 * and this should not be used for security (cryptography, passwords) or where
2608 * money is on the line (loot-boxes, casinos). There are many random number
2609 * libraries available with different characteristics and you should pick one
2610 * of those to meet any serious needs.
2611 *
2612 * \param n the number of possible outcomes. n must be positive.
2613 * \returns a random value in the range of [0 .. n-1].
2614 *
2615 * \threadsafety All calls should be made from a single thread
2616 *
2617 * \since This function is available since SDL 3.0.0.
2618 *
2619 * \sa SDL_srand
2620 * \sa SDL_randf
2621 */
2622extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand(Sint32 n);
2623
2624/**
2625 * Generate a uniform pseudo-random floating point number less than 1.0
2626 *
2627 * If you want reproducible output, be sure to initialize with SDL_srand()
2628 * first.
2629 *
2630 * There are no guarantees as to the quality of the random sequence produced,
2631 * and this should not be used for security (cryptography, passwords) or where
2632 * money is on the line (loot-boxes, casinos). There are many random number
2633 * libraries available with different characteristics and you should pick one
2634 * of those to meet any serious needs.
2635 *
2636 * \returns a random value in the range of [0.0, 1.0).
2637 *
2638 * \threadsafety All calls should be made from a single thread
2639 *
2640 * \since This function is available since SDL 3.0.0.
2641 *
2642 * \sa SDL_srand
2643 * \sa SDL_rand
2644 */
2645extern SDL_DECLSPEC float SDLCALL SDL_randf(void);
2646
2647/**
2648 * Generate 32 pseudo-random bits.
2649 *
2650 * You likely want to use SDL_rand() to get a psuedo-random number instead.
2651 *
2652 * There are no guarantees as to the quality of the random sequence produced,
2653 * and this should not be used for security (cryptography, passwords) or where
2654 * money is on the line (loot-boxes, casinos). There are many random number
2655 * libraries available with different characteristics and you should pick one
2656 * of those to meet any serious needs.
2657 *
2658 * \returns a random value in the range of [0-SDL_MAX_UINT32].
2659 *
2660 * \threadsafety All calls should be made from a single thread
2661 *
2662 * \since This function is available since SDL 3.0.0.
2663 *
2664 * \sa SDL_rand
2665 * \sa SDL_randf
2666 * \sa SDL_srand
2667 */
2668extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits(void);
2669
2670/**
2671 * Generate a pseudo-random number less than n for positive n
2672 *
2673 * The method used is faster and of better quality than `rand() % n`. Odds are
2674 * roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and
2675 * much worse as n gets bigger.
2676 *
2677 * Example: to simulate a d6 use `SDL_rand_r(state, 6) + 1` The +1 converts
2678 * 0..5 to 1..6
2679 *
2680 * If you want to generate a pseudo-random number in the full range of Sint32,
2681 * you should use: (Sint32)SDL_rand_bits_r(state)
2682 *
2683 * There are no guarantees as to the quality of the random sequence produced,
2684 * and this should not be used for security (cryptography, passwords) or where
2685 * money is on the line (loot-boxes, casinos). There are many random number
2686 * libraries available with different characteristics and you should pick one
2687 * of those to meet any serious needs.
2688 *
2689 * \param state a pointer to the current random number state, this may not be
2690 * NULL.
2691 * \param n the number of possible outcomes. n must be positive.
2692 * \returns a random value in the range of [0 .. n-1].
2693 *
2694 * \threadsafety This function is thread-safe, as long as the state pointer
2695 * isn't shared between threads.
2696 *
2697 * \since This function is available since SDL 3.0.0.
2698 *
2699 * \sa SDL_rand
2700 * \sa SDL_rand_bits_r
2701 * \sa SDL_randf_r
2702 */
2703extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand_r(Uint64 *state, Sint32 n);
2704
2705/**
2706 * Generate a uniform pseudo-random floating point number less than 1.0
2707 *
2708 * If you want reproducible output, be sure to initialize with SDL_srand()
2709 * first.
2710 *
2711 * There are no guarantees as to the quality of the random sequence produced,
2712 * and this should not be used for security (cryptography, passwords) or where
2713 * money is on the line (loot-boxes, casinos). There are many random number
2714 * libraries available with different characteristics and you should pick one
2715 * of those to meet any serious needs.
2716 *
2717 * \param state a pointer to the current random number state, this may not be
2718 * NULL.
2719 * \returns a random value in the range of [0.0, 1.0).
2720 *
2721 * \threadsafety This function is thread-safe, as long as the state pointer
2722 * isn't shared between threads.
2723 *
2724 * \since This function is available since SDL 3.0.0.
2725 *
2726 * \sa SDL_rand_bits_r
2727 * \sa SDL_rand_r
2728 * \sa SDL_randf
2729 */
2730extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state);
2731
2732/**
2733 * Generate 32 pseudo-random bits.
2734 *
2735 * You likely want to use SDL_rand_r() to get a psuedo-random number instead.
2736 *
2737 * There are no guarantees as to the quality of the random sequence produced,
2738 * and this should not be used for security (cryptography, passwords) or where
2739 * money is on the line (loot-boxes, casinos). There are many random number
2740 * libraries available with different characteristics and you should pick one
2741 * of those to meet any serious needs.
2742 *
2743 * \param state a pointer to the current random number state, this may not be
2744 * NULL.
2745 * \returns a random value in the range of [0-SDL_MAX_UINT32].
2746 *
2747 * \threadsafety This function is thread-safe, as long as the state pointer
2748 * isn't shared between threads.
2749 *
2750 * \since This function is available since SDL 3.0.0.
2751 *
2752 * \sa SDL_rand_r
2753 * \sa SDL_randf_r
2754 */
2755extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state);
2756
2757
2758#ifndef SDL_PI_D
2759#define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */
2760#endif
2761#ifndef SDL_PI_F
2762#define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */
2763#endif
2764
2765/**
2766 * Compute the arc cosine of `x`.
2767 *
2768 * The definition of `y = acos(x)` is `x = cos(y)`.
2769 *
2770 * Domain: `-1 <= x <= 1`
2771 *
2772 * Range: `0 <= y <= Pi`
2773 *
2774 * This function operates on double-precision floating point values, use
2775 * SDL_acosf for single-precision floats.
2776 *
2777 * This function may use a different approximation across different versions,
2778 * platforms and configurations. i.e, it can return a different value given
2779 * the same input on different machines or operating systems, or if SDL is
2780 * updated.
2781 *
2782 * \param x floating point value.
2783 * \returns arc cosine of `x`, in radians.
2784 *
2785 * \threadsafety It is safe to call this function from any thread.
2786 *
2787 * \since This function is available since SDL 3.0.0.
2788 *
2789 * \sa SDL_acosf
2790 * \sa SDL_asin
2791 * \sa SDL_cos
2792 */
2793extern SDL_DECLSPEC double SDLCALL SDL_acos(double x);
2794
2795/**
2796 * Compute the arc cosine of `x`.
2797 *
2798 * The definition of `y = acos(x)` is `x = cos(y)`.
2799 *
2800 * Domain: `-1 <= x <= 1`
2801 *
2802 * Range: `0 <= y <= Pi`
2803 *
2804 * This function operates on single-precision floating point values, use
2805 * SDL_acos for double-precision floats.
2806 *
2807 * This function may use a different approximation across different versions,
2808 * platforms and configurations. i.e, it can return a different value given
2809 * the same input on different machines or operating systems, or if SDL is
2810 * updated.
2811 *
2812 * \param x floating point value.
2813 * \returns arc cosine of `x`, in radians.
2814 *
2815 * \threadsafety It is safe to call this function from any thread.
2816 *
2817 * \since This function is available since SDL 3.0.0.
2818 *
2819 * \sa SDL_acos
2820 * \sa SDL_asinf
2821 * \sa SDL_cosf
2822 */
2823extern SDL_DECLSPEC float SDLCALL SDL_acosf(float x);
2824
2825/**
2826 * Compute the arc sine of `x`.
2827 *
2828 * The definition of `y = asin(x)` is `x = sin(y)`.
2829 *
2830 * Domain: `-1 <= x <= 1`
2831 *
2832 * Range: `-Pi/2 <= y <= Pi/2`
2833 *
2834 * This function operates on double-precision floating point values, use
2835 * SDL_asinf for single-precision floats.
2836 *
2837 * This function may use a different approximation across different versions,
2838 * platforms and configurations. i.e, it can return a different value given
2839 * the same input on different machines or operating systems, or if SDL is
2840 * updated.
2841 *
2842 * \param x floating point value.
2843 * \returns arc sine of `x`, in radians.
2844 *
2845 * \threadsafety It is safe to call this function from any thread.
2846 *
2847 * \since This function is available since SDL 3.0.0.
2848 *
2849 * \sa SDL_asinf
2850 * \sa SDL_acos
2851 * \sa SDL_sin
2852 */
2853extern SDL_DECLSPEC double SDLCALL SDL_asin(double x);
2854
2855/**
2856 * Compute the arc sine of `x`.
2857 *
2858 * The definition of `y = asin(x)` is `x = sin(y)`.
2859 *
2860 * Domain: `-1 <= x <= 1`
2861 *
2862 * Range: `-Pi/2 <= y <= Pi/2`
2863 *
2864 * This function operates on single-precision floating point values, use
2865 * SDL_asin for double-precision floats.
2866 *
2867 * This function may use a different approximation across different versions,
2868 * platforms and configurations. i.e, it can return a different value given
2869 * the same input on different machines or operating systems, or if SDL is
2870 * updated.
2871 *
2872 * \param x floating point value.
2873 * \returns arc sine of `x`, in radians.
2874 *
2875 * \threadsafety It is safe to call this function from any thread.
2876 *
2877 * \since This function is available since SDL 3.0.0.
2878 *
2879 * \sa SDL_asin
2880 * \sa SDL_acosf
2881 * \sa SDL_sinf
2882 */
2883extern SDL_DECLSPEC float SDLCALL SDL_asinf(float x);
2884
2885/**
2886 * Compute the arc tangent of `x`.
2887 *
2888 * The definition of `y = atan(x)` is `x = tan(y)`.
2889 *
2890 * Domain: `-INF <= x <= INF`
2891 *
2892 * Range: `-Pi/2 <= y <= Pi/2`
2893 *
2894 * This function operates on double-precision floating point values, use
2895 * SDL_atanf for single-precision floats.
2896 *
2897 * To calculate the arc tangent of y / x, use SDL_atan2.
2898 *
2899 * This function may use a different approximation across different versions,
2900 * platforms and configurations. i.e, it can return a different value given
2901 * the same input on different machines or operating systems, or if SDL is
2902 * updated.
2903 *
2904 * \param x floating point value.
2905 * \returns arc tangent of of `x` in radians, or 0 if `x = 0`.
2906 *
2907 * \threadsafety It is safe to call this function from any thread.
2908 *
2909 * \since This function is available since SDL 3.0.0.
2910 *
2911 * \sa SDL_atanf
2912 * \sa SDL_atan2
2913 * \sa SDL_tan
2914 */
2915extern SDL_DECLSPEC double SDLCALL SDL_atan(double x);
2916
2917/**
2918 * Compute the arc tangent of `x`.
2919 *
2920 * The definition of `y = atan(x)` is `x = tan(y)`.
2921 *
2922 * Domain: `-INF <= x <= INF`
2923 *
2924 * Range: `-Pi/2 <= y <= Pi/2`
2925 *
2926 * This function operates on single-precision floating point values, use
2927 * SDL_atan for dboule-precision floats.
2928 *
2929 * To calculate the arc tangent of y / x, use SDL_atan2f.
2930 *
2931 * This function may use a different approximation across different versions,
2932 * platforms and configurations. i.e, it can return a different value given
2933 * the same input on different machines or operating systems, or if SDL is
2934 * updated.
2935 *
2936 * \param x floating point value.
2937 * \returns arc tangent of of `x` in radians, or 0 if `x = 0`.
2938 *
2939 * \threadsafety It is safe to call this function from any thread.
2940 *
2941 * \since This function is available since SDL 3.0.0.
2942 *
2943 * \sa SDL_atan
2944 * \sa SDL_atan2f
2945 * \sa SDL_tanf
2946 */
2947extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x);
2948
2949/**
2950 * Compute the arc tangent of `y / x`, using the signs of x and y to adjust
2951 * the result's quadrant.
2952 *
2953 * The definition of `z = atan2(x, y)` is `y = x tan(z)`, where the quadrant
2954 * of z is determined based on the signs of x and y.
2955 *
2956 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
2957 *
2958 * Range: `-Pi/2 <= y <= Pi/2`
2959 *
2960 * This function operates on double-precision floating point values, use
2961 * SDL_atan2f for single-precision floats.
2962 *
2963 * To calculate the arc tangent of a single value, use SDL_atan.
2964 *
2965 * This function may use a different approximation across different versions,
2966 * platforms and configurations. i.e, it can return a different value given
2967 * the same input on different machines or operating systems, or if SDL is
2968 * updated.
2969 *
2970 * \param y floating point value of the numerator (y coordinate).
2971 * \param x floating point value of the denominator (x coordinate).
2972 * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either
2973 * `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`.
2974 *
2975 * \threadsafety It is safe to call this function from any thread.
2976 *
2977 * \since This function is available since SDL 3.0.0.
2978 *
2979 * \sa SDL_atan2f
2980 * \sa SDL_atan
2981 * \sa SDL_tan
2982 */
2983extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x);
2984
2985/**
2986 * Compute the arc tangent of `y / x`, using the signs of x and y to adjust
2987 * the result's quadrant.
2988 *
2989 * The definition of `z = atan2(x, y)` is `y = x tan(z)`, where the quadrant
2990 * of z is determined based on the signs of x and y.
2991 *
2992 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
2993 *
2994 * Range: `-Pi/2 <= y <= Pi/2`
2995 *
2996 * This function operates on single-precision floating point values, use
2997 * SDL_atan2 for double-precision floats.
2998 *
2999 * To calculate the arc tangent of a single value, use SDL_atanf.
3000 *
3001 * This function may use a different approximation across different versions,
3002 * platforms and configurations. i.e, it can return a different value given
3003 * the same input on different machines or operating systems, or if SDL is
3004 * updated.
3005 *
3006 * \param y floating point value of the numerator (y coordinate).
3007 * \param x floating point value of the denominator (x coordinate).
3008 * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either
3009 * `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`.
3010 *
3011 * \threadsafety It is safe to call this function from any thread.
3012 *
3013 * \since This function is available since SDL 3.0.0.
3014 *
3015 * \sa SDL_atan2f
3016 * \sa SDL_atan
3017 * \sa SDL_tan
3018 */
3019extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x);
3020
3021/**
3022 * Compute the ceiling of `x`.
3023 *
3024 * The ceiling of `x` is the smallest integer `y` such that `y > x`, i.e `x`
3025 * rounded up to the nearest integer.
3026 *
3027 * Domain: `-INF <= x <= INF`
3028 *
3029 * Range: `-INF <= y <= INF`, y integer
3030 *
3031 * This function operates on double-precision floating point values, use
3032 * SDL_ceilf for single-precision floats.
3033 *
3034 * \param x floating point value.
3035 * \returns the ceiling of `x`.
3036 *
3037 * \threadsafety It is safe to call this function from any thread.
3038 *
3039 * \since This function is available since SDL 3.0.0.
3040 *
3041 * \sa SDL_ceilf
3042 * \sa SDL_floor
3043 * \sa SDL_trunc
3044 * \sa SDL_round
3045 * \sa SDL_lround
3046 */
3047extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x);
3048
3049/**
3050 * Compute the ceiling of `x`.
3051 *
3052 * The ceiling of `x` is the smallest integer `y` such that `y > x`, i.e `x`
3053 * rounded up to the nearest integer.
3054 *
3055 * Domain: `-INF <= x <= INF`
3056 *
3057 * Range: `-INF <= y <= INF`, y integer
3058 *
3059 * This function operates on single-precision floating point values, use
3060 * SDL_ceil for double-precision floats.
3061 *
3062 * \param x floating point value.
3063 * \returns the ceiling of `x`.
3064 *
3065 * \threadsafety It is safe to call this function from any thread.
3066 *
3067 * \since This function is available since SDL 3.0.0.
3068 *
3069 * \sa SDL_ceil
3070 * \sa SDL_floorf
3071 * \sa SDL_truncf
3072 * \sa SDL_roundf
3073 * \sa SDL_lroundf
3074 */
3075extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x);
3076
3077/**
3078 * Copy the sign of one floating-point value to another.
3079 *
3080 * The definition of copysign is that ``copysign(x, y) = abs(x) * sign(y)``.
3081 *
3082 * Domain: `-INF <= x <= INF`, ``-INF <= y <= f``
3083 *
3084 * Range: `-INF <= z <= INF`
3085 *
3086 * This function operates on double-precision floating point values, use
3087 * SDL_copysignf for single-precision floats.
3088 *
3089 * \param x floating point value to use as the magnitude.
3090 * \param y floating point value to use as the sign.
3091 * \returns the floating point value with the sign of y and the magnitude of
3092 * x.
3093 *
3094 * \threadsafety It is safe to call this function from any thread.
3095 *
3096 * \since This function is available since SDL 3.0.0.
3097 *
3098 * \sa SDL_copysignf
3099 * \sa SDL_fabs
3100 */
3101extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y);
3102
3103/**
3104 * Copy the sign of one floating-point value to another.
3105 *
3106 * The definition of copysign is that ``copysign(x, y) = abs(x) * sign(y)``.
3107 *
3108 * Domain: `-INF <= x <= INF`, ``-INF <= y <= f``
3109 *
3110 * Range: `-INF <= z <= INF`
3111 *
3112 * This function operates on single-precision floating point values, use
3113 * SDL_copysign for double-precision floats.
3114 *
3115 * \param x floating point value to use as the magnitude.
3116 * \param y floating point value to use as the sign.
3117 * \returns the floating point value with the sign of y and the magnitude of
3118 * x.
3119 *
3120 * \threadsafety It is safe to call this function from any thread.
3121 *
3122 * \since This function is available since SDL 3.0.0.
3123 *
3124 * \sa SDL_copysignf
3125 * \sa SDL_fabsf
3126 */
3127extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y);
3128
3129/**
3130 * Compute the cosine of `x`.
3131 *
3132 * Domain: `-INF <= x <= INF`
3133 *
3134 * Range: `-1 <= y <= 1`
3135 *
3136 * This function operates on double-precision floating point values, use
3137 * SDL_cosf for single-precision floats.
3138 *
3139 * This function may use a different approximation across different versions,
3140 * platforms and configurations. i.e, it can return a different value given
3141 * the same input on different machines or operating systems, or if SDL is
3142 * updated.
3143 *
3144 * \param x floating point value, in radians.
3145 * \returns cosine of `x`.
3146 *
3147 * \threadsafety It is safe to call this function from any thread.
3148 *
3149 * \since This function is available since SDL 3.0.0.
3150 *
3151 * \sa SDL_cosf
3152 * \sa SDL_acos
3153 * \sa SDL_sin
3154 */
3155extern SDL_DECLSPEC double SDLCALL SDL_cos(double x);
3156
3157/**
3158 * Compute the cosine of `x`.
3159 *
3160 * Domain: `-INF <= x <= INF`
3161 *
3162 * Range: `-1 <= y <= 1`
3163 *
3164 * This function operates on single-precision floating point values, use
3165 * SDL_cos for double-precision floats.
3166 *
3167 * This function may use a different approximation across different versions,
3168 * platforms and configurations. i.e, it can return a different value given
3169 * the same input on different machines or operating systems, or if SDL is
3170 * updated.
3171 *
3172 * \param x floating point value, in radians.
3173 * \returns cosine of `x`.
3174 *
3175 * \threadsafety It is safe to call this function from any thread.
3176 *
3177 * \since This function is available since SDL 3.0.0.
3178 *
3179 * \sa SDL_cos
3180 * \sa SDL_acosf
3181 * \sa SDL_sinf
3182 */
3183extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x);
3184
3185/**
3186 * Compute the exponential of `x`.
3187 *
3188 * The definition of `y = exp(x)` is `y = e^x`, where `e` is the base of the
3189 * natural logarithm. The inverse is the natural logarithm, SDL_log.
3190 *
3191 * Domain: `-INF <= x <= INF`
3192 *
3193 * Range: `0 <= y <= INF`
3194 *
3195 * The output will overflow if `exp(x)` is too large to be represented.
3196 *
3197 * This function operates on double-precision floating point values, use
3198 * SDL_expf for single-precision floats.
3199 *
3200 * This function may use a different approximation across different versions,
3201 * platforms and configurations. i.e, it can return a different value given
3202 * the same input on different machines or operating systems, or if SDL is
3203 * updated.
3204 *
3205 * \param x floating point value.
3206 * \returns value of `e^x`.
3207 *
3208 * \threadsafety It is safe to call this function from any thread.
3209 *
3210 * \since This function is available since SDL 3.0.0.
3211 *
3212 * \sa SDL_expf
3213 * \sa SDL_log
3214 */
3215extern SDL_DECLSPEC double SDLCALL SDL_exp(double x);
3216
3217/**
3218 * Compute the exponential of `x`.
3219 *
3220 * The definition of `y = exp(x)` is `y = e^x`, where `e` is the base of the
3221 * natural logarithm. The inverse is the natural logarithm, SDL_logf.
3222 *
3223 * Domain: `-INF <= x <= INF`
3224 *
3225 * Range: `0 <= y <= INF`
3226 *
3227 * The output will overflow if `exp(x)` is too large to be represented.
3228 *
3229 * This function operates on single-precision floating point values, use
3230 * SDL_exp for double-precision floats.
3231 *
3232 * This function may use a different approximation across different versions,
3233 * platforms and configurations. i.e, it can return a different value given
3234 * the same input on different machines or operating systems, or if SDL is
3235 * updated.
3236 *
3237 * \param x floating point value.
3238 * \returns value of `e^x`.
3239 *
3240 * \threadsafety It is safe to call this function from any thread.
3241 *
3242 * \since This function is available since SDL 3.0.0.
3243 *
3244 * \sa SDL_exp
3245 * \sa SDL_logf
3246 */
3247extern SDL_DECLSPEC float SDLCALL SDL_expf(float x);
3248
3249/**
3250 * Compute the absolute value of `x`
3251 *
3252 * Domain: `-INF <= x <= INF`
3253 *
3254 * Range: `0 <= y <= INF`
3255 *
3256 * This function operates on double-precision floating point values, use
3257 * SDL_copysignf for single-precision floats.
3258 *
3259 * \param x floating point value to use as the magnitude.
3260 * \returns the absolute value of `x`.
3261 *
3262 * \threadsafety It is safe to call this function from any thread.
3263 *
3264 * \since This function is available since SDL 3.0.0.
3265 *
3266 * \sa SDL_fabsf
3267 */
3268extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x);
3269
3270/**
3271 * Compute the absolute value of `x`
3272 *
3273 * Domain: `-INF <= x <= INF`
3274 *
3275 * Range: `0 <= y <= INF`
3276 *
3277 * This function operates on single-precision floating point values, use
3278 * SDL_copysignf for double-precision floats.
3279 *
3280 * \param x floating point value to use as the magnitude.
3281 * \returns the absolute value of `x`.
3282 *
3283 * \threadsafety It is safe to call this function from any thread.
3284 *
3285 * \since This function is available since SDL 3.0.0.
3286 *
3287 * \sa SDL_fabs
3288 */
3289extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x);
3290
3291/**
3292 * Compute the floor of `x`.
3293 *
3294 * The floor of `x` is the largest integer `y` such that `y > x`, i.e `x`
3295 * rounded down to the nearest integer.
3296 *
3297 * Domain: `-INF <= x <= INF`
3298 *
3299 * Range: `-INF <= y <= INF`, y integer
3300 *
3301 * This function operates on double-precision floating point values, use
3302 * SDL_floorf for single-precision floats.
3303 *
3304 * \param x floating point value.
3305 * \returns the floor of `x`.
3306 *
3307 * \threadsafety It is safe to call this function from any thread.
3308 *
3309 * \since This function is available since SDL 3.0.0.
3310 *
3311 * \sa SDL_floorf
3312 * \sa SDL_ceil
3313 * \sa SDL_trunc
3314 * \sa SDL_round
3315 * \sa SDL_lround
3316 */
3317extern SDL_DECLSPEC double SDLCALL SDL_floor(double x);
3318
3319/**
3320 * Compute the floor of `x`.
3321 *
3322 * The floor of `x` is the largest integer `y` such that `y > x`, i.e `x`
3323 * rounded down to the nearest integer.
3324 *
3325 * Domain: `-INF <= x <= INF`
3326 *
3327 * Range: `-INF <= y <= INF`, y integer
3328 *
3329 * This function operates on single-precision floating point values, use
3330 * SDL_floorf for double-precision floats.
3331 *
3332 * \param x floating point value.
3333 * \returns the floor of `x`.
3334 *
3335 * \threadsafety It is safe to call this function from any thread.
3336 *
3337 * \since This function is available since SDL 3.0.0.
3338 *
3339 * \sa SDL_floor
3340 * \sa SDL_ceilf
3341 * \sa SDL_truncf
3342 * \sa SDL_roundf
3343 * \sa SDL_lroundf
3344 */
3345extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x);
3346
3347/**
3348 * Truncate `x` to an integer.
3349 *
3350 * Rounds `x` to the next closest integer to 0. This is equivalent to removing
3351 * the fractional part of `x`, leaving only the integer part.
3352 *
3353 * Domain: `-INF <= x <= INF`
3354 *
3355 * Range: `-INF <= y <= INF`, y integer
3356 *
3357 * This function operates on double-precision floating point values, use
3358 * SDL_truncf for single-precision floats.
3359 *
3360 * \param x floating point value.
3361 * \returns `x` truncated to an integer.
3362 *
3363 * \threadsafety It is safe to call this function from any thread.
3364 *
3365 * \since This function is available since SDL 3.0.0.
3366 *
3367 * \sa SDL_truncf
3368 * \sa SDL_fmod
3369 * \sa SDL_ceil
3370 * \sa SDL_floor
3371 * \sa SDL_round
3372 * \sa SDL_lround
3373 */
3374extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x);
3375
3376/**
3377 * Truncate `x` to an integer.
3378 *
3379 * Rounds `x` to the next closest integer to 0. This is equivalent to removing
3380 * the fractional part of `x`, leaving only the integer part.
3381 *
3382 * Domain: `-INF <= x <= INF`
3383 *
3384 * Range: `-INF <= y <= INF`, y integer
3385 *
3386 * This function operates on single-precision floating point values, use
3387 * SDL_truncf for double-precision floats.
3388 *
3389 * \param x floating point value.
3390 * \returns `x` truncated to an integer.
3391 *
3392 * \threadsafety It is safe to call this function from any thread.
3393 *
3394 * \since This function is available since SDL 3.0.0.
3395 *
3396 * \sa SDL_trunc
3397 * \sa SDL_fmodf
3398 * \sa SDL_ceilf
3399 * \sa SDL_floorf
3400 * \sa SDL_roundf
3401 * \sa SDL_lroundf
3402 */
3403extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x);
3404
3405/**
3406 * Return the floating-point remainder of `x / y`
3407 *
3408 * Divides `x` by `y`, and returns the remainder.
3409 *
3410 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`, `y != 0`
3411 *
3412 * Range: `-y <= z <= y`
3413 *
3414 * This function operates on double-precision floating point values, use
3415 * SDL_fmodf for single-precision floats.
3416 *
3417 * \param x the numerator.
3418 * \param y the denominator. Must not be 0.
3419 * \returns the remainder of `x / y`.
3420 *
3421 * \threadsafety It is safe to call this function from any thread.
3422 *
3423 * \since This function is available since SDL 3.0.0.
3424 *
3425 * \sa SDL_fmodf
3426 * \sa SDL_modf
3427 * \sa SDL_trunc
3428 * \sa SDL_ceil
3429 * \sa SDL_floor
3430 * \sa SDL_round
3431 * \sa SDL_lround
3432 */
3433extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y);
3434
3435/**
3436 * Return the floating-point remainder of `x / y`
3437 *
3438 * Divides `x` by `y`, and returns the remainder.
3439 *
3440 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`, `y != 0`
3441 *
3442 * Range: `-y <= z <= y`
3443 *
3444 * This function operates on single-precision floating point values, use
3445 * SDL_fmod for single-precision floats.
3446 *
3447 * \param x the numerator.
3448 * \param y the denominator. Must not be 0.
3449 * \returns the remainder of `x / y`.
3450 *
3451 * \threadsafety It is safe to call this function from any thread.
3452 *
3453 * \since This function is available since SDL 3.0.0.
3454 *
3455 * \sa SDL_fmod
3456 * \sa SDL_truncf
3457 * \sa SDL_modff
3458 * \sa SDL_ceilf
3459 * \sa SDL_floorf
3460 * \sa SDL_roundf
3461 * \sa SDL_lroundf
3462 */
3463extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y);
3464
3465/**
3466 * Return whether the value is infinity.
3467 *
3468 * \param x double-precision floating point value.
3469 * \returns non-zero if the value is infinity, 0 otherwise.
3470 *
3471 * \threadsafety It is safe to call this function from any thread.
3472 *
3473 * \since This function is available since SDL 3.0.0.
3474 *
3475 * \sa SDL_isinff
3476 */
3477extern SDL_DECLSPEC int SDLCALL SDL_isinf(double x);
3478
3479/**
3480 * Return whether the value is infinity.
3481 *
3482 * \param x floating point value.
3483 * \returns non-zero if the value is infinity, 0 otherwise.
3484 *
3485 * \threadsafety It is safe to call this function from any thread.
3486 *
3487 * \since This function is available since SDL 3.0.0.
3488 *
3489 * \sa SDL_isinf
3490 */
3491extern SDL_DECLSPEC int SDLCALL SDL_isinff(float x);
3492
3493/**
3494 * Return whether the value is NaN.
3495 *
3496 * \param x double-precision floating point value.
3497 * \returns non-zero if the value is NaN, 0 otherwise.
3498 *
3499 * \threadsafety It is safe to call this function from any thread.
3500 *
3501 * \since This function is available since SDL 3.0.0.
3502 *
3503 * \sa SDL_isnanf
3504 */
3505extern SDL_DECLSPEC int SDLCALL SDL_isnan(double x);
3506
3507/**
3508 * Return whether the value is NaN.
3509 *
3510 * \param x floating point value.
3511 * \returns non-zero if the value is NaN, 0 otherwise.
3512 *
3513 * \threadsafety It is safe to call this function from any thread.
3514 *
3515 * \since This function is available since SDL 3.0.0.
3516 *
3517 * \sa SDL_isnan
3518 */
3519extern SDL_DECLSPEC int SDLCALL SDL_isnanf(float x);
3520
3521/**
3522 * Compute the natural logarithm of `x`.
3523 *
3524 * Domain: `0 < x <= INF`
3525 *
3526 * Range: `-INF <= y <= INF`
3527 *
3528 * It is an error for `x` to be less than or equal to 0.
3529 *
3530 * This function operates on double-precision floating point values, use
3531 * SDL_logf for single-precision floats.
3532 *
3533 * This function may use a different approximation across different versions,
3534 * platforms and configurations. i.e, it can return a different value given
3535 * the same input on different machines or operating systems, or if SDL is
3536 * updated.
3537 *
3538 * \param x floating point value. Must be greater than 0.
3539 * \returns the natural logarithm of `x`.
3540 *
3541 * \threadsafety It is safe to call this function from any thread.
3542 *
3543 * \since This function is available since SDL 3.0.0.
3544 *
3545 * \sa SDL_logf
3546 * \sa SDL_log10
3547 * \sa SDL_exp
3548 */
3549extern SDL_DECLSPEC double SDLCALL SDL_log(double x);
3550
3551/**
3552 * Compute the natural logarithm of `x`.
3553 *
3554 * Domain: `0 < x <= INF`
3555 *
3556 * Range: `-INF <= y <= INF`
3557 *
3558 * It is an error for `x` to be less than or equal to 0.
3559 *
3560 * This function operates on single-precision floating point values, use
3561 * SDL_log for double-precision floats.
3562 *
3563 * This function may use a different approximation across different versions,
3564 * platforms and configurations. i.e, it can return a different value given
3565 * the same input on different machines or operating systems, or if SDL is
3566 * updated.
3567 *
3568 * \param x floating point value. Must be greater than 0.
3569 * \returns the natural logarithm of `x`.
3570 *
3571 * \threadsafety It is safe to call this function from any thread.
3572 *
3573 * \since This function is available since SDL 3.0.0.
3574 *
3575 * \sa SDL_log
3576 * \sa SDL_expf
3577 */
3578extern SDL_DECLSPEC float SDLCALL SDL_logf(float x);
3579
3580/**
3581 * Compute the base-10 logarithm of `x`.
3582 *
3583 * Domain: `0 < x <= INF`
3584 *
3585 * Range: `-INF <= y <= INF`
3586 *
3587 * It is an error for `x` to be less than or equal to 0.
3588 *
3589 * This function operates on double-precision floating point values, use
3590 * SDL_log10f for single-precision floats.
3591 *
3592 * This function may use a different approximation across different versions,
3593 * platforms and configurations. i.e, it can return a different value given
3594 * the same input on different machines or operating systems, or if SDL is
3595 * updated.
3596 *
3597 * \param x floating point value. Must be greater than 0.
3598 * \returns the logarithm of `x`.
3599 *
3600 * \threadsafety It is safe to call this function from any thread.
3601 *
3602 * \since This function is available since SDL 3.0.0.
3603 *
3604 * \sa SDL_log10f
3605 * \sa SDL_log
3606 * \sa SDL_pow
3607 */
3608extern SDL_DECLSPEC double SDLCALL SDL_log10(double x);
3609
3610/**
3611 * Compute the base-10 logarithm of `x`.
3612 *
3613 * Domain: `0 < x <= INF`
3614 *
3615 * Range: `-INF <= y <= INF`
3616 *
3617 * It is an error for `x` to be less than or equal to 0.
3618 *
3619 * This function operates on single-precision floating point values, use
3620 * SDL_log10 for double-precision floats.
3621 *
3622 * This function may use a different approximation across different versions,
3623 * platforms and configurations. i.e, it can return a different value given
3624 * the same input on different machines or operating systems, or if SDL is
3625 * updated.
3626 *
3627 * \param x floating point value. Must be greater than 0.
3628 * \returns the logarithm of `x`.
3629 *
3630 * \threadsafety It is safe to call this function from any thread.
3631 *
3632 * \since This function is available since SDL 3.0.0.
3633 *
3634 * \sa SDL_log10
3635 * \sa SDL_logf
3636 * \sa SDL_powf
3637 */
3638extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x);
3639
3640/**
3641 * Split `x` into integer and fractional parts
3642 *
3643 * This function operates on double-precision floating point values, use
3644 * SDL_modff for single-precision floats.
3645 *
3646 * \param x floating point value.
3647 * \param y output pointer to store the integer part of `x`.
3648 * \returns the fractional part of `x`.
3649 *
3650 * \threadsafety It is safe to call this function from any thread.
3651 *
3652 * \since This function is available since SDL 3.0.0.
3653 *
3654 * \sa SDL_modff
3655 * \sa SDL_trunc
3656 * \sa SDL_fmod
3657 */
3658extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y);
3659
3660/**
3661 * Split `x` into integer and fractional parts
3662 *
3663 * This function operates on single-precision floating point values, use
3664 * SDL_modf for double-precision floats.
3665 *
3666 * \param x floating point value.
3667 * \param y output pointer to store the integer part of `x`.
3668 * \returns the fractional part of `x`.
3669 *
3670 * \threadsafety It is safe to call this function from any thread.
3671 *
3672 * \since This function is available since SDL 3.0.0.
3673 *
3674 * \sa SDL_modf
3675 * \sa SDL_truncf
3676 * \sa SDL_fmodf
3677 */
3678extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y);
3679
3680/**
3681 * Raise `x` to the power `y`
3682 *
3683 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
3684 *
3685 * Range: `-INF <= z <= INF`
3686 *
3687 * If `y` is the base of the natural logarithm (e), consider using SDL_exp
3688 * instead.
3689 *
3690 * This function operates on double-precision floating point values, use
3691 * SDL_powf for single-precision floats.
3692 *
3693 * This function may use a different approximation across different versions,
3694 * platforms and configurations. i.e, it can return a different value given
3695 * the same input on different machines or operating systems, or if SDL is
3696 * updated.
3697 *
3698 * \param x the base.
3699 * \param y the exponent.
3700 * \returns `x` raised to the power `y`.
3701 *
3702 * \threadsafety It is safe to call this function from any thread.
3703 *
3704 * \since This function is available since SDL 3.0.0.
3705 *
3706 * \sa SDL_powf
3707 * \sa SDL_exp
3708 * \sa SDL_log
3709 */
3710extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y);
3711
3712/**
3713 * Raise `x` to the power `y`
3714 *
3715 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
3716 *
3717 * Range: `-INF <= z <= INF`
3718 *
3719 * If `y` is the base of the natural logarithm (e), consider using SDL_exp
3720 * instead.
3721 *
3722 * This function operates on single-precision floating point values, use
3723 * SDL_powf for double-precision floats.
3724 *
3725 * This function may use a different approximation across different versions,
3726 * platforms and configurations. i.e, it can return a different value given
3727 * the same input on different machines or operating systems, or if SDL is
3728 * updated.
3729 *
3730 * \param x the base.
3731 * \param y the exponent.
3732 * \returns `x` raised to the power `y`.
3733 *
3734 * \threadsafety It is safe to call this function from any thread.
3735 *
3736 * \since This function is available since SDL 3.0.0.
3737 *
3738 * \sa SDL_pow
3739 * \sa SDL_expf
3740 * \sa SDL_logf
3741 */
3742extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y);
3743
3744/**
3745 * Round `x` to the nearest integer.
3746 *
3747 * Rounds `x` to the nearest integer. Values halfway between integers will be
3748 * rounded away from zero.
3749 *
3750 * Domain: `-INF <= x <= INF`
3751 *
3752 * Range: `-INF <= y <= INF`, y integer
3753 *
3754 * This function operates on double-precision floating point values, use
3755 * SDL_roundf for single-precision floats. To get the result as an integer
3756 * type, use SDL_lround.
3757 *
3758 * \param x floating point value.
3759 * \returns the nearest integer to `x`.
3760 *
3761 * \threadsafety It is safe to call this function from any thread.
3762 *
3763 * \since This function is available since SDL 3.0.0.
3764 *
3765 * \sa SDL_roundf
3766 * \sa SDL_lround
3767 * \sa SDL_floor
3768 * \sa SDL_ceil
3769 * \sa SDL_trunc
3770 */
3771extern SDL_DECLSPEC double SDLCALL SDL_round(double x);
3772
3773/**
3774 * Round `x` to the nearest integer.
3775 *
3776 * Rounds `x` to the nearest integer. Values halfway between integers will be
3777 * rounded away from zero.
3778 *
3779 * Domain: `-INF <= x <= INF`
3780 *
3781 * Range: `-INF <= y <= INF`, y integer
3782 *
3783 * This function operates on double-precision floating point values, use
3784 * SDL_roundf for single-precision floats. To get the result as an integer
3785 * type, use SDL_lroundf.
3786 *
3787 * \param x floating point value.
3788 * \returns the nearest integer to `x`.
3789 *
3790 * \threadsafety It is safe to call this function from any thread.
3791 *
3792 * \since This function is available since SDL 3.0.0.
3793 *
3794 * \sa SDL_round
3795 * \sa SDL_lroundf
3796 * \sa SDL_floorf
3797 * \sa SDL_ceilf
3798 * \sa SDL_truncf
3799 */
3800extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x);
3801
3802/**
3803 * Round `x` to the nearest integer representable as a long
3804 *
3805 * Rounds `x` to the nearest integer. Values halfway between integers will be
3806 * rounded away from zero.
3807 *
3808 * Domain: `-INF <= x <= INF`
3809 *
3810 * Range: `MIN_LONG <= y <= MAX_LONG`
3811 *
3812 * This function operates on double-precision floating point values, use
3813 * SDL_lround for single-precision floats. To get the result as a
3814 * floating-point type, use SDL_round.
3815 *
3816 * \param x floating point value.
3817 * \returns the nearest integer to `x`.
3818 *
3819 * \threadsafety It is safe to call this function from any thread.
3820 *
3821 * \since This function is available since SDL 3.0.0.
3822 *
3823 * \sa SDL_lroundf
3824 * \sa SDL_round
3825 * \sa SDL_floor
3826 * \sa SDL_ceil
3827 * \sa SDL_trunc
3828 */
3829extern SDL_DECLSPEC long SDLCALL SDL_lround(double x);
3830
3831/**
3832 * Round `x` to the nearest integer representable as a long
3833 *
3834 * Rounds `x` to the nearest integer. Values halfway between integers will be
3835 * rounded away from zero.
3836 *
3837 * Domain: `-INF <= x <= INF`
3838 *
3839 * Range: `MIN_LONG <= y <= MAX_LONG`
3840 *
3841 * This function operates on single-precision floating point values, use
3842 * SDL_lroundf for double-precision floats. To get the result as a
3843 * floating-point type, use SDL_roundf,
3844 *
3845 * \param x floating point value.
3846 * \returns the nearest integer to `x`.
3847 *
3848 * \threadsafety It is safe to call this function from any thread.
3849 *
3850 * \since This function is available since SDL 3.0.0.
3851 *
3852 * \sa SDL_lround
3853 * \sa SDL_roundf
3854 * \sa SDL_floorf
3855 * \sa SDL_ceilf
3856 * \sa SDL_truncf
3857 */
3858extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x);
3859
3860/**
3861 * Scale `x` by an integer power of two.
3862 *
3863 * Multiplies `x` by the `n`th power of the floating point radix (always 2).
3864 *
3865 * Domain: `-INF <= x <= INF`, `n` integer
3866 *
3867 * Range: `-INF <= y <= INF`
3868 *
3869 * This function operates on double-precision floating point values, use
3870 * SDL_scalbnf for single-precision floats.
3871 *
3872 * \param x floating point value to be scaled.
3873 * \param n integer exponent.
3874 * \returns `x * 2^n`.
3875 *
3876 * \threadsafety It is safe to call this function from any thread.
3877 *
3878 * \since This function is available since SDL 3.0.0.
3879 *
3880 * \sa SDL_scalbnf
3881 * \sa SDL_pow
3882 */
3883extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n);
3884
3885/**
3886 * Scale `x` by an integer power of two.
3887 *
3888 * Multiplies `x` by the `n`th power of the floating point radix (always 2).
3889 *
3890 * Domain: `-INF <= x <= INF`, `n` integer
3891 *
3892 * Range: `-INF <= y <= INF`
3893 *
3894 * This function operates on single-precision floating point values, use
3895 * SDL_scalbn for double-precision floats.
3896 *
3897 * \param x floating point value to be scaled.
3898 * \param n integer exponent.
3899 * \returns `x * 2^n`.
3900 *
3901 * \threadsafety It is safe to call this function from any thread.
3902 *
3903 * \since This function is available since SDL 3.0.0.
3904 *
3905 * \sa SDL_scalbn
3906 * \sa SDL_powf
3907 */
3908extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n);
3909
3910/**
3911 * Compute the sine of `x`.
3912 *
3913 * Domain: `-INF <= x <= INF`
3914 *
3915 * Range: `-1 <= y <= 1`
3916 *
3917 * This function operates on double-precision floating point values, use
3918 * SDL_sinf for single-precision floats.
3919 *
3920 * This function may use a different approximation across different versions,
3921 * platforms and configurations. i.e, it can return a different value given
3922 * the same input on different machines or operating systems, or if SDL is
3923 * updated.
3924 *
3925 * \param x floating point value, in radians.
3926 * \returns sine of `x`.
3927 *
3928 * \threadsafety It is safe to call this function from any thread.
3929 *
3930 * \since This function is available since SDL 3.0.0.
3931 *
3932 * \sa SDL_sinf
3933 * \sa SDL_asin
3934 * \sa SDL_cos
3935 */
3936extern SDL_DECLSPEC double SDLCALL SDL_sin(double x);
3937
3938/**
3939 * Compute the sine of `x`.
3940 *
3941 * Domain: `-INF <= x <= INF`
3942 *
3943 * Range: `-1 <= y <= 1`
3944 *
3945 * This function operates on single-precision floating point values, use
3946 * SDL_sinf for double-precision floats.
3947 *
3948 * This function may use a different approximation across different versions,
3949 * platforms and configurations. i.e, it can return a different value given
3950 * the same input on different machines or operating systems, or if SDL is
3951 * updated.
3952 *
3953 * \param x floating point value, in radians.
3954 * \returns sine of `x`.
3955 *
3956 * \threadsafety It is safe to call this function from any thread.
3957 *
3958 * \since This function is available since SDL 3.0.0.
3959 *
3960 * \sa SDL_sin
3961 * \sa SDL_asinf
3962 * \sa SDL_cosf
3963 */
3964extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x);
3965
3966/**
3967 * Compute the square root of `x`.
3968 *
3969 * Domain: `0 <= x <= INF`
3970 *
3971 * Range: `0 <= y <= INF`
3972 *
3973 * This function operates on double-precision floating point values, use
3974 * SDL_sqrtf for single-precision floats.
3975 *
3976 * This function may use a different approximation across different versions,
3977 * platforms and configurations. i.e, it can return a different value given
3978 * the same input on different machines or operating systems, or if SDL is
3979 * updated.
3980 *
3981 * \param x floating point value. Must be greater than or equal to 0.
3982 * \returns square root of `x`.
3983 *
3984 * \threadsafety It is safe to call this function from any thread.
3985 *
3986 * \since This function is available since SDL 3.0.0.
3987 *
3988 * \sa SDL_sqrtf
3989 */
3990extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x);
3991
3992/**
3993 * Compute the square root of `x`.
3994 *
3995 * Domain: `0 <= x <= INF`
3996 *
3997 * Range: `0 <= y <= INF`
3998 *
3999 * This function operates on single-precision floating point values, use
4000 * SDL_sqrt for double-precision floats.
4001 *
4002 * This function may use a different approximation across different versions,
4003 * platforms and configurations. i.e, it can return a different value given
4004 * the same input on different machines or operating systems, or if SDL is
4005 * updated.
4006 *
4007 * \param x floating point value. Must be greater than or equal to 0.
4008 * \returns square root of `x`.
4009 *
4010 * \threadsafety It is safe to call this function from any thread.
4011 *
4012 * \since This function is available since SDL 3.0.0.
4013 *
4014 * \sa SDL_sqrt
4015 */
4016extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x);
4017
4018/**
4019 * Compute the tangent of `x`.
4020 *
4021 * Domain: `-INF <= x <= INF`
4022 *
4023 * Range: `-INF <= y <= INF`
4024 *
4025 * This function operates on double-precision floating point values, use
4026 * SDL_tanf for single-precision floats.
4027 *
4028 * This function may use a different approximation across different versions,
4029 * platforms and configurations. i.e, it can return a different value given
4030 * the same input on different machines or operating systems, or if SDL is
4031 * updated.
4032 *
4033 * \param x floating point value, in radians.
4034 * \returns tangent of `x`.
4035 *
4036 * \threadsafety It is safe to call this function from any thread.
4037 *
4038 * \since This function is available since SDL 3.0.0.
4039 *
4040 * \sa SDL_tanf
4041 * \sa SDL_sin
4042 * \sa SDL_cos
4043 * \sa SDL_atan
4044 * \sa SDL_atan2
4045 */
4046extern SDL_DECLSPEC double SDLCALL SDL_tan(double x);
4047
4048/**
4049 * Compute the tangent of `x`.
4050 *
4051 * Domain: `-INF <= x <= INF`
4052 *
4053 * Range: `-INF <= y <= INF`
4054 *
4055 * This function operates on single-precision floating point values, use
4056 * SDL_tanf for double-precision floats.
4057 *
4058 * This function may use a different approximation across different versions,
4059 * platforms and configurations. i.e, it can return a different value given
4060 * the same input on different machines or operating systems, or if SDL is
4061 * updated.
4062 *
4063 * \param x floating point value, in radians.
4064 * \returns tangent of `x`.
4065 *
4066 * \threadsafety It is safe to call this function from any thread.
4067 *
4068 * \since This function is available since SDL 3.0.0.
4069 *
4070 * \sa SDL_tan
4071 * \sa SDL_sinf
4072 * \sa SDL_cosf
4073 * \sa SDL_atanf
4074 * \sa SDL_atan2f
4075 */
4076extern SDL_DECLSPEC float SDLCALL SDL_tanf(float x);
4077
4078/* The SDL implementation of iconv() returns these error codes */
4079#define SDL_ICONV_ERROR (size_t)-1
4080#define SDL_ICONV_E2BIG (size_t)-2
4081#define SDL_ICONV_EILSEQ (size_t)-3
4082#define SDL_ICONV_EINVAL (size_t)-4
4083
4084typedef struct SDL_iconv_data_t *SDL_iconv_t;
4085
4086/**
4087 * This function allocates a context for the specified character set
4088 * conversion.
4089 *
4090 * \param tocode The target character encoding, must not be NULL.
4091 * \param fromcode The source character encoding, must not be NULL.
4092 * \returns a handle that must be freed with SDL_iconv_close, or
4093 * SDL_ICONV_ERROR on failure.
4094 *
4095 * \since This function is available since SDL 3.0.0.
4096 *
4097 * \sa SDL_iconv
4098 * \sa SDL_iconv_close
4099 * \sa SDL_iconv_string
4100 */
4101extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode,
4102 const char *fromcode);
4103
4104/**
4105 * This function frees a context used for character set conversion.
4106 *
4107 * \param cd The character set conversion handle.
4108 * \returns 0 on success, or -1 on failure.
4109 *
4110 * \since This function is available since SDL 3.0.0.
4111 *
4112 * \sa SDL_iconv
4113 * \sa SDL_iconv_open
4114 * \sa SDL_iconv_string
4115 */
4116extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd);
4117
4118/**
4119 * This function converts text between encodings, reading from and writing to
4120 * a buffer.
4121 *
4122 * It returns the number of succesful conversions.
4123 *
4124 * \param cd The character set conversion context, created in
4125 * SDL_iconv_open().
4126 * \param inbuf Address of variable that points to the first character of the
4127 * input sequence.
4128 * \param inbytesleft The number of bytes in the input buffer.
4129 * \param outbuf Address of variable that points to the output buffer.
4130 * \param outbytesleft The number of bytes in the output buffer.
4131 * \returns the number of conversions on success, else SDL_ICONV_E2BIG is
4132 * returned when the output buffer is too small, or SDL_ICONV_EILSEQ
4133 * is returned when an invalid input sequence is encountered, or
4134 * SDL_ICONV_EINVAL is returned when an incomplete input sequence is
4135 * encountered.
4136 *
4137 * On exit:
4138 *
4139 * - inbuf will point to the beginning of the next multibyte
4140 * sequence. On error, this is the location of the problematic
4141 * input sequence. On success, this is the end of the input
4142 * sequence. - inbytesleft will be set to the number of bytes left
4143 * to convert, which will be 0 on success. - outbuf will point to
4144 * the location where to store the next output byte. - outbytesleft
4145 * will be set to the number of bytes left in the output buffer.
4146 *
4147 * \since This function is available since SDL 3.0.0.
4148 *
4149 * \sa SDL_iconv_open
4150 * \sa SDL_iconv_close
4151 * \sa SDL_iconv_string
4152 */
4153extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
4154 size_t *inbytesleft, char **outbuf,
4155 size_t *outbytesleft);
4156
4157/**
4158 * Helper function to convert a string's encoding in one call.
4159 *
4160 * This function converts a buffer or string between encodings in one pass.
4161 *
4162 * The string does not need to be NULL-terminated; this function operates on
4163 * the number of bytes specified in `inbytesleft` whether there is a NULL
4164 * character anywhere in the buffer.
4165 *
4166 * The returned string is owned by the caller, and should be passed to
4167 * SDL_free when no longer needed.
4168 *
4169 * \param tocode the character encoding of the output string. Examples are
4170 * "UTF-8", "UCS-4", etc.
4171 * \param fromcode the character encoding of data in `inbuf`.
4172 * \param inbuf the string to convert to a different encoding.
4173 * \param inbytesleft the size of the input string _in bytes_.
4174 * \returns a new string, converted to the new encoding, or NULL on error.
4175 *
4176 * \since This function is available since SDL 3.0.0.
4177 *
4178 * \sa SDL_iconv_open
4179 * \sa SDL_iconv_close
4180 * \sa SDL_iconv
4181 */
4182extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode,
4183 const char *fromcode,
4184 const char *inbuf,
4185 size_t inbytesleft);
4186
4187/* Some helper macros for common cases... */
4188#define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1)
4189#define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1)
4190#define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1)
4191#define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", (char *)S, (SDL_wcslen(S)+1)*sizeof(wchar_t))
4192
4193/* force builds using Clang's static analysis tools to use literal C runtime
4194 here, since there are possibly tests that are ineffective otherwise. */
4195#if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS)
4196
4197/* The analyzer knows about strlcpy even when the system doesn't provide it */
4198#if !defined(HAVE_STRLCPY) && !defined(strlcpy)
4199size_t strlcpy(char *dst, const char *src, size_t size);
4200#endif
4201
4202/* The analyzer knows about strlcat even when the system doesn't provide it */
4203#if !defined(HAVE_STRLCAT) && !defined(strlcat)
4204size_t strlcat(char *dst, const char *src, size_t size);
4205#endif
4206
4207#if !defined(HAVE_WCSLCPY) && !defined(wcslcpy)
4208size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size);
4209#endif
4210
4211#if !defined(HAVE_WCSLCAT) && !defined(wcslcat)
4212size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size);
4213#endif
4214
4215/* Starting LLVM 16, the analyser errors out if these functions do not have
4216 their prototype defined (clang-diagnostic-implicit-function-declaration) */
4217#include <stdio.h>
4218#include <stdlib.h>
4219#include <strings.h>
4220
4221#define SDL_malloc malloc
4222#define SDL_calloc calloc
4223#define SDL_realloc realloc
4224#define SDL_free free
4225#ifndef SDL_memcpy
4226#define SDL_memcpy memcpy
4227#endif
4228#ifndef SDL_memmove
4229#define SDL_memmove memmove
4230#endif
4231#ifndef SDL_memset
4232#define SDL_memset memset
4233#endif
4234#define SDL_memcmp memcmp
4235#define SDL_strlcpy strlcpy
4236#define SDL_strlcat strlcat
4237#define SDL_strlen strlen
4238#define SDL_wcslen wcslen
4239#define SDL_wcslcpy wcslcpy
4240#define SDL_wcslcat wcslcat
4241#define SDL_strdup strdup
4242#define SDL_wcsdup wcsdup
4243#define SDL_strchr strchr
4244#define SDL_strrchr strrchr
4245#define SDL_strstr strstr
4246#define SDL_wcsstr wcsstr
4247#define SDL_strtok_r strtok_r
4248#define SDL_strcmp strcmp
4249#define SDL_wcscmp wcscmp
4250#define SDL_strncmp strncmp
4251#define SDL_wcsncmp wcsncmp
4252#define SDL_strcasecmp strcasecmp
4253#define SDL_strncasecmp strncasecmp
4254#define SDL_strpbrk strpbrk
4255#define SDL_sscanf sscanf
4256#define SDL_vsscanf vsscanf
4257#define SDL_snprintf snprintf
4258#define SDL_vsnprintf vsnprintf
4259#endif
4260
4261/**
4262 * Multiply two integers, checking for overflow.
4263 *
4264 * If `a * b` would overflow, return false.
4265 *
4266 * Otherwise store `a * b` via ret and return true.
4267 *
4268 * \param a the multiplicand.
4269 * \param b the multiplier.
4270 * \param ret on non-overflow output, stores the multiplication result, may
4271 * not be NULL.
4272 * \returns false on overflow, true if result is multiplied without overflow.
4273 *
4274 * \threadsafety It is safe to call this function from any thread.
4275 *
4276 * \since This function is available since SDL 3.0.0.
4277 */
4278SDL_FORCE_INLINE bool SDL_size_mul_check_overflow(size_t a, size_t b, size_t *ret)
4279{
4280 if (a != 0 && b > SDL_SIZE_MAX / a) {
4281 return false;
4282 }
4283 *ret = a * b;
4284 return true;
4285}
4286
4287#ifndef SDL_WIKI_DOCUMENTATION_SECTION
4288#if SDL_HAS_BUILTIN(__builtin_mul_overflow)
4289/* This needs to be wrapped in an inline rather than being a direct #define,
4290 * because __builtin_mul_overflow() is type-generic, but we want to be
4291 * consistent about interpreting a and b as size_t. */
4292SDL_FORCE_INLINE bool SDL_size_mul_check_overflow_builtin(size_t a, size_t b, size_t *ret)
4293{
4294 return (__builtin_mul_overflow(a, b, ret) == 0);
4295}
4296#define SDL_size_mul_check_overflow(a, b, ret) SDL_size_mul_check_overflow_builtin(a, b, ret)
4297#endif
4298#endif
4299
4300/**
4301 * Add two integers, checking for overflow.
4302 *
4303 * If `a + b` would overflow, return -1.
4304 *
4305 * Otherwise store `a + b` via ret and return 0.
4306 *
4307 * \param a the first addend.
4308 * \param b the second addend.
4309 * \param ret on non-overflow output, stores the addition result, may not be
4310 * NULL.
4311 * \returns false on overflow, true if result is added without overflow.
4312 *
4313 * \threadsafety It is safe to call this function from any thread.
4314 *
4315 * \since This function is available since SDL 3.0.0.
4316 */
4317SDL_FORCE_INLINE bool SDL_size_add_check_overflow(size_t a, size_t b, size_t *ret)
4318{
4319 if (b > SDL_SIZE_MAX - a) {
4320 return false;
4321 }
4322 *ret = a + b;
4323 return true;
4324}
4325
4326#ifndef SDL_WIKI_DOCUMENTATION_SECTION
4327#if SDL_HAS_BUILTIN(__builtin_add_overflow)
4328/* This needs to be wrapped in an inline rather than being a direct #define,
4329 * the same as the call to __builtin_mul_overflow() above. */
4330SDL_FORCE_INLINE bool SDL_size_add_check_overflow_builtin(size_t a, size_t b, size_t *ret)
4331{
4332 return (__builtin_add_overflow(a, b, ret) == 0);
4333}
4334#define SDL_size_add_check_overflow(a, b, ret) SDL_size_add_check_overflow_builtin(a, b, ret)
4335#endif
4336#endif
4337
4338/* This is a generic function pointer which should be cast to the type you expect */
4339#ifdef SDL_WIKI_DOCUMENTATION_SECTION
4340
4341/**
4342 * A generic function pointer.
4343 *
4344 * In theory, generic function pointers should use this, instead of `void *`,
4345 * since some platforms could treat code addresses differently than data
4346 * addresses. Although in current times no popular platforms make this
4347 * distinction, it is more correct and portable to use the correct type for a
4348 * generic pointer.
4349 *
4350 * If for some reason you need to force this typedef to be an actual `void *`,
4351 * perhaps to work around a compiler or existing code, you can define
4352 * `SDL_FUNCTION_POINTER_IS_VOID_POINTER` before including any SDL headers.
4353 *
4354 * \since This datatype is available since SDL 3.0.0.
4355 */
4356typedef void (*SDL_FunctionPointer)(void);
4357#elif defined(SDL_FUNCTION_POINTER_IS_VOID_POINTER)
4358typedef void *SDL_FunctionPointer;
4359#else
4360typedef void (*SDL_FunctionPointer)(void);
4361#endif
4362
4363/* Ends C function definitions when using C++ */
4364#ifdef __cplusplus
4365}
4366#endif
4367#include <SDL3/SDL_close_code.h>
4368
4369#endif /* SDL_stdinc_h_ */
#define SDL_ALLOC_SIZE(p)
#define SDL_ALLOC_SIZE2(p1, p2)
#define SDL_FORCE_INLINE
#define SDL_MALLOC
void SDL_DestroyEnvironment(SDL_Environment *env)
wchar_t * SDL_wcsdup(const wchar_t *wstr)
double SDL_sqrt(double x)
int SDL_atoi(const char *str)
#define SDL_memset
SDL_iconv_t SDL_iconv_open(const char *tocode, const char *fromcode)
unsigned long long SDL_strtoull(const char *str, char **endp, int base)
float SDL_tanf(float x)
bool SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, SDL_calloc_func calloc_func, SDL_realloc_func realloc_func, SDL_free_func free_func)
char * SDL_strtok_r(char *s1, const char *s2, char **saveptr)
int SDL_isspace(int x)
int SDL_isalnum(int x)
char * SDL_strlwr(char *str)
struct SDL_iconv_data_t * SDL_iconv_t
wchar_t * SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen)
SDL_FORCE_INLINE bool SDL_size_mul_check_overflow(size_t a, size_t b, size_t *ret)
int SDL_tolower(int x)
float SDL_modff(float x, float *y)
double SDL_modf(double x, double *y)
Uint32 SDL_murmur3_32(const void *data, size_t len, Uint32 seed)
const char * SDL_getenv_unsafe(const char *name)
int SDL_abs(int x)
int SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3)
char * SDL_ulltoa(unsigned long long value, char *str, int radix)
size_t SDL_iconv(SDL_iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft)
Sint32 SDL_rand_r(Uint64 *state, Sint32 n)
double SDL_tan(double x)
uint8_t Uint8
Definition SDL_stdinc.h:320
char * SDL_ltoa(long value, char *str, int radix)
void SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare)
int SDL_isxdigit(int x)
Uint32 SDL_StepUTF8(const char **pstr, size_t *pslen)
float SDL_ceilf(float x)
int64_t Sint64
Definition SDL_stdinc.h:367
void SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func, SDL_calloc_func *calloc_func, SDL_realloc_func *realloc_func, SDL_free_func *free_func)
void *(* SDL_malloc_func)(size_t size)
Definition SDL_stdinc.h:794
int(* SDL_CompareCallback_r)(void *userdata, const void *a, const void *b)
#define SDL_OUT_BYTECAP(x)
Definition SDL_stdinc.h:552
char * SDL_strrchr(const char *str, int c)
#define SDL_SIZE_MAX
Definition SDL_stdinc.h:94
int SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen)
uint16_t Uint16
Definition SDL_stdinc.h:338
int SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt,...) SDL_SCANF_VARARG_FUNC(2)
char ** SDL_GetEnvironmentVariables(SDL_Environment *env)
SDL_FORCE_INLINE bool SDL_size_add_check_overflow(size_t a, size_t b, size_t *ret)
float SDL_atanf(float x)
int SDL_isprint(int x)
#define SDL_PRINTF_VARARG_FUNCV(fmtargnumber)
Definition SDL_stdinc.h:566
int SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen)
void SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata)
char * SDL_itoa(int value, char *str, int radix)
float SDL_copysignf(float x, float y)
SDL_MALLOC char * SDL_strndup(const char *str, size_t maxlen)
char * SDL_strupr(char *str)
float SDL_acosf(float x)
size_t SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen)
int SDL_strncmp(const char *str1, const char *str2, size_t maxlen)
struct SDL_Environment SDL_Environment
Definition SDL_stdinc.h:997
char * SDL_strchr(const char *str, int c)
SDL_MALLOC void * SDL_aligned_alloc(size_t alignment, size_t size)
#define SDL_IN_BYTECAP(x)
Definition SDL_stdinc.h:548
int SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2)
float SDL_randf(void)
bool SDL_SetEnvironmentVariable(SDL_Environment *env, const char *name, const char *value, bool overwrite)
Sint32 SDL_rand(Sint32 n)
char * SDL_uitoa(unsigned int value, char *str, int radix)
void * alloca(size_t)
int SDL_isalpha(int x)
double SDL_round(double x)
long SDL_lround(double x)
int SDL_isdigit(int x)
int SDL_isblank(int x)
size_t SDL_strnlen(const char *str, size_t maxlen)
int SDL_iconv_close(SDL_iconv_t cd)
int SDL_isinff(float x)
double SDL_sin(double x)
char * SDL_strcasestr(const char *haystack, const char *needle)
float SDL_scalbnf(float x, int n)
double SDL_pow(double x, double y)
size_t SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes)
float SDL_asinf(float x)
double SDL_asin(double x)
double SDL_acos(double x)
int8_t Sint8
Definition SDL_stdinc.h:311
wchar_t * SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle)
char * SDL_lltoa(long long value, char *str, int radix)
int(* SDL_CompareCallback)(const void *a, const void *b)
float SDL_sinf(float x)
int SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt,...) SDL_WPRINTF_VARARG_FUNC(3)
int SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3)
#define SDL_SCANF_VARARG_FUNCV(fmtargnumber)
Definition SDL_stdinc.h:568
void SDL_srand(Uint64 seed)
Uint32 SDL_rand_bits_r(Uint64 *state)
double SDL_ceil(double x)
size_t SDL_utf8strnlen(const char *str, size_t bytes)
int SDL_strcasecmp(const char *str1, const char *str2)
void * SDL_memset4(void *dst, Uint32 val, size_t dwords)
#define SDL_SCANF_FORMAT_STRING
Definition SDL_stdinc.h:555
char * SDL_strstr(const char *haystack, const char *needle)
int SDL_GetNumAllocations(void)
double SDL_exp(double x)
char * SDL_UCS4ToUTF8(Uint32 codepoint, char *dst)
size_t SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen)
double SDL_atan(double x)
float SDL_sqrtf(float x)
size_t SDL_wcslen(const wchar_t *wstr)
int32_t Sint32
Definition SDL_stdinc.h:347
size_t SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen)
#define SDL_INOUT_Z_CAP(x)
Definition SDL_stdinc.h:549
double SDL_scalbn(double x, int n)
char * SDL_iconv_string(const char *tocode, const char *fromcode, const char *inbuf, size_t inbytesleft)
int SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2)
double SDL_fmod(double x, double y)
double SDL_fabs(double x)
int SDL_ispunct(int x)
float SDL_truncf(float x)
char * SDL_strpbrk(const char *str, const char *breakset)
double SDL_log10(double x)
SDL_MALLOC size_t size
Definition SDL_stdinc.h:720
float SDL_expf(float x)
#define SDL_WPRINTF_VARARG_FUNCV(fmtargnumber)
Definition SDL_stdinc.h:570
char * SDL_strrev(char *str)
double SDL_floor(double x)
int SDL_wcscmp(const wchar_t *str1, const wchar_t *str2)
long SDL_strtol(const char *str, char **endp, int base)
SDL_Environment * SDL_CreateEnvironment(bool populated)
Uint32 SDL_crc32(Uint32 crc, const void *data, size_t len)
int SDL_islower(int x)
void SDL_aligned_free(void *mem)
float SDL_logf(float x)
int SDL_isnan(double x)
int SDL_isinf(double x)
float SDL_log10f(float x)
void(* SDL_free_func)(void *mem)
Definition SDL_stdinc.h:854
int SDL_memcmp(const void *s1, const void *s2, size_t len)
const char * SDL_getenv(const char *name)
int16_t Sint16
Definition SDL_stdinc.h:329
float SDL_roundf(float x)
double SDL_strtod(const char *str, char **endp)
long SDL_lroundf(float x)
char * SDL_ultoa(unsigned long value, char *str, int radix)
double SDL_atof(const char *str)
const char * SDL_GetEnvironmentVariable(SDL_Environment *env, const char *name)
char * SDL_strnstr(const char *haystack, const char *needle, size_t maxlen)
Uint32 SDL_rand_bits(void)
size_t SDL_wcsnlen(const wchar_t *wstr, size_t maxlen)
unsigned long SDL_strtoul(const char *str, char **endp, int base)
float SDL_floorf(float x)
int SDL_strcmp(const char *str1, const char *str2)
double SDL_cos(double x)
#define SDL_PRINTF_FORMAT_STRING
Definition SDL_stdinc.h:554
float SDL_fmodf(float x, float y)
void SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func, SDL_calloc_func *calloc_func, SDL_realloc_func *realloc_func, SDL_free_func *free_func)
SDL_MALLOC void * SDL_malloc(size_t size)
#define SDL_PRINTF_VARARG_FUNC(fmtargnumber)
Definition SDL_stdinc.h:565
#define SDL_COMPILE_TIME_ASSERT(name, x)
Definition SDL_stdinc.h:112
float SDL_atan2f(float y, float x)
int SDL_isupper(int x)
int SDL_unsetenv_unsafe(const char *name)
long SDL_wcstol(const wchar_t *str, wchar_t **endp, int base)
float SDL_fabsf(float x)
uint64_t Uint64
Definition SDL_stdinc.h:378
long long SDL_strtoll(const char *str, char **endp, int base)
SDL_MALLOC char * SDL_strdup(const char *str)
int SDL_iscntrl(int x)
void * SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare)
#define SDL_memcpy
void SDL_free(void *mem)
void * SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata)
void *(* SDL_calloc_func)(size_t nmemb, size_t size)
Definition SDL_stdinc.h:815
#define SDL_SCANF_VARARG_FUNC(fmtargnumber)
Definition SDL_stdinc.h:567
double SDL_atan2(double y, double x)
double SDL_log(double x)
void(* SDL_FunctionPointer)(void)
int SDL_isnanf(float x)
int SDL_toupper(int x)
uint32_t Uint32
Definition SDL_stdinc.h:356
float SDL_powf(float x, float y)
SDL_Environment * SDL_GetEnvironment(void)
size_t SDL_strlen(const char *str)
bool SDL_UnsetEnvironmentVariable(SDL_Environment *env, const char *name)
#define SDL_memmove
Uint16 SDL_crc16(Uint16 crc, const void *data, size_t len)
int SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(3)
float SDL_cosf(float x)
int SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen)
size_t SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen)
double SDL_copysign(double x, double y)
int SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2)
Sint64 SDL_Time
Definition SDL_stdinc.h:395
void *(* SDL_realloc_func)(void *mem, size_t size)
Definition SDL_stdinc.h:836
size_t SDL_utf8strlen(const char *str)
int SDL_isgraph(int x)
float SDL_randf_r(Uint64 *state)
int SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
#define SDL_OUT_Z_CAP(x)
Definition SDL_stdinc.h:550
#define SDL_WPRINTF_VARARG_FUNC(fmtargnumber)
Definition SDL_stdinc.h:569
double SDL_trunc(double x)
int SDL_setenv_unsafe(const char *name, const char *value, int overwrite)