|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 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 * SDL provides its own implementation of some of the most important C runtime
|
|
|
26 * functions.
|
|
|
27 *
|
|
|
28 * Using these functions allows an app to have access to common C
|
|
|
29 * functionality without depending on a specific C runtime (or a C runtime at
|
|
|
30 * all). More importantly, the SDL implementations work identically across
|
|
|
31 * platforms, so apps can avoid surprises like snprintf() behaving differently
|
|
|
32 * between Windows and Linux builds, or itoa() only existing on some
|
|
|
33 * platforms.
|
|
|
34 *
|
|
|
35 * For many of the most common functions, like SDL_memcpy, SDL might just call
|
|
|
36 * through to the usual C runtime behind the scenes, if it makes sense to do
|
|
|
37 * so (if it's faster and always available/reliable on a given platform),
|
|
|
38 * reducing library size and offering the most optimized option.
|
|
|
39 *
|
|
|
40 * SDL also offers other C-runtime-adjacent functionality in this header that
|
|
|
41 * either isn't, strictly speaking, part of any C runtime standards, like
|
|
|
42 * SDL_crc32() and SDL_reinterpret_cast, etc. It also offers a few better
|
|
|
43 * options, like SDL_strlcpy(), which functions as a safer form of strcpy().
|
|
|
44 */
|
|
|
45
|
|
|
46 #ifndef SDL_stdinc_h_
|
|
|
47 #define SDL_stdinc_h_
|
|
|
48
|
|
|
49 #include <SDL3/SDL_platform_defines.h>
|
|
|
50
|
|
|
51 #include <stdarg.h>
|
|
|
52 #include <string.h>
|
|
|
53 #include <wchar.h>
|
|
|
54
|
|
|
55 /* Most everything except Visual Studio 2008 and earlier has stdint.h now */
|
|
|
56 #if defined(_MSC_VER) && (_MSC_VER < 1600)
|
|
|
57 typedef signed __int8 int8_t;
|
|
|
58 typedef unsigned __int8 uint8_t;
|
|
|
59 typedef signed __int16 int16_t;
|
|
|
60 typedef unsigned __int16 uint16_t;
|
|
|
61 typedef signed __int32 int32_t;
|
|
|
62 typedef unsigned __int32 uint32_t;
|
|
|
63 typedef signed __int64 int64_t;
|
|
|
64 typedef unsigned __int64 uint64_t;
|
|
|
65 #ifndef _INTPTR_T_DEFINED
|
|
|
66 #ifdef _WIN64
|
|
|
67 typedef __int64 intptr_t;
|
|
|
68 #else
|
|
|
69 typedef int intptr_t;
|
|
|
70 #endif
|
|
|
71 #endif
|
|
|
72 #ifndef _UINTPTR_T_DEFINED
|
|
|
73 #ifdef _WIN64
|
|
|
74 typedef unsigned __int64 uintptr_t;
|
|
|
75 #else
|
|
|
76 typedef unsigned int uintptr_t;
|
|
|
77 #endif
|
|
|
78 #endif
|
|
|
79 #else
|
|
|
80 #include <stdint.h>
|
|
|
81 #endif
|
|
|
82
|
|
|
83 #if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \
|
|
|
84 defined(SDL_INCLUDE_INTTYPES_H)
|
|
|
85 #include <inttypes.h>
|
|
|
86 #endif
|
|
|
87
|
|
|
88 #ifndef __cplusplus
|
|
|
89 #if defined(__has_include) && !defined(SDL_INCLUDE_STDBOOL_H)
|
|
|
90 #if __has_include(<stdbool.h>)
|
|
|
91 #define SDL_INCLUDE_STDBOOL_H
|
|
|
92 #endif
|
|
|
93 #endif
|
|
|
94 #if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \
|
|
|
95 (defined(_MSC_VER) && (_MSC_VER >= 1910 /* Visual Studio 2017 */)) || \
|
|
|
96 defined(SDL_INCLUDE_STDBOOL_H)
|
|
|
97 #include <stdbool.h>
|
|
|
98 #elif !defined(__bool_true_false_are_defined) && !defined(bool)
|
|
|
99 #define bool unsigned char
|
|
|
100 #define false 0
|
|
|
101 #define true 1
|
|
|
102 #define __bool_true_false_are_defined 1
|
|
|
103 #endif
|
|
|
104 #endif /* !__cplusplus */
|
|
|
105
|
|
|
106 #ifndef SDL_DISABLE_ALLOCA
|
|
|
107 # ifndef alloca
|
|
|
108 # ifdef HAVE_ALLOCA_H
|
|
|
109 # include <alloca.h>
|
|
|
110 # elif defined(SDL_PLATFORM_NETBSD)
|
|
|
111 # if defined(__STRICT_ANSI__)
|
|
|
112 # define SDL_DISABLE_ALLOCA
|
|
|
113 # else
|
|
|
114 # include <stdlib.h>
|
|
|
115 # endif
|
|
|
116 # elif defined(__GNUC__)
|
|
|
117 # define alloca __builtin_alloca
|
|
|
118 # elif defined(_MSC_VER)
|
|
|
119 # include <malloc.h>
|
|
|
120 # define alloca _alloca
|
|
|
121 # elif defined(__WATCOMC__)
|
|
|
122 # include <malloc.h>
|
|
|
123 # elif defined(__BORLANDC__)
|
|
|
124 # include <malloc.h>
|
|
|
125 # elif defined(__DMC__)
|
|
|
126 # include <stdlib.h>
|
|
|
127 # elif defined(SDL_PLATFORM_AIX)
|
|
|
128 # pragma alloca
|
|
|
129 # elif defined(__MRC__)
|
|
|
130 void *alloca(unsigned);
|
|
|
131 # else
|
|
|
132 void *alloca(size_t);
|
|
|
133 # endif
|
|
|
134 # endif
|
|
|
135 #endif
|
|
|
136
|
|
|
137
|
|
|
138 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
139
|
|
|
140 /**
|
|
|
141 * Don't let SDL use "long long" C types.
|
|
|
142 *
|
|
|
143 * SDL will define this if it believes the compiler doesn't understand the
|
|
|
144 * "long long" syntax for C datatypes. This can happen on older compilers.
|
|
|
145 *
|
|
|
146 * If _your_ compiler doesn't support "long long" but SDL doesn't know it, it
|
|
|
147 * is safe to define this yourself to build against the SDL headers.
|
|
|
148 *
|
|
|
149 * If this is defined, it will remove access to some C runtime support
|
|
|
150 * functions, like SDL_ulltoa and SDL_strtoll that refer to this datatype
|
|
|
151 * explicitly. The rest of SDL will still be available.
|
|
|
152 *
|
|
|
153 * SDL's own source code cannot be built with a compiler that has this
|
|
|
154 * defined, for various technical reasons.
|
|
|
155 */
|
|
|
156 #define SDL_NOLONGLONG 1
|
|
|
157
|
|
|
158 #elif defined(_MSC_VER) && (_MSC_VER < 1310) /* long long introduced in Visual Studio.NET 2003 */
|
|
|
159 # define SDL_NOLONGLONG 1
|
|
|
160 #endif
|
|
|
161
|
|
|
162
|
|
|
163 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
164
|
|
|
165 /**
|
|
|
166 * The largest value that a `size_t` can hold for the target platform.
|
|
|
167 *
|
|
|
168 * `size_t` is generally the same size as a pointer in modern times, but this
|
|
|
169 * can get weird on very old and very esoteric machines. For example, on a
|
|
|
170 * 16-bit Intel 286, you might have a 32-bit "far" pointer (16-bit segment
|
|
|
171 * plus 16-bit offset), but `size_t` is 16 bits, because it can only deal with
|
|
|
172 * the offset into an individual segment.
|
|
|
173 *
|
|
|
174 * In modern times, it's generally expected to cover an entire linear address
|
|
|
175 * space. But be careful!
|
|
|
176 *
|
|
|
177 * \since This macro is available since SDL 3.2.0.
|
|
|
178 */
|
|
|
179 #define SDL_SIZE_MAX SIZE_MAX
|
|
|
180
|
|
|
181 #elif defined(SIZE_MAX)
|
|
|
182 # define SDL_SIZE_MAX SIZE_MAX
|
|
|
183 #else
|
|
|
184 # define SDL_SIZE_MAX ((size_t) -1)
|
|
|
185 #endif
|
|
|
186
|
|
|
187 #ifndef SDL_COMPILE_TIME_ASSERT
|
|
|
188 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
189
|
|
|
190 /**
|
|
|
191 * A compile-time assertion.
|
|
|
192 *
|
|
|
193 * This can check constant values _known to the compiler at build time_ for
|
|
|
194 * correctness, and end the compile with the error if they fail.
|
|
|
195 *
|
|
|
196 * Often times these are used to verify basic truths, like the size of a
|
|
|
197 * datatype is what is expected:
|
|
|
198 *
|
|
|
199 * ```c
|
|
|
200 * SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4);
|
|
|
201 * ```
|
|
|
202 *
|
|
|
203 * The `name` parameter must be a valid C symbol, and must be unique across
|
|
|
204 * all compile-time asserts in the same compilation unit (one run of the
|
|
|
205 * compiler), or the build might fail with cryptic errors on some targets.
|
|
|
206 * This is used with a C language trick that works on older compilers that
|
|
|
207 * don't support better assertion techniques.
|
|
|
208 *
|
|
|
209 * If you need an assertion that operates at runtime, on variable data, you
|
|
|
210 * should try SDL_assert instead.
|
|
|
211 *
|
|
|
212 * \param name a unique identifier for this assertion.
|
|
|
213 * \param x the value to test. Must be a boolean value.
|
|
|
214 *
|
|
|
215 * \threadsafety This macro doesn't generate any code to run.
|
|
|
216 *
|
|
|
217 * \since This macro is available since SDL 3.2.0.
|
|
|
218 *
|
|
|
219 * \sa SDL_assert
|
|
|
220 */
|
|
|
221 #define SDL_COMPILE_TIME_ASSERT(name, x) FailToCompileIf_x_IsFalse(x)
|
|
|
222 #elif defined(__cplusplus)
|
|
|
223 /* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */
|
|
|
224 #if (__cplusplus >= 201103L)
|
|
|
225 #define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x)
|
|
|
226 #endif
|
|
|
227 #elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L)
|
|
|
228 #define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x)
|
|
|
229 #elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L)
|
|
|
230 #define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x)
|
|
|
231 #endif
|
|
|
232 #endif /* !SDL_COMPILE_TIME_ASSERT */
|
|
|
233
|
|
|
234 #ifndef SDL_COMPILE_TIME_ASSERT
|
|
|
235 /* universal, but may trigger -Wunused-local-typedefs */
|
|
|
236 #define SDL_COMPILE_TIME_ASSERT(name, x) \
|
|
|
237 typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1]
|
|
|
238 #endif
|
|
|
239
|
|
|
240 /**
|
|
|
241 * The number of elements in a static array.
|
|
|
242 *
|
|
|
243 * This will compile but return incorrect results for a pointer to an array;
|
|
|
244 * it has to be an array the compiler knows the size of.
|
|
|
245 *
|
|
|
246 * This macro looks like it double-evaluates the argument, but it does so
|
|
|
247 * inside of `sizeof`, so there are no side-effects here, as expressions do
|
|
|
248 * not actually run any code in these cases.
|
|
|
249 *
|
|
|
250 * \since This macro is available since SDL 3.2.0.
|
|
|
251 */
|
|
|
252 #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0]))
|
|
|
253
|
|
|
254 /**
|
|
|
255 * Macro useful for building other macros with strings in them.
|
|
|
256 *
|
|
|
257 * For example:
|
|
|
258 *
|
|
|
259 * ```c
|
|
|
260 * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")`
|
|
|
261 * ```
|
|
|
262 *
|
|
|
263 * \param arg the text to turn into a string literal.
|
|
|
264 *
|
|
|
265 * \since This macro is available since SDL 3.2.0.
|
|
|
266 */
|
|
|
267 #define SDL_STRINGIFY_ARG(arg) #arg
|
|
|
268
|
|
|
269 /**
|
|
|
270 * \name Cast operators
|
|
|
271 *
|
|
|
272 * Use proper C++ casts when compiled as C++ to be compatible with the option
|
|
|
273 * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above).
|
|
|
274 */
|
|
|
275 /* @{ */
|
|
|
276
|
|
|
277 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
278
|
|
|
279 /**
|
|
|
280 * Handle a Reinterpret Cast properly whether using C or C++.
|
|
|
281 *
|
|
|
282 * If compiled as C++, this macro offers a proper C++ reinterpret_cast<>.
|
|
|
283 *
|
|
|
284 * If compiled as C, this macro does a normal C-style cast.
|
|
|
285 *
|
|
|
286 * This is helpful to avoid compiler warnings in C++.
|
|
|
287 *
|
|
|
288 * \param type the type to cast the expression to.
|
|
|
289 * \param expression the expression to cast to a different type.
|
|
|
290 * \returns `expression`, cast to `type`.
|
|
|
291 *
|
|
|
292 * \threadsafety It is safe to call this macro from any thread.
|
|
|
293 *
|
|
|
294 * \since This macro is available since SDL 3.2.0.
|
|
|
295 *
|
|
|
296 * \sa SDL_static_cast
|
|
|
297 * \sa SDL_const_cast
|
|
|
298 */
|
|
|
299 #define SDL_reinterpret_cast(type, expression) reinterpret_cast<type>(expression) /* or `((type)(expression))` in C */
|
|
|
300
|
|
|
301 /**
|
|
|
302 * Handle a Static Cast properly whether using C or C++.
|
|
|
303 *
|
|
|
304 * If compiled as C++, this macro offers a proper C++ static_cast<>.
|
|
|
305 *
|
|
|
306 * If compiled as C, this macro does a normal C-style cast.
|
|
|
307 *
|
|
|
308 * This is helpful to avoid compiler warnings in C++.
|
|
|
309 *
|
|
|
310 * \param type the type to cast the expression to.
|
|
|
311 * \param expression the expression to cast to a different type.
|
|
|
312 * \returns `expression`, cast to `type`.
|
|
|
313 *
|
|
|
314 * \threadsafety It is safe to call this macro from any thread.
|
|
|
315 *
|
|
|
316 * \since This macro is available since SDL 3.2.0.
|
|
|
317 *
|
|
|
318 * \sa SDL_reinterpret_cast
|
|
|
319 * \sa SDL_const_cast
|
|
|
320 */
|
|
|
321 #define SDL_static_cast(type, expression) static_cast<type>(expression) /* or `((type)(expression))` in C */
|
|
|
322
|
|
|
323 /**
|
|
|
324 * Handle a Const Cast properly whether using C or C++.
|
|
|
325 *
|
|
|
326 * If compiled as C++, this macro offers a proper C++ const_cast<>.
|
|
|
327 *
|
|
|
328 * If compiled as C, this macro does a normal C-style cast.
|
|
|
329 *
|
|
|
330 * This is helpful to avoid compiler warnings in C++.
|
|
|
331 *
|
|
|
332 * \param type the type to cast the expression to.
|
|
|
333 * \param expression the expression to cast to a different type.
|
|
|
334 * \returns `expression`, cast to `type`.
|
|
|
335 *
|
|
|
336 * \threadsafety It is safe to call this macro from any thread.
|
|
|
337 *
|
|
|
338 * \since This macro is available since SDL 3.2.0.
|
|
|
339 *
|
|
|
340 * \sa SDL_reinterpret_cast
|
|
|
341 * \sa SDL_static_cast
|
|
|
342 */
|
|
|
343 #define SDL_const_cast(type, expression) const_cast<type>(expression) /* or `((type)(expression))` in C */
|
|
|
344
|
|
|
345 #elif defined(__cplusplus)
|
|
|
346 #define SDL_reinterpret_cast(type, expression) reinterpret_cast<type>(expression)
|
|
|
347 #define SDL_static_cast(type, expression) static_cast<type>(expression)
|
|
|
348 #define SDL_const_cast(type, expression) const_cast<type>(expression)
|
|
|
349 #else
|
|
|
350 #define SDL_reinterpret_cast(type, expression) ((type)(expression))
|
|
|
351 #define SDL_static_cast(type, expression) ((type)(expression))
|
|
|
352 #define SDL_const_cast(type, expression) ((type)(expression))
|
|
|
353 #endif
|
|
|
354
|
|
|
355 /* @} *//* Cast operators */
|
|
|
356
|
|
|
357 /**
|
|
|
358 * Define a four character code as a Uint32.
|
|
|
359 *
|
|
|
360 * \param A the first ASCII character.
|
|
|
361 * \param B the second ASCII character.
|
|
|
362 * \param C the third ASCII character.
|
|
|
363 * \param D the fourth ASCII character.
|
|
|
364 * \returns the four characters converted into a Uint32, one character
|
|
|
365 * per-byte.
|
|
|
366 *
|
|
|
367 * \threadsafety It is safe to call this macro from any thread.
|
|
|
368 *
|
|
|
369 * \since This macro is available since SDL 3.2.0.
|
|
|
370 */
|
|
|
371 #define SDL_FOURCC(A, B, C, D) \
|
|
|
372 ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \
|
|
|
373 (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \
|
|
|
374 (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (C))) << 16) | \
|
|
|
375 (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (D))) << 24))
|
|
|
376
|
|
|
377 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
378
|
|
|
379 /**
|
|
|
380 * Append the 64 bit integer suffix to a signed integer literal.
|
|
|
381 *
|
|
|
382 * This helps compilers that might believe a integer literal larger than
|
|
|
383 * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_SINT64_C(0xFFFFFFFF1)`
|
|
|
384 * instead of `0xFFFFFFFF1` by itself.
|
|
|
385 *
|
|
|
386 * \since This macro is available since SDL 3.2.0.
|
|
|
387 *
|
|
|
388 * \sa SDL_UINT64_C
|
|
|
389 */
|
|
|
390 #define SDL_SINT64_C(c) c ## LL /* or whatever the current compiler uses. */
|
|
|
391
|
|
|
392 /**
|
|
|
393 * Append the 64 bit integer suffix to an unsigned integer literal.
|
|
|
394 *
|
|
|
395 * This helps compilers that might believe a integer literal larger than
|
|
|
396 * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_UINT64_C(0xFFFFFFFF1)`
|
|
|
397 * instead of `0xFFFFFFFF1` by itself.
|
|
|
398 *
|
|
|
399 * \since This macro is available since SDL 3.2.0.
|
|
|
400 *
|
|
|
401 * \sa SDL_SINT64_C
|
|
|
402 */
|
|
|
403 #define SDL_UINT64_C(c) c ## ULL /* or whatever the current compiler uses. */
|
|
|
404
|
|
|
405 #else /* !SDL_WIKI_DOCUMENTATION_SECTION */
|
|
|
406
|
|
|
407 #ifndef SDL_SINT64_C
|
|
|
408 #if defined(INT64_C)
|
|
|
409 #define SDL_SINT64_C(c) INT64_C(c)
|
|
|
410 #elif defined(_MSC_VER)
|
|
|
411 #define SDL_SINT64_C(c) c ## i64
|
|
|
412 #elif defined(__LP64__) || defined(_LP64)
|
|
|
413 #define SDL_SINT64_C(c) c ## L
|
|
|
414 #else
|
|
|
415 #define SDL_SINT64_C(c) c ## LL
|
|
|
416 #endif
|
|
|
417 #endif /* !SDL_SINT64_C */
|
|
|
418
|
|
|
419 #ifndef SDL_UINT64_C
|
|
|
420 #if defined(UINT64_C)
|
|
|
421 #define SDL_UINT64_C(c) UINT64_C(c)
|
|
|
422 #elif defined(_MSC_VER)
|
|
|
423 #define SDL_UINT64_C(c) c ## ui64
|
|
|
424 #elif defined(__LP64__) || defined(_LP64)
|
|
|
425 #define SDL_UINT64_C(c) c ## UL
|
|
|
426 #else
|
|
|
427 #define SDL_UINT64_C(c) c ## ULL
|
|
|
428 #endif
|
|
|
429 #endif /* !SDL_UINT64_C */
|
|
|
430
|
|
|
431 #endif /* !SDL_WIKI_DOCUMENTATION_SECTION */
|
|
|
432
|
|
|
433 /**
|
|
|
434 * \name Basic data types
|
|
|
435 */
|
|
|
436 /* @{ */
|
|
|
437
|
|
|
438 /**
|
|
|
439 * A signed 8-bit integer type.
|
|
|
440 *
|
|
|
441 * \since This macro is available since SDL 3.2.0.
|
|
|
442 */
|
|
|
443 typedef int8_t Sint8;
|
|
|
444 #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */
|
|
|
445 #define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */
|
|
|
446
|
|
|
447 /**
|
|
|
448 * An unsigned 8-bit integer type.
|
|
|
449 *
|
|
|
450 * \since This macro is available since SDL 3.2.0.
|
|
|
451 */
|
|
|
452 typedef uint8_t Uint8;
|
|
|
453 #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */
|
|
|
454 #define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */
|
|
|
455
|
|
|
456 /**
|
|
|
457 * A signed 16-bit integer type.
|
|
|
458 *
|
|
|
459 * \since This macro is available since SDL 3.2.0.
|
|
|
460 */
|
|
|
461 typedef int16_t Sint16;
|
|
|
462 #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */
|
|
|
463 #define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */
|
|
|
464
|
|
|
465 /**
|
|
|
466 * An unsigned 16-bit integer type.
|
|
|
467 *
|
|
|
468 * \since This macro is available since SDL 3.2.0.
|
|
|
469 */
|
|
|
470 typedef uint16_t Uint16;
|
|
|
471 #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */
|
|
|
472 #define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */
|
|
|
473
|
|
|
474 /**
|
|
|
475 * A signed 32-bit integer type.
|
|
|
476 *
|
|
|
477 * \since This macro is available since SDL 3.2.0.
|
|
|
478 */
|
|
|
479 typedef int32_t Sint32;
|
|
|
480 #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */
|
|
|
481 #define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */
|
|
|
482
|
|
|
483 /**
|
|
|
484 * An unsigned 32-bit integer type.
|
|
|
485 *
|
|
|
486 * \since This macro is available since SDL 3.2.0.
|
|
|
487 */
|
|
|
488 typedef uint32_t Uint32;
|
|
|
489 #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */
|
|
|
490 #define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */
|
|
|
491
|
|
|
492 /**
|
|
|
493 * A signed 64-bit integer type.
|
|
|
494 *
|
|
|
495 * \since This macro is available since SDL 3.2.0.
|
|
|
496 *
|
|
|
497 * \sa SDL_SINT64_C
|
|
|
498 */
|
|
|
499 typedef int64_t Sint64;
|
|
|
500 #define SDL_MAX_SINT64 SDL_SINT64_C(0x7FFFFFFFFFFFFFFF) /* 9223372036854775807 */
|
|
|
501 #define SDL_MIN_SINT64 ~SDL_SINT64_C(0x7FFFFFFFFFFFFFFF) /* -9223372036854775808 */
|
|
|
502
|
|
|
503 /**
|
|
|
504 * An unsigned 64-bit integer type.
|
|
|
505 *
|
|
|
506 * \since This macro is available since SDL 3.2.0.
|
|
|
507 *
|
|
|
508 * \sa SDL_UINT64_C
|
|
|
509 */
|
|
|
510 typedef uint64_t Uint64;
|
|
|
511 #define SDL_MAX_UINT64 SDL_UINT64_C(0xFFFFFFFFFFFFFFFF) /* 18446744073709551615 */
|
|
|
512 #define SDL_MIN_UINT64 SDL_UINT64_C(0x0000000000000000) /* 0 */
|
|
|
513
|
|
|
514 /**
|
|
|
515 * SDL times are signed, 64-bit integers representing nanoseconds since the
|
|
|
516 * Unix epoch (Jan 1, 1970).
|
|
|
517 *
|
|
|
518 * They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS()
|
|
|
519 * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with
|
|
|
520 * SDL_TimeToWindows() and SDL_TimeFromWindows().
|
|
|
521 *
|
|
|
522 * \since This datatype is available since SDL 3.2.0.
|
|
|
523 *
|
|
|
524 * \sa SDL_MAX_SINT64
|
|
|
525 * \sa SDL_MIN_SINT64
|
|
|
526 */
|
|
|
527 typedef Sint64 SDL_Time;
|
|
|
528 #define SDL_MAX_TIME SDL_MAX_SINT64
|
|
|
529 #define SDL_MIN_TIME SDL_MIN_SINT64
|
|
|
530
|
|
|
531 /* @} *//* Basic data types */
|
|
|
532
|
|
|
533 /**
|
|
|
534 * \name Floating-point constants
|
|
|
535 */
|
|
|
536 /* @{ */
|
|
|
537
|
|
|
538 #ifdef FLT_EPSILON
|
|
|
539 #define SDL_FLT_EPSILON FLT_EPSILON
|
|
|
540 #else
|
|
|
541
|
|
|
542 /**
|
|
|
543 * Epsilon constant, used for comparing floating-point numbers.
|
|
|
544 *
|
|
|
545 * Equals by default to platform-defined `FLT_EPSILON`, or
|
|
|
546 * `1.1920928955078125e-07F` if that's not available.
|
|
|
547 *
|
|
|
548 * \since This macro is available since SDL 3.2.0.
|
|
|
549 */
|
|
|
550 #define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */
|
|
|
551 #endif
|
|
|
552
|
|
|
553 /* @} *//* Floating-point constants */
|
|
|
554
|
|
|
555 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
556
|
|
|
557 /**
|
|
|
558 * A printf-formatting string for an Sint64 value.
|
|
|
559 *
|
|
|
560 * Use it like this:
|
|
|
561 *
|
|
|
562 * ```c
|
|
|
563 * SDL_Log("There are %" SDL_PRIs64 " bottles of beer on the wall.", bottles);
|
|
|
564 * ```
|
|
|
565 *
|
|
|
566 * \since This macro is available since SDL 3.2.0.
|
|
|
567 */
|
|
|
568 #define SDL_PRIs64 "lld"
|
|
|
569
|
|
|
570 /**
|
|
|
571 * A printf-formatting string for a Uint64 value.
|
|
|
572 *
|
|
|
573 * Use it like this:
|
|
|
574 *
|
|
|
575 * ```c
|
|
|
576 * SDL_Log("There are %" SDL_PRIu64 " bottles of beer on the wall.", bottles);
|
|
|
577 * ```
|
|
|
578 *
|
|
|
579 * \since This macro is available since SDL 3.2.0.
|
|
|
580 */
|
|
|
581 #define SDL_PRIu64 "llu"
|
|
|
582
|
|
|
583 /**
|
|
|
584 * A printf-formatting string for a Uint64 value as lower-case hexadecimal.
|
|
|
585 *
|
|
|
586 * Use it like this:
|
|
|
587 *
|
|
|
588 * ```c
|
|
|
589 * SDL_Log("There are %" SDL_PRIx64 " bottles of beer on the wall.", bottles);
|
|
|
590 * ```
|
|
|
591 *
|
|
|
592 * \since This macro is available since SDL 3.2.0.
|
|
|
593 */
|
|
|
594 #define SDL_PRIx64 "llx"
|
|
|
595
|
|
|
596 /**
|
|
|
597 * A printf-formatting string for a Uint64 value as upper-case hexadecimal.
|
|
|
598 *
|
|
|
599 * Use it like this:
|
|
|
600 *
|
|
|
601 * ```c
|
|
|
602 * SDL_Log("There are %" SDL_PRIX64 " bottles of beer on the wall.", bottles);
|
|
|
603 * ```
|
|
|
604 *
|
|
|
605 * \since This macro is available since SDL 3.2.0.
|
|
|
606 */
|
|
|
607 #define SDL_PRIX64 "llX"
|
|
|
608
|
|
|
609 /**
|
|
|
610 * A printf-formatting string for an Sint32 value.
|
|
|
611 *
|
|
|
612 * Use it like this:
|
|
|
613 *
|
|
|
614 * ```c
|
|
|
615 * SDL_Log("There are %" SDL_PRIs32 " bottles of beer on the wall.", bottles);
|
|
|
616 * ```
|
|
|
617 *
|
|
|
618 * \since This macro is available since SDL 3.2.0.
|
|
|
619 */
|
|
|
620 #define SDL_PRIs32 "d"
|
|
|
621
|
|
|
622 /**
|
|
|
623 * A printf-formatting string for a Uint32 value.
|
|
|
624 *
|
|
|
625 * Use it like this:
|
|
|
626 *
|
|
|
627 * ```c
|
|
|
628 * SDL_Log("There are %" SDL_PRIu32 " bottles of beer on the wall.", bottles);
|
|
|
629 * ```
|
|
|
630 *
|
|
|
631 * \since This macro is available since SDL 3.2.0.
|
|
|
632 */
|
|
|
633 #define SDL_PRIu32 "u"
|
|
|
634
|
|
|
635 /**
|
|
|
636 * A printf-formatting string for a Uint32 value as lower-case hexadecimal.
|
|
|
637 *
|
|
|
638 * Use it like this:
|
|
|
639 *
|
|
|
640 * ```c
|
|
|
641 * SDL_Log("There are %" SDL_PRIx32 " bottles of beer on the wall.", bottles);
|
|
|
642 * ```
|
|
|
643 *
|
|
|
644 * \since This macro is available since SDL 3.2.0.
|
|
|
645 */
|
|
|
646 #define SDL_PRIx32 "x"
|
|
|
647
|
|
|
648 /**
|
|
|
649 * A printf-formatting string for a Uint32 value as upper-case hexadecimal.
|
|
|
650 *
|
|
|
651 * Use it like this:
|
|
|
652 *
|
|
|
653 * ```c
|
|
|
654 * SDL_Log("There are %" SDL_PRIX32 " bottles of beer on the wall.", bottles);
|
|
|
655 * ```
|
|
|
656 *
|
|
|
657 * \since This macro is available since SDL 3.2.0.
|
|
|
658 */
|
|
|
659 #define SDL_PRIX32 "X"
|
|
|
660
|
|
|
661 /**
|
|
|
662 * A printf-formatting string prefix for a `long long` value.
|
|
|
663 *
|
|
|
664 * This is just the prefix! You probably actually want SDL_PRILLd, SDL_PRILLu,
|
|
|
665 * SDL_PRILLx, or SDL_PRILLX instead.
|
|
|
666 *
|
|
|
667 * Use it like this:
|
|
|
668 *
|
|
|
669 * ```c
|
|
|
670 * SDL_Log("There are %" SDL_PRILL_PREFIX "d bottles of beer on the wall.", bottles);
|
|
|
671 * ```
|
|
|
672 *
|
|
|
673 * \since This macro is available since SDL 3.2.0.
|
|
|
674 */
|
|
|
675 #define SDL_PRILL_PREFIX "ll"
|
|
|
676
|
|
|
677 /**
|
|
|
678 * A printf-formatting string for a `long long` value.
|
|
|
679 *
|
|
|
680 * Use it like this:
|
|
|
681 *
|
|
|
682 * ```c
|
|
|
683 * SDL_Log("There are %" SDL_PRILLd " bottles of beer on the wall.", bottles);
|
|
|
684 * ```
|
|
|
685 *
|
|
|
686 * \since This macro is available since SDL 3.2.0.
|
|
|
687 */
|
|
|
688 #define SDL_PRILLd SDL_PRILL_PREFIX "d"
|
|
|
689
|
|
|
690 /**
|
|
|
691 * A printf-formatting string for a `unsigned long long` value.
|
|
|
692 *
|
|
|
693 * Use it like this:
|
|
|
694 *
|
|
|
695 * ```c
|
|
|
696 * SDL_Log("There are %" SDL_PRILLu " bottles of beer on the wall.", bottles);
|
|
|
697 * ```
|
|
|
698 *
|
|
|
699 * \since This macro is available since SDL 3.2.0.
|
|
|
700 */
|
|
|
701 #define SDL_PRILLu SDL_PRILL_PREFIX "u"
|
|
|
702
|
|
|
703 /**
|
|
|
704 * A printf-formatting string for an `unsigned long long` value as lower-case
|
|
|
705 * hexadecimal.
|
|
|
706 *
|
|
|
707 * Use it like this:
|
|
|
708 *
|
|
|
709 * ```c
|
|
|
710 * SDL_Log("There are %" SDL_PRILLx " bottles of beer on the wall.", bottles);
|
|
|
711 * ```
|
|
|
712 *
|
|
|
713 * \since This macro is available since SDL 3.2.0.
|
|
|
714 */
|
|
|
715 #define SDL_PRILLx SDL_PRILL_PREFIX "x"
|
|
|
716
|
|
|
717 /**
|
|
|
718 * A printf-formatting string for an `unsigned long long` value as upper-case
|
|
|
719 * hexadecimal.
|
|
|
720 *
|
|
|
721 * Use it like this:
|
|
|
722 *
|
|
|
723 * ```c
|
|
|
724 * SDL_Log("There are %" SDL_PRILLX " bottles of beer on the wall.", bottles);
|
|
|
725 * ```
|
|
|
726 *
|
|
|
727 * \since This macro is available since SDL 3.2.0.
|
|
|
728 */
|
|
|
729 #define SDL_PRILLX SDL_PRILL_PREFIX "X"
|
|
|
730 #endif /* SDL_WIKI_DOCUMENTATION_SECTION */
|
|
|
731
|
|
|
732 /* Make sure we have macros for printing width-based integers.
|
|
|
733 * <inttypes.h> should define these but this is not true all platforms.
|
|
|
734 * (for example win32) */
|
|
|
735 #ifndef SDL_PRIs64
|
|
|
736 #if defined(SDL_PLATFORM_WINDOWS)
|
|
|
737 #define SDL_PRIs64 "I64d"
|
|
|
738 #elif defined(PRId64)
|
|
|
739 #define SDL_PRIs64 PRId64
|
|
|
740 #elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__)
|
|
|
741 #define SDL_PRIs64 "ld"
|
|
|
742 #else
|
|
|
743 #define SDL_PRIs64 "lld"
|
|
|
744 #endif
|
|
|
745 #endif
|
|
|
746 #ifndef SDL_PRIu64
|
|
|
747 #if defined(SDL_PLATFORM_WINDOWS)
|
|
|
748 #define SDL_PRIu64 "I64u"
|
|
|
749 #elif defined(PRIu64)
|
|
|
750 #define SDL_PRIu64 PRIu64
|
|
|
751 #elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__)
|
|
|
752 #define SDL_PRIu64 "lu"
|
|
|
753 #else
|
|
|
754 #define SDL_PRIu64 "llu"
|
|
|
755 #endif
|
|
|
756 #endif
|
|
|
757 #ifndef SDL_PRIx64
|
|
|
758 #if defined(SDL_PLATFORM_WINDOWS)
|
|
|
759 #define SDL_PRIx64 "I64x"
|
|
|
760 #elif defined(PRIx64)
|
|
|
761 #define SDL_PRIx64 PRIx64
|
|
|
762 #elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE)
|
|
|
763 #define SDL_PRIx64 "lx"
|
|
|
764 #else
|
|
|
765 #define SDL_PRIx64 "llx"
|
|
|
766 #endif
|
|
|
767 #endif
|
|
|
768 #ifndef SDL_PRIX64
|
|
|
769 #if defined(SDL_PLATFORM_WINDOWS)
|
|
|
770 #define SDL_PRIX64 "I64X"
|
|
|
771 #elif defined(PRIX64)
|
|
|
772 #define SDL_PRIX64 PRIX64
|
|
|
773 #elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE)
|
|
|
774 #define SDL_PRIX64 "lX"
|
|
|
775 #else
|
|
|
776 #define SDL_PRIX64 "llX"
|
|
|
777 #endif
|
|
|
778 #endif
|
|
|
779 #ifndef SDL_PRIs32
|
|
|
780 #ifdef PRId32
|
|
|
781 #define SDL_PRIs32 PRId32
|
|
|
782 #else
|
|
|
783 #define SDL_PRIs32 "d"
|
|
|
784 #endif
|
|
|
785 #endif
|
|
|
786 #ifndef SDL_PRIu32
|
|
|
787 #ifdef PRIu32
|
|
|
788 #define SDL_PRIu32 PRIu32
|
|
|
789 #else
|
|
|
790 #define SDL_PRIu32 "u"
|
|
|
791 #endif
|
|
|
792 #endif
|
|
|
793 #ifndef SDL_PRIx32
|
|
|
794 #ifdef PRIx32
|
|
|
795 #define SDL_PRIx32 PRIx32
|
|
|
796 #else
|
|
|
797 #define SDL_PRIx32 "x"
|
|
|
798 #endif
|
|
|
799 #endif
|
|
|
800 #ifndef SDL_PRIX32
|
|
|
801 #ifdef PRIX32
|
|
|
802 #define SDL_PRIX32 PRIX32
|
|
|
803 #else
|
|
|
804 #define SDL_PRIX32 "X"
|
|
|
805 #endif
|
|
|
806 #endif
|
|
|
807 /* Specifically for the `long long` -- SDL-specific. */
|
|
|
808 #ifdef SDL_PLATFORM_WINDOWS
|
|
|
809 #ifndef SDL_NOLONGLONG
|
|
|
810 SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 for windows - make sure `long long` is 64 bits. */
|
|
|
811 #endif
|
|
|
812 #define SDL_PRILL_PREFIX "I64"
|
|
|
813 #else
|
|
|
814 #define SDL_PRILL_PREFIX "ll"
|
|
|
815 #endif
|
|
|
816 #ifndef SDL_PRILLd
|
|
|
817 #define SDL_PRILLd SDL_PRILL_PREFIX "d"
|
|
|
818 #endif
|
|
|
819 #ifndef SDL_PRILLu
|
|
|
820 #define SDL_PRILLu SDL_PRILL_PREFIX "u"
|
|
|
821 #endif
|
|
|
822 #ifndef SDL_PRILLx
|
|
|
823 #define SDL_PRILLx SDL_PRILL_PREFIX "x"
|
|
|
824 #endif
|
|
|
825 #ifndef SDL_PRILLX
|
|
|
826 #define SDL_PRILLX SDL_PRILL_PREFIX "X"
|
|
|
827 #endif
|
|
|
828
|
|
|
829 /* Annotations to help code analysis tools */
|
|
|
830 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
831
|
|
|
832 /**
|
|
|
833 * Macro that annotates function params with input buffer size.
|
|
|
834 *
|
|
|
835 * If we were to annotate `memcpy`:
|
|
|
836 *
|
|
|
837 * ```c
|
|
|
838 * void *memcpy(void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len);
|
|
|
839 * ```
|
|
|
840 *
|
|
|
841 * This notes that `src` should be `len` bytes in size and is only read by the
|
|
|
842 * function. The compiler or other analysis tools can warn when this doesn't
|
|
|
843 * appear to be the case.
|
|
|
844 *
|
|
|
845 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
846 *
|
|
|
847 * \since This macro is available since SDL 3.2.0.
|
|
|
848 */
|
|
|
849 #define SDL_IN_BYTECAP(x) _In_bytecount_(x)
|
|
|
850
|
|
|
851 /**
|
|
|
852 * Macro that annotates function params with input/output string buffer size.
|
|
|
853 *
|
|
|
854 * If we were to annotate `strlcat`:
|
|
|
855 *
|
|
|
856 * ```c
|
|
|
857 * size_t strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);
|
|
|
858 * ```
|
|
|
859 *
|
|
|
860 * This notes that `dst` is a null-terminated C string, should be `maxlen`
|
|
|
861 * bytes in size, and is both read from and written to by the function. The
|
|
|
862 * compiler or other analysis tools can warn when this doesn't appear to be
|
|
|
863 * the case.
|
|
|
864 *
|
|
|
865 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
866 *
|
|
|
867 * \since This macro is available since SDL 3.2.0.
|
|
|
868 */
|
|
|
869 #define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x)
|
|
|
870
|
|
|
871 /**
|
|
|
872 * Macro that annotates function params with output string buffer size.
|
|
|
873 *
|
|
|
874 * If we were to annotate `snprintf`:
|
|
|
875 *
|
|
|
876 * ```c
|
|
|
877 * int snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, ...);
|
|
|
878 * ```
|
|
|
879 *
|
|
|
880 * This notes that `text` is a null-terminated C string, should be `maxlen`
|
|
|
881 * bytes in size, and is only written to by the function. The compiler or
|
|
|
882 * other analysis tools can warn when this doesn't appear to be the case.
|
|
|
883 *
|
|
|
884 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
885 *
|
|
|
886 * \since This macro is available since SDL 3.2.0.
|
|
|
887 */
|
|
|
888 #define SDL_OUT_Z_CAP(x) _Out_z_cap_(x)
|
|
|
889
|
|
|
890 /**
|
|
|
891 * Macro that annotates function params with output buffer size.
|
|
|
892 *
|
|
|
893 * If we were to annotate `wcsncpy`:
|
|
|
894 *
|
|
|
895 * ```c
|
|
|
896 * char *wcscpy(SDL_OUT_CAP(bufsize) wchar_t *dst, const wchar_t *src, size_t bufsize);
|
|
|
897 * ```
|
|
|
898 *
|
|
|
899 * This notes that `dst` should have a capacity of `bufsize` wchar_t in size,
|
|
|
900 * and is only written to by the function. The compiler or other analysis
|
|
|
901 * tools can warn when this doesn't appear to be the case.
|
|
|
902 *
|
|
|
903 * This operates on counts of objects, not bytes. Use SDL_OUT_BYTECAP for
|
|
|
904 * bytes.
|
|
|
905 *
|
|
|
906 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
907 *
|
|
|
908 * \since This macro is available since SDL 3.2.0.
|
|
|
909 */
|
|
|
910 #define SDL_OUT_CAP(x) _Out_cap_(x)
|
|
|
911
|
|
|
912 /**
|
|
|
913 * Macro that annotates function params with output buffer size.
|
|
|
914 *
|
|
|
915 * If we were to annotate `memcpy`:
|
|
|
916 *
|
|
|
917 * ```c
|
|
|
918 * void *memcpy(SDL_OUT_BYTECAP(bufsize) void *dst, const void *src, size_t bufsize);
|
|
|
919 * ```
|
|
|
920 *
|
|
|
921 * This notes that `dst` should have a capacity of `bufsize` bytes in size,
|
|
|
922 * and is only written to by the function. The compiler or other analysis
|
|
|
923 * tools can warn when this doesn't appear to be the case.
|
|
|
924 *
|
|
|
925 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
926 *
|
|
|
927 * \since This macro is available since SDL 3.2.0.
|
|
|
928 */
|
|
|
929 #define SDL_OUT_BYTECAP(x) _Out_bytecap_(x)
|
|
|
930
|
|
|
931 /**
|
|
|
932 * Macro that annotates function params with output buffer string size.
|
|
|
933 *
|
|
|
934 * If we were to annotate `strcpy`:
|
|
|
935 *
|
|
|
936 * ```c
|
|
|
937 * char *strcpy(SDL_OUT_Z_BYTECAP(bufsize) char *dst, const char *src, size_t bufsize);
|
|
|
938 * ```
|
|
|
939 *
|
|
|
940 * This notes that `dst` should have a capacity of `bufsize` bytes in size,
|
|
|
941 * and a zero-terminated string is written to it by the function. The compiler
|
|
|
942 * or other analysis tools can warn when this doesn't appear to be the case.
|
|
|
943 *
|
|
|
944 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
945 *
|
|
|
946 * \since This macro is available since SDL 3.2.0.
|
|
|
947 */
|
|
|
948 #define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x)
|
|
|
949
|
|
|
950 /**
|
|
|
951 * Macro that annotates function params as printf-style format strings.
|
|
|
952 *
|
|
|
953 * If we were to annotate `fprintf`:
|
|
|
954 *
|
|
|
955 * ```c
|
|
|
956 * int fprintf(FILE *f, SDL_PRINTF_FORMAT_STRING const char *fmt, ...);
|
|
|
957 * ```
|
|
|
958 *
|
|
|
959 * This notes that `fmt` should be a printf-style format string. The compiler
|
|
|
960 * or other analysis tools can warn when this doesn't appear to be the case.
|
|
|
961 *
|
|
|
962 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
963 *
|
|
|
964 * \since This macro is available since SDL 3.2.0.
|
|
|
965 */
|
|
|
966 #define SDL_PRINTF_FORMAT_STRING _Printf_format_string_
|
|
|
967
|
|
|
968 /**
|
|
|
969 * Macro that annotates function params as scanf-style format strings.
|
|
|
970 *
|
|
|
971 * If we were to annotate `fscanf`:
|
|
|
972 *
|
|
|
973 * ```c
|
|
|
974 * int fscanf(FILE *f, SDL_SCANF_FORMAT_STRING const char *fmt, ...);
|
|
|
975 * ```
|
|
|
976 *
|
|
|
977 * This notes that `fmt` should be a scanf-style format string. The compiler
|
|
|
978 * or other analysis tools can warn when this doesn't appear to be the case.
|
|
|
979 *
|
|
|
980 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
981 *
|
|
|
982 * \since This macro is available since SDL 3.2.0.
|
|
|
983 */
|
|
|
984 #define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_
|
|
|
985
|
|
|
986 /**
|
|
|
987 * Macro that annotates a vararg function that operates like printf.
|
|
|
988 *
|
|
|
989 * If we were to annotate `fprintf`:
|
|
|
990 *
|
|
|
991 * ```c
|
|
|
992 * int fprintf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
|
|
|
993 * ```
|
|
|
994 *
|
|
|
995 * This notes that the second parameter should be a printf-style format
|
|
|
996 * string, followed by `...`. The compiler or other analysis tools can warn
|
|
|
997 * when this doesn't appear to be the case.
|
|
|
998 *
|
|
|
999 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
1000 *
|
|
|
1001 * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
|
|
|
1002 * between them will cover at least Visual Studio, GCC, and Clang.
|
|
|
1003 *
|
|
|
1004 * \since This macro is available since SDL 3.2.0.
|
|
|
1005 */
|
|
|
1006 #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 )))
|
|
|
1007
|
|
|
1008 /**
|
|
|
1009 * Macro that annotates a va_list function that operates like printf.
|
|
|
1010 *
|
|
|
1011 * If we were to annotate `vfprintf`:
|
|
|
1012 *
|
|
|
1013 * ```c
|
|
|
1014 * int vfprintf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
|
|
|
1015 * ```
|
|
|
1016 *
|
|
|
1017 * This notes that the second parameter should be a printf-style format
|
|
|
1018 * string, followed by a va_list. The compiler or other analysis tools can
|
|
|
1019 * warn when this doesn't appear to be the case.
|
|
|
1020 *
|
|
|
1021 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
1022 *
|
|
|
1023 * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
|
|
|
1024 * between them will cover at least Visual Studio, GCC, and Clang.
|
|
|
1025 *
|
|
|
1026 * \since This macro is available since SDL 3.2.0.
|
|
|
1027 */
|
|
|
1028 #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 )))
|
|
|
1029
|
|
|
1030 /**
|
|
|
1031 * Macro that annotates a vararg function that operates like scanf.
|
|
|
1032 *
|
|
|
1033 * If we were to annotate `fscanf`:
|
|
|
1034 *
|
|
|
1035 * ```c
|
|
|
1036 * int fscanf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNCV(2);
|
|
|
1037 * ```
|
|
|
1038 *
|
|
|
1039 * This notes that the second parameter should be a scanf-style format string,
|
|
|
1040 * followed by `...`. The compiler or other analysis tools can warn when this
|
|
|
1041 * doesn't appear to be the case.
|
|
|
1042 *
|
|
|
1043 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
1044 *
|
|
|
1045 * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which
|
|
|
1046 * between them will cover at least Visual Studio, GCC, and Clang.
|
|
|
1047 *
|
|
|
1048 * \since This macro is available since SDL 3.2.0.
|
|
|
1049 */
|
|
|
1050 #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 )))
|
|
|
1051
|
|
|
1052 /**
|
|
|
1053 * Macro that annotates a va_list function that operates like scanf.
|
|
|
1054 *
|
|
|
1055 * If we were to annotate `vfscanf`:
|
|
|
1056 *
|
|
|
1057 * ```c
|
|
|
1058 * int vfscanf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
|
|
|
1059 * ```
|
|
|
1060 *
|
|
|
1061 * This notes that the second parameter should be a scanf-style format string,
|
|
|
1062 * followed by a va_list. The compiler or other analysis tools can warn when
|
|
|
1063 * this doesn't appear to be the case.
|
|
|
1064 *
|
|
|
1065 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
1066 *
|
|
|
1067 * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which
|
|
|
1068 * between them will cover at least Visual Studio, GCC, and Clang.
|
|
|
1069 *
|
|
|
1070 * \since This macro is available since SDL 3.2.0.
|
|
|
1071 */
|
|
|
1072 #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 )))
|
|
|
1073
|
|
|
1074 /**
|
|
|
1075 * Macro that annotates a vararg function that operates like wprintf.
|
|
|
1076 *
|
|
|
1077 * If we were to annotate `fwprintf`:
|
|
|
1078 *
|
|
|
1079 * ```c
|
|
|
1080 * int fwprintf(FILE *f, const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(2);
|
|
|
1081 * ```
|
|
|
1082 *
|
|
|
1083 * This notes that the second parameter should be a wprintf-style format wide
|
|
|
1084 * string, followed by `...`. The compiler or other analysis tools can warn
|
|
|
1085 * when this doesn't appear to be the case.
|
|
|
1086 *
|
|
|
1087 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
1088 *
|
|
|
1089 * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
|
|
|
1090 * between them will cover at least Visual Studio, GCC, and Clang.
|
|
|
1091 *
|
|
|
1092 * \since This macro is available since SDL 3.2.0.
|
|
|
1093 */
|
|
|
1094 #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */
|
|
|
1095
|
|
|
1096 /**
|
|
|
1097 * Macro that annotates a va_list function that operates like wprintf.
|
|
|
1098 *
|
|
|
1099 * If we were to annotate `vfwprintf`:
|
|
|
1100 *
|
|
|
1101 * ```c
|
|
|
1102 * int vfwprintf(FILE *f, const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNC(2);
|
|
|
1103 * ```
|
|
|
1104 *
|
|
|
1105 * This notes that the second parameter should be a wprintf-style format wide
|
|
|
1106 * string, followed by a va_list. The compiler or other analysis tools can
|
|
|
1107 * warn when this doesn't appear to be the case.
|
|
|
1108 *
|
|
|
1109 * On compilers without this annotation mechanism, this is defined to nothing.
|
|
|
1110 *
|
|
|
1111 * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
|
|
|
1112 * between them will cover at least Visual Studio, GCC, and Clang.
|
|
|
1113 *
|
|
|
1114 * \since This macro is available since SDL 3.2.0.
|
|
|
1115 */
|
|
|
1116 #define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */
|
|
|
1117
|
|
|
1118 #elif defined(SDL_DISABLE_ANALYZE_MACROS)
|
|
|
1119 #define SDL_IN_BYTECAP(x)
|
|
|
1120 #define SDL_INOUT_Z_CAP(x)
|
|
|
1121 #define SDL_OUT_Z_CAP(x)
|
|
|
1122 #define SDL_OUT_CAP(x)
|
|
|
1123 #define SDL_OUT_BYTECAP(x)
|
|
|
1124 #define SDL_OUT_Z_BYTECAP(x)
|
|
|
1125 #define SDL_PRINTF_FORMAT_STRING
|
|
|
1126 #define SDL_SCANF_FORMAT_STRING
|
|
|
1127 #define SDL_PRINTF_VARARG_FUNC( fmtargnumber )
|
|
|
1128 #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber )
|
|
|
1129 #define SDL_SCANF_VARARG_FUNC( fmtargnumber )
|
|
|
1130 #define SDL_SCANF_VARARG_FUNCV( fmtargnumber )
|
|
|
1131 #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber )
|
|
|
1132 #define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber )
|
|
|
1133 #else
|
|
|
1134 #if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */
|
|
|
1135 #include <sal.h>
|
|
|
1136
|
|
|
1137 #define SDL_IN_BYTECAP(x) _In_bytecount_(x)
|
|
|
1138 #define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x)
|
|
|
1139 #define SDL_OUT_Z_CAP(x) _Out_z_cap_(x)
|
|
|
1140 #define SDL_OUT_CAP(x) _Out_cap_(x)
|
|
|
1141 #define SDL_OUT_BYTECAP(x) _Out_bytecap_(x)
|
|
|
1142 #define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x)
|
|
|
1143
|
|
|
1144 #define SDL_PRINTF_FORMAT_STRING _Printf_format_string_
|
|
|
1145 #define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_
|
|
|
1146 #else
|
|
|
1147 #define SDL_IN_BYTECAP(x)
|
|
|
1148 #define SDL_INOUT_Z_CAP(x)
|
|
|
1149 #define SDL_OUT_Z_CAP(x)
|
|
|
1150 #define SDL_OUT_CAP(x)
|
|
|
1151 #define SDL_OUT_BYTECAP(x)
|
|
|
1152 #define SDL_OUT_Z_BYTECAP(x)
|
|
|
1153 #define SDL_PRINTF_FORMAT_STRING
|
|
|
1154 #define SDL_SCANF_FORMAT_STRING
|
|
|
1155 #endif
|
|
|
1156 #if defined(__GNUC__) || defined(__clang__)
|
|
|
1157 #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 )))
|
|
|
1158 #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 )))
|
|
|
1159 #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 )))
|
|
|
1160 #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 )))
|
|
|
1161 #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */
|
|
|
1162 #define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */
|
|
|
1163 #else
|
|
|
1164 #define SDL_PRINTF_VARARG_FUNC( fmtargnumber )
|
|
|
1165 #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber )
|
|
|
1166 #define SDL_SCANF_VARARG_FUNC( fmtargnumber )
|
|
|
1167 #define SDL_SCANF_VARARG_FUNCV( fmtargnumber )
|
|
|
1168 #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber )
|
|
|
1169 #define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber )
|
|
|
1170 #endif
|
|
|
1171 #endif /* SDL_DISABLE_ANALYZE_MACROS */
|
|
|
1172
|
|
|
1173 /** \cond */
|
|
|
1174 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
|
|
|
1175 SDL_COMPILE_TIME_ASSERT(bool_size, sizeof(bool) == 1);
|
|
|
1176 SDL_COMPILE_TIME_ASSERT(uint8_size, sizeof(Uint8) == 1);
|
|
|
1177 SDL_COMPILE_TIME_ASSERT(sint8_size, sizeof(Sint8) == 1);
|
|
|
1178 SDL_COMPILE_TIME_ASSERT(uint16_size, sizeof(Uint16) == 2);
|
|
|
1179 SDL_COMPILE_TIME_ASSERT(sint16_size, sizeof(Sint16) == 2);
|
|
|
1180 SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4);
|
|
|
1181 SDL_COMPILE_TIME_ASSERT(sint32_size, sizeof(Sint32) == 4);
|
|
|
1182 SDL_COMPILE_TIME_ASSERT(uint64_size, sizeof(Uint64) == 8);
|
|
|
1183 SDL_COMPILE_TIME_ASSERT(sint64_size, sizeof(Sint64) == 8);
|
|
|
1184 #ifndef SDL_NOLONGLONG
|
|
|
1185 SDL_COMPILE_TIME_ASSERT(uint64_longlong, sizeof(Uint64) <= sizeof(unsigned long long));
|
|
|
1186 SDL_COMPILE_TIME_ASSERT(size_t_longlong, sizeof(size_t) <= sizeof(unsigned long long));
|
|
|
1187 #endif
|
|
|
1188 typedef struct SDL_alignment_test
|
|
|
1189 {
|
|
|
1190 Uint8 a;
|
|
|
1191 void *b;
|
|
|
1192 } SDL_alignment_test;
|
|
|
1193 SDL_COMPILE_TIME_ASSERT(struct_alignment, sizeof(SDL_alignment_test) == (2 * sizeof(void *)));
|
|
|
1194 SDL_COMPILE_TIME_ASSERT(two_s_complement, SDL_static_cast(int, ~SDL_static_cast(int, 0)) == SDL_static_cast(int, -1));
|
|
|
1195 #endif /* DOXYGEN_SHOULD_IGNORE_THIS */
|
|
|
1196 /** \endcond */
|
|
|
1197
|
|
|
1198 /* Check to make sure enums are the size of ints, for structure packing.
|
|
|
1199 For both Watcom C/C++ and Borland C/C++ the compiler option that makes
|
|
|
1200 enums having the size of an int must be enabled.
|
|
|
1201 This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11).
|
|
|
1202 */
|
|
|
1203
|
|
|
1204 /** \cond */
|
|
|
1205 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
|
|
|
1206 #if !defined(SDL_PLATFORM_VITA) && !defined(SDL_PLATFORM_3DS)
|
|
|
1207 /* TODO: include/SDL_stdinc.h:390: error: size of array 'SDL_dummy_enum' is negative */
|
|
|
1208 typedef enum SDL_DUMMY_ENUM
|
|
|
1209 {
|
|
|
1210 DUMMY_ENUM_VALUE
|
|
|
1211 } SDL_DUMMY_ENUM;
|
|
|
1212
|
|
|
1213 SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int));
|
|
|
1214 #endif
|
|
|
1215 #endif /* DOXYGEN_SHOULD_IGNORE_THIS */
|
|
|
1216 /** \endcond */
|
|
|
1217
|
|
|
1218 #include <SDL3/SDL_begin_code.h>
|
|
|
1219 /* Set up for C function definitions, even when using C++ */
|
|
|
1220 #ifdef __cplusplus
|
|
|
1221 extern "C" {
|
|
|
1222 #endif
|
|
|
1223
|
|
|
1224 /**
|
|
|
1225 * A macro to initialize an SDL interface.
|
|
|
1226 *
|
|
|
1227 * This macro will initialize an SDL interface structure and should be called
|
|
|
1228 * before you fill out the fields with your implementation.
|
|
|
1229 *
|
|
|
1230 * You can use it like this:
|
|
|
1231 *
|
|
|
1232 * ```c
|
|
|
1233 * SDL_IOStreamInterface iface;
|
|
|
1234 *
|
|
|
1235 * SDL_INIT_INTERFACE(&iface);
|
|
|
1236 *
|
|
|
1237 * // Fill in the interface function pointers with your implementation
|
|
|
1238 * iface.seek = ...
|
|
|
1239 *
|
|
|
1240 * stream = SDL_OpenIO(&iface, NULL);
|
|
|
1241 * ```
|
|
|
1242 *
|
|
|
1243 * If you are using designated initializers, you can use the size of the
|
|
|
1244 * interface as the version, e.g.
|
|
|
1245 *
|
|
|
1246 * ```c
|
|
|
1247 * SDL_IOStreamInterface iface = {
|
|
|
1248 * .version = sizeof(iface),
|
|
|
1249 * .seek = ...
|
|
|
1250 * };
|
|
|
1251 * stream = SDL_OpenIO(&iface, NULL);
|
|
|
1252 * ```
|
|
|
1253 *
|
|
|
1254 * \threadsafety It is safe to call this macro from any thread.
|
|
|
1255 *
|
|
|
1256 * \since This macro is available since SDL 3.2.0.
|
|
|
1257 *
|
|
|
1258 * \sa SDL_IOStreamInterface
|
|
|
1259 * \sa SDL_StorageInterface
|
|
|
1260 * \sa SDL_VirtualJoystickDesc
|
|
|
1261 */
|
|
|
1262 #define SDL_INIT_INTERFACE(iface) \
|
|
|
1263 do { \
|
|
|
1264 SDL_zerop(iface); \
|
|
|
1265 (iface)->version = sizeof(*(iface)); \
|
|
|
1266 } while (0)
|
|
|
1267
|
|
|
1268
|
|
|
1269 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
1270
|
|
|
1271 /**
|
|
|
1272 * Allocate memory on the stack (maybe).
|
|
|
1273 *
|
|
|
1274 * If SDL knows how to access alloca() on the current platform, it will use it
|
|
|
1275 * to stack-allocate memory here. If it doesn't, it will use SDL_malloc() to
|
|
|
1276 * heap-allocate memory.
|
|
|
1277 *
|
|
|
1278 * Since this might not be stack memory at all, it's important that you check
|
|
|
1279 * the returned pointer for NULL, and that you call SDL_stack_free on the
|
|
|
1280 * memory when done with it. Since this might be stack memory, it's important
|
|
|
1281 * that you don't allocate large amounts of it, or allocate in a loop without
|
|
|
1282 * returning from the function, so the stack doesn't overflow.
|
|
|
1283 *
|
|
|
1284 * \param type the datatype of the memory to allocate.
|
|
|
1285 * \param count the number of `type` objects to allocate.
|
|
|
1286 * \returns newly-allocated memory, or NULL on failure.
|
|
|
1287 *
|
|
|
1288 * \threadsafety It is safe to call this macro from any thread.
|
|
|
1289 *
|
|
|
1290 * \since This macro is available since SDL 3.2.0.
|
|
|
1291 *
|
|
|
1292 * \sa SDL_stack_free
|
|
|
1293 */
|
|
|
1294 #define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count))
|
|
|
1295
|
|
|
1296 /**
|
|
|
1297 * Free memory previously allocated with SDL_stack_alloc.
|
|
|
1298 *
|
|
|
1299 * If SDL used alloca() to allocate this memory, this macro does nothing and
|
|
|
1300 * the allocated memory will be automatically released when the function that
|
|
|
1301 * called SDL_stack_alloc() returns. If SDL used SDL_malloc(), it will
|
|
|
1302 * SDL_free the memory immediately.
|
|
|
1303 *
|
|
|
1304 * \param data the pointer, from SDL_stack_alloc(), to free.
|
|
|
1305 *
|
|
|
1306 * \threadsafety It is safe to call this macro from any thread.
|
|
|
1307 *
|
|
|
1308 * \since This macro is available since SDL 3.2.0.
|
|
|
1309 *
|
|
|
1310 * \sa SDL_stack_alloc
|
|
|
1311 */
|
|
|
1312 #define SDL_stack_free(data)
|
|
|
1313 #elif !defined(SDL_DISABLE_ALLOCA)
|
|
|
1314 #define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count))
|
|
|
1315 #define SDL_stack_free(data)
|
|
|
1316 #else
|
|
|
1317 #define SDL_stack_alloc(type, count) (type*)SDL_malloc(sizeof(type)*(count))
|
|
|
1318 #define SDL_stack_free(data) SDL_free(data)
|
|
|
1319 #endif
|
|
|
1320
|
|
|
1321 /**
|
|
|
1322 * Allocate uninitialized memory.
|
|
|
1323 *
|
|
|
1324 * The allocated memory returned by this function must be freed with
|
|
|
1325 * SDL_free().
|
|
|
1326 *
|
|
|
1327 * If `size` is 0, it will be set to 1.
|
|
|
1328 *
|
|
|
1329 * If the allocation is successful, the returned pointer is guaranteed to be
|
|
|
1330 * aligned to either the *fundamental alignment* (`alignof(max_align_t)` in
|
|
|
1331 * C11 and later) or `2 * sizeof(void *)`, whichever is smaller. Use
|
|
|
1332 * SDL_aligned_alloc() if you need to allocate memory aligned to an alignment
|
|
|
1333 * greater than this guarantee.
|
|
|
1334 *
|
|
|
1335 * \param size the size to allocate.
|
|
|
1336 * \returns a pointer to the allocated memory, or NULL if allocation failed.
|
|
|
1337 *
|
|
|
1338 * \threadsafety It is safe to call this function from any thread.
|
|
|
1339 *
|
|
|
1340 * \since This function is available since SDL 3.2.0.
|
|
|
1341 *
|
|
|
1342 * \sa SDL_free
|
|
|
1343 * \sa SDL_calloc
|
|
|
1344 * \sa SDL_realloc
|
|
|
1345 * \sa SDL_aligned_alloc
|
|
|
1346 */
|
|
|
1347 extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size);
|
|
|
1348
|
|
|
1349 /**
|
|
|
1350 * Allocate a zero-initialized array.
|
|
|
1351 *
|
|
|
1352 * The memory returned by this function must be freed with SDL_free().
|
|
|
1353 *
|
|
|
1354 * If either of `nmemb` or `size` is 0, they will both be set to 1.
|
|
|
1355 *
|
|
|
1356 * If the allocation is successful, the returned pointer is guaranteed to be
|
|
|
1357 * aligned to either the *fundamental alignment* (`alignof(max_align_t)` in
|
|
|
1358 * C11 and later) or `2 * sizeof(void *)`, whichever is smaller.
|
|
|
1359 *
|
|
|
1360 * \param nmemb the number of elements in the array.
|
|
|
1361 * \param size the size of each element of the array.
|
|
|
1362 * \returns a pointer to the allocated array, or NULL if allocation failed.
|
|
|
1363 *
|
|
|
1364 * \threadsafety It is safe to call this function from any thread.
|
|
|
1365 *
|
|
|
1366 * \since This function is available since SDL 3.2.0.
|
|
|
1367 *
|
|
|
1368 * \sa SDL_free
|
|
|
1369 * \sa SDL_malloc
|
|
|
1370 * \sa SDL_realloc
|
|
|
1371 */
|
|
|
1372 extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(size_t nmemb, size_t size);
|
|
|
1373
|
|
|
1374 /**
|
|
|
1375 * Change the size of allocated memory.
|
|
|
1376 *
|
|
|
1377 * The memory returned by this function must be freed with SDL_free().
|
|
|
1378 *
|
|
|
1379 * If `size` is 0, it will be set to 1. Note that this is unlike some other C
|
|
|
1380 * runtime `realloc` implementations, which may treat `realloc(mem, 0)` the
|
|
|
1381 * same way as `free(mem)`.
|
|
|
1382 *
|
|
|
1383 * If `mem` is NULL, the behavior of this function is equivalent to
|
|
|
1384 * SDL_malloc(). Otherwise, the function can have one of three possible
|
|
|
1385 * outcomes:
|
|
|
1386 *
|
|
|
1387 * - If it returns the same pointer as `mem`, it means that `mem` was resized
|
|
|
1388 * in place without freeing.
|
|
|
1389 * - If it returns a different non-NULL pointer, it means that `mem` was freed
|
|
|
1390 * and cannot be dereferenced anymore.
|
|
|
1391 * - If it returns NULL (indicating failure), then `mem` will remain valid and
|
|
|
1392 * must still be freed with SDL_free().
|
|
|
1393 *
|
|
|
1394 * If the allocation is successfully resized, the returned pointer is
|
|
|
1395 * guaranteed to be aligned to either the *fundamental alignment*
|
|
|
1396 * (`alignof(max_align_t)` in C11 and later) or `2 * sizeof(void *)`,
|
|
|
1397 * whichever is smaller.
|
|
|
1398 *
|
|
|
1399 * \param mem a pointer to allocated memory to reallocate, or NULL.
|
|
|
1400 * \param size the new size of the memory.
|
|
|
1401 * \returns a pointer to the newly allocated memory, or NULL if allocation
|
|
|
1402 * failed.
|
|
|
1403 *
|
|
|
1404 * \threadsafety It is safe to call this function from any thread.
|
|
|
1405 *
|
|
|
1406 * \since This function is available since SDL 3.2.0.
|
|
|
1407 *
|
|
|
1408 * \sa SDL_free
|
|
|
1409 * \sa SDL_malloc
|
|
|
1410 * \sa SDL_calloc
|
|
|
1411 */
|
|
|
1412 extern SDL_DECLSPEC SDL_ALLOC_SIZE(2) void * SDLCALL SDL_realloc(void *mem, size_t size);
|
|
|
1413
|
|
|
1414 /**
|
|
|
1415 * Free allocated memory.
|
|
|
1416 *
|
|
|
1417 * The pointer is no longer valid after this call and cannot be dereferenced
|
|
|
1418 * anymore.
|
|
|
1419 *
|
|
|
1420 * If `mem` is NULL, this function does nothing.
|
|
|
1421 *
|
|
|
1422 * \param mem a pointer to allocated memory, or NULL.
|
|
|
1423 *
|
|
|
1424 * \threadsafety It is safe to call this function from any thread.
|
|
|
1425 *
|
|
|
1426 * \since This function is available since SDL 3.2.0.
|
|
|
1427 *
|
|
|
1428 * \sa SDL_malloc
|
|
|
1429 * \sa SDL_calloc
|
|
|
1430 * \sa SDL_realloc
|
|
|
1431 */
|
|
|
1432 extern SDL_DECLSPEC void SDLCALL SDL_free(void *mem);
|
|
|
1433
|
|
|
1434 /**
|
|
|
1435 * A callback used to implement SDL_malloc().
|
|
|
1436 *
|
|
|
1437 * SDL will always ensure that the passed `size` is greater than 0.
|
|
|
1438 *
|
|
|
1439 * \param size the size to allocate.
|
|
|
1440 * \returns a pointer to the allocated memory, or NULL if allocation failed.
|
|
|
1441 *
|
|
|
1442 * \threadsafety It should be safe to call this callback from any thread.
|
|
|
1443 *
|
|
|
1444 * \since This datatype is available since SDL 3.2.0.
|
|
|
1445 *
|
|
|
1446 * \sa SDL_malloc
|
|
|
1447 * \sa SDL_GetOriginalMemoryFunctions
|
|
|
1448 * \sa SDL_GetMemoryFunctions
|
|
|
1449 * \sa SDL_SetMemoryFunctions
|
|
|
1450 */
|
|
|
1451 typedef void *(SDLCALL *SDL_malloc_func)(size_t size);
|
|
|
1452
|
|
|
1453 /**
|
|
|
1454 * A callback used to implement SDL_calloc().
|
|
|
1455 *
|
|
|
1456 * SDL will always ensure that the passed `nmemb` and `size` are both greater
|
|
|
1457 * than 0.
|
|
|
1458 *
|
|
|
1459 * \param nmemb the number of elements in the array.
|
|
|
1460 * \param size the size of each element of the array.
|
|
|
1461 * \returns a pointer to the allocated array, or NULL if allocation failed.
|
|
|
1462 *
|
|
|
1463 * \threadsafety It should be safe to call this callback from any thread.
|
|
|
1464 *
|
|
|
1465 * \since This datatype is available since SDL 3.2.0.
|
|
|
1466 *
|
|
|
1467 * \sa SDL_calloc
|
|
|
1468 * \sa SDL_GetOriginalMemoryFunctions
|
|
|
1469 * \sa SDL_GetMemoryFunctions
|
|
|
1470 * \sa SDL_SetMemoryFunctions
|
|
|
1471 */
|
|
|
1472 typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size);
|
|
|
1473
|
|
|
1474 /**
|
|
|
1475 * A callback used to implement SDL_realloc().
|
|
|
1476 *
|
|
|
1477 * SDL will always ensure that the passed `size` is greater than 0.
|
|
|
1478 *
|
|
|
1479 * \param mem a pointer to allocated memory to reallocate, or NULL.
|
|
|
1480 * \param size the new size of the memory.
|
|
|
1481 * \returns a pointer to the newly allocated memory, or NULL if allocation
|
|
|
1482 * failed.
|
|
|
1483 *
|
|
|
1484 * \threadsafety It should be safe to call this callback from any thread.
|
|
|
1485 *
|
|
|
1486 * \since This datatype is available since SDL 3.2.0.
|
|
|
1487 *
|
|
|
1488 * \sa SDL_realloc
|
|
|
1489 * \sa SDL_GetOriginalMemoryFunctions
|
|
|
1490 * \sa SDL_GetMemoryFunctions
|
|
|
1491 * \sa SDL_SetMemoryFunctions
|
|
|
1492 */
|
|
|
1493 typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size);
|
|
|
1494
|
|
|
1495 /**
|
|
|
1496 * A callback used to implement SDL_free().
|
|
|
1497 *
|
|
|
1498 * SDL will always ensure that the passed `mem` is a non-NULL pointer.
|
|
|
1499 *
|
|
|
1500 * \param mem a pointer to allocated memory.
|
|
|
1501 *
|
|
|
1502 * \threadsafety It should be safe to call this callback from any thread.
|
|
|
1503 *
|
|
|
1504 * \since This datatype is available since SDL 3.2.0.
|
|
|
1505 *
|
|
|
1506 * \sa SDL_free
|
|
|
1507 * \sa SDL_GetOriginalMemoryFunctions
|
|
|
1508 * \sa SDL_GetMemoryFunctions
|
|
|
1509 * \sa SDL_SetMemoryFunctions
|
|
|
1510 */
|
|
|
1511 typedef void (SDLCALL *SDL_free_func)(void *mem);
|
|
|
1512
|
|
|
1513 /**
|
|
|
1514 * Get the original set of SDL memory functions.
|
|
|
1515 *
|
|
|
1516 * This is what SDL_malloc and friends will use by default, if there has been
|
|
|
1517 * no call to SDL_SetMemoryFunctions. This is not necessarily using the C
|
|
|
1518 * runtime's `malloc` functions behind the scenes! Different platforms and
|
|
|
1519 * build configurations might do any number of unexpected things.
|
|
|
1520 *
|
|
|
1521 * \param malloc_func filled with malloc function.
|
|
|
1522 * \param calloc_func filled with calloc function.
|
|
|
1523 * \param realloc_func filled with realloc function.
|
|
|
1524 * \param free_func filled with free function.
|
|
|
1525 *
|
|
|
1526 * \threadsafety It is safe to call this function from any thread.
|
|
|
1527 *
|
|
|
1528 * \since This function is available since SDL 3.2.0.
|
|
|
1529 */
|
|
|
1530 extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func,
|
|
|
1531 SDL_calloc_func *calloc_func,
|
|
|
1532 SDL_realloc_func *realloc_func,
|
|
|
1533 SDL_free_func *free_func);
|
|
|
1534
|
|
|
1535 /**
|
|
|
1536 * Get the current set of SDL memory functions.
|
|
|
1537 *
|
|
|
1538 * \param malloc_func filled with malloc function.
|
|
|
1539 * \param calloc_func filled with calloc function.
|
|
|
1540 * \param realloc_func filled with realloc function.
|
|
|
1541 * \param free_func filled with free function.
|
|
|
1542 *
|
|
|
1543 * \threadsafety This does not hold a lock, so do not call this in the
|
|
|
1544 * unlikely event of a background thread calling
|
|
|
1545 * SDL_SetMemoryFunctions simultaneously.
|
|
|
1546 *
|
|
|
1547 * \since This function is available since SDL 3.2.0.
|
|
|
1548 *
|
|
|
1549 * \sa SDL_SetMemoryFunctions
|
|
|
1550 * \sa SDL_GetOriginalMemoryFunctions
|
|
|
1551 */
|
|
|
1552 extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func,
|
|
|
1553 SDL_calloc_func *calloc_func,
|
|
|
1554 SDL_realloc_func *realloc_func,
|
|
|
1555 SDL_free_func *free_func);
|
|
|
1556
|
|
|
1557 /**
|
|
|
1558 * Replace SDL's memory allocation functions with a custom set.
|
|
|
1559 *
|
|
|
1560 * It is not safe to call this function once any allocations have been made,
|
|
|
1561 * as future calls to SDL_free will use the new allocator, even if they came
|
|
|
1562 * from an SDL_malloc made with the old one!
|
|
|
1563 *
|
|
|
1564 * If used, usually this needs to be the first call made into the SDL library,
|
|
|
1565 * if not the very first thing done at program startup time.
|
|
|
1566 *
|
|
|
1567 * \param malloc_func custom malloc function.
|
|
|
1568 * \param calloc_func custom calloc function.
|
|
|
1569 * \param realloc_func custom realloc function.
|
|
|
1570 * \param free_func custom free function.
|
|
|
1571 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1572 * information.
|
|
|
1573 *
|
|
|
1574 * \threadsafety It is safe to call this function from any thread, but one
|
|
|
1575 * should not replace the memory functions once any allocations
|
|
|
1576 * are made!
|
|
|
1577 *
|
|
|
1578 * \since This function is available since SDL 3.2.0.
|
|
|
1579 *
|
|
|
1580 * \sa SDL_GetMemoryFunctions
|
|
|
1581 * \sa SDL_GetOriginalMemoryFunctions
|
|
|
1582 */
|
|
|
1583 extern SDL_DECLSPEC bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
|
|
|
1584 SDL_calloc_func calloc_func,
|
|
|
1585 SDL_realloc_func realloc_func,
|
|
|
1586 SDL_free_func free_func);
|
|
|
1587
|
|
|
1588 /**
|
|
|
1589 * Allocate memory aligned to a specific alignment.
|
|
|
1590 *
|
|
|
1591 * The memory returned by this function must be freed with SDL_aligned_free(),
|
|
|
1592 * _not_ SDL_free().
|
|
|
1593 *
|
|
|
1594 * If `alignment` is less than the size of `void *`, it will be increased to
|
|
|
1595 * match that.
|
|
|
1596 *
|
|
|
1597 * The returned memory address will be a multiple of the alignment value, and
|
|
|
1598 * the size of the memory allocated will be a multiple of the alignment value.
|
|
|
1599 *
|
|
|
1600 * \param alignment the alignment of the memory.
|
|
|
1601 * \param size the size to allocate.
|
|
|
1602 * \returns a pointer to the aligned memory, or NULL if allocation failed.
|
|
|
1603 *
|
|
|
1604 * \threadsafety It is safe to call this function from any thread.
|
|
|
1605 *
|
|
|
1606 * \since This function is available since SDL 3.2.0.
|
|
|
1607 *
|
|
|
1608 * \sa SDL_aligned_free
|
|
|
1609 */
|
|
|
1610 extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_aligned_alloc(size_t alignment, size_t size);
|
|
|
1611
|
|
|
1612 /**
|
|
|
1613 * Free memory allocated by SDL_aligned_alloc().
|
|
|
1614 *
|
|
|
1615 * The pointer is no longer valid after this call and cannot be dereferenced
|
|
|
1616 * anymore.
|
|
|
1617 *
|
|
|
1618 * If `mem` is NULL, this function does nothing.
|
|
|
1619 *
|
|
|
1620 * \param mem a pointer previously returned by SDL_aligned_alloc(), or NULL.
|
|
|
1621 *
|
|
|
1622 * \threadsafety It is safe to call this function from any thread.
|
|
|
1623 *
|
|
|
1624 * \since This function is available since SDL 3.2.0.
|
|
|
1625 *
|
|
|
1626 * \sa SDL_aligned_alloc
|
|
|
1627 */
|
|
|
1628 extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem);
|
|
|
1629
|
|
|
1630 /**
|
|
|
1631 * Get the number of outstanding (unfreed) allocations.
|
|
|
1632 *
|
|
|
1633 * \returns the number of allocations or -1 if allocation counting is
|
|
|
1634 * disabled.
|
|
|
1635 *
|
|
|
1636 * \threadsafety It is safe to call this function from any thread.
|
|
|
1637 *
|
|
|
1638 * \since This function is available since SDL 3.2.0.
|
|
|
1639 */
|
|
|
1640 extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void);
|
|
|
1641
|
|
|
1642 /**
|
|
|
1643 * A thread-safe set of environment variables
|
|
|
1644 *
|
|
|
1645 * \since This struct is available since SDL 3.2.0.
|
|
|
1646 *
|
|
|
1647 * \sa SDL_GetEnvironment
|
|
|
1648 * \sa SDL_CreateEnvironment
|
|
|
1649 * \sa SDL_GetEnvironmentVariable
|
|
|
1650 * \sa SDL_GetEnvironmentVariables
|
|
|
1651 * \sa SDL_SetEnvironmentVariable
|
|
|
1652 * \sa SDL_UnsetEnvironmentVariable
|
|
|
1653 * \sa SDL_DestroyEnvironment
|
|
|
1654 */
|
|
|
1655 typedef struct SDL_Environment SDL_Environment;
|
|
|
1656
|
|
|
1657 /**
|
|
|
1658 * Get the process environment.
|
|
|
1659 *
|
|
|
1660 * This is initialized at application start and is not affected by setenv()
|
|
|
1661 * and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and
|
|
|
1662 * SDL_UnsetEnvironmentVariable() if you want to modify this environment, or
|
|
|
1663 * SDL_setenv_unsafe() or SDL_unsetenv_unsafe() if you want changes to persist
|
|
|
1664 * in the C runtime environment after SDL_Quit().
|
|
|
1665 *
|
|
|
1666 * \returns a pointer to the environment for the process or NULL on failure;
|
|
|
1667 * call SDL_GetError() for more information.
|
|
|
1668 *
|
|
|
1669 * \threadsafety It is safe to call this function from any thread.
|
|
|
1670 *
|
|
|
1671 * \since This function is available since SDL 3.2.0.
|
|
|
1672 *
|
|
|
1673 * \sa SDL_GetEnvironmentVariable
|
|
|
1674 * \sa SDL_GetEnvironmentVariables
|
|
|
1675 * \sa SDL_SetEnvironmentVariable
|
|
|
1676 * \sa SDL_UnsetEnvironmentVariable
|
|
|
1677 */
|
|
|
1678 extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_GetEnvironment(void);
|
|
|
1679
|
|
|
1680 /**
|
|
|
1681 * Create a set of environment variables
|
|
|
1682 *
|
|
|
1683 * \param populated true to initialize it from the C runtime environment,
|
|
|
1684 * false to create an empty environment.
|
|
|
1685 * \returns a pointer to the new environment or NULL on failure; call
|
|
|
1686 * SDL_GetError() for more information.
|
|
|
1687 *
|
|
|
1688 * \threadsafety If `populated` is false, it is safe to call this function
|
|
|
1689 * from any thread, otherwise it is safe if no other threads are
|
|
|
1690 * calling setenv() or unsetenv()
|
|
|
1691 *
|
|
|
1692 * \since This function is available since SDL 3.2.0.
|
|
|
1693 *
|
|
|
1694 * \sa SDL_GetEnvironmentVariable
|
|
|
1695 * \sa SDL_GetEnvironmentVariables
|
|
|
1696 * \sa SDL_SetEnvironmentVariable
|
|
|
1697 * \sa SDL_UnsetEnvironmentVariable
|
|
|
1698 * \sa SDL_DestroyEnvironment
|
|
|
1699 */
|
|
|
1700 extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_CreateEnvironment(bool populated);
|
|
|
1701
|
|
|
1702 /**
|
|
|
1703 * Get the value of a variable in the environment.
|
|
|
1704 *
|
|
|
1705 * \param env the environment to query.
|
|
|
1706 * \param name the name of the variable to get.
|
|
|
1707 * \returns a pointer to the value of the variable or NULL if it can't be
|
|
|
1708 * found.
|
|
|
1709 *
|
|
|
1710 * \threadsafety It is safe to call this function from any thread.
|
|
|
1711 *
|
|
|
1712 * \since This function is available since SDL 3.2.0.
|
|
|
1713 *
|
|
|
1714 * \sa SDL_GetEnvironment
|
|
|
1715 * \sa SDL_CreateEnvironment
|
|
|
1716 * \sa SDL_GetEnvironmentVariables
|
|
|
1717 * \sa SDL_SetEnvironmentVariable
|
|
|
1718 * \sa SDL_UnsetEnvironmentVariable
|
|
|
1719 */
|
|
|
1720 extern SDL_DECLSPEC const char * SDLCALL SDL_GetEnvironmentVariable(SDL_Environment *env, const char *name);
|
|
|
1721
|
|
|
1722 /**
|
|
|
1723 * Get all variables in the environment.
|
|
|
1724 *
|
|
|
1725 * \param env the environment to query.
|
|
|
1726 * \returns a NULL terminated array of pointers to environment variables in
|
|
|
1727 * the form "variable=value" or NULL on failure; call SDL_GetError()
|
|
|
1728 * for more information. This is a single allocation that should be
|
|
|
1729 * freed with SDL_free() when it is no longer needed.
|
|
|
1730 *
|
|
|
1731 * \threadsafety It is safe to call this function from any thread.
|
|
|
1732 *
|
|
|
1733 * \since This function is available since SDL 3.2.0.
|
|
|
1734 *
|
|
|
1735 * \sa SDL_GetEnvironment
|
|
|
1736 * \sa SDL_CreateEnvironment
|
|
|
1737 * \sa SDL_GetEnvironmentVariables
|
|
|
1738 * \sa SDL_SetEnvironmentVariable
|
|
|
1739 * \sa SDL_UnsetEnvironmentVariable
|
|
|
1740 */
|
|
|
1741 extern SDL_DECLSPEC char ** SDLCALL SDL_GetEnvironmentVariables(SDL_Environment *env);
|
|
|
1742
|
|
|
1743 /**
|
|
|
1744 * Set the value of a variable in the environment.
|
|
|
1745 *
|
|
|
1746 * \param env the environment to modify.
|
|
|
1747 * \param name the name of the variable to set.
|
|
|
1748 * \param value the value of the variable to set.
|
|
|
1749 * \param overwrite true to overwrite the variable if it exists, false to
|
|
|
1750 * return success without setting the variable if it already
|
|
|
1751 * exists.
|
|
|
1752 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1753 * information.
|
|
|
1754 *
|
|
|
1755 * \threadsafety It is safe to call this function from any thread.
|
|
|
1756 *
|
|
|
1757 * \since This function is available since SDL 3.2.0.
|
|
|
1758 *
|
|
|
1759 * \sa SDL_GetEnvironment
|
|
|
1760 * \sa SDL_CreateEnvironment
|
|
|
1761 * \sa SDL_GetEnvironmentVariable
|
|
|
1762 * \sa SDL_GetEnvironmentVariables
|
|
|
1763 * \sa SDL_UnsetEnvironmentVariable
|
|
|
1764 */
|
|
|
1765 extern SDL_DECLSPEC bool SDLCALL SDL_SetEnvironmentVariable(SDL_Environment *env, const char *name, const char *value, bool overwrite);
|
|
|
1766
|
|
|
1767 /**
|
|
|
1768 * Clear a variable from the environment.
|
|
|
1769 *
|
|
|
1770 * \param env the environment to modify.
|
|
|
1771 * \param name the name of the variable to unset.
|
|
|
1772 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1773 * information.
|
|
|
1774 *
|
|
|
1775 * \threadsafety It is safe to call this function from any thread.
|
|
|
1776 *
|
|
|
1777 * \since This function is available since SDL 3.2.0.
|
|
|
1778 *
|
|
|
1779 * \sa SDL_GetEnvironment
|
|
|
1780 * \sa SDL_CreateEnvironment
|
|
|
1781 * \sa SDL_GetEnvironmentVariable
|
|
|
1782 * \sa SDL_GetEnvironmentVariables
|
|
|
1783 * \sa SDL_SetEnvironmentVariable
|
|
|
1784 * \sa SDL_UnsetEnvironmentVariable
|
|
|
1785 */
|
|
|
1786 extern SDL_DECLSPEC bool SDLCALL SDL_UnsetEnvironmentVariable(SDL_Environment *env, const char *name);
|
|
|
1787
|
|
|
1788 /**
|
|
|
1789 * Destroy a set of environment variables.
|
|
|
1790 *
|
|
|
1791 * \param env the environment to destroy.
|
|
|
1792 *
|
|
|
1793 * \threadsafety It is safe to call this function from any thread, as long as
|
|
|
1794 * the environment is no longer in use.
|
|
|
1795 *
|
|
|
1796 * \since This function is available since SDL 3.2.0.
|
|
|
1797 *
|
|
|
1798 * \sa SDL_CreateEnvironment
|
|
|
1799 */
|
|
|
1800 extern SDL_DECLSPEC void SDLCALL SDL_DestroyEnvironment(SDL_Environment *env);
|
|
|
1801
|
|
|
1802 /**
|
|
|
1803 * Get the value of a variable in the environment.
|
|
|
1804 *
|
|
|
1805 * This function uses SDL's cached copy of the environment and is thread-safe.
|
|
|
1806 *
|
|
|
1807 * \param name the name of the variable to get.
|
|
|
1808 * \returns a pointer to the value of the variable or NULL if it can't be
|
|
|
1809 * found.
|
|
|
1810 *
|
|
|
1811 * \threadsafety It is safe to call this function from any thread.
|
|
|
1812 *
|
|
|
1813 * \since This function is available since SDL 3.2.0.
|
|
|
1814 */
|
|
|
1815 extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name);
|
|
|
1816
|
|
|
1817 /**
|
|
|
1818 * Get the value of a variable in the environment.
|
|
|
1819 *
|
|
|
1820 * This function bypasses SDL's cached copy of the environment and is not
|
|
|
1821 * thread-safe.
|
|
|
1822 *
|
|
|
1823 * \param name the name of the variable to get.
|
|
|
1824 * \returns a pointer to the value of the variable or NULL if it can't be
|
|
|
1825 * found.
|
|
|
1826 *
|
|
|
1827 * \threadsafety This function is not thread safe, consider using SDL_getenv()
|
|
|
1828 * instead.
|
|
|
1829 *
|
|
|
1830 * \since This function is available since SDL 3.2.0.
|
|
|
1831 *
|
|
|
1832 * \sa SDL_getenv
|
|
|
1833 */
|
|
|
1834 extern SDL_DECLSPEC const char * SDLCALL SDL_getenv_unsafe(const char *name);
|
|
|
1835
|
|
|
1836 /**
|
|
|
1837 * Set the value of a variable in the environment.
|
|
|
1838 *
|
|
|
1839 * \param name the name of the variable to set.
|
|
|
1840 * \param value the value of the variable to set.
|
|
|
1841 * \param overwrite 1 to overwrite the variable if it exists, 0 to return
|
|
|
1842 * success without setting the variable if it already exists.
|
|
|
1843 * \returns 0 on success, -1 on error.
|
|
|
1844 *
|
|
|
1845 * \threadsafety This function is not thread safe, consider using
|
|
|
1846 * SDL_SetEnvironmentVariable() instead.
|
|
|
1847 *
|
|
|
1848 * \since This function is available since SDL 3.2.0.
|
|
|
1849 *
|
|
|
1850 * \sa SDL_SetEnvironmentVariable
|
|
|
1851 */
|
|
|
1852 extern SDL_DECLSPEC int SDLCALL SDL_setenv_unsafe(const char *name, const char *value, int overwrite);
|
|
|
1853
|
|
|
1854 /**
|
|
|
1855 * Clear a variable from the environment.
|
|
|
1856 *
|
|
|
1857 * \param name the name of the variable to unset.
|
|
|
1858 * \returns 0 on success, -1 on error.
|
|
|
1859 *
|
|
|
1860 * \threadsafety This function is not thread safe, consider using
|
|
|
1861 * SDL_UnsetEnvironmentVariable() instead.
|
|
|
1862 *
|
|
|
1863 * \since This function is available since SDL 3.2.0.
|
|
|
1864 *
|
|
|
1865 * \sa SDL_UnsetEnvironmentVariable
|
|
|
1866 */
|
|
|
1867 extern SDL_DECLSPEC int SDLCALL SDL_unsetenv_unsafe(const char *name);
|
|
|
1868
|
|
|
1869 /**
|
|
|
1870 * A callback used with SDL sorting and binary search functions.
|
|
|
1871 *
|
|
|
1872 * \param a a pointer to the first element being compared.
|
|
|
1873 * \param b a pointer to the second element being compared.
|
|
|
1874 * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted
|
|
|
1875 * before `a`, 0 if they are equal. If two elements are equal, their
|
|
|
1876 * order in the sorted array is undefined.
|
|
|
1877 *
|
|
|
1878 * \since This callback is available since SDL 3.2.0.
|
|
|
1879 *
|
|
|
1880 * \sa SDL_bsearch
|
|
|
1881 * \sa SDL_qsort
|
|
|
1882 */
|
|
|
1883 typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b);
|
|
|
1884
|
|
|
1885 /**
|
|
|
1886 * Sort an array.
|
|
|
1887 *
|
|
|
1888 * For example:
|
|
|
1889 *
|
|
|
1890 * ```c
|
|
|
1891 * typedef struct {
|
|
|
1892 * int key;
|
|
|
1893 * const char *string;
|
|
|
1894 * } data;
|
|
|
1895 *
|
|
|
1896 * int SDLCALL compare(const void *a, const void *b)
|
|
|
1897 * {
|
|
|
1898 * const data *A = (const data *)a;
|
|
|
1899 * const data *B = (const data *)b;
|
|
|
1900 *
|
|
|
1901 * if (A->n < B->n) {
|
|
|
1902 * return -1;
|
|
|
1903 * } else if (B->n < A->n) {
|
|
|
1904 * return 1;
|
|
|
1905 * } else {
|
|
|
1906 * return 0;
|
|
|
1907 * }
|
|
|
1908 * }
|
|
|
1909 *
|
|
|
1910 * data values[] = {
|
|
|
1911 * { 3, "third" }, { 1, "first" }, { 2, "second" }
|
|
|
1912 * };
|
|
|
1913 *
|
|
|
1914 * SDL_qsort(values, SDL_arraysize(values), sizeof(values[0]), compare);
|
|
|
1915 * ```
|
|
|
1916 *
|
|
|
1917 * \param base a pointer to the start of the array.
|
|
|
1918 * \param nmemb the number of elements in the array.
|
|
|
1919 * \param size the size of the elements in the array.
|
|
|
1920 * \param compare a function used to compare elements in the array.
|
|
|
1921 *
|
|
|
1922 * \threadsafety It is safe to call this function from any thread.
|
|
|
1923 *
|
|
|
1924 * \since This function is available since SDL 3.2.0.
|
|
|
1925 *
|
|
|
1926 * \sa SDL_bsearch
|
|
|
1927 * \sa SDL_qsort_r
|
|
|
1928 */
|
|
|
1929 extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare);
|
|
|
1930
|
|
|
1931 /**
|
|
|
1932 * Perform a binary search on a previously sorted array.
|
|
|
1933 *
|
|
|
1934 * For example:
|
|
|
1935 *
|
|
|
1936 * ```c
|
|
|
1937 * typedef struct {
|
|
|
1938 * int key;
|
|
|
1939 * const char *string;
|
|
|
1940 * } data;
|
|
|
1941 *
|
|
|
1942 * int SDLCALL compare(const void *a, const void *b)
|
|
|
1943 * {
|
|
|
1944 * const data *A = (const data *)a;
|
|
|
1945 * const data *B = (const data *)b;
|
|
|
1946 *
|
|
|
1947 * if (A->n < B->n) {
|
|
|
1948 * return -1;
|
|
|
1949 * } else if (B->n < A->n) {
|
|
|
1950 * return 1;
|
|
|
1951 * } else {
|
|
|
1952 * return 0;
|
|
|
1953 * }
|
|
|
1954 * }
|
|
|
1955 *
|
|
|
1956 * data values[] = {
|
|
|
1957 * { 1, "first" }, { 2, "second" }, { 3, "third" }
|
|
|
1958 * };
|
|
|
1959 * data key = { 2, NULL };
|
|
|
1960 *
|
|
|
1961 * data *result = SDL_bsearch(&key, values, SDL_arraysize(values), sizeof(values[0]), compare);
|
|
|
1962 * ```
|
|
|
1963 *
|
|
|
1964 * \param key a pointer to a key equal to the element being searched for.
|
|
|
1965 * \param base a pointer to the start of the array.
|
|
|
1966 * \param nmemb the number of elements in the array.
|
|
|
1967 * \param size the size of the elements in the array.
|
|
|
1968 * \param compare a function used to compare elements in the array.
|
|
|
1969 * \returns a pointer to the matching element in the array, or NULL if not
|
|
|
1970 * found.
|
|
|
1971 *
|
|
|
1972 * \threadsafety It is safe to call this function from any thread.
|
|
|
1973 *
|
|
|
1974 * \since This function is available since SDL 3.2.0.
|
|
|
1975 *
|
|
|
1976 * \sa SDL_bsearch_r
|
|
|
1977 * \sa SDL_qsort
|
|
|
1978 */
|
|
|
1979 extern SDL_DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare);
|
|
|
1980
|
|
|
1981 /**
|
|
|
1982 * A callback used with SDL sorting and binary search functions.
|
|
|
1983 *
|
|
|
1984 * \param userdata the `userdata` pointer passed to the sort function.
|
|
|
1985 * \param a a pointer to the first element being compared.
|
|
|
1986 * \param b a pointer to the second element being compared.
|
|
|
1987 * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted
|
|
|
1988 * before `a`, 0 if they are equal. If two elements are equal, their
|
|
|
1989 * order in the sorted array is undefined.
|
|
|
1990 *
|
|
|
1991 * \since This callback is available since SDL 3.2.0.
|
|
|
1992 *
|
|
|
1993 * \sa SDL_qsort_r
|
|
|
1994 * \sa SDL_bsearch_r
|
|
|
1995 */
|
|
|
1996 typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, const void *b);
|
|
|
1997
|
|
|
1998 /**
|
|
|
1999 * Sort an array, passing a userdata pointer to the compare function.
|
|
|
2000 *
|
|
|
2001 * For example:
|
|
|
2002 *
|
|
|
2003 * ```c
|
|
|
2004 * typedef enum {
|
|
|
2005 * sort_increasing,
|
|
|
2006 * sort_decreasing,
|
|
|
2007 * } sort_method;
|
|
|
2008 *
|
|
|
2009 * typedef struct {
|
|
|
2010 * int key;
|
|
|
2011 * const char *string;
|
|
|
2012 * } data;
|
|
|
2013 *
|
|
|
2014 * int SDLCALL compare(const void *userdata, const void *a, const void *b)
|
|
|
2015 * {
|
|
|
2016 * sort_method method = (sort_method)(uintptr_t)userdata;
|
|
|
2017 * const data *A = (const data *)a;
|
|
|
2018 * const data *B = (const data *)b;
|
|
|
2019 *
|
|
|
2020 * if (A->key < B->key) {
|
|
|
2021 * return (method == sort_increasing) ? -1 : 1;
|
|
|
2022 * } else if (B->key < A->key) {
|
|
|
2023 * return (method == sort_increasing) ? 1 : -1;
|
|
|
2024 * } else {
|
|
|
2025 * return 0;
|
|
|
2026 * }
|
|
|
2027 * }
|
|
|
2028 *
|
|
|
2029 * data values[] = {
|
|
|
2030 * { 3, "third" }, { 1, "first" }, { 2, "second" }
|
|
|
2031 * };
|
|
|
2032 *
|
|
|
2033 * SDL_qsort_r(values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing);
|
|
|
2034 * ```
|
|
|
2035 *
|
|
|
2036 * \param base a pointer to the start of the array.
|
|
|
2037 * \param nmemb the number of elements in the array.
|
|
|
2038 * \param size the size of the elements in the array.
|
|
|
2039 * \param compare a function used to compare elements in the array.
|
|
|
2040 * \param userdata a pointer to pass to the compare function.
|
|
|
2041 *
|
|
|
2042 * \threadsafety It is safe to call this function from any thread.
|
|
|
2043 *
|
|
|
2044 * \since This function is available since SDL 3.2.0.
|
|
|
2045 *
|
|
|
2046 * \sa SDL_bsearch_r
|
|
|
2047 * \sa SDL_qsort
|
|
|
2048 */
|
|
|
2049 extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata);
|
|
|
2050
|
|
|
2051 /**
|
|
|
2052 * Perform a binary search on a previously sorted array, passing a userdata
|
|
|
2053 * pointer to the compare function.
|
|
|
2054 *
|
|
|
2055 * For example:
|
|
|
2056 *
|
|
|
2057 * ```c
|
|
|
2058 * typedef enum {
|
|
|
2059 * sort_increasing,
|
|
|
2060 * sort_decreasing,
|
|
|
2061 * } sort_method;
|
|
|
2062 *
|
|
|
2063 * typedef struct {
|
|
|
2064 * int key;
|
|
|
2065 * const char *string;
|
|
|
2066 * } data;
|
|
|
2067 *
|
|
|
2068 * int SDLCALL compare(const void *userdata, const void *a, const void *b)
|
|
|
2069 * {
|
|
|
2070 * sort_method method = (sort_method)(uintptr_t)userdata;
|
|
|
2071 * const data *A = (const data *)a;
|
|
|
2072 * const data *B = (const data *)b;
|
|
|
2073 *
|
|
|
2074 * if (A->key < B->key) {
|
|
|
2075 * return (method == sort_increasing) ? -1 : 1;
|
|
|
2076 * } else if (B->key < A->key) {
|
|
|
2077 * return (method == sort_increasing) ? 1 : -1;
|
|
|
2078 * } else {
|
|
|
2079 * return 0;
|
|
|
2080 * }
|
|
|
2081 * }
|
|
|
2082 *
|
|
|
2083 * data values[] = {
|
|
|
2084 * { 1, "first" }, { 2, "second" }, { 3, "third" }
|
|
|
2085 * };
|
|
|
2086 * data key = { 2, NULL };
|
|
|
2087 *
|
|
|
2088 * data *result = SDL_bsearch_r(&key, values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing);
|
|
|
2089 * ```
|
|
|
2090 *
|
|
|
2091 * \param key a pointer to a key equal to the element being searched for.
|
|
|
2092 * \param base a pointer to the start of the array.
|
|
|
2093 * \param nmemb the number of elements in the array.
|
|
|
2094 * \param size the size of the elements in the array.
|
|
|
2095 * \param compare a function used to compare elements in the array.
|
|
|
2096 * \param userdata a pointer to pass to the compare function.
|
|
|
2097 * \returns a pointer to the matching element in the array, or NULL if not
|
|
|
2098 * found.
|
|
|
2099 *
|
|
|
2100 * \threadsafety It is safe to call this function from any thread.
|
|
|
2101 *
|
|
|
2102 * \since This function is available since SDL 3.2.0.
|
|
|
2103 *
|
|
|
2104 * \sa SDL_bsearch
|
|
|
2105 * \sa SDL_qsort_r
|
|
|
2106 */
|
|
|
2107 extern 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);
|
|
|
2108
|
|
|
2109 /**
|
|
|
2110 * Compute the absolute value of `x`.
|
|
|
2111 *
|
|
|
2112 * \param x an integer value.
|
|
|
2113 * \returns the absolute value of x.
|
|
|
2114 *
|
|
|
2115 * \threadsafety It is safe to call this function from any thread.
|
|
|
2116 *
|
|
|
2117 * \since This function is available since SDL 3.2.0.
|
|
|
2118 */
|
|
|
2119 extern SDL_DECLSPEC int SDLCALL SDL_abs(int x);
|
|
|
2120
|
|
|
2121 /**
|
|
|
2122 * Return the lesser of two values.
|
|
|
2123 *
|
|
|
2124 * This is a helper macro that might be more clear than writing out the
|
|
|
2125 * comparisons directly, and works with any type that can be compared with the
|
|
|
2126 * `<` operator. However, it double-evaluates both its parameters, so do not
|
|
|
2127 * use expressions with side-effects here.
|
|
|
2128 *
|
|
|
2129 * \param x the first value to compare.
|
|
|
2130 * \param y the second value to compare.
|
|
|
2131 * \returns the lesser of `x` and `y`.
|
|
|
2132 *
|
|
|
2133 * \threadsafety It is safe to call this macro from any thread.
|
|
|
2134 *
|
|
|
2135 * \since This macro is available since SDL 3.2.0.
|
|
|
2136 */
|
|
|
2137 #define SDL_min(x, y) (((x) < (y)) ? (x) : (y))
|
|
|
2138
|
|
|
2139 /**
|
|
|
2140 * Return the greater of two values.
|
|
|
2141 *
|
|
|
2142 * This is a helper macro that might be more clear than writing out the
|
|
|
2143 * comparisons directly, and works with any type that can be compared with the
|
|
|
2144 * `>` operator. However, it double-evaluates both its parameters, so do not
|
|
|
2145 * use expressions with side-effects here.
|
|
|
2146 *
|
|
|
2147 * \param x the first value to compare.
|
|
|
2148 * \param y the second value to compare.
|
|
|
2149 * \returns the greater of `x` and `y`.
|
|
|
2150 *
|
|
|
2151 * \threadsafety It is safe to call this macro from any thread.
|
|
|
2152 *
|
|
|
2153 * \since This macro is available since SDL 3.2.0.
|
|
|
2154 */
|
|
|
2155 #define SDL_max(x, y) (((x) > (y)) ? (x) : (y))
|
|
|
2156
|
|
|
2157 /**
|
|
|
2158 * Return a value clamped to a range.
|
|
|
2159 *
|
|
|
2160 * If `x` is outside the range a values between `a` and `b`, the returned
|
|
|
2161 * value will be `a` or `b` as appropriate. Otherwise, `x` is returned.
|
|
|
2162 *
|
|
|
2163 * This macro will produce incorrect results if `b` is less than `a`.
|
|
|
2164 *
|
|
|
2165 * This is a helper macro that might be more clear than writing out the
|
|
|
2166 * comparisons directly, and works with any type that can be compared with the
|
|
|
2167 * `<` and `>` operators. However, it double-evaluates all its parameters, so
|
|
|
2168 * do not use expressions with side-effects here.
|
|
|
2169 *
|
|
|
2170 * \param x the value to compare.
|
|
|
2171 * \param a the low end value.
|
|
|
2172 * \param b the high end value.
|
|
|
2173 * \returns x, clamped between a and b.
|
|
|
2174 *
|
|
|
2175 * \threadsafety It is safe to call this macro from any thread.
|
|
|
2176 *
|
|
|
2177 * \since This macro is available since SDL 3.2.0.
|
|
|
2178 */
|
|
|
2179 #define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x)))
|
|
|
2180
|
|
|
2181 /**
|
|
|
2182 * Query if a character is alphabetic (a letter).
|
|
|
2183 *
|
|
|
2184 * **WARNING**: Regardless of system locale, this will only treat ASCII values
|
|
|
2185 * for English 'a-z' and 'A-Z' as true.
|
|
|
2186 *
|
|
|
2187 * \param x character value to check.
|
|
|
2188 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2189 *
|
|
|
2190 * \threadsafety It is safe to call this function from any thread.
|
|
|
2191 *
|
|
|
2192 * \since This function is available since SDL 3.2.0.
|
|
|
2193 */
|
|
|
2194 extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x);
|
|
|
2195
|
|
|
2196 /**
|
|
|
2197 * Query if a character is alphabetic (a letter) or a number.
|
|
|
2198 *
|
|
|
2199 * **WARNING**: Regardless of system locale, this will only treat ASCII values
|
|
|
2200 * for English 'a-z', 'A-Z', and '0-9' as true.
|
|
|
2201 *
|
|
|
2202 * \param x character value to check.
|
|
|
2203 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2204 *
|
|
|
2205 * \threadsafety It is safe to call this function from any thread.
|
|
|
2206 *
|
|
|
2207 * \since This function is available since SDL 3.2.0.
|
|
|
2208 */
|
|
|
2209 extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x);
|
|
|
2210
|
|
|
2211 /**
|
|
|
2212 * Report if a character is blank (a space or tab).
|
|
|
2213 *
|
|
|
2214 * **WARNING**: Regardless of system locale, this will only treat ASCII values
|
|
|
2215 * 0x20 (space) or 0x9 (tab) as true.
|
|
|
2216 *
|
|
|
2217 * \param x character value to check.
|
|
|
2218 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2219 *
|
|
|
2220 * \threadsafety It is safe to call this function from any thread.
|
|
|
2221 *
|
|
|
2222 * \since This function is available since SDL 3.2.0.
|
|
|
2223 */
|
|
|
2224 extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x);
|
|
|
2225
|
|
|
2226 /**
|
|
|
2227 * Report if a character is a control character.
|
|
|
2228 *
|
|
|
2229 * **WARNING**: Regardless of system locale, this will only treat ASCII values
|
|
|
2230 * 0 through 0x1F, and 0x7F, as true.
|
|
|
2231 *
|
|
|
2232 * \param x character value to check.
|
|
|
2233 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2234 *
|
|
|
2235 * \threadsafety It is safe to call this function from any thread.
|
|
|
2236 *
|
|
|
2237 * \since This function is available since SDL 3.2.0.
|
|
|
2238 */
|
|
|
2239 extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x);
|
|
|
2240
|
|
|
2241 /**
|
|
|
2242 * Report if a character is a numeric digit.
|
|
|
2243 *
|
|
|
2244 * **WARNING**: Regardless of system locale, this will only treat ASCII values
|
|
|
2245 * '0' (0x30) through '9' (0x39), as true.
|
|
|
2246 *
|
|
|
2247 * \param x character value to check.
|
|
|
2248 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2249 *
|
|
|
2250 * \threadsafety It is safe to call this function from any thread.
|
|
|
2251 *
|
|
|
2252 * \since This function is available since SDL 3.2.0.
|
|
|
2253 */
|
|
|
2254 extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x);
|
|
|
2255
|
|
|
2256 /**
|
|
|
2257 * Report if a character is a hexadecimal digit.
|
|
|
2258 *
|
|
|
2259 * **WARNING**: Regardless of system locale, this will only treat ASCII values
|
|
|
2260 * 'A' through 'F', 'a' through 'f', and '0' through '9', as true.
|
|
|
2261 *
|
|
|
2262 * \param x character value to check.
|
|
|
2263 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2264 *
|
|
|
2265 * \threadsafety It is safe to call this function from any thread.
|
|
|
2266 *
|
|
|
2267 * \since This function is available since SDL 3.2.0.
|
|
|
2268 */
|
|
|
2269 extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x);
|
|
|
2270
|
|
|
2271 /**
|
|
|
2272 * Report if a character is a punctuation mark.
|
|
|
2273 *
|
|
|
2274 * **WARNING**: Regardless of system locale, this is equivalent to
|
|
|
2275 * `((SDL_isgraph(x)) && (!SDL_isalnum(x)))`.
|
|
|
2276 *
|
|
|
2277 * \param x character value to check.
|
|
|
2278 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2279 *
|
|
|
2280 * \threadsafety It is safe to call this function from any thread.
|
|
|
2281 *
|
|
|
2282 * \since This function is available since SDL 3.2.0.
|
|
|
2283 *
|
|
|
2284 * \sa SDL_isgraph
|
|
|
2285 * \sa SDL_isalnum
|
|
|
2286 */
|
|
|
2287 extern SDL_DECLSPEC int SDLCALL SDL_ispunct(int x);
|
|
|
2288
|
|
|
2289 /**
|
|
|
2290 * Report if a character is whitespace.
|
|
|
2291 *
|
|
|
2292 * **WARNING**: Regardless of system locale, this will only treat the
|
|
|
2293 * following ASCII values as true:
|
|
|
2294 *
|
|
|
2295 * - space (0x20)
|
|
|
2296 * - tab (0x09)
|
|
|
2297 * - newline (0x0A)
|
|
|
2298 * - vertical tab (0x0B)
|
|
|
2299 * - form feed (0x0C)
|
|
|
2300 * - return (0x0D)
|
|
|
2301 *
|
|
|
2302 * \param x character value to check.
|
|
|
2303 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2304 *
|
|
|
2305 * \threadsafety It is safe to call this function from any thread.
|
|
|
2306 *
|
|
|
2307 * \since This function is available since SDL 3.2.0.
|
|
|
2308 */
|
|
|
2309 extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x);
|
|
|
2310
|
|
|
2311 /**
|
|
|
2312 * Report if a character is upper case.
|
|
|
2313 *
|
|
|
2314 * **WARNING**: Regardless of system locale, this will only treat ASCII values
|
|
|
2315 * 'A' through 'Z' as true.
|
|
|
2316 *
|
|
|
2317 * \param x character value to check.
|
|
|
2318 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2319 *
|
|
|
2320 * \threadsafety It is safe to call this function from any thread.
|
|
|
2321 *
|
|
|
2322 * \since This function is available since SDL 3.2.0.
|
|
|
2323 */
|
|
|
2324 extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x);
|
|
|
2325
|
|
|
2326 /**
|
|
|
2327 * Report if a character is lower case.
|
|
|
2328 *
|
|
|
2329 * **WARNING**: Regardless of system locale, this will only treat ASCII values
|
|
|
2330 * 'a' through 'z' as true.
|
|
|
2331 *
|
|
|
2332 * \param x character value to check.
|
|
|
2333 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2334 *
|
|
|
2335 * \threadsafety It is safe to call this function from any thread.
|
|
|
2336 *
|
|
|
2337 * \since This function is available since SDL 3.2.0.
|
|
|
2338 */
|
|
|
2339 extern SDL_DECLSPEC int SDLCALL SDL_islower(int x);
|
|
|
2340
|
|
|
2341 /**
|
|
|
2342 * Report if a character is "printable".
|
|
|
2343 *
|
|
|
2344 * Be advised that "printable" has a definition that goes back to text
|
|
|
2345 * terminals from the dawn of computing, making this a sort of special case
|
|
|
2346 * function that is not suitable for Unicode (or most any) text management.
|
|
|
2347 *
|
|
|
2348 * **WARNING**: Regardless of system locale, this will only treat ASCII values
|
|
|
2349 * ' ' (0x20) through '~' (0x7E) as true.
|
|
|
2350 *
|
|
|
2351 * \param x character value to check.
|
|
|
2352 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2353 *
|
|
|
2354 * \threadsafety It is safe to call this function from any thread.
|
|
|
2355 *
|
|
|
2356 * \since This function is available since SDL 3.2.0.
|
|
|
2357 */
|
|
|
2358 extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x);
|
|
|
2359
|
|
|
2360 /**
|
|
|
2361 * Report if a character is any "printable" except space.
|
|
|
2362 *
|
|
|
2363 * Be advised that "printable" has a definition that goes back to text
|
|
|
2364 * terminals from the dawn of computing, making this a sort of special case
|
|
|
2365 * function that is not suitable for Unicode (or most any) text management.
|
|
|
2366 *
|
|
|
2367 * **WARNING**: Regardless of system locale, this is equivalent to
|
|
|
2368 * `(SDL_isprint(x)) && ((x) != ' ')`.
|
|
|
2369 *
|
|
|
2370 * \param x character value to check.
|
|
|
2371 * \returns non-zero if x falls within the character class, zero otherwise.
|
|
|
2372 *
|
|
|
2373 * \threadsafety It is safe to call this function from any thread.
|
|
|
2374 *
|
|
|
2375 * \since This function is available since SDL 3.2.0.
|
|
|
2376 *
|
|
|
2377 * \sa SDL_isprint
|
|
|
2378 */
|
|
|
2379 extern SDL_DECLSPEC int SDLCALL SDL_isgraph(int x);
|
|
|
2380
|
|
|
2381 /**
|
|
|
2382 * Convert low-ASCII English letters to uppercase.
|
|
|
2383 *
|
|
|
2384 * **WARNING**: Regardless of system locale, this will only convert ASCII
|
|
|
2385 * values 'a' through 'z' to uppercase.
|
|
|
2386 *
|
|
|
2387 * This function returns the uppercase equivalent of `x`. If a character
|
|
|
2388 * cannot be converted, or is already uppercase, this function returns `x`.
|
|
|
2389 *
|
|
|
2390 * \param x character value to check.
|
|
|
2391 * \returns capitalized version of x, or x if no conversion available.
|
|
|
2392 *
|
|
|
2393 * \threadsafety It is safe to call this function from any thread.
|
|
|
2394 *
|
|
|
2395 * \since This function is available since SDL 3.2.0.
|
|
|
2396 */
|
|
|
2397 extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x);
|
|
|
2398
|
|
|
2399 /**
|
|
|
2400 * Convert low-ASCII English letters to lowercase.
|
|
|
2401 *
|
|
|
2402 * **WARNING**: Regardless of system locale, this will only convert ASCII
|
|
|
2403 * values 'A' through 'Z' to lowercase.
|
|
|
2404 *
|
|
|
2405 * This function returns the lowercase equivalent of `x`. If a character
|
|
|
2406 * cannot be converted, or is already lowercase, this function returns `x`.
|
|
|
2407 *
|
|
|
2408 * \param x character value to check.
|
|
|
2409 * \returns lowercase version of x, or x if no conversion available.
|
|
|
2410 *
|
|
|
2411 * \threadsafety It is safe to call this function from any thread.
|
|
|
2412 *
|
|
|
2413 * \since This function is available since SDL 3.2.0.
|
|
|
2414 */
|
|
|
2415 extern SDL_DECLSPEC int SDLCALL SDL_tolower(int x);
|
|
|
2416
|
|
|
2417 /**
|
|
|
2418 * Calculate a CRC-16 value.
|
|
|
2419 *
|
|
|
2420 * https://en.wikipedia.org/wiki/Cyclic_redundancy_check
|
|
|
2421 *
|
|
|
2422 * This function can be called multiple times, to stream data to be
|
|
|
2423 * checksummed in blocks. Each call must provide the previous CRC-16 return
|
|
|
2424 * value to be updated with the next block. The first call to this function
|
|
|
2425 * for a set of blocks should pass in a zero CRC value.
|
|
|
2426 *
|
|
|
2427 * \param crc the current checksum for this data set, or 0 for a new data set.
|
|
|
2428 * \param data a new block of data to add to the checksum.
|
|
|
2429 * \param len the size, in bytes, of the new block of data.
|
|
|
2430 * \returns a CRC-16 checksum value of all blocks in the data set.
|
|
|
2431 *
|
|
|
2432 * \threadsafety It is safe to call this function from any thread.
|
|
|
2433 *
|
|
|
2434 * \since This function is available since SDL 3.2.0.
|
|
|
2435 */
|
|
|
2436 extern SDL_DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len);
|
|
|
2437
|
|
|
2438 /**
|
|
|
2439 * Calculate a CRC-32 value.
|
|
|
2440 *
|
|
|
2441 * https://en.wikipedia.org/wiki/Cyclic_redundancy_check
|
|
|
2442 *
|
|
|
2443 * This function can be called multiple times, to stream data to be
|
|
|
2444 * checksummed in blocks. Each call must provide the previous CRC-32 return
|
|
|
2445 * value to be updated with the next block. The first call to this function
|
|
|
2446 * for a set of blocks should pass in a zero CRC value.
|
|
|
2447 *
|
|
|
2448 * \param crc the current checksum for this data set, or 0 for a new data set.
|
|
|
2449 * \param data a new block of data to add to the checksum.
|
|
|
2450 * \param len the size, in bytes, of the new block of data.
|
|
|
2451 * \returns a CRC-32 checksum value of all blocks in the data set.
|
|
|
2452 *
|
|
|
2453 * \threadsafety It is safe to call this function from any thread.
|
|
|
2454 *
|
|
|
2455 * \since This function is available since SDL 3.2.0.
|
|
|
2456 */
|
|
|
2457 extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len);
|
|
|
2458
|
|
|
2459 /**
|
|
|
2460 * Calculate a 32-bit MurmurHash3 value for a block of data.
|
|
|
2461 *
|
|
|
2462 * https://en.wikipedia.org/wiki/MurmurHash
|
|
|
2463 *
|
|
|
2464 * A seed may be specified, which changes the final results consistently, but
|
|
|
2465 * this does not work like SDL_crc16 and SDL_crc32: you can't feed a previous
|
|
|
2466 * result from this function back into itself as the next seed value to
|
|
|
2467 * calculate a hash in chunks; it won't produce the same hash as it would if
|
|
|
2468 * the same data was provided in a single call.
|
|
|
2469 *
|
|
|
2470 * If you aren't sure what to provide for a seed, zero is fine. Murmur3 is not
|
|
|
2471 * cryptographically secure, so it shouldn't be used for hashing top-secret
|
|
|
2472 * data.
|
|
|
2473 *
|
|
|
2474 * \param data the data to be hashed.
|
|
|
2475 * \param len the size of data, in bytes.
|
|
|
2476 * \param seed a value that alters the final hash value.
|
|
|
2477 * \returns a Murmur3 32-bit hash value.
|
|
|
2478 *
|
|
|
2479 * \threadsafety It is safe to call this function from any thread.
|
|
|
2480 *
|
|
|
2481 * \since This function is available since SDL 3.2.0.
|
|
|
2482 */
|
|
|
2483 extern SDL_DECLSPEC Uint32 SDLCALL SDL_murmur3_32(const void *data, size_t len, Uint32 seed);
|
|
|
2484
|
|
|
2485 /**
|
|
|
2486 * Copy non-overlapping memory.
|
|
|
2487 *
|
|
|
2488 * The memory regions must not overlap. If they do, use SDL_memmove() instead.
|
|
|
2489 *
|
|
|
2490 * \param dst The destination memory region. Must not be NULL, and must not
|
|
|
2491 * overlap with `src`.
|
|
|
2492 * \param src The source memory region. Must not be NULL, and must not overlap
|
|
|
2493 * with `dst`.
|
|
|
2494 * \param len The length in bytes of both `dst` and `src`.
|
|
|
2495 * \returns `dst`.
|
|
|
2496 *
|
|
|
2497 * \threadsafety It is safe to call this function from any thread.
|
|
|
2498 *
|
|
|
2499 * \since This function is available since SDL 3.2.0.
|
|
|
2500 *
|
|
|
2501 * \sa SDL_memmove
|
|
|
2502 */
|
|
|
2503 extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len);
|
|
|
2504
|
|
|
2505 /* Take advantage of compiler optimizations for memcpy */
|
|
|
2506 #ifndef SDL_SLOW_MEMCPY
|
|
|
2507 #ifdef SDL_memcpy
|
|
|
2508 #undef SDL_memcpy
|
|
|
2509 #endif
|
|
|
2510 #define SDL_memcpy memcpy
|
|
|
2511 #endif
|
|
|
2512
|
|
|
2513
|
|
|
2514 /**
|
|
|
2515 * A macro to copy memory between objects, with basic type checking.
|
|
|
2516 *
|
|
|
2517 * SDL_memcpy and SDL_memmove do not care where you copy memory to and from,
|
|
|
2518 * which can lead to bugs. This macro aims to avoid most of those bugs by
|
|
|
2519 * making sure that the source and destination are both pointers to objects
|
|
|
2520 * that are the same size. It does not check that the objects are the same
|
|
|
2521 * _type_, just that the copy will not overflow either object.
|
|
|
2522 *
|
|
|
2523 * The size check happens at compile time, and the compiler will throw an
|
|
|
2524 * error if the objects are different sizes.
|
|
|
2525 *
|
|
|
2526 * Generally this is intended to copy a single object, not an array.
|
|
|
2527 *
|
|
|
2528 * This macro looks like it double-evaluates its parameters, but the extras
|
|
|
2529 * them are in `sizeof` sections, which generate no code nor side-effects.
|
|
|
2530 *
|
|
|
2531 * \param dst a pointer to the destination object. Must not be NULL.
|
|
|
2532 * \param src a pointer to the source object. Must not be NULL.
|
|
|
2533 *
|
|
|
2534 * \threadsafety It is safe to call this function from any thread.
|
|
|
2535 *
|
|
|
2536 * \since This function is available since SDL 3.2.0.
|
|
|
2537 */
|
|
|
2538 #define SDL_copyp(dst, src) \
|
|
|
2539 { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \
|
|
|
2540 SDL_memcpy((dst), (src), sizeof(*(src)))
|
|
|
2541
|
|
|
2542 /**
|
|
|
2543 * Copy memory ranges that might overlap.
|
|
|
2544 *
|
|
|
2545 * It is okay for the memory regions to overlap. If you are confident that the
|
|
|
2546 * regions never overlap, using SDL_memcpy() may improve performance.
|
|
|
2547 *
|
|
|
2548 * \param dst The destination memory region. Must not be NULL.
|
|
|
2549 * \param src The source memory region. Must not be NULL.
|
|
|
2550 * \param len The length in bytes of both `dst` and `src`.
|
|
|
2551 * \returns `dst`.
|
|
|
2552 *
|
|
|
2553 * \threadsafety It is safe to call this function from any thread.
|
|
|
2554 *
|
|
|
2555 * \since This function is available since SDL 3.2.0.
|
|
|
2556 *
|
|
|
2557 * \sa SDL_memcpy
|
|
|
2558 */
|
|
|
2559 extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len);
|
|
|
2560
|
|
|
2561 /* Take advantage of compiler optimizations for memmove */
|
|
|
2562 #ifndef SDL_SLOW_MEMMOVE
|
|
|
2563 #ifdef SDL_memmove
|
|
|
2564 #undef SDL_memmove
|
|
|
2565 #endif
|
|
|
2566 #define SDL_memmove memmove
|
|
|
2567 #endif
|
|
|
2568
|
|
|
2569 /**
|
|
|
2570 * Initialize all bytes of buffer of memory to a specific value.
|
|
|
2571 *
|
|
|
2572 * This function will set `len` bytes, pointed to by `dst`, to the value
|
|
|
2573 * specified in `c`.
|
|
|
2574 *
|
|
|
2575 * Despite `c` being an `int` instead of a `char`, this only operates on
|
|
|
2576 * bytes; `c` must be a value between 0 and 255, inclusive.
|
|
|
2577 *
|
|
|
2578 * \param dst the destination memory region. Must not be NULL.
|
|
|
2579 * \param c the byte value to set.
|
|
|
2580 * \param len the length, in bytes, to set in `dst`.
|
|
|
2581 * \returns `dst`.
|
|
|
2582 *
|
|
|
2583 * \threadsafety It is safe to call this function from any thread.
|
|
|
2584 *
|
|
|
2585 * \since This function is available since SDL 3.2.0.
|
|
|
2586 */
|
|
|
2587 extern SDL_DECLSPEC void * SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len);
|
|
|
2588
|
|
|
2589 /**
|
|
|
2590 * Initialize all 32-bit words of buffer of memory to a specific value.
|
|
|
2591 *
|
|
|
2592 * This function will set a buffer of `dwords` Uint32 values, pointed to by
|
|
|
2593 * `dst`, to the value specified in `val`.
|
|
|
2594 *
|
|
|
2595 * Unlike SDL_memset, this sets 32-bit values, not bytes, so it's not limited
|
|
|
2596 * to a range of 0-255.
|
|
|
2597 *
|
|
|
2598 * \param dst the destination memory region. Must not be NULL.
|
|
|
2599 * \param val the Uint32 value to set.
|
|
|
2600 * \param dwords the number of Uint32 values to set in `dst`.
|
|
|
2601 * \returns `dst`.
|
|
|
2602 *
|
|
|
2603 * \threadsafety It is safe to call this function from any thread.
|
|
|
2604 *
|
|
|
2605 * \since This function is available since SDL 3.2.0.
|
|
|
2606 */
|
|
|
2607 extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwords);
|
|
|
2608
|
|
|
2609 /* Take advantage of compiler optimizations for memset */
|
|
|
2610 #ifndef SDL_SLOW_MEMSET
|
|
|
2611 #ifdef SDL_memset
|
|
|
2612 #undef SDL_memset
|
|
|
2613 #endif
|
|
|
2614 #define SDL_memset memset
|
|
|
2615 #endif
|
|
|
2616
|
|
|
2617 /**
|
|
|
2618 * Clear an object's memory to zero.
|
|
|
2619 *
|
|
|
2620 * This is wrapper over SDL_memset that handles calculating the object size,
|
|
|
2621 * so there's no chance of copy/paste errors, and the code is cleaner.
|
|
|
2622 *
|
|
|
2623 * This requires an object, not a pointer to an object, nor an array.
|
|
|
2624 *
|
|
|
2625 * \param x the object to clear.
|
|
|
2626 *
|
|
|
2627 * \threadsafety It is safe to call this macro from any thread.
|
|
|
2628 *
|
|
|
2629 * \since This macro is available since SDL 3.2.0.
|
|
|
2630 *
|
|
|
2631 * \sa SDL_zerop
|
|
|
2632 * \sa SDL_zeroa
|
|
|
2633 */
|
|
|
2634 #define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x)))
|
|
|
2635
|
|
|
2636 /**
|
|
|
2637 * Clear an object's memory to zero, using a pointer.
|
|
|
2638 *
|
|
|
2639 * This is wrapper over SDL_memset that handles calculating the object size,
|
|
|
2640 * so there's no chance of copy/paste errors, and the code is cleaner.
|
|
|
2641 *
|
|
|
2642 * This requires a pointer to an object, not an object itself, nor an array.
|
|
|
2643 *
|
|
|
2644 * \param x a pointer to the object to clear.
|
|
|
2645 *
|
|
|
2646 * \threadsafety It is safe to call this macro from any thread.
|
|
|
2647 *
|
|
|
2648 * \since This macro is available since SDL 3.2.0.
|
|
|
2649 *
|
|
|
2650 * \sa SDL_zero
|
|
|
2651 * \sa SDL_zeroa
|
|
|
2652 */
|
|
|
2653 #define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x)))
|
|
|
2654
|
|
|
2655 /**
|
|
|
2656 * Clear an array's memory to zero.
|
|
|
2657 *
|
|
|
2658 * This is wrapper over SDL_memset that handles calculating the array size, so
|
|
|
2659 * there's no chance of copy/paste errors, and the code is cleaner.
|
|
|
2660 *
|
|
|
2661 * This requires an array, not an object, nor a pointer to an object.
|
|
|
2662 *
|
|
|
2663 * \param x an array to clear.
|
|
|
2664 *
|
|
|
2665 * \threadsafety It is safe to call this macro from any thread.
|
|
|
2666 *
|
|
|
2667 * \since This macro is available since SDL 3.2.0.
|
|
|
2668 *
|
|
|
2669 * \sa SDL_zero
|
|
|
2670 * \sa SDL_zerop
|
|
|
2671 */
|
|
|
2672 #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x)))
|
|
|
2673
|
|
|
2674
|
|
|
2675 /**
|
|
|
2676 * Compare two buffers of memory.
|
|
|
2677 *
|
|
|
2678 * \param s1 the first buffer to compare. NULL is not permitted!
|
|
|
2679 * \param s2 the second buffer to compare. NULL is not permitted!
|
|
|
2680 * \param len the number of bytes to compare between the buffers.
|
|
|
2681 * \returns less than zero if s1 is "less than" s2, greater than zero if s1 is
|
|
|
2682 * "greater than" s2, and zero if the buffers match exactly for `len`
|
|
|
2683 * bytes.
|
|
|
2684 *
|
|
|
2685 * \threadsafety It is safe to call this function from any thread.
|
|
|
2686 *
|
|
|
2687 * \since This function is available since SDL 3.2.0.
|
|
|
2688 */
|
|
|
2689 extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len);
|
|
|
2690
|
|
|
2691 /**
|
|
|
2692 * This works exactly like wcslen() but doesn't require access to a C runtime.
|
|
|
2693 *
|
|
|
2694 * Counts the number of wchar_t values in `wstr`, excluding the null
|
|
|
2695 * terminator.
|
|
|
2696 *
|
|
|
2697 * Like SDL_strlen only counts bytes and not codepoints in a UTF-8 string,
|
|
|
2698 * this counts wchar_t values in a string, even if the string's encoding is of
|
|
|
2699 * variable width, like UTF-16.
|
|
|
2700 *
|
|
|
2701 * Also be aware that wchar_t is different sizes on different platforms (4
|
|
|
2702 * bytes on Linux, 2 on Windows, etc).
|
|
|
2703 *
|
|
|
2704 * \param wstr The null-terminated wide string to read. Must not be NULL.
|
|
|
2705 * \returns the length (in wchar_t values, excluding the null terminator) of
|
|
|
2706 * `wstr`.
|
|
|
2707 *
|
|
|
2708 * \threadsafety It is safe to call this function from any thread.
|
|
|
2709 *
|
|
|
2710 * \since This function is available since SDL 3.2.0.
|
|
|
2711 *
|
|
|
2712 * \sa SDL_wcsnlen
|
|
|
2713 * \sa SDL_utf8strlen
|
|
|
2714 * \sa SDL_utf8strnlen
|
|
|
2715 */
|
|
|
2716 extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr);
|
|
|
2717
|
|
|
2718 /**
|
|
|
2719 * This works exactly like wcsnlen() but doesn't require access to a C
|
|
|
2720 * runtime.
|
|
|
2721 *
|
|
|
2722 * Counts up to a maximum of `maxlen` wchar_t values in `wstr`, excluding the
|
|
|
2723 * null terminator.
|
|
|
2724 *
|
|
|
2725 * Like SDL_strnlen only counts bytes and not codepoints in a UTF-8 string,
|
|
|
2726 * this counts wchar_t values in a string, even if the string's encoding is of
|
|
|
2727 * variable width, like UTF-16.
|
|
|
2728 *
|
|
|
2729 * Also be aware that wchar_t is different sizes on different platforms (4
|
|
|
2730 * bytes on Linux, 2 on Windows, etc).
|
|
|
2731 *
|
|
|
2732 * Also, `maxlen` is a count of wide characters, not bytes!
|
|
|
2733 *
|
|
|
2734 * \param wstr The null-terminated wide string to read. Must not be NULL.
|
|
|
2735 * \param maxlen The maximum amount of wide characters to count.
|
|
|
2736 * \returns the length (in wide characters, excluding the null terminator) of
|
|
|
2737 * `wstr` but never more than `maxlen`.
|
|
|
2738 *
|
|
|
2739 * \threadsafety It is safe to call this function from any thread.
|
|
|
2740 *
|
|
|
2741 * \since This function is available since SDL 3.2.0.
|
|
|
2742 *
|
|
|
2743 * \sa SDL_wcslen
|
|
|
2744 * \sa SDL_utf8strlen
|
|
|
2745 * \sa SDL_utf8strnlen
|
|
|
2746 */
|
|
|
2747 extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen);
|
|
|
2748
|
|
|
2749 /**
|
|
|
2750 * Copy a wide string.
|
|
|
2751 *
|
|
|
2752 * This function copies `maxlen` - 1 wide characters from `src` to `dst`, then
|
|
|
2753 * appends a null terminator.
|
|
|
2754 *
|
|
|
2755 * `src` and `dst` must not overlap.
|
|
|
2756 *
|
|
|
2757 * If `maxlen` is 0, no wide characters are copied and no null terminator is
|
|
|
2758 * written.
|
|
|
2759 *
|
|
|
2760 * \param dst The destination buffer. Must not be NULL, and must not overlap
|
|
|
2761 * with `src`.
|
|
|
2762 * \param src The null-terminated wide string to copy. Must not be NULL, and
|
|
|
2763 * must not overlap with `dst`.
|
|
|
2764 * \param maxlen The length (in wide characters) of the destination buffer.
|
|
|
2765 * \returns the length (in wide characters, excluding the null terminator) of
|
|
|
2766 * `src`.
|
|
|
2767 *
|
|
|
2768 * \threadsafety It is safe to call this function from any thread.
|
|
|
2769 *
|
|
|
2770 * \since This function is available since SDL 3.2.0.
|
|
|
2771 *
|
|
|
2772 * \sa SDL_wcslcat
|
|
|
2773 */
|
|
|
2774 extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen);
|
|
|
2775
|
|
|
2776 /**
|
|
|
2777 * Concatenate wide strings.
|
|
|
2778 *
|
|
|
2779 * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters
|
|
|
2780 * from `src` to the end of the wide string in `dst`, then appends a null
|
|
|
2781 * terminator.
|
|
|
2782 *
|
|
|
2783 * `src` and `dst` must not overlap.
|
|
|
2784 *
|
|
|
2785 * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is
|
|
|
2786 * unmodified.
|
|
|
2787 *
|
|
|
2788 * \param dst The destination buffer already containing the first
|
|
|
2789 * null-terminated wide string. Must not be NULL and must not
|
|
|
2790 * overlap with `src`.
|
|
|
2791 * \param src The second null-terminated wide string. Must not be NULL, and
|
|
|
2792 * must not overlap with `dst`.
|
|
|
2793 * \param maxlen The length (in wide characters) of the destination buffer.
|
|
|
2794 * \returns the length (in wide characters, excluding the null terminator) of
|
|
|
2795 * the string in `dst` plus the length of `src`.
|
|
|
2796 *
|
|
|
2797 * \threadsafety It is safe to call this function from any thread.
|
|
|
2798 *
|
|
|
2799 * \since This function is available since SDL 3.2.0.
|
|
|
2800 *
|
|
|
2801 * \sa SDL_wcslcpy
|
|
|
2802 */
|
|
|
2803 extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen);
|
|
|
2804
|
|
|
2805 /**
|
|
|
2806 * Allocate a copy of a wide string.
|
|
|
2807 *
|
|
|
2808 * This allocates enough space for a null-terminated copy of `wstr`, using
|
|
|
2809 * SDL_malloc, and then makes a copy of the string into this space.
|
|
|
2810 *
|
|
|
2811 * The returned string is owned by the caller, and should be passed to
|
|
|
2812 * SDL_free when no longer needed.
|
|
|
2813 *
|
|
|
2814 * \param wstr the string to copy.
|
|
|
2815 * \returns a pointer to the newly-allocated wide string.
|
|
|
2816 *
|
|
|
2817 * \threadsafety It is safe to call this function from any thread.
|
|
|
2818 *
|
|
|
2819 * \since This function is available since SDL 3.2.0.
|
|
|
2820 */
|
|
|
2821 extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr);
|
|
|
2822
|
|
|
2823 /**
|
|
|
2824 * Search a wide string for the first instance of a specific substring.
|
|
|
2825 *
|
|
|
2826 * The search ends once it finds the requested substring, or a null terminator
|
|
|
2827 * byte to end the string.
|
|
|
2828 *
|
|
|
2829 * Note that this looks for strings of _wide characters_, not _codepoints_, so
|
|
|
2830 * it's legal to search for malformed and incomplete UTF-16 sequences.
|
|
|
2831 *
|
|
|
2832 * \param haystack the wide string to search. Must not be NULL.
|
|
|
2833 * \param needle the wide string to search for. Must not be NULL.
|
|
|
2834 * \returns a pointer to the first instance of `needle` in the string, or NULL
|
|
|
2835 * if not found.
|
|
|
2836 *
|
|
|
2837 * \threadsafety It is safe to call this function from any thread.
|
|
|
2838 *
|
|
|
2839 * \since This function is available since SDL 3.2.0.
|
|
|
2840 */
|
|
|
2841 extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle);
|
|
|
2842
|
|
|
2843 /**
|
|
|
2844 * Search a wide string, up to n wide chars, for the first instance of a
|
|
|
2845 * specific substring.
|
|
|
2846 *
|
|
|
2847 * The search ends once it finds the requested substring, or a null terminator
|
|
|
2848 * value to end the string, or `maxlen` wide character have been examined. It
|
|
|
2849 * is possible to use this function on a wide string without a null
|
|
|
2850 * terminator.
|
|
|
2851 *
|
|
|
2852 * Note that this looks for strings of _wide characters_, not _codepoints_, so
|
|
|
2853 * it's legal to search for malformed and incomplete UTF-16 sequences.
|
|
|
2854 *
|
|
|
2855 * \param haystack the wide string to search. Must not be NULL.
|
|
|
2856 * \param needle the wide string to search for. Must not be NULL.
|
|
|
2857 * \param maxlen the maximum number of wide characters to search in
|
|
|
2858 * `haystack`.
|
|
|
2859 * \returns a pointer to the first instance of `needle` in the string, or NULL
|
|
|
2860 * if not found.
|
|
|
2861 *
|
|
|
2862 * \threadsafety It is safe to call this function from any thread.
|
|
|
2863 *
|
|
|
2864 * \since This function is available since SDL 3.2.0.
|
|
|
2865 */
|
|
|
2866 extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen);
|
|
|
2867
|
|
|
2868 /**
|
|
|
2869 * Compare two null-terminated wide strings.
|
|
|
2870 *
|
|
|
2871 * This only compares wchar_t values until it hits a null-terminating
|
|
|
2872 * character; it does not care if the string is well-formed UTF-16 (or UTF-32,
|
|
|
2873 * depending on your platform's wchar_t size), or uses valid Unicode values.
|
|
|
2874 *
|
|
|
2875 * \param str1 the first string to compare. NULL is not permitted!
|
|
|
2876 * \param str2 the second string to compare. NULL is not permitted!
|
|
|
2877 * \returns less than zero if str1 is "less than" str2, greater than zero if
|
|
|
2878 * str1 is "greater than" str2, and zero if the strings match
|
|
|
2879 * exactly.
|
|
|
2880 *
|
|
|
2881 * \threadsafety It is safe to call this function from any thread.
|
|
|
2882 *
|
|
|
2883 * \since This function is available since SDL 3.2.0.
|
|
|
2884 */
|
|
|
2885 extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2);
|
|
|
2886
|
|
|
2887 /**
|
|
|
2888 * Compare two wide strings up to a number of wchar_t values.
|
|
|
2889 *
|
|
|
2890 * This only compares wchar_t values; it does not care if the string is
|
|
|
2891 * well-formed UTF-16 (or UTF-32, depending on your platform's wchar_t size),
|
|
|
2892 * or uses valid Unicode values.
|
|
|
2893 *
|
|
|
2894 * Note that while this function is intended to be used with UTF-16 (or
|
|
|
2895 * UTF-32, depending on your platform's definition of wchar_t), it is
|
|
|
2896 * comparing raw wchar_t values and not Unicode codepoints: `maxlen` specifies
|
|
|
2897 * a wchar_t limit! If the limit lands in the middle of a multi-wchar UTF-16
|
|
|
2898 * sequence, it will only compare a portion of the final character.
|
|
|
2899 *
|
|
|
2900 * `maxlen` specifies a maximum number of wchar_t to compare; if the strings
|
|
|
2901 * match to this number of wide chars (or both have matched to a
|
|
|
2902 * null-terminator character before this count), they will be considered
|
|
|
2903 * equal.
|
|
|
2904 *
|
|
|
2905 * \param str1 the first string to compare. NULL is not permitted!
|
|
|
2906 * \param str2 the second string to compare. NULL is not permitted!
|
|
|
2907 * \param maxlen the maximum number of wchar_t to compare.
|
|
|
2908 * \returns less than zero if str1 is "less than" str2, greater than zero if
|
|
|
2909 * str1 is "greater than" str2, and zero if the strings match
|
|
|
2910 * exactly.
|
|
|
2911 *
|
|
|
2912 * \threadsafety It is safe to call this function from any thread.
|
|
|
2913 *
|
|
|
2914 * \since This function is available since SDL 3.2.0.
|
|
|
2915 */
|
|
|
2916 extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen);
|
|
|
2917
|
|
|
2918 /**
|
|
|
2919 * Compare two null-terminated wide strings, case-insensitively.
|
|
|
2920 *
|
|
|
2921 * This will work with Unicode strings, using a technique called
|
|
|
2922 * "case-folding" to handle the vast majority of case-sensitive human
|
|
|
2923 * languages regardless of system locale. It can deal with expanding values: a
|
|
|
2924 * German Eszett character can compare against two ASCII 's' chars and be
|
|
|
2925 * considered a match, for example. A notable exception: it does not handle
|
|
|
2926 * the Turkish 'i' character; human language is complicated!
|
|
|
2927 *
|
|
|
2928 * Depending on your platform, "wchar_t" might be 2 bytes, and expected to be
|
|
|
2929 * UTF-16 encoded (like Windows), or 4 bytes in UTF-32 format. Since this
|
|
|
2930 * handles Unicode, it expects the string to be well-formed and not a
|
|
|
2931 * null-terminated string of arbitrary bytes. Characters that are not valid
|
|
|
2932 * UTF-16 (or UTF-32) are treated as Unicode character U+FFFD (REPLACEMENT
|
|
|
2933 * CHARACTER), which is to say two strings of random bits may turn out to
|
|
|
2934 * match if they convert to the same amount of replacement characters.
|
|
|
2935 *
|
|
|
2936 * \param str1 the first string to compare. NULL is not permitted!
|
|
|
2937 * \param str2 the second string to compare. NULL is not permitted!
|
|
|
2938 * \returns less than zero if str1 is "less than" str2, greater than zero if
|
|
|
2939 * str1 is "greater than" str2, and zero if the strings match
|
|
|
2940 * exactly.
|
|
|
2941 *
|
|
|
2942 * \threadsafety It is safe to call this function from any thread.
|
|
|
2943 *
|
|
|
2944 * \since This function is available since SDL 3.2.0.
|
|
|
2945 */
|
|
|
2946 extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2);
|
|
|
2947
|
|
|
2948 /**
|
|
|
2949 * Compare two wide strings, case-insensitively, up to a number of wchar_t.
|
|
|
2950 *
|
|
|
2951 * This will work with Unicode strings, using a technique called
|
|
|
2952 * "case-folding" to handle the vast majority of case-sensitive human
|
|
|
2953 * languages regardless of system locale. It can deal with expanding values: a
|
|
|
2954 * German Eszett character can compare against two ASCII 's' chars and be
|
|
|
2955 * considered a match, for example. A notable exception: it does not handle
|
|
|
2956 * the Turkish 'i' character; human language is complicated!
|
|
|
2957 *
|
|
|
2958 * Depending on your platform, "wchar_t" might be 2 bytes, and expected to be
|
|
|
2959 * UTF-16 encoded (like Windows), or 4 bytes in UTF-32 format. Since this
|
|
|
2960 * handles Unicode, it expects the string to be well-formed and not a
|
|
|
2961 * null-terminated string of arbitrary bytes. Characters that are not valid
|
|
|
2962 * UTF-16 (or UTF-32) are treated as Unicode character U+FFFD (REPLACEMENT
|
|
|
2963 * CHARACTER), which is to say two strings of random bits may turn out to
|
|
|
2964 * match if they convert to the same amount of replacement characters.
|
|
|
2965 *
|
|
|
2966 * Note that while this function might deal with variable-sized characters,
|
|
|
2967 * `maxlen` specifies a _wchar_ limit! If the limit lands in the middle of a
|
|
|
2968 * multi-byte UTF-16 sequence, it may convert a portion of the final character
|
|
|
2969 * to one or more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not
|
|
|
2970 * to overflow a buffer.
|
|
|
2971 *
|
|
|
2972 * `maxlen` specifies a maximum number of wchar_t values to compare; if the
|
|
|
2973 * strings match to this number of wchar_t (or both have matched to a
|
|
|
2974 * null-terminator character before this number of bytes), they will be
|
|
|
2975 * considered equal.
|
|
|
2976 *
|
|
|
2977 * \param str1 the first string to compare. NULL is not permitted!
|
|
|
2978 * \param str2 the second string to compare. NULL is not permitted!
|
|
|
2979 * \param maxlen the maximum number of wchar_t values to compare.
|
|
|
2980 * \returns less than zero if str1 is "less than" str2, greater than zero if
|
|
|
2981 * str1 is "greater than" str2, and zero if the strings match
|
|
|
2982 * exactly.
|
|
|
2983 *
|
|
|
2984 * \threadsafety It is safe to call this function from any thread.
|
|
|
2985 *
|
|
|
2986 * \since This function is available since SDL 3.2.0.
|
|
|
2987 */
|
|
|
2988 extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen);
|
|
|
2989
|
|
|
2990 /**
|
|
|
2991 * Parse a `long` from a wide string.
|
|
|
2992 *
|
|
|
2993 * If `str` starts with whitespace, then those whitespace characters are
|
|
|
2994 * skipped before attempting to parse the number.
|
|
|
2995 *
|
|
|
2996 * If the parsed number does not fit inside a `long`, the result is clamped to
|
|
|
2997 * the minimum and maximum representable `long` values.
|
|
|
2998 *
|
|
|
2999 * \param str The null-terminated wide string to read. Must not be NULL.
|
|
|
3000 * \param endp If not NULL, the address of the first invalid wide character
|
|
|
3001 * (i.e. the next character after the parsed number) will be
|
|
|
3002 * written to this pointer.
|
|
|
3003 * \param base The base of the integer to read. Supported values are 0 and 2
|
|
|
3004 * to 36 inclusive. If 0, the base will be inferred from the
|
|
|
3005 * number's prefix (0x for hexadecimal, 0 for octal, decimal
|
|
|
3006 * otherwise).
|
|
|
3007 * \returns the parsed `long`, or 0 if no number could be parsed.
|
|
|
3008 *
|
|
|
3009 * \threadsafety It is safe to call this function from any thread.
|
|
|
3010 *
|
|
|
3011 * \since This function is available since SDL 3.2.0.
|
|
|
3012 *
|
|
|
3013 * \sa SDL_strtol
|
|
|
3014 */
|
|
|
3015 extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base);
|
|
|
3016
|
|
|
3017 /**
|
|
|
3018 * This works exactly like strlen() but doesn't require access to a C runtime.
|
|
|
3019 *
|
|
|
3020 * Counts the bytes in `str`, excluding the null terminator.
|
|
|
3021 *
|
|
|
3022 * If you need the length of a UTF-8 string, consider using SDL_utf8strlen().
|
|
|
3023 *
|
|
|
3024 * \param str The null-terminated string to read. Must not be NULL.
|
|
|
3025 * \returns the length (in bytes, excluding the null terminator) of `src`.
|
|
|
3026 *
|
|
|
3027 * \threadsafety It is safe to call this function from any thread.
|
|
|
3028 *
|
|
|
3029 * \since This function is available since SDL 3.2.0.
|
|
|
3030 *
|
|
|
3031 * \sa SDL_strnlen
|
|
|
3032 * \sa SDL_utf8strlen
|
|
|
3033 * \sa SDL_utf8strnlen
|
|
|
3034 */
|
|
|
3035 extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str);
|
|
|
3036
|
|
|
3037 /**
|
|
|
3038 * This works exactly like strnlen() but doesn't require access to a C
|
|
|
3039 * runtime.
|
|
|
3040 *
|
|
|
3041 * Counts up to a maximum of `maxlen` bytes in `str`, excluding the null
|
|
|
3042 * terminator.
|
|
|
3043 *
|
|
|
3044 * If you need the length of a UTF-8 string, consider using SDL_utf8strnlen().
|
|
|
3045 *
|
|
|
3046 * \param str The null-terminated string to read. Must not be NULL.
|
|
|
3047 * \param maxlen The maximum amount of bytes to count.
|
|
|
3048 * \returns the length (in bytes, excluding the null terminator) of `src` but
|
|
|
3049 * never more than `maxlen`.
|
|
|
3050 *
|
|
|
3051 * \threadsafety It is safe to call this function from any thread.
|
|
|
3052 *
|
|
|
3053 * \since This function is available since SDL 3.2.0.
|
|
|
3054 *
|
|
|
3055 * \sa SDL_strlen
|
|
|
3056 * \sa SDL_utf8strlen
|
|
|
3057 * \sa SDL_utf8strnlen
|
|
|
3058 */
|
|
|
3059 extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen);
|
|
|
3060
|
|
|
3061 /**
|
|
|
3062 * Copy a string.
|
|
|
3063 *
|
|
|
3064 * This function copies up to `maxlen` - 1 characters from `src` to `dst`,
|
|
|
3065 * then appends a null terminator.
|
|
|
3066 *
|
|
|
3067 * If `maxlen` is 0, no characters are copied and no null terminator is
|
|
|
3068 * written.
|
|
|
3069 *
|
|
|
3070 * If you want to copy an UTF-8 string but need to ensure that multi-byte
|
|
|
3071 * sequences are not truncated, consider using SDL_utf8strlcpy().
|
|
|
3072 *
|
|
|
3073 * \param dst The destination buffer. Must not be NULL, and must not overlap
|
|
|
3074 * with `src`.
|
|
|
3075 * \param src The null-terminated string to copy. Must not be NULL, and must
|
|
|
3076 * not overlap with `dst`.
|
|
|
3077 * \param maxlen The length (in characters) of the destination buffer.
|
|
|
3078 * \returns the length (in characters, excluding the null terminator) of
|
|
|
3079 * `src`.
|
|
|
3080 *
|
|
|
3081 * \threadsafety It is safe to call this function from any thread.
|
|
|
3082 *
|
|
|
3083 * \since This function is available since SDL 3.2.0.
|
|
|
3084 *
|
|
|
3085 * \sa SDL_strlcat
|
|
|
3086 * \sa SDL_utf8strlcpy
|
|
|
3087 */
|
|
|
3088 extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);
|
|
|
3089
|
|
|
3090 /**
|
|
|
3091 * Copy an UTF-8 string.
|
|
|
3092 *
|
|
|
3093 * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst` while
|
|
|
3094 * also ensuring that the string written to `dst` does not end in a truncated
|
|
|
3095 * multi-byte sequence. Finally, it appends a null terminator.
|
|
|
3096 *
|
|
|
3097 * `src` and `dst` must not overlap.
|
|
|
3098 *
|
|
|
3099 * Note that unlike SDL_strlcpy(), this function returns the number of bytes
|
|
|
3100 * written, not the length of `src`.
|
|
|
3101 *
|
|
|
3102 * \param dst The destination buffer. Must not be NULL, and must not overlap
|
|
|
3103 * with `src`.
|
|
|
3104 * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and
|
|
|
3105 * must not overlap with `dst`.
|
|
|
3106 * \param dst_bytes The length (in bytes) of the destination buffer. Must not
|
|
|
3107 * be 0.
|
|
|
3108 * \returns the number of bytes written, excluding the null terminator.
|
|
|
3109 *
|
|
|
3110 * \threadsafety It is safe to call this function from any thread.
|
|
|
3111 *
|
|
|
3112 * \since This function is available since SDL 3.2.0.
|
|
|
3113 *
|
|
|
3114 * \sa SDL_strlcpy
|
|
|
3115 */
|
|
|
3116 extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes);
|
|
|
3117
|
|
|
3118 /**
|
|
|
3119 * Concatenate strings.
|
|
|
3120 *
|
|
|
3121 * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from
|
|
|
3122 * `src` to the end of the string in `dst`, then appends a null terminator.
|
|
|
3123 *
|
|
|
3124 * `src` and `dst` must not overlap.
|
|
|
3125 *
|
|
|
3126 * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is
|
|
|
3127 * unmodified.
|
|
|
3128 *
|
|
|
3129 * \param dst The destination buffer already containing the first
|
|
|
3130 * null-terminated string. Must not be NULL and must not overlap
|
|
|
3131 * with `src`.
|
|
|
3132 * \param src The second null-terminated string. Must not be NULL, and must
|
|
|
3133 * not overlap with `dst`.
|
|
|
3134 * \param maxlen The length (in characters) of the destination buffer.
|
|
|
3135 * \returns the length (in characters, excluding the null terminator) of the
|
|
|
3136 * string in `dst` plus the length of `src`.
|
|
|
3137 *
|
|
|
3138 * \threadsafety It is safe to call this function from any thread.
|
|
|
3139 *
|
|
|
3140 * \since This function is available since SDL 3.2.0.
|
|
|
3141 *
|
|
|
3142 * \sa SDL_strlcpy
|
|
|
3143 */
|
|
|
3144 extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);
|
|
|
3145
|
|
|
3146 /**
|
|
|
3147 * Allocate a copy of a string.
|
|
|
3148 *
|
|
|
3149 * This allocates enough space for a null-terminated copy of `str`, using
|
|
|
3150 * SDL_malloc, and then makes a copy of the string into this space.
|
|
|
3151 *
|
|
|
3152 * The returned string is owned by the caller, and should be passed to
|
|
|
3153 * SDL_free when no longer needed.
|
|
|
3154 *
|
|
|
3155 * \param str the string to copy.
|
|
|
3156 * \returns a pointer to the newly-allocated string.
|
|
|
3157 *
|
|
|
3158 * \threadsafety It is safe to call this function from any thread.
|
|
|
3159 *
|
|
|
3160 * \since This function is available since SDL 3.2.0.
|
|
|
3161 */
|
|
|
3162 extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str);
|
|
|
3163
|
|
|
3164 /**
|
|
|
3165 * Allocate a copy of a string, up to n characters.
|
|
|
3166 *
|
|
|
3167 * This allocates enough space for a null-terminated copy of `str`, up to
|
|
|
3168 * `maxlen` bytes, using SDL_malloc, and then makes a copy of the string into
|
|
|
3169 * this space.
|
|
|
3170 *
|
|
|
3171 * If the string is longer than `maxlen` bytes, the returned string will be
|
|
|
3172 * `maxlen` bytes long, plus a null-terminator character that isn't included
|
|
|
3173 * in the count.
|
|
|
3174 *
|
|
|
3175 * The returned string is owned by the caller, and should be passed to
|
|
|
3176 * SDL_free when no longer needed.
|
|
|
3177 *
|
|
|
3178 * \param str the string to copy.
|
|
|
3179 * \param maxlen the maximum length of the copied string, not counting the
|
|
|
3180 * null-terminator character.
|
|
|
3181 * \returns a pointer to the newly-allocated string.
|
|
|
3182 *
|
|
|
3183 * \threadsafety It is safe to call this function from any thread.
|
|
|
3184 *
|
|
|
3185 * \since This function is available since SDL 3.2.0.
|
|
|
3186 */
|
|
|
3187 extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen);
|
|
|
3188
|
|
|
3189 /**
|
|
|
3190 * Reverse a string's contents.
|
|
|
3191 *
|
|
|
3192 * This reverses a null-terminated string in-place. Only the content of the
|
|
|
3193 * string is reversed; the null-terminator character remains at the end of the
|
|
|
3194 * reversed string.
|
|
|
3195 *
|
|
|
3196 * **WARNING**: This function reverses the _bytes_ of the string, not the
|
|
|
3197 * codepoints. If `str` is a UTF-8 string with Unicode codepoints > 127, this
|
|
|
3198 * will ruin the string data. You should only use this function on strings
|
|
|
3199 * that are completely comprised of low ASCII characters.
|
|
|
3200 *
|
|
|
3201 * \param str the string to reverse.
|
|
|
3202 * \returns `str`.
|
|
|
3203 *
|
|
|
3204 * \threadsafety It is safe to call this function from any thread.
|
|
|
3205 *
|
|
|
3206 * \since This function is available since SDL 3.2.0.
|
|
|
3207 */
|
|
|
3208 extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str);
|
|
|
3209
|
|
|
3210 /**
|
|
|
3211 * Convert a string to uppercase.
|
|
|
3212 *
|
|
|
3213 * **WARNING**: Regardless of system locale, this will only convert ASCII
|
|
|
3214 * values 'A' through 'Z' to uppercase.
|
|
|
3215 *
|
|
|
3216 * This function operates on a null-terminated string of bytes--even if it is
|
|
|
3217 * malformed UTF-8!--and converts ASCII characters 'a' through 'z' to their
|
|
|
3218 * uppercase equivalents in-place, returning the original `str` pointer.
|
|
|
3219 *
|
|
|
3220 * \param str the string to convert in-place. Can not be NULL.
|
|
|
3221 * \returns the `str` pointer passed into this function.
|
|
|
3222 *
|
|
|
3223 * \threadsafety It is safe to call this function from any thread.
|
|
|
3224 *
|
|
|
3225 * \since This function is available since SDL 3.2.0.
|
|
|
3226 *
|
|
|
3227 * \sa SDL_strlwr
|
|
|
3228 */
|
|
|
3229 extern SDL_DECLSPEC char * SDLCALL SDL_strupr(char *str);
|
|
|
3230
|
|
|
3231 /**
|
|
|
3232 * Convert a string to lowercase.
|
|
|
3233 *
|
|
|
3234 * **WARNING**: Regardless of system locale, this will only convert ASCII
|
|
|
3235 * values 'A' through 'Z' to lowercase.
|
|
|
3236 *
|
|
|
3237 * This function operates on a null-terminated string of bytes--even if it is
|
|
|
3238 * malformed UTF-8!--and converts ASCII characters 'A' through 'Z' to their
|
|
|
3239 * lowercase equivalents in-place, returning the original `str` pointer.
|
|
|
3240 *
|
|
|
3241 * \param str the string to convert in-place. Can not be NULL.
|
|
|
3242 * \returns the `str` pointer passed into this function.
|
|
|
3243 *
|
|
|
3244 * \threadsafety It is safe to call this function from any thread.
|
|
|
3245 *
|
|
|
3246 * \since This function is available since SDL 3.2.0.
|
|
|
3247 *
|
|
|
3248 * \sa SDL_strupr
|
|
|
3249 */
|
|
|
3250 extern SDL_DECLSPEC char * SDLCALL SDL_strlwr(char *str);
|
|
|
3251
|
|
|
3252 /**
|
|
|
3253 * Search a string for the first instance of a specific byte.
|
|
|
3254 *
|
|
|
3255 * The search ends once it finds the requested byte value, or a null
|
|
|
3256 * terminator byte to end the string.
|
|
|
3257 *
|
|
|
3258 * Note that this looks for _bytes_, not _characters_, so you cannot match
|
|
|
3259 * against a Unicode codepoint > 255, regardless of character encoding.
|
|
|
3260 *
|
|
|
3261 * \param str the string to search. Must not be NULL.
|
|
|
3262 * \param c the byte value to search for.
|
|
|
3263 * \returns a pointer to the first instance of `c` in the string, or NULL if
|
|
|
3264 * not found.
|
|
|
3265 *
|
|
|
3266 * \threadsafety It is safe to call this function from any thread.
|
|
|
3267 *
|
|
|
3268 * \since This function is available since SDL 3.2.0.
|
|
|
3269 */
|
|
|
3270 extern SDL_DECLSPEC char * SDLCALL SDL_strchr(const char *str, int c);
|
|
|
3271
|
|
|
3272 /**
|
|
|
3273 * Search a string for the last instance of a specific byte.
|
|
|
3274 *
|
|
|
3275 * The search must go until it finds a null terminator byte to end the string.
|
|
|
3276 *
|
|
|
3277 * Note that this looks for _bytes_, not _characters_, so you cannot match
|
|
|
3278 * against a Unicode codepoint > 255, regardless of character encoding.
|
|
|
3279 *
|
|
|
3280 * \param str the string to search. Must not be NULL.
|
|
|
3281 * \param c the byte value to search for.
|
|
|
3282 * \returns a pointer to the last instance of `c` in the string, or NULL if
|
|
|
3283 * not found.
|
|
|
3284 *
|
|
|
3285 * \threadsafety It is safe to call this function from any thread.
|
|
|
3286 *
|
|
|
3287 * \since This function is available since SDL 3.2.0.
|
|
|
3288 */
|
|
|
3289 extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c);
|
|
|
3290
|
|
|
3291 /**
|
|
|
3292 * Search a string for the first instance of a specific substring.
|
|
|
3293 *
|
|
|
3294 * The search ends once it finds the requested substring, or a null terminator
|
|
|
3295 * byte to end the string.
|
|
|
3296 *
|
|
|
3297 * Note that this looks for strings of _bytes_, not _characters_, so it's
|
|
|
3298 * legal to search for malformed and incomplete UTF-8 sequences.
|
|
|
3299 *
|
|
|
3300 * \param haystack the string to search. Must not be NULL.
|
|
|
3301 * \param needle the string to search for. Must not be NULL.
|
|
|
3302 * \returns a pointer to the first instance of `needle` in the string, or NULL
|
|
|
3303 * if not found.
|
|
|
3304 *
|
|
|
3305 * \threadsafety It is safe to call this function from any thread.
|
|
|
3306 *
|
|
|
3307 * \since This function is available since SDL 3.2.0.
|
|
|
3308 */
|
|
|
3309 extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *needle);
|
|
|
3310
|
|
|
3311 /**
|
|
|
3312 * Search a string, up to n bytes, for the first instance of a specific
|
|
|
3313 * substring.
|
|
|
3314 *
|
|
|
3315 * The search ends once it finds the requested substring, or a null terminator
|
|
|
3316 * byte to end the string, or `maxlen` bytes have been examined. It is
|
|
|
3317 * possible to use this function on a string without a null terminator.
|
|
|
3318 *
|
|
|
3319 * Note that this looks for strings of _bytes_, not _characters_, so it's
|
|
|
3320 * legal to search for malformed and incomplete UTF-8 sequences.
|
|
|
3321 *
|
|
|
3322 * \param haystack the string to search. Must not be NULL.
|
|
|
3323 * \param needle the string to search for. Must not be NULL.
|
|
|
3324 * \param maxlen the maximum number of bytes to search in `haystack`.
|
|
|
3325 * \returns a pointer to the first instance of `needle` in the string, or NULL
|
|
|
3326 * if not found.
|
|
|
3327 *
|
|
|
3328 * \threadsafety It is safe to call this function from any thread.
|
|
|
3329 *
|
|
|
3330 * \since This function is available since SDL 3.2.0.
|
|
|
3331 */
|
|
|
3332 extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen);
|
|
|
3333
|
|
|
3334 /**
|
|
|
3335 * Search a UTF-8 string for the first instance of a specific substring,
|
|
|
3336 * case-insensitively.
|
|
|
3337 *
|
|
|
3338 * This will work with Unicode strings, using a technique called
|
|
|
3339 * "case-folding" to handle the vast majority of case-sensitive human
|
|
|
3340 * languages regardless of system locale. It can deal with expanding values: a
|
|
|
3341 * German Eszett character can compare against two ASCII 's' chars and be
|
|
|
3342 * considered a match, for example. A notable exception: it does not handle
|
|
|
3343 * the Turkish 'i' character; human language is complicated!
|
|
|
3344 *
|
|
|
3345 * Since this handles Unicode, it expects the strings to be well-formed UTF-8
|
|
|
3346 * and not a null-terminated string of arbitrary bytes. Bytes that are not
|
|
|
3347 * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT
|
|
|
3348 * CHARACTER), which is to say two strings of random bits may turn out to
|
|
|
3349 * match if they convert to the same amount of replacement characters.
|
|
|
3350 *
|
|
|
3351 * \param haystack the string to search. Must not be NULL.
|
|
|
3352 * \param needle the string to search for. Must not be NULL.
|
|
|
3353 * \returns a pointer to the first instance of `needle` in the string, or NULL
|
|
|
3354 * if not found.
|
|
|
3355 *
|
|
|
3356 * \threadsafety It is safe to call this function from any thread.
|
|
|
3357 *
|
|
|
3358 * \since This function is available since SDL 3.2.0.
|
|
|
3359 */
|
|
|
3360 extern SDL_DECLSPEC char * SDLCALL SDL_strcasestr(const char *haystack, const char *needle);
|
|
|
3361
|
|
|
3362 /**
|
|
|
3363 * This works exactly like strtok_r() but doesn't require access to a C
|
|
|
3364 * runtime.
|
|
|
3365 *
|
|
|
3366 * Break a string up into a series of tokens.
|
|
|
3367 *
|
|
|
3368 * To start tokenizing a new string, `str` should be the non-NULL address of
|
|
|
3369 * the string to start tokenizing. Future calls to get the next token from the
|
|
|
3370 * same string should specify a NULL.
|
|
|
3371 *
|
|
|
3372 * Note that this function will overwrite pieces of `str` with null chars to
|
|
|
3373 * split it into tokens. This function cannot be used with const/read-only
|
|
|
3374 * strings!
|
|
|
3375 *
|
|
|
3376 * `saveptr` just needs to point to a `char *` that can be overwritten; SDL
|
|
|
3377 * will use this to save tokenizing state between calls. It is initialized if
|
|
|
3378 * `str` is non-NULL, and used to resume tokenizing when `str` is NULL.
|
|
|
3379 *
|
|
|
3380 * \param str the string to tokenize, or NULL to continue tokenizing.
|
|
|
3381 * \param delim the delimiter string that separates tokens.
|
|
|
3382 * \param saveptr pointer to a char *, used for ongoing state.
|
|
|
3383 * \returns A pointer to the next token, or NULL if no tokens remain.
|
|
|
3384 *
|
|
|
3385 * \threadsafety It is safe to call this function from any thread.
|
|
|
3386 *
|
|
|
3387 * \since This function is available since SDL 3.2.0.
|
|
|
3388 */
|
|
|
3389 extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *str, const char *delim, char **saveptr);
|
|
|
3390
|
|
|
3391 /**
|
|
|
3392 * Count the number of codepoints in a UTF-8 string.
|
|
|
3393 *
|
|
|
3394 * Counts the _codepoints_, not _bytes_, in `str`, excluding the null
|
|
|
3395 * terminator.
|
|
|
3396 *
|
|
|
3397 * If you need to count the bytes in a string instead, consider using
|
|
|
3398 * SDL_strlen().
|
|
|
3399 *
|
|
|
3400 * Since this handles Unicode, it expects the strings to be well-formed UTF-8
|
|
|
3401 * and not a null-terminated string of arbitrary bytes. Bytes that are not
|
|
|
3402 * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT
|
|
|
3403 * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the
|
|
|
3404 * count by several replacement characters.
|
|
|
3405 *
|
|
|
3406 * \param str The null-terminated UTF-8 string to read. Must not be NULL.
|
|
|
3407 * \returns The length (in codepoints, excluding the null terminator) of
|
|
|
3408 * `src`.
|
|
|
3409 *
|
|
|
3410 * \threadsafety It is safe to call this function from any thread.
|
|
|
3411 *
|
|
|
3412 * \since This function is available since SDL 3.2.0.
|
|
|
3413 *
|
|
|
3414 * \sa SDL_utf8strnlen
|
|
|
3415 * \sa SDL_strlen
|
|
|
3416 */
|
|
|
3417 extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str);
|
|
|
3418
|
|
|
3419 /**
|
|
|
3420 * Count the number of codepoints in a UTF-8 string, up to n bytes.
|
|
|
3421 *
|
|
|
3422 * Counts the _codepoints_, not _bytes_, in `str`, excluding the null
|
|
|
3423 * terminator.
|
|
|
3424 *
|
|
|
3425 * If you need to count the bytes in a string instead, consider using
|
|
|
3426 * SDL_strnlen().
|
|
|
3427 *
|
|
|
3428 * The counting stops at `bytes` bytes (not codepoints!). This seems
|
|
|
3429 * counterintuitive, but makes it easy to express the total size of the
|
|
|
3430 * string's buffer.
|
|
|
3431 *
|
|
|
3432 * Since this handles Unicode, it expects the strings to be well-formed UTF-8
|
|
|
3433 * and not a null-terminated string of arbitrary bytes. Bytes that are not
|
|
|
3434 * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT
|
|
|
3435 * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the
|
|
|
3436 * count by several replacement characters.
|
|
|
3437 *
|
|
|
3438 * \param str The null-terminated UTF-8 string to read. Must not be NULL.
|
|
|
3439 * \param bytes The maximum amount of bytes to count.
|
|
|
3440 * \returns The length (in codepoints, excluding the null terminator) of `src`
|
|
|
3441 * but never more than `maxlen`.
|
|
|
3442 *
|
|
|
3443 * \threadsafety It is safe to call this function from any thread.
|
|
|
3444 *
|
|
|
3445 * \since This function is available since SDL 3.2.0.
|
|
|
3446 *
|
|
|
3447 * \sa SDL_utf8strlen
|
|
|
3448 * \sa SDL_strnlen
|
|
|
3449 */
|
|
|
3450 extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes);
|
|
|
3451
|
|
|
3452 /**
|
|
|
3453 * Convert an integer into a string.
|
|
|
3454 *
|
|
|
3455 * This requires a radix to specified for string format. Specifying 10
|
|
|
3456 * produces a decimal number, 16 hexadecimal, etc. Must be in the range of 2
|
|
|
3457 * to 36.
|
|
|
3458 *
|
|
|
3459 * Note that this function will overflow a buffer if `str` is not large enough
|
|
|
3460 * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
|
|
|
3461 * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
|
|
|
3462 * much more space than you expect to use (and don't forget possible negative
|
|
|
3463 * signs, null terminator bytes, etc).
|
|
|
3464 *
|
|
|
3465 * \param value the integer to convert.
|
|
|
3466 * \param str the buffer to write the string into.
|
|
|
3467 * \param radix the radix to use for string generation.
|
|
|
3468 * \returns `str`.
|
|
|
3469 *
|
|
|
3470 * \threadsafety It is safe to call this function from any thread.
|
|
|
3471 *
|
|
|
3472 * \since This function is available since SDL 3.2.0.
|
|
|
3473 *
|
|
|
3474 * \sa SDL_uitoa
|
|
|
3475 * \sa SDL_ltoa
|
|
|
3476 * \sa SDL_lltoa
|
|
|
3477 */
|
|
|
3478 extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix);
|
|
|
3479
|
|
|
3480 /**
|
|
|
3481 * Convert an unsigned integer into a string.
|
|
|
3482 *
|
|
|
3483 * This requires a radix to specified for string format. Specifying 10
|
|
|
3484 * produces a decimal number, 16 hexadecimal, etc. Must be in the range of 2
|
|
|
3485 * to 36.
|
|
|
3486 *
|
|
|
3487 * Note that this function will overflow a buffer if `str` is not large enough
|
|
|
3488 * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
|
|
|
3489 * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
|
|
|
3490 * much more space than you expect to use (and don't forget null terminator
|
|
|
3491 * bytes, etc).
|
|
|
3492 *
|
|
|
3493 * \param value the unsigned integer to convert.
|
|
|
3494 * \param str the buffer to write the string into.
|
|
|
3495 * \param radix the radix to use for string generation.
|
|
|
3496 * \returns `str`.
|
|
|
3497 *
|
|
|
3498 * \threadsafety It is safe to call this function from any thread.
|
|
|
3499 *
|
|
|
3500 * \since This function is available since SDL 3.2.0.
|
|
|
3501 *
|
|
|
3502 * \sa SDL_itoa
|
|
|
3503 * \sa SDL_ultoa
|
|
|
3504 * \sa SDL_ulltoa
|
|
|
3505 */
|
|
|
3506 extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix);
|
|
|
3507
|
|
|
3508 /**
|
|
|
3509 * Convert a long integer into a string.
|
|
|
3510 *
|
|
|
3511 * This requires a radix to specified for string format. Specifying 10
|
|
|
3512 * produces a decimal number, 16 hexadecimal, etc. Must be in the range of 2
|
|
|
3513 * to 36.
|
|
|
3514 *
|
|
|
3515 * Note that this function will overflow a buffer if `str` is not large enough
|
|
|
3516 * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
|
|
|
3517 * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
|
|
|
3518 * much more space than you expect to use (and don't forget possible negative
|
|
|
3519 * signs, null terminator bytes, etc).
|
|
|
3520 *
|
|
|
3521 * \param value the long integer to convert.
|
|
|
3522 * \param str the buffer to write the string into.
|
|
|
3523 * \param radix the radix to use for string generation.
|
|
|
3524 * \returns `str`.
|
|
|
3525 *
|
|
|
3526 * \threadsafety It is safe to call this function from any thread.
|
|
|
3527 *
|
|
|
3528 * \since This function is available since SDL 3.2.0.
|
|
|
3529 *
|
|
|
3530 * \sa SDL_ultoa
|
|
|
3531 * \sa SDL_itoa
|
|
|
3532 * \sa SDL_lltoa
|
|
|
3533 */
|
|
|
3534 extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix);
|
|
|
3535
|
|
|
3536 /**
|
|
|
3537 * Convert an unsigned long integer into a string.
|
|
|
3538 *
|
|
|
3539 * This requires a radix to specified for string format. Specifying 10
|
|
|
3540 * produces a decimal number, 16 hexadecimal, etc. Must be in the range of 2
|
|
|
3541 * to 36.
|
|
|
3542 *
|
|
|
3543 * Note that this function will overflow a buffer if `str` is not large enough
|
|
|
3544 * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
|
|
|
3545 * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
|
|
|
3546 * much more space than you expect to use (and don't forget null terminator
|
|
|
3547 * bytes, etc).
|
|
|
3548 *
|
|
|
3549 * \param value the unsigned long integer to convert.
|
|
|
3550 * \param str the buffer to write the string into.
|
|
|
3551 * \param radix the radix to use for string generation.
|
|
|
3552 * \returns `str`.
|
|
|
3553 *
|
|
|
3554 * \threadsafety It is safe to call this function from any thread.
|
|
|
3555 *
|
|
|
3556 * \since This function is available since SDL 3.2.0.
|
|
|
3557 *
|
|
|
3558 * \sa SDL_ltoa
|
|
|
3559 * \sa SDL_uitoa
|
|
|
3560 * \sa SDL_ulltoa
|
|
|
3561 */
|
|
|
3562 extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix);
|
|
|
3563
|
|
|
3564 #ifndef SDL_NOLONGLONG
|
|
|
3565
|
|
|
3566 /**
|
|
|
3567 * Convert a long long integer into a string.
|
|
|
3568 *
|
|
|
3569 * This requires a radix to specified for string format. Specifying 10
|
|
|
3570 * produces a decimal number, 16 hexadecimal, etc. Must be in the range of 2
|
|
|
3571 * to 36.
|
|
|
3572 *
|
|
|
3573 * Note that this function will overflow a buffer if `str` is not large enough
|
|
|
3574 * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
|
|
|
3575 * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
|
|
|
3576 * much more space than you expect to use (and don't forget possible negative
|
|
|
3577 * signs, null terminator bytes, etc).
|
|
|
3578 *
|
|
|
3579 * \param value the long long integer to convert.
|
|
|
3580 * \param str the buffer to write the string into.
|
|
|
3581 * \param radix the radix to use for string generation.
|
|
|
3582 * \returns `str`.
|
|
|
3583 *
|
|
|
3584 * \threadsafety It is safe to call this function from any thread.
|
|
|
3585 *
|
|
|
3586 * \since This function is available since SDL 3.2.0.
|
|
|
3587 *
|
|
|
3588 * \sa SDL_ulltoa
|
|
|
3589 * \sa SDL_itoa
|
|
|
3590 * \sa SDL_ltoa
|
|
|
3591 */
|
|
|
3592 extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(long long value, char *str, int radix);
|
|
|
3593
|
|
|
3594 /**
|
|
|
3595 * Convert an unsigned long long integer into a string.
|
|
|
3596 *
|
|
|
3597 * This requires a radix to specified for string format. Specifying 10
|
|
|
3598 * produces a decimal number, 16 hexadecimal, etc. Must be in the range of 2
|
|
|
3599 * to 36.
|
|
|
3600 *
|
|
|
3601 * Note that this function will overflow a buffer if `str` is not large enough
|
|
|
3602 * to hold the output! It may be safer to use SDL_snprintf to clamp output, or
|
|
|
3603 * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate
|
|
|
3604 * much more space than you expect to use (and don't forget null terminator
|
|
|
3605 * bytes, etc).
|
|
|
3606 *
|
|
|
3607 * \param value the unsigned long long integer to convert.
|
|
|
3608 * \param str the buffer to write the string into.
|
|
|
3609 * \param radix the radix to use for string generation.
|
|
|
3610 * \returns `str`.
|
|
|
3611 *
|
|
|
3612 * \threadsafety It is safe to call this function from any thread.
|
|
|
3613 *
|
|
|
3614 * \since This function is available since SDL 3.2.0.
|
|
|
3615 *
|
|
|
3616 * \sa SDL_lltoa
|
|
|
3617 * \sa SDL_uitoa
|
|
|
3618 * \sa SDL_ultoa
|
|
|
3619 */
|
|
|
3620 extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *str, int radix);
|
|
|
3621 #endif
|
|
|
3622
|
|
|
3623 /**
|
|
|
3624 * Parse an `int` from a string.
|
|
|
3625 *
|
|
|
3626 * The result of calling `SDL_atoi(str)` is equivalent to
|
|
|
3627 * `(int)SDL_strtol(str, NULL, 10)`.
|
|
|
3628 *
|
|
|
3629 * \param str The null-terminated string to read. Must not be NULL.
|
|
|
3630 * \returns the parsed `int`.
|
|
|
3631 *
|
|
|
3632 * \threadsafety It is safe to call this function from any thread.
|
|
|
3633 *
|
|
|
3634 * \since This function is available since SDL 3.2.0.
|
|
|
3635 *
|
|
|
3636 * \sa SDL_atof
|
|
|
3637 * \sa SDL_strtol
|
|
|
3638 * \sa SDL_strtoul
|
|
|
3639 * \sa SDL_strtoll
|
|
|
3640 * \sa SDL_strtoull
|
|
|
3641 * \sa SDL_strtod
|
|
|
3642 * \sa SDL_itoa
|
|
|
3643 */
|
|
|
3644 extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str);
|
|
|
3645
|
|
|
3646 /**
|
|
|
3647 * Parse a `double` from a string.
|
|
|
3648 *
|
|
|
3649 * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str,
|
|
|
3650 * NULL)`.
|
|
|
3651 *
|
|
|
3652 * \param str The null-terminated string to read. Must not be NULL.
|
|
|
3653 * \returns the parsed `double`.
|
|
|
3654 *
|
|
|
3655 * \threadsafety It is safe to call this function from any thread.
|
|
|
3656 *
|
|
|
3657 * \since This function is available since SDL 3.2.0.
|
|
|
3658 *
|
|
|
3659 * \sa SDL_atoi
|
|
|
3660 * \sa SDL_strtol
|
|
|
3661 * \sa SDL_strtoul
|
|
|
3662 * \sa SDL_strtoll
|
|
|
3663 * \sa SDL_strtoull
|
|
|
3664 * \sa SDL_strtod
|
|
|
3665 */
|
|
|
3666 extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str);
|
|
|
3667
|
|
|
3668 /**
|
|
|
3669 * Parse a `long` from a string.
|
|
|
3670 *
|
|
|
3671 * If `str` starts with whitespace, then those whitespace characters are
|
|
|
3672 * skipped before attempting to parse the number.
|
|
|
3673 *
|
|
|
3674 * If the parsed number does not fit inside a `long`, the result is clamped to
|
|
|
3675 * the minimum and maximum representable `long` values.
|
|
|
3676 *
|
|
|
3677 * \param str The null-terminated string to read. Must not be NULL.
|
|
|
3678 * \param endp If not NULL, the address of the first invalid character (i.e.
|
|
|
3679 * the next character after the parsed number) will be written to
|
|
|
3680 * this pointer.
|
|
|
3681 * \param base The base of the integer to read. Supported values are 0 and 2
|
|
|
3682 * to 36 inclusive. If 0, the base will be inferred from the
|
|
|
3683 * number's prefix (0x for hexadecimal, 0 for octal, decimal
|
|
|
3684 * otherwise).
|
|
|
3685 * \returns the parsed `long`, or 0 if no number could be parsed.
|
|
|
3686 *
|
|
|
3687 * \threadsafety It is safe to call this function from any thread.
|
|
|
3688 *
|
|
|
3689 * \since This function is available since SDL 3.2.0.
|
|
|
3690 *
|
|
|
3691 * \sa SDL_atoi
|
|
|
3692 * \sa SDL_atof
|
|
|
3693 * \sa SDL_strtoul
|
|
|
3694 * \sa SDL_strtoll
|
|
|
3695 * \sa SDL_strtoull
|
|
|
3696 * \sa SDL_strtod
|
|
|
3697 * \sa SDL_ltoa
|
|
|
3698 * \sa SDL_wcstol
|
|
|
3699 */
|
|
|
3700 extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base);
|
|
|
3701
|
|
|
3702 /**
|
|
|
3703 * Parse an `unsigned long` from a string.
|
|
|
3704 *
|
|
|
3705 * If `str` starts with whitespace, then those whitespace characters are
|
|
|
3706 * skipped before attempting to parse the number.
|
|
|
3707 *
|
|
|
3708 * If the parsed number does not fit inside an `unsigned long`, the result is
|
|
|
3709 * clamped to the maximum representable `unsigned long` value.
|
|
|
3710 *
|
|
|
3711 * \param str The null-terminated string to read. Must not be NULL.
|
|
|
3712 * \param endp If not NULL, the address of the first invalid character (i.e.
|
|
|
3713 * the next character after the parsed number) will be written to
|
|
|
3714 * this pointer.
|
|
|
3715 * \param base The base of the integer to read. Supported values are 0 and 2
|
|
|
3716 * to 36 inclusive. If 0, the base will be inferred from the
|
|
|
3717 * number's prefix (0x for hexadecimal, 0 for octal, decimal
|
|
|
3718 * otherwise).
|
|
|
3719 * \returns the parsed `unsigned long`, or 0 if no number could be parsed.
|
|
|
3720 *
|
|
|
3721 * \threadsafety It is safe to call this function from any thread.
|
|
|
3722 *
|
|
|
3723 * \since This function is available since SDL 3.2.0.
|
|
|
3724 *
|
|
|
3725 * \sa SDL_atoi
|
|
|
3726 * \sa SDL_atof
|
|
|
3727 * \sa SDL_strtol
|
|
|
3728 * \sa SDL_strtoll
|
|
|
3729 * \sa SDL_strtoull
|
|
|
3730 * \sa SDL_strtod
|
|
|
3731 * \sa SDL_ultoa
|
|
|
3732 */
|
|
|
3733 extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base);
|
|
|
3734
|
|
|
3735 #ifndef SDL_NOLONGLONG
|
|
|
3736
|
|
|
3737 /**
|
|
|
3738 * Parse a `long long` from a string.
|
|
|
3739 *
|
|
|
3740 * If `str` starts with whitespace, then those whitespace characters are
|
|
|
3741 * skipped before attempting to parse the number.
|
|
|
3742 *
|
|
|
3743 * If the parsed number does not fit inside a `long long`, the result is
|
|
|
3744 * clamped to the minimum and maximum representable `long long` values.
|
|
|
3745 *
|
|
|
3746 * \param str The null-terminated string to read. Must not be NULL.
|
|
|
3747 * \param endp If not NULL, the address of the first invalid character (i.e.
|
|
|
3748 * the next character after the parsed number) will be written to
|
|
|
3749 * this pointer.
|
|
|
3750 * \param base The base of the integer to read. Supported values are 0 and 2
|
|
|
3751 * to 36 inclusive. If 0, the base will be inferred from the
|
|
|
3752 * number's prefix (0x for hexadecimal, 0 for octal, decimal
|
|
|
3753 * otherwise).
|
|
|
3754 * \returns the parsed `long long`, or 0 if no number could be parsed.
|
|
|
3755 *
|
|
|
3756 * \threadsafety It is safe to call this function from any thread.
|
|
|
3757 *
|
|
|
3758 * \since This function is available since SDL 3.2.0.
|
|
|
3759 *
|
|
|
3760 * \sa SDL_atoi
|
|
|
3761 * \sa SDL_atof
|
|
|
3762 * \sa SDL_strtol
|
|
|
3763 * \sa SDL_strtoul
|
|
|
3764 * \sa SDL_strtoull
|
|
|
3765 * \sa SDL_strtod
|
|
|
3766 * \sa SDL_lltoa
|
|
|
3767 */
|
|
|
3768 extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, int base);
|
|
|
3769
|
|
|
3770 /**
|
|
|
3771 * Parse an `unsigned long long` from a string.
|
|
|
3772 *
|
|
|
3773 * If `str` starts with whitespace, then those whitespace characters are
|
|
|
3774 * skipped before attempting to parse the number.
|
|
|
3775 *
|
|
|
3776 * If the parsed number does not fit inside an `unsigned long long`, the
|
|
|
3777 * result is clamped to the maximum representable `unsigned long long` value.
|
|
|
3778 *
|
|
|
3779 * \param str The null-terminated string to read. Must not be NULL.
|
|
|
3780 * \param endp If not NULL, the address of the first invalid character (i.e.
|
|
|
3781 * the next character after the parsed number) will be written to
|
|
|
3782 * this pointer.
|
|
|
3783 * \param base The base of the integer to read. Supported values are 0 and 2
|
|
|
3784 * to 36 inclusive. If 0, the base will be inferred from the
|
|
|
3785 * number's prefix (0x for hexadecimal, 0 for octal, decimal
|
|
|
3786 * otherwise).
|
|
|
3787 * \returns the parsed `unsigned long long`, or 0 if no number could be
|
|
|
3788 * parsed.
|
|
|
3789 *
|
|
|
3790 * \threadsafety It is safe to call this function from any thread.
|
|
|
3791 *
|
|
|
3792 * \since This function is available since SDL 3.2.0.
|
|
|
3793 *
|
|
|
3794 * \sa SDL_atoi
|
|
|
3795 * \sa SDL_atof
|
|
|
3796 * \sa SDL_strtol
|
|
|
3797 * \sa SDL_strtoll
|
|
|
3798 * \sa SDL_strtoul
|
|
|
3799 * \sa SDL_strtod
|
|
|
3800 * \sa SDL_ulltoa
|
|
|
3801 */
|
|
|
3802 extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, char **endp, int base);
|
|
|
3803 #endif
|
|
|
3804
|
|
|
3805 /**
|
|
|
3806 * Parse a `double` from a string.
|
|
|
3807 *
|
|
|
3808 * This function makes fewer guarantees than the C runtime `strtod`:
|
|
|
3809 *
|
|
|
3810 * - Only decimal notation is guaranteed to be supported. The handling of
|
|
|
3811 * scientific and hexadecimal notation is unspecified.
|
|
|
3812 * - Whether or not INF and NAN can be parsed is unspecified.
|
|
|
3813 * - The precision of the result is unspecified.
|
|
|
3814 *
|
|
|
3815 * \param str the null-terminated string to read. Must not be NULL.
|
|
|
3816 * \param endp if not NULL, the address of the first invalid character (i.e.
|
|
|
3817 * the next character after the parsed number) will be written to
|
|
|
3818 * this pointer.
|
|
|
3819 * \returns the parsed `double`, or 0 if no number could be parsed.
|
|
|
3820 *
|
|
|
3821 * \threadsafety It is safe to call this function from any thread.
|
|
|
3822 *
|
|
|
3823 * \since This function is available since SDL 3.2.0.
|
|
|
3824 *
|
|
|
3825 * \sa SDL_atoi
|
|
|
3826 * \sa SDL_atof
|
|
|
3827 * \sa SDL_strtol
|
|
|
3828 * \sa SDL_strtoll
|
|
|
3829 * \sa SDL_strtoul
|
|
|
3830 * \sa SDL_strtoull
|
|
|
3831 */
|
|
|
3832 extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp);
|
|
|
3833
|
|
|
3834 /**
|
|
|
3835 * Compare two null-terminated UTF-8 strings.
|
|
|
3836 *
|
|
|
3837 * Due to the nature of UTF-8 encoding, this will work with Unicode strings,
|
|
|
3838 * since effectively this function just compares bytes until it hits a
|
|
|
3839 * null-terminating character. Also due to the nature of UTF-8, this can be
|
|
|
3840 * used with SDL_qsort() to put strings in (roughly) alphabetical order.
|
|
|
3841 *
|
|
|
3842 * \param str1 the first string to compare. NULL is not permitted!
|
|
|
3843 * \param str2 the second string to compare. NULL is not permitted!
|
|
|
3844 * \returns less than zero if str1 is "less than" str2, greater than zero if
|
|
|
3845 * str1 is "greater than" str2, and zero if the strings match
|
|
|
3846 * exactly.
|
|
|
3847 *
|
|
|
3848 * \threadsafety It is safe to call this function from any thread.
|
|
|
3849 *
|
|
|
3850 * \since This function is available since SDL 3.2.0.
|
|
|
3851 */
|
|
|
3852 extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2);
|
|
|
3853
|
|
|
3854 /**
|
|
|
3855 * Compare two UTF-8 strings up to a number of bytes.
|
|
|
3856 *
|
|
|
3857 * Due to the nature of UTF-8 encoding, this will work with Unicode strings,
|
|
|
3858 * since effectively this function just compares bytes until it hits a
|
|
|
3859 * null-terminating character. Also due to the nature of UTF-8, this can be
|
|
|
3860 * used with SDL_qsort() to put strings in (roughly) alphabetical order.
|
|
|
3861 *
|
|
|
3862 * Note that while this function is intended to be used with UTF-8, it is
|
|
|
3863 * doing a bytewise comparison, and `maxlen` specifies a _byte_ limit! If the
|
|
|
3864 * limit lands in the middle of a multi-byte UTF-8 sequence, it will only
|
|
|
3865 * compare a portion of the final character.
|
|
|
3866 *
|
|
|
3867 * `maxlen` specifies a maximum number of bytes to compare; if the strings
|
|
|
3868 * match to this number of bytes (or both have matched to a null-terminator
|
|
|
3869 * character before this number of bytes), they will be considered equal.
|
|
|
3870 *
|
|
|
3871 * \param str1 the first string to compare. NULL is not permitted!
|
|
|
3872 * \param str2 the second string to compare. NULL is not permitted!
|
|
|
3873 * \param maxlen the maximum number of _bytes_ to compare.
|
|
|
3874 * \returns less than zero if str1 is "less than" str2, greater than zero if
|
|
|
3875 * str1 is "greater than" str2, and zero if the strings match
|
|
|
3876 * exactly.
|
|
|
3877 *
|
|
|
3878 * \threadsafety It is safe to call this function from any thread.
|
|
|
3879 *
|
|
|
3880 * \since This function is available since SDL 3.2.0.
|
|
|
3881 */
|
|
|
3882 extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, size_t maxlen);
|
|
|
3883
|
|
|
3884 /**
|
|
|
3885 * Compare two null-terminated UTF-8 strings, case-insensitively.
|
|
|
3886 *
|
|
|
3887 * This will work with Unicode strings, using a technique called
|
|
|
3888 * "case-folding" to handle the vast majority of case-sensitive human
|
|
|
3889 * languages regardless of system locale. It can deal with expanding values: a
|
|
|
3890 * German Eszett character can compare against two ASCII 's' chars and be
|
|
|
3891 * considered a match, for example. A notable exception: it does not handle
|
|
|
3892 * the Turkish 'i' character; human language is complicated!
|
|
|
3893 *
|
|
|
3894 * Since this handles Unicode, it expects the string to be well-formed UTF-8
|
|
|
3895 * and not a null-terminated string of arbitrary bytes. Bytes that are not
|
|
|
3896 * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT
|
|
|
3897 * CHARACTER), which is to say two strings of random bits may turn out to
|
|
|
3898 * match if they convert to the same amount of replacement characters.
|
|
|
3899 *
|
|
|
3900 * \param str1 the first string to compare. NULL is not permitted!
|
|
|
3901 * \param str2 the second string to compare. NULL is not permitted!
|
|
|
3902 * \returns less than zero if str1 is "less than" str2, greater than zero if
|
|
|
3903 * str1 is "greater than" str2, and zero if the strings match
|
|
|
3904 * exactly.
|
|
|
3905 *
|
|
|
3906 * \threadsafety It is safe to call this function from any thread.
|
|
|
3907 *
|
|
|
3908 * \since This function is available since SDL 3.2.0.
|
|
|
3909 */
|
|
|
3910 extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2);
|
|
|
3911
|
|
|
3912
|
|
|
3913 /**
|
|
|
3914 * Compare two UTF-8 strings, case-insensitively, up to a number of bytes.
|
|
|
3915 *
|
|
|
3916 * This will work with Unicode strings, using a technique called
|
|
|
3917 * "case-folding" to handle the vast majority of case-sensitive human
|
|
|
3918 * languages regardless of system locale. It can deal with expanding values: a
|
|
|
3919 * German Eszett character can compare against two ASCII 's' chars and be
|
|
|
3920 * considered a match, for example. A notable exception: it does not handle
|
|
|
3921 * the Turkish 'i' character; human language is complicated!
|
|
|
3922 *
|
|
|
3923 * Since this handles Unicode, it expects the string to be well-formed UTF-8
|
|
|
3924 * and not a null-terminated string of arbitrary bytes. Bytes that are not
|
|
|
3925 * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT
|
|
|
3926 * CHARACTER), which is to say two strings of random bits may turn out to
|
|
|
3927 * match if they convert to the same amount of replacement characters.
|
|
|
3928 *
|
|
|
3929 * Note that while this function is intended to be used with UTF-8, `maxlen`
|
|
|
3930 * specifies a _byte_ limit! If the limit lands in the middle of a multi-byte
|
|
|
3931 * UTF-8 sequence, it may convert a portion of the final character to one or
|
|
|
3932 * more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not to overflow
|
|
|
3933 * a buffer.
|
|
|
3934 *
|
|
|
3935 * `maxlen` specifies a maximum number of bytes to compare; if the strings
|
|
|
3936 * match to this number of bytes (or both have matched to a null-terminator
|
|
|
3937 * character before this number of bytes), they will be considered equal.
|
|
|
3938 *
|
|
|
3939 * \param str1 the first string to compare. NULL is not permitted!
|
|
|
3940 * \param str2 the second string to compare. NULL is not permitted!
|
|
|
3941 * \param maxlen the maximum number of bytes to compare.
|
|
|
3942 * \returns less than zero if str1 is "less than" str2, greater than zero if
|
|
|
3943 * str1 is "greater than" str2, and zero if the strings match
|
|
|
3944 * exactly.
|
|
|
3945 *
|
|
|
3946 * \threadsafety It is safe to call this function from any thread.
|
|
|
3947 *
|
|
|
3948 * \since This function is available since SDL 3.2.0.
|
|
|
3949 */
|
|
|
3950 extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen);
|
|
|
3951
|
|
|
3952 /**
|
|
|
3953 * Searches a string for the first occurrence of any character contained in a
|
|
|
3954 * breakset, and returns a pointer from the string to that character.
|
|
|
3955 *
|
|
|
3956 * \param str The null-terminated string to be searched. Must not be NULL, and
|
|
|
3957 * must not overlap with `breakset`.
|
|
|
3958 * \param breakset A null-terminated string containing the list of characters
|
|
|
3959 * to look for. Must not be NULL, and must not overlap with
|
|
|
3960 * `str`.
|
|
|
3961 * \returns A pointer to the location, in str, of the first occurrence of a
|
|
|
3962 * character present in the breakset, or NULL if none is found.
|
|
|
3963 *
|
|
|
3964 * \threadsafety It is safe to call this function from any thread.
|
|
|
3965 *
|
|
|
3966 * \since This function is available since SDL 3.2.0.
|
|
|
3967 */
|
|
|
3968 extern SDL_DECLSPEC char * SDLCALL SDL_strpbrk(const char *str, const char *breakset);
|
|
|
3969
|
|
|
3970 /**
|
|
|
3971 * The Unicode REPLACEMENT CHARACTER codepoint.
|
|
|
3972 *
|
|
|
3973 * SDL_StepUTF8() and SDL_StepBackUTF8() report this codepoint when they
|
|
|
3974 * encounter a UTF-8 string with encoding errors.
|
|
|
3975 *
|
|
|
3976 * This tends to render as something like a question mark in most places.
|
|
|
3977 *
|
|
|
3978 * \since This macro is available since SDL 3.2.0.
|
|
|
3979 *
|
|
|
3980 * \sa SDL_StepBackUTF8
|
|
|
3981 * \sa SDL_StepUTF8
|
|
|
3982 */
|
|
|
3983 #define SDL_INVALID_UNICODE_CODEPOINT 0xFFFD
|
|
|
3984
|
|
|
3985 /**
|
|
|
3986 * Decode a UTF-8 string, one Unicode codepoint at a time.
|
|
|
3987 *
|
|
|
3988 * This will return the first Unicode codepoint in the UTF-8 encoded string in
|
|
|
3989 * `*pstr`, and then advance `*pstr` past any consumed bytes before returning.
|
|
|
3990 *
|
|
|
3991 * It will not access more than `*pslen` bytes from the string. `*pslen` will
|
|
|
3992 * be adjusted, as well, subtracting the number of bytes consumed.
|
|
|
3993 *
|
|
|
3994 * `pslen` is allowed to be NULL, in which case the string _must_ be
|
|
|
3995 * NULL-terminated, as the function will blindly read until it sees the NULL
|
|
|
3996 * char.
|
|
|
3997 *
|
|
|
3998 * if `*pslen` is zero, it assumes the end of string is reached and returns a
|
|
|
3999 * zero codepoint regardless of the contents of the string buffer.
|
|
|
4000 *
|
|
|
4001 * If the resulting codepoint is zero (a NULL terminator), or `*pslen` is
|
|
|
4002 * zero, it will not advance `*pstr` or `*pslen` at all.
|
|
|
4003 *
|
|
|
4004 * Generally this function is called in a loop until it returns zero,
|
|
|
4005 * adjusting its parameters each iteration.
|
|
|
4006 *
|
|
|
4007 * If an invalid UTF-8 sequence is encountered, this function returns
|
|
|
4008 * SDL_INVALID_UNICODE_CODEPOINT and advances the string/length by one byte
|
|
|
4009 * (which is to say, a multibyte sequence might produce several
|
|
|
4010 * SDL_INVALID_UNICODE_CODEPOINT returns before it syncs to the next valid
|
|
|
4011 * UTF-8 sequence).
|
|
|
4012 *
|
|
|
4013 * Several things can generate invalid UTF-8 sequences, including overlong
|
|
|
4014 * encodings, the use of UTF-16 surrogate values, and truncated data. Please
|
|
|
4015 * refer to
|
|
|
4016 * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt)
|
|
|
4017 * for details.
|
|
|
4018 *
|
|
|
4019 * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted.
|
|
|
4020 * \param pslen a pointer to the number of bytes in the string, to be read and
|
|
|
4021 * adjusted. NULL is allowed.
|
|
|
4022 * \returns the first Unicode codepoint in the string.
|
|
|
4023 *
|
|
|
4024 * \threadsafety It is safe to call this function from any thread.
|
|
|
4025 *
|
|
|
4026 * \since This function is available since SDL 3.2.0.
|
|
|
4027 */
|
|
|
4028 extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen);
|
|
|
4029
|
|
|
4030 /**
|
|
|
4031 * Decode a UTF-8 string in reverse, one Unicode codepoint at a time.
|
|
|
4032 *
|
|
|
4033 * This will go to the start of the previous Unicode codepoint in the string,
|
|
|
4034 * move `*pstr` to that location and return that codepoint.
|
|
|
4035 *
|
|
|
4036 * If `*pstr` is already at the start of the string), it will not advance
|
|
|
4037 * `*pstr` at all.
|
|
|
4038 *
|
|
|
4039 * Generally this function is called in a loop until it returns zero,
|
|
|
4040 * adjusting its parameter each iteration.
|
|
|
4041 *
|
|
|
4042 * If an invalid UTF-8 sequence is encountered, this function returns
|
|
|
4043 * SDL_INVALID_UNICODE_CODEPOINT.
|
|
|
4044 *
|
|
|
4045 * Several things can generate invalid UTF-8 sequences, including overlong
|
|
|
4046 * encodings, the use of UTF-16 surrogate values, and truncated data. Please
|
|
|
4047 * refer to
|
|
|
4048 * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt)
|
|
|
4049 * for details.
|
|
|
4050 *
|
|
|
4051 * \param start a pointer to the beginning of the UTF-8 string.
|
|
|
4052 * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted.
|
|
|
4053 * \returns the previous Unicode codepoint in the string.
|
|
|
4054 *
|
|
|
4055 * \threadsafety It is safe to call this function from any thread.
|
|
|
4056 *
|
|
|
4057 * \since This function is available since SDL 3.2.0.
|
|
|
4058 */
|
|
|
4059 extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepBackUTF8(const char *start, const char **pstr);
|
|
|
4060
|
|
|
4061 /**
|
|
|
4062 * Convert a single Unicode codepoint to UTF-8.
|
|
|
4063 *
|
|
|
4064 * The buffer pointed to by `dst` must be at least 4 bytes long, as this
|
|
|
4065 * function may generate between 1 and 4 bytes of output.
|
|
|
4066 *
|
|
|
4067 * This function returns the first byte _after_ the newly-written UTF-8
|
|
|
4068 * sequence, which is useful for encoding multiple codepoints in a loop, or
|
|
|
4069 * knowing where to write a NULL-terminator character to end the string (in
|
|
|
4070 * either case, plan to have a buffer of _more_ than 4 bytes!).
|
|
|
4071 *
|
|
|
4072 * If `codepoint` is an invalid value (outside the Unicode range, or a UTF-16
|
|
|
4073 * surrogate value, etc), this will use U+FFFD (REPLACEMENT CHARACTER) for the
|
|
|
4074 * codepoint instead, and not set an error.
|
|
|
4075 *
|
|
|
4076 * If `dst` is NULL, this returns NULL immediately without writing to the
|
|
|
4077 * pointer and without setting an error.
|
|
|
4078 *
|
|
|
4079 * \param codepoint a Unicode codepoint to convert to UTF-8.
|
|
|
4080 * \param dst the location to write the encoded UTF-8. Must point to at least
|
|
|
4081 * 4 bytes!
|
|
|
4082 * \returns the first byte past the newly-written UTF-8 sequence.
|
|
|
4083 *
|
|
|
4084 * \threadsafety It is safe to call this function from any thread.
|
|
|
4085 *
|
|
|
4086 * \since This function is available since SDL 3.2.0.
|
|
|
4087 */
|
|
|
4088 extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst);
|
|
|
4089
|
|
|
4090 /**
|
|
|
4091 * This works exactly like sscanf() but doesn't require access to a C runtime.
|
|
|
4092 *
|
|
|
4093 * Scan a string, matching a format string, converting each '%' item and
|
|
|
4094 * storing it to pointers provided through variable arguments.
|
|
|
4095 *
|
|
|
4096 * \param text the string to scan. Must not be NULL.
|
|
|
4097 * \param fmt a printf-style format string. Must not be NULL.
|
|
|
4098 * \param ... a list of pointers to values to be filled in with scanned items.
|
|
|
4099 * \returns the number of items that matched the format string.
|
|
|
4100 *
|
|
|
4101 * \threadsafety It is safe to call this function from any thread.
|
|
|
4102 *
|
|
|
4103 * \since This function is available since SDL 3.2.0.
|
|
|
4104 */
|
|
|
4105 extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2);
|
|
|
4106
|
|
|
4107 /**
|
|
|
4108 * This works exactly like vsscanf() but doesn't require access to a C
|
|
|
4109 * runtime.
|
|
|
4110 *
|
|
|
4111 * Functions identically to SDL_sscanf(), except it takes a `va_list` instead
|
|
|
4112 * of using `...` variable arguments.
|
|
|
4113 *
|
|
|
4114 * \param text the string to scan. Must not be NULL.
|
|
|
4115 * \param fmt a printf-style format string. Must not be NULL.
|
|
|
4116 * \param ap a `va_list` of pointers to values to be filled in with scanned
|
|
|
4117 * items.
|
|
|
4118 * \returns the number of items that matched the format string.
|
|
|
4119 *
|
|
|
4120 * \threadsafety It is safe to call this function from any thread.
|
|
|
4121 *
|
|
|
4122 * \since This function is available since SDL 3.2.0.
|
|
|
4123 */
|
|
|
4124 extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2);
|
|
|
4125
|
|
|
4126 /**
|
|
|
4127 * This works exactly like snprintf() but doesn't require access to a C
|
|
|
4128 * runtime.
|
|
|
4129 *
|
|
|
4130 * Format a string of up to `maxlen`-1 bytes, converting each '%' item with
|
|
|
4131 * values provided through variable arguments.
|
|
|
4132 *
|
|
|
4133 * While some C runtimes differ on how to deal with too-large strings, this
|
|
|
4134 * function null-terminates the output, by treating the null-terminator as
|
|
|
4135 * part of the `maxlen` count. Note that if `maxlen` is zero, however, no
|
|
|
4136 * bytes will be written at all.
|
|
|
4137 *
|
|
|
4138 * This function returns the number of _bytes_ (not _characters_) that should
|
|
|
4139 * be written, excluding the null-terminator character. If this returns a
|
|
|
4140 * number >= `maxlen`, it means the output string was truncated. A negative
|
|
|
4141 * return value means an error occurred.
|
|
|
4142 *
|
|
|
4143 * Referencing the output string's pointer with a format item is undefined
|
|
|
4144 * behavior.
|
|
|
4145 *
|
|
|
4146 * \param text the buffer to write the string into. Must not be NULL.
|
|
|
4147 * \param maxlen the maximum bytes to write, including the null-terminator.
|
|
|
4148 * \param fmt a printf-style format string. Must not be NULL.
|
|
|
4149 * \param ... a list of values to be used with the format string.
|
|
|
4150 * \returns the number of bytes that should be written, not counting the
|
|
|
4151 * null-terminator char, or a negative value on error.
|
|
|
4152 *
|
|
|
4153 * \threadsafety It is safe to call this function from any thread.
|
|
|
4154 *
|
|
|
4155 * \since This function is available since SDL 3.2.0.
|
|
|
4156 */
|
|
|
4157 extern 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);
|
|
|
4158
|
|
|
4159 /**
|
|
|
4160 * This works exactly like swprintf() but doesn't require access to a C
|
|
|
4161 * runtime.
|
|
|
4162 *
|
|
|
4163 * Format a wide string of up to `maxlen`-1 wchar_t values, converting each
|
|
|
4164 * '%' item with values provided through variable arguments.
|
|
|
4165 *
|
|
|
4166 * While some C runtimes differ on how to deal with too-large strings, this
|
|
|
4167 * function null-terminates the output, by treating the null-terminator as
|
|
|
4168 * part of the `maxlen` count. Note that if `maxlen` is zero, however, no wide
|
|
|
4169 * characters will be written at all.
|
|
|
4170 *
|
|
|
4171 * This function returns the number of _wide characters_ (not _codepoints_)
|
|
|
4172 * that should be written, excluding the null-terminator character. If this
|
|
|
4173 * returns a number >= `maxlen`, it means the output string was truncated. A
|
|
|
4174 * negative return value means an error occurred.
|
|
|
4175 *
|
|
|
4176 * Referencing the output string's pointer with a format item is undefined
|
|
|
4177 * behavior.
|
|
|
4178 *
|
|
|
4179 * \param text the buffer to write the wide string into. Must not be NULL.
|
|
|
4180 * \param maxlen the maximum wchar_t values to write, including the
|
|
|
4181 * null-terminator.
|
|
|
4182 * \param fmt a printf-style format string. Must not be NULL.
|
|
|
4183 * \param ... a list of values to be used with the format string.
|
|
|
4184 * \returns the number of wide characters that should be written, not counting
|
|
|
4185 * the null-terminator char, or a negative value on error.
|
|
|
4186 *
|
|
|
4187 * \threadsafety It is safe to call this function from any thread.
|
|
|
4188 *
|
|
|
4189 * \since This function is available since SDL 3.2.0.
|
|
|
4190 */
|
|
|
4191 extern 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);
|
|
|
4192
|
|
|
4193 /**
|
|
|
4194 * This works exactly like vsnprintf() but doesn't require access to a C
|
|
|
4195 * runtime.
|
|
|
4196 *
|
|
|
4197 * Functions identically to SDL_snprintf(), except it takes a `va_list`
|
|
|
4198 * instead of using `...` variable arguments.
|
|
|
4199 *
|
|
|
4200 * \param text the buffer to write the string into. Must not be NULL.
|
|
|
4201 * \param maxlen the maximum bytes to write, including the null-terminator.
|
|
|
4202 * \param fmt a printf-style format string. Must not be NULL.
|
|
|
4203 * \param ap a `va_list` values to be used with the format string.
|
|
|
4204 * \returns the number of bytes that should be written, not counting the
|
|
|
4205 * null-terminator char, or a negative value on error.
|
|
|
4206 *
|
|
|
4207 * \threadsafety It is safe to call this function from any thread.
|
|
|
4208 *
|
|
|
4209 * \since This function is available since SDL 3.2.0.
|
|
|
4210 */
|
|
|
4211 extern 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);
|
|
|
4212
|
|
|
4213 /**
|
|
|
4214 * This works exactly like vswprintf() but doesn't require access to a C
|
|
|
4215 * runtime.
|
|
|
4216 *
|
|
|
4217 * Functions identically to SDL_swprintf(), except it takes a `va_list`
|
|
|
4218 * instead of using `...` variable arguments.
|
|
|
4219 *
|
|
|
4220 * \param text the buffer to write the string into. Must not be NULL.
|
|
|
4221 * \param maxlen the maximum wide characters to write, including the
|
|
|
4222 * null-terminator.
|
|
|
4223 * \param fmt a printf-style format wide string. Must not be NULL.
|
|
|
4224 * \param ap a `va_list` values to be used with the format string.
|
|
|
4225 * \returns the number of wide characters that should be written, not counting
|
|
|
4226 * the null-terminator char, or a negative value on error.
|
|
|
4227 *
|
|
|
4228 * \threadsafety It is safe to call this function from any thread.
|
|
|
4229 *
|
|
|
4230 * \since This function is available since SDL 3.2.0.
|
|
|
4231 */
|
|
|
4232 extern 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);
|
|
|
4233
|
|
|
4234 /**
|
|
|
4235 * This works exactly like asprintf() but doesn't require access to a C
|
|
|
4236 * runtime.
|
|
|
4237 *
|
|
|
4238 * Functions identically to SDL_snprintf(), except it allocates a buffer large
|
|
|
4239 * enough to hold the output string on behalf of the caller.
|
|
|
4240 *
|
|
|
4241 * On success, this function returns the number of bytes (not characters)
|
|
|
4242 * comprising the output string, not counting the null-terminator character,
|
|
|
4243 * and sets `*strp` to the newly-allocated string.
|
|
|
4244 *
|
|
|
4245 * On error, this function returns a negative number, and the value of `*strp`
|
|
|
4246 * is undefined.
|
|
|
4247 *
|
|
|
4248 * The returned string is owned by the caller, and should be passed to
|
|
|
4249 * SDL_free when no longer needed.
|
|
|
4250 *
|
|
|
4251 * \param strp on output, is set to the new string. Must not be NULL.
|
|
|
4252 * \param fmt a printf-style format string. Must not be NULL.
|
|
|
4253 * \param ... a list of values to be used with the format string.
|
|
|
4254 * \returns the number of bytes in the newly-allocated string, not counting
|
|
|
4255 * the null-terminator char, or a negative value on error.
|
|
|
4256 *
|
|
|
4257 * \threadsafety It is safe to call this function from any thread.
|
|
|
4258 *
|
|
|
4259 * \since This function is available since SDL 3.2.0.
|
|
|
4260 */
|
|
|
4261 extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
|
|
|
4262
|
|
|
4263 /**
|
|
|
4264 * This works exactly like vasprintf() but doesn't require access to a C
|
|
|
4265 * runtime.
|
|
|
4266 *
|
|
|
4267 * Functions identically to SDL_asprintf(), except it takes a `va_list`
|
|
|
4268 * instead of using `...` variable arguments.
|
|
|
4269 *
|
|
|
4270 * \param strp on output, is set to the new string. Must not be NULL.
|
|
|
4271 * \param fmt a printf-style format string. Must not be NULL.
|
|
|
4272 * \param ap a `va_list` values to be used with the format string.
|
|
|
4273 * \returns the number of bytes in the newly-allocated string, not counting
|
|
|
4274 * the null-terminator char, or a negative value on error.
|
|
|
4275 *
|
|
|
4276 * \threadsafety It is safe to call this function from any thread.
|
|
|
4277 *
|
|
|
4278 * \since This function is available since SDL 3.2.0.
|
|
|
4279 */
|
|
|
4280 extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
|
|
|
4281
|
|
|
4282 /**
|
|
|
4283 * Seeds the pseudo-random number generator.
|
|
|
4284 *
|
|
|
4285 * Reusing the seed number will cause SDL_rand() to repeat the same stream of
|
|
|
4286 * 'random' numbers.
|
|
|
4287 *
|
|
|
4288 * \param seed the value to use as a random number seed, or 0 to use
|
|
|
4289 * SDL_GetPerformanceCounter().
|
|
|
4290 *
|
|
|
4291 * \threadsafety This should be called on the same thread that calls
|
|
|
4292 * SDL_rand()
|
|
|
4293 *
|
|
|
4294 * \since This function is available since SDL 3.2.0.
|
|
|
4295 *
|
|
|
4296 * \sa SDL_rand
|
|
|
4297 * \sa SDL_rand_bits
|
|
|
4298 * \sa SDL_randf
|
|
|
4299 */
|
|
|
4300 extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed);
|
|
|
4301
|
|
|
4302 /**
|
|
|
4303 * Generate a pseudo-random number less than n for positive n
|
|
|
4304 *
|
|
|
4305 * The method used is faster and of better quality than `rand() % n`. Odds are
|
|
|
4306 * roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and
|
|
|
4307 * much worse as n gets bigger.
|
|
|
4308 *
|
|
|
4309 * Example: to simulate a d6 use `SDL_rand(6) + 1` The +1 converts 0..5 to
|
|
|
4310 * 1..6
|
|
|
4311 *
|
|
|
4312 * If you want to generate a pseudo-random number in the full range of Sint32,
|
|
|
4313 * you should use: (Sint32)SDL_rand_bits()
|
|
|
4314 *
|
|
|
4315 * If you want reproducible output, be sure to initialize with SDL_srand()
|
|
|
4316 * first.
|
|
|
4317 *
|
|
|
4318 * There are no guarantees as to the quality of the random sequence produced,
|
|
|
4319 * and this should not be used for security (cryptography, passwords) or where
|
|
|
4320 * money is on the line (loot-boxes, casinos). There are many random number
|
|
|
4321 * libraries available with different characteristics and you should pick one
|
|
|
4322 * of those to meet any serious needs.
|
|
|
4323 *
|
|
|
4324 * \param n the number of possible outcomes. n must be positive.
|
|
|
4325 * \returns a random value in the range of [0 .. n-1].
|
|
|
4326 *
|
|
|
4327 * \threadsafety All calls should be made from a single thread
|
|
|
4328 *
|
|
|
4329 * \since This function is available since SDL 3.2.0.
|
|
|
4330 *
|
|
|
4331 * \sa SDL_srand
|
|
|
4332 * \sa SDL_randf
|
|
|
4333 */
|
|
|
4334 extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand(Sint32 n);
|
|
|
4335
|
|
|
4336 /**
|
|
|
4337 * Generate a uniform pseudo-random floating point number less than 1.0
|
|
|
4338 *
|
|
|
4339 * If you want reproducible output, be sure to initialize with SDL_srand()
|
|
|
4340 * first.
|
|
|
4341 *
|
|
|
4342 * There are no guarantees as to the quality of the random sequence produced,
|
|
|
4343 * and this should not be used for security (cryptography, passwords) or where
|
|
|
4344 * money is on the line (loot-boxes, casinos). There are many random number
|
|
|
4345 * libraries available with different characteristics and you should pick one
|
|
|
4346 * of those to meet any serious needs.
|
|
|
4347 *
|
|
|
4348 * \returns a random value in the range of [0.0, 1.0).
|
|
|
4349 *
|
|
|
4350 * \threadsafety All calls should be made from a single thread
|
|
|
4351 *
|
|
|
4352 * \since This function is available since SDL 3.2.0.
|
|
|
4353 *
|
|
|
4354 * \sa SDL_srand
|
|
|
4355 * \sa SDL_rand
|
|
|
4356 */
|
|
|
4357 extern SDL_DECLSPEC float SDLCALL SDL_randf(void);
|
|
|
4358
|
|
|
4359 /**
|
|
|
4360 * Generate 32 pseudo-random bits.
|
|
|
4361 *
|
|
|
4362 * You likely want to use SDL_rand() to get a psuedo-random number instead.
|
|
|
4363 *
|
|
|
4364 * There are no guarantees as to the quality of the random sequence produced,
|
|
|
4365 * and this should not be used for security (cryptography, passwords) or where
|
|
|
4366 * money is on the line (loot-boxes, casinos). There are many random number
|
|
|
4367 * libraries available with different characteristics and you should pick one
|
|
|
4368 * of those to meet any serious needs.
|
|
|
4369 *
|
|
|
4370 * \returns a random value in the range of [0-SDL_MAX_UINT32].
|
|
|
4371 *
|
|
|
4372 * \threadsafety All calls should be made from a single thread
|
|
|
4373 *
|
|
|
4374 * \since This function is available since SDL 3.2.0.
|
|
|
4375 *
|
|
|
4376 * \sa SDL_rand
|
|
|
4377 * \sa SDL_randf
|
|
|
4378 * \sa SDL_srand
|
|
|
4379 */
|
|
|
4380 extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits(void);
|
|
|
4381
|
|
|
4382 /**
|
|
|
4383 * Generate a pseudo-random number less than n for positive n
|
|
|
4384 *
|
|
|
4385 * The method used is faster and of better quality than `rand() % n`. Odds are
|
|
|
4386 * roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and
|
|
|
4387 * much worse as n gets bigger.
|
|
|
4388 *
|
|
|
4389 * Example: to simulate a d6 use `SDL_rand_r(state, 6) + 1` The +1 converts
|
|
|
4390 * 0..5 to 1..6
|
|
|
4391 *
|
|
|
4392 * If you want to generate a pseudo-random number in the full range of Sint32,
|
|
|
4393 * you should use: (Sint32)SDL_rand_bits_r(state)
|
|
|
4394 *
|
|
|
4395 * There are no guarantees as to the quality of the random sequence produced,
|
|
|
4396 * and this should not be used for security (cryptography, passwords) or where
|
|
|
4397 * money is on the line (loot-boxes, casinos). There are many random number
|
|
|
4398 * libraries available with different characteristics and you should pick one
|
|
|
4399 * of those to meet any serious needs.
|
|
|
4400 *
|
|
|
4401 * \param state a pointer to the current random number state, this may not be
|
|
|
4402 * NULL.
|
|
|
4403 * \param n the number of possible outcomes. n must be positive.
|
|
|
4404 * \returns a random value in the range of [0 .. n-1].
|
|
|
4405 *
|
|
|
4406 * \threadsafety This function is thread-safe, as long as the state pointer
|
|
|
4407 * isn't shared between threads.
|
|
|
4408 *
|
|
|
4409 * \since This function is available since SDL 3.2.0.
|
|
|
4410 *
|
|
|
4411 * \sa SDL_rand
|
|
|
4412 * \sa SDL_rand_bits_r
|
|
|
4413 * \sa SDL_randf_r
|
|
|
4414 */
|
|
|
4415 extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand_r(Uint64 *state, Sint32 n);
|
|
|
4416
|
|
|
4417 /**
|
|
|
4418 * Generate a uniform pseudo-random floating point number less than 1.0
|
|
|
4419 *
|
|
|
4420 * If you want reproducible output, be sure to initialize with SDL_srand()
|
|
|
4421 * first.
|
|
|
4422 *
|
|
|
4423 * There are no guarantees as to the quality of the random sequence produced,
|
|
|
4424 * and this should not be used for security (cryptography, passwords) or where
|
|
|
4425 * money is on the line (loot-boxes, casinos). There are many random number
|
|
|
4426 * libraries available with different characteristics and you should pick one
|
|
|
4427 * of those to meet any serious needs.
|
|
|
4428 *
|
|
|
4429 * \param state a pointer to the current random number state, this may not be
|
|
|
4430 * NULL.
|
|
|
4431 * \returns a random value in the range of [0.0, 1.0).
|
|
|
4432 *
|
|
|
4433 * \threadsafety This function is thread-safe, as long as the state pointer
|
|
|
4434 * isn't shared between threads.
|
|
|
4435 *
|
|
|
4436 * \since This function is available since SDL 3.2.0.
|
|
|
4437 *
|
|
|
4438 * \sa SDL_rand_bits_r
|
|
|
4439 * \sa SDL_rand_r
|
|
|
4440 * \sa SDL_randf
|
|
|
4441 */
|
|
|
4442 extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state);
|
|
|
4443
|
|
|
4444 /**
|
|
|
4445 * Generate 32 pseudo-random bits.
|
|
|
4446 *
|
|
|
4447 * You likely want to use SDL_rand_r() to get a psuedo-random number instead.
|
|
|
4448 *
|
|
|
4449 * There are no guarantees as to the quality of the random sequence produced,
|
|
|
4450 * and this should not be used for security (cryptography, passwords) or where
|
|
|
4451 * money is on the line (loot-boxes, casinos). There are many random number
|
|
|
4452 * libraries available with different characteristics and you should pick one
|
|
|
4453 * of those to meet any serious needs.
|
|
|
4454 *
|
|
|
4455 * \param state a pointer to the current random number state, this may not be
|
|
|
4456 * NULL.
|
|
|
4457 * \returns a random value in the range of [0-SDL_MAX_UINT32].
|
|
|
4458 *
|
|
|
4459 * \threadsafety This function is thread-safe, as long as the state pointer
|
|
|
4460 * isn't shared between threads.
|
|
|
4461 *
|
|
|
4462 * \since This function is available since SDL 3.2.0.
|
|
|
4463 *
|
|
|
4464 * \sa SDL_rand_r
|
|
|
4465 * \sa SDL_randf_r
|
|
|
4466 */
|
|
|
4467 extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state);
|
|
|
4468
|
|
|
4469 #ifndef SDL_PI_D
|
|
|
4470
|
|
|
4471 /**
|
|
|
4472 * The value of Pi, as a double-precision floating point literal.
|
|
|
4473 *
|
|
|
4474 * \since This macro is available since SDL 3.2.0.
|
|
|
4475 *
|
|
|
4476 * \sa SDL_PI_F
|
|
|
4477 */
|
|
|
4478 #define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */
|
|
|
4479 #endif
|
|
|
4480
|
|
|
4481 #ifndef SDL_PI_F
|
|
|
4482
|
|
|
4483 /**
|
|
|
4484 * The value of Pi, as a single-precision floating point literal.
|
|
|
4485 *
|
|
|
4486 * \since This macro is available since SDL 3.2.0.
|
|
|
4487 *
|
|
|
4488 * \sa SDL_PI_D
|
|
|
4489 */
|
|
|
4490 #define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */
|
|
|
4491 #endif
|
|
|
4492
|
|
|
4493 /**
|
|
|
4494 * Compute the arc cosine of `x`.
|
|
|
4495 *
|
|
|
4496 * The definition of `y = acos(x)` is `x = cos(y)`.
|
|
|
4497 *
|
|
|
4498 * Domain: `-1 <= x <= 1`
|
|
|
4499 *
|
|
|
4500 * Range: `0 <= y <= Pi`
|
|
|
4501 *
|
|
|
4502 * This function operates on double-precision floating point values, use
|
|
|
4503 * SDL_acosf for single-precision floats.
|
|
|
4504 *
|
|
|
4505 * This function may use a different approximation across different versions,
|
|
|
4506 * platforms and configurations. i.e, it can return a different value given
|
|
|
4507 * the same input on different machines or operating systems, or if SDL is
|
|
|
4508 * updated.
|
|
|
4509 *
|
|
|
4510 * \param x floating point value.
|
|
|
4511 * \returns arc cosine of `x`, in radians.
|
|
|
4512 *
|
|
|
4513 * \threadsafety It is safe to call this function from any thread.
|
|
|
4514 *
|
|
|
4515 * \since This function is available since SDL 3.2.0.
|
|
|
4516 *
|
|
|
4517 * \sa SDL_acosf
|
|
|
4518 * \sa SDL_asin
|
|
|
4519 * \sa SDL_cos
|
|
|
4520 */
|
|
|
4521 extern SDL_DECLSPEC double SDLCALL SDL_acos(double x);
|
|
|
4522
|
|
|
4523 /**
|
|
|
4524 * Compute the arc cosine of `x`.
|
|
|
4525 *
|
|
|
4526 * The definition of `y = acos(x)` is `x = cos(y)`.
|
|
|
4527 *
|
|
|
4528 * Domain: `-1 <= x <= 1`
|
|
|
4529 *
|
|
|
4530 * Range: `0 <= y <= Pi`
|
|
|
4531 *
|
|
|
4532 * This function operates on single-precision floating point values, use
|
|
|
4533 * SDL_acos for double-precision floats.
|
|
|
4534 *
|
|
|
4535 * This function may use a different approximation across different versions,
|
|
|
4536 * platforms and configurations. i.e, it can return a different value given
|
|
|
4537 * the same input on different machines or operating systems, or if SDL is
|
|
|
4538 * updated.
|
|
|
4539 *
|
|
|
4540 * \param x floating point value.
|
|
|
4541 * \returns arc cosine of `x`, in radians.
|
|
|
4542 *
|
|
|
4543 * \threadsafety It is safe to call this function from any thread.
|
|
|
4544 *
|
|
|
4545 * \since This function is available since SDL 3.2.0.
|
|
|
4546 *
|
|
|
4547 * \sa SDL_acos
|
|
|
4548 * \sa SDL_asinf
|
|
|
4549 * \sa SDL_cosf
|
|
|
4550 */
|
|
|
4551 extern SDL_DECLSPEC float SDLCALL SDL_acosf(float x);
|
|
|
4552
|
|
|
4553 /**
|
|
|
4554 * Compute the arc sine of `x`.
|
|
|
4555 *
|
|
|
4556 * The definition of `y = asin(x)` is `x = sin(y)`.
|
|
|
4557 *
|
|
|
4558 * Domain: `-1 <= x <= 1`
|
|
|
4559 *
|
|
|
4560 * Range: `-Pi/2 <= y <= Pi/2`
|
|
|
4561 *
|
|
|
4562 * This function operates on double-precision floating point values, use
|
|
|
4563 * SDL_asinf for single-precision floats.
|
|
|
4564 *
|
|
|
4565 * This function may use a different approximation across different versions,
|
|
|
4566 * platforms and configurations. i.e, it can return a different value given
|
|
|
4567 * the same input on different machines or operating systems, or if SDL is
|
|
|
4568 * updated.
|
|
|
4569 *
|
|
|
4570 * \param x floating point value.
|
|
|
4571 * \returns arc sine of `x`, in radians.
|
|
|
4572 *
|
|
|
4573 * \threadsafety It is safe to call this function from any thread.
|
|
|
4574 *
|
|
|
4575 * \since This function is available since SDL 3.2.0.
|
|
|
4576 *
|
|
|
4577 * \sa SDL_asinf
|
|
|
4578 * \sa SDL_acos
|
|
|
4579 * \sa SDL_sin
|
|
|
4580 */
|
|
|
4581 extern SDL_DECLSPEC double SDLCALL SDL_asin(double x);
|
|
|
4582
|
|
|
4583 /**
|
|
|
4584 * Compute the arc sine of `x`.
|
|
|
4585 *
|
|
|
4586 * The definition of `y = asin(x)` is `x = sin(y)`.
|
|
|
4587 *
|
|
|
4588 * Domain: `-1 <= x <= 1`
|
|
|
4589 *
|
|
|
4590 * Range: `-Pi/2 <= y <= Pi/2`
|
|
|
4591 *
|
|
|
4592 * This function operates on single-precision floating point values, use
|
|
|
4593 * SDL_asin for double-precision floats.
|
|
|
4594 *
|
|
|
4595 * This function may use a different approximation across different versions,
|
|
|
4596 * platforms and configurations. i.e, it can return a different value given
|
|
|
4597 * the same input on different machines or operating systems, or if SDL is
|
|
|
4598 * updated.
|
|
|
4599 *
|
|
|
4600 * \param x floating point value.
|
|
|
4601 * \returns arc sine of `x`, in radians.
|
|
|
4602 *
|
|
|
4603 * \threadsafety It is safe to call this function from any thread.
|
|
|
4604 *
|
|
|
4605 * \since This function is available since SDL 3.2.0.
|
|
|
4606 *
|
|
|
4607 * \sa SDL_asin
|
|
|
4608 * \sa SDL_acosf
|
|
|
4609 * \sa SDL_sinf
|
|
|
4610 */
|
|
|
4611 extern SDL_DECLSPEC float SDLCALL SDL_asinf(float x);
|
|
|
4612
|
|
|
4613 /**
|
|
|
4614 * Compute the arc tangent of `x`.
|
|
|
4615 *
|
|
|
4616 * The definition of `y = atan(x)` is `x = tan(y)`.
|
|
|
4617 *
|
|
|
4618 * Domain: `-INF <= x <= INF`
|
|
|
4619 *
|
|
|
4620 * Range: `-Pi/2 <= y <= Pi/2`
|
|
|
4621 *
|
|
|
4622 * This function operates on double-precision floating point values, use
|
|
|
4623 * SDL_atanf for single-precision floats.
|
|
|
4624 *
|
|
|
4625 * To calculate the arc tangent of y / x, use SDL_atan2.
|
|
|
4626 *
|
|
|
4627 * This function may use a different approximation across different versions,
|
|
|
4628 * platforms and configurations. i.e, it can return a different value given
|
|
|
4629 * the same input on different machines or operating systems, or if SDL is
|
|
|
4630 * updated.
|
|
|
4631 *
|
|
|
4632 * \param x floating point value.
|
|
|
4633 * \returns arc tangent of of `x` in radians, or 0 if `x = 0`.
|
|
|
4634 *
|
|
|
4635 * \threadsafety It is safe to call this function from any thread.
|
|
|
4636 *
|
|
|
4637 * \since This function is available since SDL 3.2.0.
|
|
|
4638 *
|
|
|
4639 * \sa SDL_atanf
|
|
|
4640 * \sa SDL_atan2
|
|
|
4641 * \sa SDL_tan
|
|
|
4642 */
|
|
|
4643 extern SDL_DECLSPEC double SDLCALL SDL_atan(double x);
|
|
|
4644
|
|
|
4645 /**
|
|
|
4646 * Compute the arc tangent of `x`.
|
|
|
4647 *
|
|
|
4648 * The definition of `y = atan(x)` is `x = tan(y)`.
|
|
|
4649 *
|
|
|
4650 * Domain: `-INF <= x <= INF`
|
|
|
4651 *
|
|
|
4652 * Range: `-Pi/2 <= y <= Pi/2`
|
|
|
4653 *
|
|
|
4654 * This function operates on single-precision floating point values, use
|
|
|
4655 * SDL_atan for dboule-precision floats.
|
|
|
4656 *
|
|
|
4657 * To calculate the arc tangent of y / x, use SDL_atan2f.
|
|
|
4658 *
|
|
|
4659 * This function may use a different approximation across different versions,
|
|
|
4660 * platforms and configurations. i.e, it can return a different value given
|
|
|
4661 * the same input on different machines or operating systems, or if SDL is
|
|
|
4662 * updated.
|
|
|
4663 *
|
|
|
4664 * \param x floating point value.
|
|
|
4665 * \returns arc tangent of of `x` in radians, or 0 if `x = 0`.
|
|
|
4666 *
|
|
|
4667 * \threadsafety It is safe to call this function from any thread.
|
|
|
4668 *
|
|
|
4669 * \since This function is available since SDL 3.2.0.
|
|
|
4670 *
|
|
|
4671 * \sa SDL_atan
|
|
|
4672 * \sa SDL_atan2f
|
|
|
4673 * \sa SDL_tanf
|
|
|
4674 */
|
|
|
4675 extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x);
|
|
|
4676
|
|
|
4677 /**
|
|
|
4678 * Compute the arc tangent of `y / x`, using the signs of x and y to adjust
|
|
|
4679 * the result's quadrant.
|
|
|
4680 *
|
|
|
4681 * The definition of `z = atan2(x, y)` is `y = x tan(z)`, where the quadrant
|
|
|
4682 * of z is determined based on the signs of x and y.
|
|
|
4683 *
|
|
|
4684 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
|
|
|
4685 *
|
|
|
4686 * Range: `-Pi <= y <= Pi`
|
|
|
4687 *
|
|
|
4688 * This function operates on double-precision floating point values, use
|
|
|
4689 * SDL_atan2f for single-precision floats.
|
|
|
4690 *
|
|
|
4691 * To calculate the arc tangent of a single value, use SDL_atan.
|
|
|
4692 *
|
|
|
4693 * This function may use a different approximation across different versions,
|
|
|
4694 * platforms and configurations. i.e, it can return a different value given
|
|
|
4695 * the same input on different machines or operating systems, or if SDL is
|
|
|
4696 * updated.
|
|
|
4697 *
|
|
|
4698 * \param y floating point value of the numerator (y coordinate).
|
|
|
4699 * \param x floating point value of the denominator (x coordinate).
|
|
|
4700 * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either
|
|
|
4701 * `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`.
|
|
|
4702 *
|
|
|
4703 * \threadsafety It is safe to call this function from any thread.
|
|
|
4704 *
|
|
|
4705 * \since This function is available since SDL 3.2.0.
|
|
|
4706 *
|
|
|
4707 * \sa SDL_atan2f
|
|
|
4708 * \sa SDL_atan
|
|
|
4709 * \sa SDL_tan
|
|
|
4710 */
|
|
|
4711 extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x);
|
|
|
4712
|
|
|
4713 /**
|
|
|
4714 * Compute the arc tangent of `y / x`, using the signs of x and y to adjust
|
|
|
4715 * the result's quadrant.
|
|
|
4716 *
|
|
|
4717 * The definition of `z = atan2(x, y)` is `y = x tan(z)`, where the quadrant
|
|
|
4718 * of z is determined based on the signs of x and y.
|
|
|
4719 *
|
|
|
4720 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
|
|
|
4721 *
|
|
|
4722 * Range: `-Pi <= y <= Pi`
|
|
|
4723 *
|
|
|
4724 * This function operates on single-precision floating point values, use
|
|
|
4725 * SDL_atan2 for double-precision floats.
|
|
|
4726 *
|
|
|
4727 * To calculate the arc tangent of a single value, use SDL_atanf.
|
|
|
4728 *
|
|
|
4729 * This function may use a different approximation across different versions,
|
|
|
4730 * platforms and configurations. i.e, it can return a different value given
|
|
|
4731 * the same input on different machines or operating systems, or if SDL is
|
|
|
4732 * updated.
|
|
|
4733 *
|
|
|
4734 * \param y floating point value of the numerator (y coordinate).
|
|
|
4735 * \param x floating point value of the denominator (x coordinate).
|
|
|
4736 * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either
|
|
|
4737 * `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`.
|
|
|
4738 *
|
|
|
4739 * \threadsafety It is safe to call this function from any thread.
|
|
|
4740 *
|
|
|
4741 * \since This function is available since SDL 3.2.0.
|
|
|
4742 *
|
|
|
4743 * \sa SDL_atan2
|
|
|
4744 * \sa SDL_atan
|
|
|
4745 * \sa SDL_tan
|
|
|
4746 */
|
|
|
4747 extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x);
|
|
|
4748
|
|
|
4749 /**
|
|
|
4750 * Compute the ceiling of `x`.
|
|
|
4751 *
|
|
|
4752 * The ceiling of `x` is the smallest integer `y` such that `y >= x`, i.e `x`
|
|
|
4753 * rounded up to the nearest integer.
|
|
|
4754 *
|
|
|
4755 * Domain: `-INF <= x <= INF`
|
|
|
4756 *
|
|
|
4757 * Range: `-INF <= y <= INF`, y integer
|
|
|
4758 *
|
|
|
4759 * This function operates on double-precision floating point values, use
|
|
|
4760 * SDL_ceilf for single-precision floats.
|
|
|
4761 *
|
|
|
4762 * \param x floating point value.
|
|
|
4763 * \returns the ceiling of `x`.
|
|
|
4764 *
|
|
|
4765 * \threadsafety It is safe to call this function from any thread.
|
|
|
4766 *
|
|
|
4767 * \since This function is available since SDL 3.2.0.
|
|
|
4768 *
|
|
|
4769 * \sa SDL_ceilf
|
|
|
4770 * \sa SDL_floor
|
|
|
4771 * \sa SDL_trunc
|
|
|
4772 * \sa SDL_round
|
|
|
4773 * \sa SDL_lround
|
|
|
4774 */
|
|
|
4775 extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x);
|
|
|
4776
|
|
|
4777 /**
|
|
|
4778 * Compute the ceiling of `x`.
|
|
|
4779 *
|
|
|
4780 * The ceiling of `x` is the smallest integer `y` such that `y >= x`, i.e `x`
|
|
|
4781 * rounded up to the nearest integer.
|
|
|
4782 *
|
|
|
4783 * Domain: `-INF <= x <= INF`
|
|
|
4784 *
|
|
|
4785 * Range: `-INF <= y <= INF`, y integer
|
|
|
4786 *
|
|
|
4787 * This function operates on single-precision floating point values, use
|
|
|
4788 * SDL_ceil for double-precision floats.
|
|
|
4789 *
|
|
|
4790 * \param x floating point value.
|
|
|
4791 * \returns the ceiling of `x`.
|
|
|
4792 *
|
|
|
4793 * \threadsafety It is safe to call this function from any thread.
|
|
|
4794 *
|
|
|
4795 * \since This function is available since SDL 3.2.0.
|
|
|
4796 *
|
|
|
4797 * \sa SDL_ceil
|
|
|
4798 * \sa SDL_floorf
|
|
|
4799 * \sa SDL_truncf
|
|
|
4800 * \sa SDL_roundf
|
|
|
4801 * \sa SDL_lroundf
|
|
|
4802 */
|
|
|
4803 extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x);
|
|
|
4804
|
|
|
4805 /**
|
|
|
4806 * Copy the sign of one floating-point value to another.
|
|
|
4807 *
|
|
|
4808 * The definition of copysign is that ``copysign(x, y) = abs(x) * sign(y)``.
|
|
|
4809 *
|
|
|
4810 * Domain: `-INF <= x <= INF`, ``-INF <= y <= f``
|
|
|
4811 *
|
|
|
4812 * Range: `-INF <= z <= INF`
|
|
|
4813 *
|
|
|
4814 * This function operates on double-precision floating point values, use
|
|
|
4815 * SDL_copysignf for single-precision floats.
|
|
|
4816 *
|
|
|
4817 * \param x floating point value to use as the magnitude.
|
|
|
4818 * \param y floating point value to use as the sign.
|
|
|
4819 * \returns the floating point value with the sign of y and the magnitude of
|
|
|
4820 * x.
|
|
|
4821 *
|
|
|
4822 * \threadsafety It is safe to call this function from any thread.
|
|
|
4823 *
|
|
|
4824 * \since This function is available since SDL 3.2.0.
|
|
|
4825 *
|
|
|
4826 * \sa SDL_copysignf
|
|
|
4827 * \sa SDL_fabs
|
|
|
4828 */
|
|
|
4829 extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y);
|
|
|
4830
|
|
|
4831 /**
|
|
|
4832 * Copy the sign of one floating-point value to another.
|
|
|
4833 *
|
|
|
4834 * The definition of copysign is that ``copysign(x, y) = abs(x) * sign(y)``.
|
|
|
4835 *
|
|
|
4836 * Domain: `-INF <= x <= INF`, ``-INF <= y <= f``
|
|
|
4837 *
|
|
|
4838 * Range: `-INF <= z <= INF`
|
|
|
4839 *
|
|
|
4840 * This function operates on single-precision floating point values, use
|
|
|
4841 * SDL_copysign for double-precision floats.
|
|
|
4842 *
|
|
|
4843 * \param x floating point value to use as the magnitude.
|
|
|
4844 * \param y floating point value to use as the sign.
|
|
|
4845 * \returns the floating point value with the sign of y and the magnitude of
|
|
|
4846 * x.
|
|
|
4847 *
|
|
|
4848 * \threadsafety It is safe to call this function from any thread.
|
|
|
4849 *
|
|
|
4850 * \since This function is available since SDL 3.2.0.
|
|
|
4851 *
|
|
|
4852 * \sa SDL_copysign
|
|
|
4853 * \sa SDL_fabsf
|
|
|
4854 */
|
|
|
4855 extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y);
|
|
|
4856
|
|
|
4857 /**
|
|
|
4858 * Compute the cosine of `x`.
|
|
|
4859 *
|
|
|
4860 * Domain: `-INF <= x <= INF`
|
|
|
4861 *
|
|
|
4862 * Range: `-1 <= y <= 1`
|
|
|
4863 *
|
|
|
4864 * This function operates on double-precision floating point values, use
|
|
|
4865 * SDL_cosf for single-precision floats.
|
|
|
4866 *
|
|
|
4867 * This function may use a different approximation across different versions,
|
|
|
4868 * platforms and configurations. i.e, it can return a different value given
|
|
|
4869 * the same input on different machines or operating systems, or if SDL is
|
|
|
4870 * updated.
|
|
|
4871 *
|
|
|
4872 * \param x floating point value, in radians.
|
|
|
4873 * \returns cosine of `x`.
|
|
|
4874 *
|
|
|
4875 * \threadsafety It is safe to call this function from any thread.
|
|
|
4876 *
|
|
|
4877 * \since This function is available since SDL 3.2.0.
|
|
|
4878 *
|
|
|
4879 * \sa SDL_cosf
|
|
|
4880 * \sa SDL_acos
|
|
|
4881 * \sa SDL_sin
|
|
|
4882 */
|
|
|
4883 extern SDL_DECLSPEC double SDLCALL SDL_cos(double x);
|
|
|
4884
|
|
|
4885 /**
|
|
|
4886 * Compute the cosine of `x`.
|
|
|
4887 *
|
|
|
4888 * Domain: `-INF <= x <= INF`
|
|
|
4889 *
|
|
|
4890 * Range: `-1 <= y <= 1`
|
|
|
4891 *
|
|
|
4892 * This function operates on single-precision floating point values, use
|
|
|
4893 * SDL_cos for double-precision floats.
|
|
|
4894 *
|
|
|
4895 * This function may use a different approximation across different versions,
|
|
|
4896 * platforms and configurations. i.e, it can return a different value given
|
|
|
4897 * the same input on different machines or operating systems, or if SDL is
|
|
|
4898 * updated.
|
|
|
4899 *
|
|
|
4900 * \param x floating point value, in radians.
|
|
|
4901 * \returns cosine of `x`.
|
|
|
4902 *
|
|
|
4903 * \threadsafety It is safe to call this function from any thread.
|
|
|
4904 *
|
|
|
4905 * \since This function is available since SDL 3.2.0.
|
|
|
4906 *
|
|
|
4907 * \sa SDL_cos
|
|
|
4908 * \sa SDL_acosf
|
|
|
4909 * \sa SDL_sinf
|
|
|
4910 */
|
|
|
4911 extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x);
|
|
|
4912
|
|
|
4913 /**
|
|
|
4914 * Compute the exponential of `x`.
|
|
|
4915 *
|
|
|
4916 * The definition of `y = exp(x)` is `y = e^x`, where `e` is the base of the
|
|
|
4917 * natural logarithm. The inverse is the natural logarithm, SDL_log.
|
|
|
4918 *
|
|
|
4919 * Domain: `-INF <= x <= INF`
|
|
|
4920 *
|
|
|
4921 * Range: `0 <= y <= INF`
|
|
|
4922 *
|
|
|
4923 * The output will overflow if `exp(x)` is too large to be represented.
|
|
|
4924 *
|
|
|
4925 * This function operates on double-precision floating point values, use
|
|
|
4926 * SDL_expf for single-precision floats.
|
|
|
4927 *
|
|
|
4928 * This function may use a different approximation across different versions,
|
|
|
4929 * platforms and configurations. i.e, it can return a different value given
|
|
|
4930 * the same input on different machines or operating systems, or if SDL is
|
|
|
4931 * updated.
|
|
|
4932 *
|
|
|
4933 * \param x floating point value.
|
|
|
4934 * \returns value of `e^x`.
|
|
|
4935 *
|
|
|
4936 * \threadsafety It is safe to call this function from any thread.
|
|
|
4937 *
|
|
|
4938 * \since This function is available since SDL 3.2.0.
|
|
|
4939 *
|
|
|
4940 * \sa SDL_expf
|
|
|
4941 * \sa SDL_log
|
|
|
4942 */
|
|
|
4943 extern SDL_DECLSPEC double SDLCALL SDL_exp(double x);
|
|
|
4944
|
|
|
4945 /**
|
|
|
4946 * Compute the exponential of `x`.
|
|
|
4947 *
|
|
|
4948 * The definition of `y = exp(x)` is `y = e^x`, where `e` is the base of the
|
|
|
4949 * natural logarithm. The inverse is the natural logarithm, SDL_logf.
|
|
|
4950 *
|
|
|
4951 * Domain: `-INF <= x <= INF`
|
|
|
4952 *
|
|
|
4953 * Range: `0 <= y <= INF`
|
|
|
4954 *
|
|
|
4955 * The output will overflow if `exp(x)` is too large to be represented.
|
|
|
4956 *
|
|
|
4957 * This function operates on single-precision floating point values, use
|
|
|
4958 * SDL_exp for double-precision floats.
|
|
|
4959 *
|
|
|
4960 * This function may use a different approximation across different versions,
|
|
|
4961 * platforms and configurations. i.e, it can return a different value given
|
|
|
4962 * the same input on different machines or operating systems, or if SDL is
|
|
|
4963 * updated.
|
|
|
4964 *
|
|
|
4965 * \param x floating point value.
|
|
|
4966 * \returns value of `e^x`.
|
|
|
4967 *
|
|
|
4968 * \threadsafety It is safe to call this function from any thread.
|
|
|
4969 *
|
|
|
4970 * \since This function is available since SDL 3.2.0.
|
|
|
4971 *
|
|
|
4972 * \sa SDL_exp
|
|
|
4973 * \sa SDL_logf
|
|
|
4974 */
|
|
|
4975 extern SDL_DECLSPEC float SDLCALL SDL_expf(float x);
|
|
|
4976
|
|
|
4977 /**
|
|
|
4978 * Compute the absolute value of `x`
|
|
|
4979 *
|
|
|
4980 * Domain: `-INF <= x <= INF`
|
|
|
4981 *
|
|
|
4982 * Range: `0 <= y <= INF`
|
|
|
4983 *
|
|
|
4984 * This function operates on double-precision floating point values, use
|
|
|
4985 * SDL_fabsf for single-precision floats.
|
|
|
4986 *
|
|
|
4987 * \param x floating point value to use as the magnitude.
|
|
|
4988 * \returns the absolute value of `x`.
|
|
|
4989 *
|
|
|
4990 * \threadsafety It is safe to call this function from any thread.
|
|
|
4991 *
|
|
|
4992 * \since This function is available since SDL 3.2.0.
|
|
|
4993 *
|
|
|
4994 * \sa SDL_fabsf
|
|
|
4995 */
|
|
|
4996 extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x);
|
|
|
4997
|
|
|
4998 /**
|
|
|
4999 * Compute the absolute value of `x`
|
|
|
5000 *
|
|
|
5001 * Domain: `-INF <= x <= INF`
|
|
|
5002 *
|
|
|
5003 * Range: `0 <= y <= INF`
|
|
|
5004 *
|
|
|
5005 * This function operates on single-precision floating point values, use
|
|
|
5006 * SDL_fabs for double-precision floats.
|
|
|
5007 *
|
|
|
5008 * \param x floating point value to use as the magnitude.
|
|
|
5009 * \returns the absolute value of `x`.
|
|
|
5010 *
|
|
|
5011 * \threadsafety It is safe to call this function from any thread.
|
|
|
5012 *
|
|
|
5013 * \since This function is available since SDL 3.2.0.
|
|
|
5014 *
|
|
|
5015 * \sa SDL_fabs
|
|
|
5016 */
|
|
|
5017 extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x);
|
|
|
5018
|
|
|
5019 /**
|
|
|
5020 * Compute the floor of `x`.
|
|
|
5021 *
|
|
|
5022 * The floor of `x` is the largest integer `y` such that `y <= x`, i.e `x`
|
|
|
5023 * rounded down to the nearest integer.
|
|
|
5024 *
|
|
|
5025 * Domain: `-INF <= x <= INF`
|
|
|
5026 *
|
|
|
5027 * Range: `-INF <= y <= INF`, y integer
|
|
|
5028 *
|
|
|
5029 * This function operates on double-precision floating point values, use
|
|
|
5030 * SDL_floorf for single-precision floats.
|
|
|
5031 *
|
|
|
5032 * \param x floating point value.
|
|
|
5033 * \returns the floor of `x`.
|
|
|
5034 *
|
|
|
5035 * \threadsafety It is safe to call this function from any thread.
|
|
|
5036 *
|
|
|
5037 * \since This function is available since SDL 3.2.0.
|
|
|
5038 *
|
|
|
5039 * \sa SDL_floorf
|
|
|
5040 * \sa SDL_ceil
|
|
|
5041 * \sa SDL_trunc
|
|
|
5042 * \sa SDL_round
|
|
|
5043 * \sa SDL_lround
|
|
|
5044 */
|
|
|
5045 extern SDL_DECLSPEC double SDLCALL SDL_floor(double x);
|
|
|
5046
|
|
|
5047 /**
|
|
|
5048 * Compute the floor of `x`.
|
|
|
5049 *
|
|
|
5050 * The floor of `x` is the largest integer `y` such that `y <= x`, i.e `x`
|
|
|
5051 * rounded down to the nearest integer.
|
|
|
5052 *
|
|
|
5053 * Domain: `-INF <= x <= INF`
|
|
|
5054 *
|
|
|
5055 * Range: `-INF <= y <= INF`, y integer
|
|
|
5056 *
|
|
|
5057 * This function operates on single-precision floating point values, use
|
|
|
5058 * SDL_floor for double-precision floats.
|
|
|
5059 *
|
|
|
5060 * \param x floating point value.
|
|
|
5061 * \returns the floor of `x`.
|
|
|
5062 *
|
|
|
5063 * \threadsafety It is safe to call this function from any thread.
|
|
|
5064 *
|
|
|
5065 * \since This function is available since SDL 3.2.0.
|
|
|
5066 *
|
|
|
5067 * \sa SDL_floor
|
|
|
5068 * \sa SDL_ceilf
|
|
|
5069 * \sa SDL_truncf
|
|
|
5070 * \sa SDL_roundf
|
|
|
5071 * \sa SDL_lroundf
|
|
|
5072 */
|
|
|
5073 extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x);
|
|
|
5074
|
|
|
5075 /**
|
|
|
5076 * Truncate `x` to an integer.
|
|
|
5077 *
|
|
|
5078 * Rounds `x` to the next closest integer to 0. This is equivalent to removing
|
|
|
5079 * the fractional part of `x`, leaving only the integer part.
|
|
|
5080 *
|
|
|
5081 * Domain: `-INF <= x <= INF`
|
|
|
5082 *
|
|
|
5083 * Range: `-INF <= y <= INF`, y integer
|
|
|
5084 *
|
|
|
5085 * This function operates on double-precision floating point values, use
|
|
|
5086 * SDL_truncf for single-precision floats.
|
|
|
5087 *
|
|
|
5088 * \param x floating point value.
|
|
|
5089 * \returns `x` truncated to an integer.
|
|
|
5090 *
|
|
|
5091 * \threadsafety It is safe to call this function from any thread.
|
|
|
5092 *
|
|
|
5093 * \since This function is available since SDL 3.2.0.
|
|
|
5094 *
|
|
|
5095 * \sa SDL_truncf
|
|
|
5096 * \sa SDL_fmod
|
|
|
5097 * \sa SDL_ceil
|
|
|
5098 * \sa SDL_floor
|
|
|
5099 * \sa SDL_round
|
|
|
5100 * \sa SDL_lround
|
|
|
5101 */
|
|
|
5102 extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x);
|
|
|
5103
|
|
|
5104 /**
|
|
|
5105 * Truncate `x` to an integer.
|
|
|
5106 *
|
|
|
5107 * Rounds `x` to the next closest integer to 0. This is equivalent to removing
|
|
|
5108 * the fractional part of `x`, leaving only the integer part.
|
|
|
5109 *
|
|
|
5110 * Domain: `-INF <= x <= INF`
|
|
|
5111 *
|
|
|
5112 * Range: `-INF <= y <= INF`, y integer
|
|
|
5113 *
|
|
|
5114 * This function operates on single-precision floating point values, use
|
|
|
5115 * SDL_trunc for double-precision floats.
|
|
|
5116 *
|
|
|
5117 * \param x floating point value.
|
|
|
5118 * \returns `x` truncated to an integer.
|
|
|
5119 *
|
|
|
5120 * \threadsafety It is safe to call this function from any thread.
|
|
|
5121 *
|
|
|
5122 * \since This function is available since SDL 3.2.0.
|
|
|
5123 *
|
|
|
5124 * \sa SDL_trunc
|
|
|
5125 * \sa SDL_fmodf
|
|
|
5126 * \sa SDL_ceilf
|
|
|
5127 * \sa SDL_floorf
|
|
|
5128 * \sa SDL_roundf
|
|
|
5129 * \sa SDL_lroundf
|
|
|
5130 */
|
|
|
5131 extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x);
|
|
|
5132
|
|
|
5133 /**
|
|
|
5134 * Return the floating-point remainder of `x / y`
|
|
|
5135 *
|
|
|
5136 * Divides `x` by `y`, and returns the remainder.
|
|
|
5137 *
|
|
|
5138 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`, `y != 0`
|
|
|
5139 *
|
|
|
5140 * Range: `-y <= z <= y`
|
|
|
5141 *
|
|
|
5142 * This function operates on double-precision floating point values, use
|
|
|
5143 * SDL_fmodf for single-precision floats.
|
|
|
5144 *
|
|
|
5145 * \param x the numerator.
|
|
|
5146 * \param y the denominator. Must not be 0.
|
|
|
5147 * \returns the remainder of `x / y`.
|
|
|
5148 *
|
|
|
5149 * \threadsafety It is safe to call this function from any thread.
|
|
|
5150 *
|
|
|
5151 * \since This function is available since SDL 3.2.0.
|
|
|
5152 *
|
|
|
5153 * \sa SDL_fmodf
|
|
|
5154 * \sa SDL_modf
|
|
|
5155 * \sa SDL_trunc
|
|
|
5156 * \sa SDL_ceil
|
|
|
5157 * \sa SDL_floor
|
|
|
5158 * \sa SDL_round
|
|
|
5159 * \sa SDL_lround
|
|
|
5160 */
|
|
|
5161 extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y);
|
|
|
5162
|
|
|
5163 /**
|
|
|
5164 * Return the floating-point remainder of `x / y`
|
|
|
5165 *
|
|
|
5166 * Divides `x` by `y`, and returns the remainder.
|
|
|
5167 *
|
|
|
5168 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`, `y != 0`
|
|
|
5169 *
|
|
|
5170 * Range: `-y <= z <= y`
|
|
|
5171 *
|
|
|
5172 * This function operates on single-precision floating point values, use
|
|
|
5173 * SDL_fmod for double-precision floats.
|
|
|
5174 *
|
|
|
5175 * \param x the numerator.
|
|
|
5176 * \param y the denominator. Must not be 0.
|
|
|
5177 * \returns the remainder of `x / y`.
|
|
|
5178 *
|
|
|
5179 * \threadsafety It is safe to call this function from any thread.
|
|
|
5180 *
|
|
|
5181 * \since This function is available since SDL 3.2.0.
|
|
|
5182 *
|
|
|
5183 * \sa SDL_fmod
|
|
|
5184 * \sa SDL_truncf
|
|
|
5185 * \sa SDL_modff
|
|
|
5186 * \sa SDL_ceilf
|
|
|
5187 * \sa SDL_floorf
|
|
|
5188 * \sa SDL_roundf
|
|
|
5189 * \sa SDL_lroundf
|
|
|
5190 */
|
|
|
5191 extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y);
|
|
|
5192
|
|
|
5193 /**
|
|
|
5194 * Return whether the value is infinity.
|
|
|
5195 *
|
|
|
5196 * \param x double-precision floating point value.
|
|
|
5197 * \returns non-zero if the value is infinity, 0 otherwise.
|
|
|
5198 *
|
|
|
5199 * \threadsafety It is safe to call this function from any thread.
|
|
|
5200 *
|
|
|
5201 * \since This function is available since SDL 3.2.0.
|
|
|
5202 *
|
|
|
5203 * \sa SDL_isinff
|
|
|
5204 */
|
|
|
5205 extern SDL_DECLSPEC int SDLCALL SDL_isinf(double x);
|
|
|
5206
|
|
|
5207 /**
|
|
|
5208 * Return whether the value is infinity.
|
|
|
5209 *
|
|
|
5210 * \param x floating point value.
|
|
|
5211 * \returns non-zero if the value is infinity, 0 otherwise.
|
|
|
5212 *
|
|
|
5213 * \threadsafety It is safe to call this function from any thread.
|
|
|
5214 *
|
|
|
5215 * \since This function is available since SDL 3.2.0.
|
|
|
5216 *
|
|
|
5217 * \sa SDL_isinf
|
|
|
5218 */
|
|
|
5219 extern SDL_DECLSPEC int SDLCALL SDL_isinff(float x);
|
|
|
5220
|
|
|
5221 /**
|
|
|
5222 * Return whether the value is NaN.
|
|
|
5223 *
|
|
|
5224 * \param x double-precision floating point value.
|
|
|
5225 * \returns non-zero if the value is NaN, 0 otherwise.
|
|
|
5226 *
|
|
|
5227 * \threadsafety It is safe to call this function from any thread.
|
|
|
5228 *
|
|
|
5229 * \since This function is available since SDL 3.2.0.
|
|
|
5230 *
|
|
|
5231 * \sa SDL_isnanf
|
|
|
5232 */
|
|
|
5233 extern SDL_DECLSPEC int SDLCALL SDL_isnan(double x);
|
|
|
5234
|
|
|
5235 /**
|
|
|
5236 * Return whether the value is NaN.
|
|
|
5237 *
|
|
|
5238 * \param x floating point value.
|
|
|
5239 * \returns non-zero if the value is NaN, 0 otherwise.
|
|
|
5240 *
|
|
|
5241 * \threadsafety It is safe to call this function from any thread.
|
|
|
5242 *
|
|
|
5243 * \since This function is available since SDL 3.2.0.
|
|
|
5244 *
|
|
|
5245 * \sa SDL_isnan
|
|
|
5246 */
|
|
|
5247 extern SDL_DECLSPEC int SDLCALL SDL_isnanf(float x);
|
|
|
5248
|
|
|
5249 /**
|
|
|
5250 * Compute the natural logarithm of `x`.
|
|
|
5251 *
|
|
|
5252 * Domain: `0 < x <= INF`
|
|
|
5253 *
|
|
|
5254 * Range: `-INF <= y <= INF`
|
|
|
5255 *
|
|
|
5256 * It is an error for `x` to be less than or equal to 0.
|
|
|
5257 *
|
|
|
5258 * This function operates on double-precision floating point values, use
|
|
|
5259 * SDL_logf for single-precision floats.
|
|
|
5260 *
|
|
|
5261 * This function may use a different approximation across different versions,
|
|
|
5262 * platforms and configurations. i.e, it can return a different value given
|
|
|
5263 * the same input on different machines or operating systems, or if SDL is
|
|
|
5264 * updated.
|
|
|
5265 *
|
|
|
5266 * \param x floating point value. Must be greater than 0.
|
|
|
5267 * \returns the natural logarithm of `x`.
|
|
|
5268 *
|
|
|
5269 * \threadsafety It is safe to call this function from any thread.
|
|
|
5270 *
|
|
|
5271 * \since This function is available since SDL 3.2.0.
|
|
|
5272 *
|
|
|
5273 * \sa SDL_logf
|
|
|
5274 * \sa SDL_log10
|
|
|
5275 * \sa SDL_exp
|
|
|
5276 */
|
|
|
5277 extern SDL_DECLSPEC double SDLCALL SDL_log(double x);
|
|
|
5278
|
|
|
5279 /**
|
|
|
5280 * Compute the natural logarithm of `x`.
|
|
|
5281 *
|
|
|
5282 * Domain: `0 < x <= INF`
|
|
|
5283 *
|
|
|
5284 * Range: `-INF <= y <= INF`
|
|
|
5285 *
|
|
|
5286 * It is an error for `x` to be less than or equal to 0.
|
|
|
5287 *
|
|
|
5288 * This function operates on single-precision floating point values, use
|
|
|
5289 * SDL_log for double-precision floats.
|
|
|
5290 *
|
|
|
5291 * This function may use a different approximation across different versions,
|
|
|
5292 * platforms and configurations. i.e, it can return a different value given
|
|
|
5293 * the same input on different machines or operating systems, or if SDL is
|
|
|
5294 * updated.
|
|
|
5295 *
|
|
|
5296 * \param x floating point value. Must be greater than 0.
|
|
|
5297 * \returns the natural logarithm of `x`.
|
|
|
5298 *
|
|
|
5299 * \threadsafety It is safe to call this function from any thread.
|
|
|
5300 *
|
|
|
5301 * \since This function is available since SDL 3.2.0.
|
|
|
5302 *
|
|
|
5303 * \sa SDL_log
|
|
|
5304 * \sa SDL_expf
|
|
|
5305 */
|
|
|
5306 extern SDL_DECLSPEC float SDLCALL SDL_logf(float x);
|
|
|
5307
|
|
|
5308 /**
|
|
|
5309 * Compute the base-10 logarithm of `x`.
|
|
|
5310 *
|
|
|
5311 * Domain: `0 < x <= INF`
|
|
|
5312 *
|
|
|
5313 * Range: `-INF <= y <= INF`
|
|
|
5314 *
|
|
|
5315 * It is an error for `x` to be less than or equal to 0.
|
|
|
5316 *
|
|
|
5317 * This function operates on double-precision floating point values, use
|
|
|
5318 * SDL_log10f for single-precision floats.
|
|
|
5319 *
|
|
|
5320 * This function may use a different approximation across different versions,
|
|
|
5321 * platforms and configurations. i.e, it can return a different value given
|
|
|
5322 * the same input on different machines or operating systems, or if SDL is
|
|
|
5323 * updated.
|
|
|
5324 *
|
|
|
5325 * \param x floating point value. Must be greater than 0.
|
|
|
5326 * \returns the logarithm of `x`.
|
|
|
5327 *
|
|
|
5328 * \threadsafety It is safe to call this function from any thread.
|
|
|
5329 *
|
|
|
5330 * \since This function is available since SDL 3.2.0.
|
|
|
5331 *
|
|
|
5332 * \sa SDL_log10f
|
|
|
5333 * \sa SDL_log
|
|
|
5334 * \sa SDL_pow
|
|
|
5335 */
|
|
|
5336 extern SDL_DECLSPEC double SDLCALL SDL_log10(double x);
|
|
|
5337
|
|
|
5338 /**
|
|
|
5339 * Compute the base-10 logarithm of `x`.
|
|
|
5340 *
|
|
|
5341 * Domain: `0 < x <= INF`
|
|
|
5342 *
|
|
|
5343 * Range: `-INF <= y <= INF`
|
|
|
5344 *
|
|
|
5345 * It is an error for `x` to be less than or equal to 0.
|
|
|
5346 *
|
|
|
5347 * This function operates on single-precision floating point values, use
|
|
|
5348 * SDL_log10 for double-precision floats.
|
|
|
5349 *
|
|
|
5350 * This function may use a different approximation across different versions,
|
|
|
5351 * platforms and configurations. i.e, it can return a different value given
|
|
|
5352 * the same input on different machines or operating systems, or if SDL is
|
|
|
5353 * updated.
|
|
|
5354 *
|
|
|
5355 * \param x floating point value. Must be greater than 0.
|
|
|
5356 * \returns the logarithm of `x`.
|
|
|
5357 *
|
|
|
5358 * \threadsafety It is safe to call this function from any thread.
|
|
|
5359 *
|
|
|
5360 * \since This function is available since SDL 3.2.0.
|
|
|
5361 *
|
|
|
5362 * \sa SDL_log10
|
|
|
5363 * \sa SDL_logf
|
|
|
5364 * \sa SDL_powf
|
|
|
5365 */
|
|
|
5366 extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x);
|
|
|
5367
|
|
|
5368 /**
|
|
|
5369 * Split `x` into integer and fractional parts
|
|
|
5370 *
|
|
|
5371 * This function operates on double-precision floating point values, use
|
|
|
5372 * SDL_modff for single-precision floats.
|
|
|
5373 *
|
|
|
5374 * \param x floating point value.
|
|
|
5375 * \param y output pointer to store the integer part of `x`.
|
|
|
5376 * \returns the fractional part of `x`.
|
|
|
5377 *
|
|
|
5378 * \threadsafety It is safe to call this function from any thread.
|
|
|
5379 *
|
|
|
5380 * \since This function is available since SDL 3.2.0.
|
|
|
5381 *
|
|
|
5382 * \sa SDL_modff
|
|
|
5383 * \sa SDL_trunc
|
|
|
5384 * \sa SDL_fmod
|
|
|
5385 */
|
|
|
5386 extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y);
|
|
|
5387
|
|
|
5388 /**
|
|
|
5389 * Split `x` into integer and fractional parts
|
|
|
5390 *
|
|
|
5391 * This function operates on single-precision floating point values, use
|
|
|
5392 * SDL_modf for double-precision floats.
|
|
|
5393 *
|
|
|
5394 * \param x floating point value.
|
|
|
5395 * \param y output pointer to store the integer part of `x`.
|
|
|
5396 * \returns the fractional part of `x`.
|
|
|
5397 *
|
|
|
5398 * \threadsafety It is safe to call this function from any thread.
|
|
|
5399 *
|
|
|
5400 * \since This function is available since SDL 3.2.0.
|
|
|
5401 *
|
|
|
5402 * \sa SDL_modf
|
|
|
5403 * \sa SDL_truncf
|
|
|
5404 * \sa SDL_fmodf
|
|
|
5405 */
|
|
|
5406 extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y);
|
|
|
5407
|
|
|
5408 /**
|
|
|
5409 * Raise `x` to the power `y`
|
|
|
5410 *
|
|
|
5411 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
|
|
|
5412 *
|
|
|
5413 * Range: `-INF <= z <= INF`
|
|
|
5414 *
|
|
|
5415 * If `y` is the base of the natural logarithm (e), consider using SDL_exp
|
|
|
5416 * instead.
|
|
|
5417 *
|
|
|
5418 * This function operates on double-precision floating point values, use
|
|
|
5419 * SDL_powf for single-precision floats.
|
|
|
5420 *
|
|
|
5421 * This function may use a different approximation across different versions,
|
|
|
5422 * platforms and configurations. i.e, it can return a different value given
|
|
|
5423 * the same input on different machines or operating systems, or if SDL is
|
|
|
5424 * updated.
|
|
|
5425 *
|
|
|
5426 * \param x the base.
|
|
|
5427 * \param y the exponent.
|
|
|
5428 * \returns `x` raised to the power `y`.
|
|
|
5429 *
|
|
|
5430 * \threadsafety It is safe to call this function from any thread.
|
|
|
5431 *
|
|
|
5432 * \since This function is available since SDL 3.2.0.
|
|
|
5433 *
|
|
|
5434 * \sa SDL_powf
|
|
|
5435 * \sa SDL_exp
|
|
|
5436 * \sa SDL_log
|
|
|
5437 */
|
|
|
5438 extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y);
|
|
|
5439
|
|
|
5440 /**
|
|
|
5441 * Raise `x` to the power `y`
|
|
|
5442 *
|
|
|
5443 * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
|
|
|
5444 *
|
|
|
5445 * Range: `-INF <= z <= INF`
|
|
|
5446 *
|
|
|
5447 * If `y` is the base of the natural logarithm (e), consider using SDL_exp
|
|
|
5448 * instead.
|
|
|
5449 *
|
|
|
5450 * This function operates on single-precision floating point values, use
|
|
|
5451 * SDL_pow for double-precision floats.
|
|
|
5452 *
|
|
|
5453 * This function may use a different approximation across different versions,
|
|
|
5454 * platforms and configurations. i.e, it can return a different value given
|
|
|
5455 * the same input on different machines or operating systems, or if SDL is
|
|
|
5456 * updated.
|
|
|
5457 *
|
|
|
5458 * \param x the base.
|
|
|
5459 * \param y the exponent.
|
|
|
5460 * \returns `x` raised to the power `y`.
|
|
|
5461 *
|
|
|
5462 * \threadsafety It is safe to call this function from any thread.
|
|
|
5463 *
|
|
|
5464 * \since This function is available since SDL 3.2.0.
|
|
|
5465 *
|
|
|
5466 * \sa SDL_pow
|
|
|
5467 * \sa SDL_expf
|
|
|
5468 * \sa SDL_logf
|
|
|
5469 */
|
|
|
5470 extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y);
|
|
|
5471
|
|
|
5472 /**
|
|
|
5473 * Round `x` to the nearest integer.
|
|
|
5474 *
|
|
|
5475 * Rounds `x` to the nearest integer. Values halfway between integers will be
|
|
|
5476 * rounded away from zero.
|
|
|
5477 *
|
|
|
5478 * Domain: `-INF <= x <= INF`
|
|
|
5479 *
|
|
|
5480 * Range: `-INF <= y <= INF`, y integer
|
|
|
5481 *
|
|
|
5482 * This function operates on double-precision floating point values, use
|
|
|
5483 * SDL_roundf for single-precision floats. To get the result as an integer
|
|
|
5484 * type, use SDL_lround.
|
|
|
5485 *
|
|
|
5486 * \param x floating point value.
|
|
|
5487 * \returns the nearest integer to `x`.
|
|
|
5488 *
|
|
|
5489 * \threadsafety It is safe to call this function from any thread.
|
|
|
5490 *
|
|
|
5491 * \since This function is available since SDL 3.2.0.
|
|
|
5492 *
|
|
|
5493 * \sa SDL_roundf
|
|
|
5494 * \sa SDL_lround
|
|
|
5495 * \sa SDL_floor
|
|
|
5496 * \sa SDL_ceil
|
|
|
5497 * \sa SDL_trunc
|
|
|
5498 */
|
|
|
5499 extern SDL_DECLSPEC double SDLCALL SDL_round(double x);
|
|
|
5500
|
|
|
5501 /**
|
|
|
5502 * Round `x` to the nearest integer.
|
|
|
5503 *
|
|
|
5504 * Rounds `x` to the nearest integer. Values halfway between integers will be
|
|
|
5505 * rounded away from zero.
|
|
|
5506 *
|
|
|
5507 * Domain: `-INF <= x <= INF`
|
|
|
5508 *
|
|
|
5509 * Range: `-INF <= y <= INF`, y integer
|
|
|
5510 *
|
|
|
5511 * This function operates on single-precision floating point values, use
|
|
|
5512 * SDL_round for double-precision floats. To get the result as an integer
|
|
|
5513 * type, use SDL_lroundf.
|
|
|
5514 *
|
|
|
5515 * \param x floating point value.
|
|
|
5516 * \returns the nearest integer to `x`.
|
|
|
5517 *
|
|
|
5518 * \threadsafety It is safe to call this function from any thread.
|
|
|
5519 *
|
|
|
5520 * \since This function is available since SDL 3.2.0.
|
|
|
5521 *
|
|
|
5522 * \sa SDL_round
|
|
|
5523 * \sa SDL_lroundf
|
|
|
5524 * \sa SDL_floorf
|
|
|
5525 * \sa SDL_ceilf
|
|
|
5526 * \sa SDL_truncf
|
|
|
5527 */
|
|
|
5528 extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x);
|
|
|
5529
|
|
|
5530 /**
|
|
|
5531 * Round `x` to the nearest integer representable as a long
|
|
|
5532 *
|
|
|
5533 * Rounds `x` to the nearest integer. Values halfway between integers will be
|
|
|
5534 * rounded away from zero.
|
|
|
5535 *
|
|
|
5536 * Domain: `-INF <= x <= INF`
|
|
|
5537 *
|
|
|
5538 * Range: `MIN_LONG <= y <= MAX_LONG`
|
|
|
5539 *
|
|
|
5540 * This function operates on double-precision floating point values, use
|
|
|
5541 * SDL_lroundf for single-precision floats. To get the result as a
|
|
|
5542 * floating-point type, use SDL_round.
|
|
|
5543 *
|
|
|
5544 * \param x floating point value.
|
|
|
5545 * \returns the nearest integer to `x`.
|
|
|
5546 *
|
|
|
5547 * \threadsafety It is safe to call this function from any thread.
|
|
|
5548 *
|
|
|
5549 * \since This function is available since SDL 3.2.0.
|
|
|
5550 *
|
|
|
5551 * \sa SDL_lroundf
|
|
|
5552 * \sa SDL_round
|
|
|
5553 * \sa SDL_floor
|
|
|
5554 * \sa SDL_ceil
|
|
|
5555 * \sa SDL_trunc
|
|
|
5556 */
|
|
|
5557 extern SDL_DECLSPEC long SDLCALL SDL_lround(double x);
|
|
|
5558
|
|
|
5559 /**
|
|
|
5560 * Round `x` to the nearest integer representable as a long
|
|
|
5561 *
|
|
|
5562 * Rounds `x` to the nearest integer. Values halfway between integers will be
|
|
|
5563 * rounded away from zero.
|
|
|
5564 *
|
|
|
5565 * Domain: `-INF <= x <= INF`
|
|
|
5566 *
|
|
|
5567 * Range: `MIN_LONG <= y <= MAX_LONG`
|
|
|
5568 *
|
|
|
5569 * This function operates on single-precision floating point values, use
|
|
|
5570 * SDL_lround for double-precision floats. To get the result as a
|
|
|
5571 * floating-point type, use SDL_roundf.
|
|
|
5572 *
|
|
|
5573 * \param x floating point value.
|
|
|
5574 * \returns the nearest integer to `x`.
|
|
|
5575 *
|
|
|
5576 * \threadsafety It is safe to call this function from any thread.
|
|
|
5577 *
|
|
|
5578 * \since This function is available since SDL 3.2.0.
|
|
|
5579 *
|
|
|
5580 * \sa SDL_lround
|
|
|
5581 * \sa SDL_roundf
|
|
|
5582 * \sa SDL_floorf
|
|
|
5583 * \sa SDL_ceilf
|
|
|
5584 * \sa SDL_truncf
|
|
|
5585 */
|
|
|
5586 extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x);
|
|
|
5587
|
|
|
5588 /**
|
|
|
5589 * Scale `x` by an integer power of two.
|
|
|
5590 *
|
|
|
5591 * Multiplies `x` by the `n`th power of the floating point radix (always 2).
|
|
|
5592 *
|
|
|
5593 * Domain: `-INF <= x <= INF`, `n` integer
|
|
|
5594 *
|
|
|
5595 * Range: `-INF <= y <= INF`
|
|
|
5596 *
|
|
|
5597 * This function operates on double-precision floating point values, use
|
|
|
5598 * SDL_scalbnf for single-precision floats.
|
|
|
5599 *
|
|
|
5600 * \param x floating point value to be scaled.
|
|
|
5601 * \param n integer exponent.
|
|
|
5602 * \returns `x * 2^n`.
|
|
|
5603 *
|
|
|
5604 * \threadsafety It is safe to call this function from any thread.
|
|
|
5605 *
|
|
|
5606 * \since This function is available since SDL 3.2.0.
|
|
|
5607 *
|
|
|
5608 * \sa SDL_scalbnf
|
|
|
5609 * \sa SDL_pow
|
|
|
5610 */
|
|
|
5611 extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n);
|
|
|
5612
|
|
|
5613 /**
|
|
|
5614 * Scale `x` by an integer power of two.
|
|
|
5615 *
|
|
|
5616 * Multiplies `x` by the `n`th power of the floating point radix (always 2).
|
|
|
5617 *
|
|
|
5618 * Domain: `-INF <= x <= INF`, `n` integer
|
|
|
5619 *
|
|
|
5620 * Range: `-INF <= y <= INF`
|
|
|
5621 *
|
|
|
5622 * This function operates on single-precision floating point values, use
|
|
|
5623 * SDL_scalbn for double-precision floats.
|
|
|
5624 *
|
|
|
5625 * \param x floating point value to be scaled.
|
|
|
5626 * \param n integer exponent.
|
|
|
5627 * \returns `x * 2^n`.
|
|
|
5628 *
|
|
|
5629 * \threadsafety It is safe to call this function from any thread.
|
|
|
5630 *
|
|
|
5631 * \since This function is available since SDL 3.2.0.
|
|
|
5632 *
|
|
|
5633 * \sa SDL_scalbn
|
|
|
5634 * \sa SDL_powf
|
|
|
5635 */
|
|
|
5636 extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n);
|
|
|
5637
|
|
|
5638 /**
|
|
|
5639 * Compute the sine of `x`.
|
|
|
5640 *
|
|
|
5641 * Domain: `-INF <= x <= INF`
|
|
|
5642 *
|
|
|
5643 * Range: `-1 <= y <= 1`
|
|
|
5644 *
|
|
|
5645 * This function operates on double-precision floating point values, use
|
|
|
5646 * SDL_sinf for single-precision floats.
|
|
|
5647 *
|
|
|
5648 * This function may use a different approximation across different versions,
|
|
|
5649 * platforms and configurations. i.e, it can return a different value given
|
|
|
5650 * the same input on different machines or operating systems, or if SDL is
|
|
|
5651 * updated.
|
|
|
5652 *
|
|
|
5653 * \param x floating point value, in radians.
|
|
|
5654 * \returns sine of `x`.
|
|
|
5655 *
|
|
|
5656 * \threadsafety It is safe to call this function from any thread.
|
|
|
5657 *
|
|
|
5658 * \since This function is available since SDL 3.2.0.
|
|
|
5659 *
|
|
|
5660 * \sa SDL_sinf
|
|
|
5661 * \sa SDL_asin
|
|
|
5662 * \sa SDL_cos
|
|
|
5663 */
|
|
|
5664 extern SDL_DECLSPEC double SDLCALL SDL_sin(double x);
|
|
|
5665
|
|
|
5666 /**
|
|
|
5667 * Compute the sine of `x`.
|
|
|
5668 *
|
|
|
5669 * Domain: `-INF <= x <= INF`
|
|
|
5670 *
|
|
|
5671 * Range: `-1 <= y <= 1`
|
|
|
5672 *
|
|
|
5673 * This function operates on single-precision floating point values, use
|
|
|
5674 * SDL_sin for double-precision floats.
|
|
|
5675 *
|
|
|
5676 * This function may use a different approximation across different versions,
|
|
|
5677 * platforms and configurations. i.e, it can return a different value given
|
|
|
5678 * the same input on different machines or operating systems, or if SDL is
|
|
|
5679 * updated.
|
|
|
5680 *
|
|
|
5681 * \param x floating point value, in radians.
|
|
|
5682 * \returns sine of `x`.
|
|
|
5683 *
|
|
|
5684 * \threadsafety It is safe to call this function from any thread.
|
|
|
5685 *
|
|
|
5686 * \since This function is available since SDL 3.2.0.
|
|
|
5687 *
|
|
|
5688 * \sa SDL_sin
|
|
|
5689 * \sa SDL_asinf
|
|
|
5690 * \sa SDL_cosf
|
|
|
5691 */
|
|
|
5692 extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x);
|
|
|
5693
|
|
|
5694 /**
|
|
|
5695 * Compute the square root of `x`.
|
|
|
5696 *
|
|
|
5697 * Domain: `0 <= x <= INF`
|
|
|
5698 *
|
|
|
5699 * Range: `0 <= y <= INF`
|
|
|
5700 *
|
|
|
5701 * This function operates on double-precision floating point values, use
|
|
|
5702 * SDL_sqrtf for single-precision floats.
|
|
|
5703 *
|
|
|
5704 * This function may use a different approximation across different versions,
|
|
|
5705 * platforms and configurations. i.e, it can return a different value given
|
|
|
5706 * the same input on different machines or operating systems, or if SDL is
|
|
|
5707 * updated.
|
|
|
5708 *
|
|
|
5709 * \param x floating point value. Must be greater than or equal to 0.
|
|
|
5710 * \returns square root of `x`.
|
|
|
5711 *
|
|
|
5712 * \threadsafety It is safe to call this function from any thread.
|
|
|
5713 *
|
|
|
5714 * \since This function is available since SDL 3.2.0.
|
|
|
5715 *
|
|
|
5716 * \sa SDL_sqrtf
|
|
|
5717 */
|
|
|
5718 extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x);
|
|
|
5719
|
|
|
5720 /**
|
|
|
5721 * Compute the square root of `x`.
|
|
|
5722 *
|
|
|
5723 * Domain: `0 <= x <= INF`
|
|
|
5724 *
|
|
|
5725 * Range: `0 <= y <= INF`
|
|
|
5726 *
|
|
|
5727 * This function operates on single-precision floating point values, use
|
|
|
5728 * SDL_sqrt for double-precision floats.
|
|
|
5729 *
|
|
|
5730 * This function may use a different approximation across different versions,
|
|
|
5731 * platforms and configurations. i.e, it can return a different value given
|
|
|
5732 * the same input on different machines or operating systems, or if SDL is
|
|
|
5733 * updated.
|
|
|
5734 *
|
|
|
5735 * \param x floating point value. Must be greater than or equal to 0.
|
|
|
5736 * \returns square root of `x`.
|
|
|
5737 *
|
|
|
5738 * \threadsafety It is safe to call this function from any thread.
|
|
|
5739 *
|
|
|
5740 * \since This function is available since SDL 3.2.0.
|
|
|
5741 *
|
|
|
5742 * \sa SDL_sqrt
|
|
|
5743 */
|
|
|
5744 extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x);
|
|
|
5745
|
|
|
5746 /**
|
|
|
5747 * Compute the tangent of `x`.
|
|
|
5748 *
|
|
|
5749 * Domain: `-INF <= x <= INF`
|
|
|
5750 *
|
|
|
5751 * Range: `-INF <= y <= INF`
|
|
|
5752 *
|
|
|
5753 * This function operates on double-precision floating point values, use
|
|
|
5754 * SDL_tanf for single-precision floats.
|
|
|
5755 *
|
|
|
5756 * This function may use a different approximation across different versions,
|
|
|
5757 * platforms and configurations. i.e, it can return a different value given
|
|
|
5758 * the same input on different machines or operating systems, or if SDL is
|
|
|
5759 * updated.
|
|
|
5760 *
|
|
|
5761 * \param x floating point value, in radians.
|
|
|
5762 * \returns tangent of `x`.
|
|
|
5763 *
|
|
|
5764 * \threadsafety It is safe to call this function from any thread.
|
|
|
5765 *
|
|
|
5766 * \since This function is available since SDL 3.2.0.
|
|
|
5767 *
|
|
|
5768 * \sa SDL_tanf
|
|
|
5769 * \sa SDL_sin
|
|
|
5770 * \sa SDL_cos
|
|
|
5771 * \sa SDL_atan
|
|
|
5772 * \sa SDL_atan2
|
|
|
5773 */
|
|
|
5774 extern SDL_DECLSPEC double SDLCALL SDL_tan(double x);
|
|
|
5775
|
|
|
5776 /**
|
|
|
5777 * Compute the tangent of `x`.
|
|
|
5778 *
|
|
|
5779 * Domain: `-INF <= x <= INF`
|
|
|
5780 *
|
|
|
5781 * Range: `-INF <= y <= INF`
|
|
|
5782 *
|
|
|
5783 * This function operates on single-precision floating point values, use
|
|
|
5784 * SDL_tan for double-precision floats.
|
|
|
5785 *
|
|
|
5786 * This function may use a different approximation across different versions,
|
|
|
5787 * platforms and configurations. i.e, it can return a different value given
|
|
|
5788 * the same input on different machines or operating systems, or if SDL is
|
|
|
5789 * updated.
|
|
|
5790 *
|
|
|
5791 * \param x floating point value, in radians.
|
|
|
5792 * \returns tangent of `x`.
|
|
|
5793 *
|
|
|
5794 * \threadsafety It is safe to call this function from any thread.
|
|
|
5795 *
|
|
|
5796 * \since This function is available since SDL 3.2.0.
|
|
|
5797 *
|
|
|
5798 * \sa SDL_tan
|
|
|
5799 * \sa SDL_sinf
|
|
|
5800 * \sa SDL_cosf
|
|
|
5801 * \sa SDL_atanf
|
|
|
5802 * \sa SDL_atan2f
|
|
|
5803 */
|
|
|
5804 extern SDL_DECLSPEC float SDLCALL SDL_tanf(float x);
|
|
|
5805
|
|
|
5806 /**
|
|
|
5807 * An opaque handle representing string encoding conversion state.
|
|
|
5808 *
|
|
|
5809 * \since This datatype is available since SDL 3.2.0.
|
|
|
5810 *
|
|
|
5811 * \sa SDL_iconv_open
|
|
|
5812 */
|
|
|
5813 typedef struct SDL_iconv_data_t *SDL_iconv_t;
|
|
|
5814
|
|
|
5815 /**
|
|
|
5816 * This function allocates a context for the specified character set
|
|
|
5817 * conversion.
|
|
|
5818 *
|
|
|
5819 * \param tocode The target character encoding, must not be NULL.
|
|
|
5820 * \param fromcode The source character encoding, must not be NULL.
|
|
|
5821 * \returns a handle that must be freed with SDL_iconv_close, or
|
|
|
5822 * SDL_ICONV_ERROR on failure.
|
|
|
5823 *
|
|
|
5824 * \since This function is available since SDL 3.2.0.
|
|
|
5825 *
|
|
|
5826 * \sa SDL_iconv
|
|
|
5827 * \sa SDL_iconv_close
|
|
|
5828 * \sa SDL_iconv_string
|
|
|
5829 */
|
|
|
5830 extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode,
|
|
|
5831 const char *fromcode);
|
|
|
5832
|
|
|
5833 /**
|
|
|
5834 * This function frees a context used for character set conversion.
|
|
|
5835 *
|
|
|
5836 * \param cd The character set conversion handle.
|
|
|
5837 * \returns 0 on success, or -1 on failure.
|
|
|
5838 *
|
|
|
5839 * \since This function is available since SDL 3.2.0.
|
|
|
5840 *
|
|
|
5841 * \sa SDL_iconv
|
|
|
5842 * \sa SDL_iconv_open
|
|
|
5843 * \sa SDL_iconv_string
|
|
|
5844 */
|
|
|
5845 extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd);
|
|
|
5846
|
|
|
5847 /**
|
|
|
5848 * This function converts text between encodings, reading from and writing to
|
|
|
5849 * a buffer.
|
|
|
5850 *
|
|
|
5851 * It returns the number of successful conversions on success. On error,
|
|
|
5852 * SDL_ICONV_E2BIG is returned when the output buffer is too small, or
|
|
|
5853 * SDL_ICONV_EILSEQ is returned when an invalid input sequence is encountered,
|
|
|
5854 * or SDL_ICONV_EINVAL is returned when an incomplete input sequence is
|
|
|
5855 * encountered.
|
|
|
5856 *
|
|
|
5857 * On exit:
|
|
|
5858 *
|
|
|
5859 * - inbuf will point to the beginning of the next multibyte sequence. On
|
|
|
5860 * error, this is the location of the problematic input sequence. On
|
|
|
5861 * success, this is the end of the input sequence.
|
|
|
5862 * - inbytesleft will be set to the number of bytes left to convert, which
|
|
|
5863 * will be 0 on success.
|
|
|
5864 * - outbuf will point to the location where to store the next output byte.
|
|
|
5865 * - outbytesleft will be set to the number of bytes left in the output
|
|
|
5866 * buffer.
|
|
|
5867 *
|
|
|
5868 * \param cd The character set conversion context, created in
|
|
|
5869 * SDL_iconv_open().
|
|
|
5870 * \param inbuf Address of variable that points to the first character of the
|
|
|
5871 * input sequence.
|
|
|
5872 * \param inbytesleft The number of bytes in the input buffer.
|
|
|
5873 * \param outbuf Address of variable that points to the output buffer.
|
|
|
5874 * \param outbytesleft The number of bytes in the output buffer.
|
|
|
5875 * \returns the number of conversions on success, or a negative error code.
|
|
|
5876 *
|
|
|
5877 * \since This function is available since SDL 3.2.0.
|
|
|
5878 *
|
|
|
5879 * \sa SDL_iconv_open
|
|
|
5880 * \sa SDL_iconv_close
|
|
|
5881 * \sa SDL_iconv_string
|
|
|
5882 */
|
|
|
5883 extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
|
|
|
5884 size_t *inbytesleft, char **outbuf,
|
|
|
5885 size_t *outbytesleft);
|
|
|
5886
|
|
|
5887 #define SDL_ICONV_ERROR (size_t)-1 /**< Generic error. Check SDL_GetError()? */
|
|
|
5888 #define SDL_ICONV_E2BIG (size_t)-2 /**< Output buffer was too small. */
|
|
|
5889 #define SDL_ICONV_EILSEQ (size_t)-3 /**< Invalid input sequence was encountered. */
|
|
|
5890 #define SDL_ICONV_EINVAL (size_t)-4 /**< Incomplete input sequence was encountered. */
|
|
|
5891
|
|
|
5892
|
|
|
5893 /**
|
|
|
5894 * Helper function to convert a string's encoding in one call.
|
|
|
5895 *
|
|
|
5896 * This function converts a buffer or string between encodings in one pass.
|
|
|
5897 *
|
|
|
5898 * The string does not need to be NULL-terminated; this function operates on
|
|
|
5899 * the number of bytes specified in `inbytesleft` whether there is a NULL
|
|
|
5900 * character anywhere in the buffer.
|
|
|
5901 *
|
|
|
5902 * The returned string is owned by the caller, and should be passed to
|
|
|
5903 * SDL_free when no longer needed.
|
|
|
5904 *
|
|
|
5905 * \param tocode the character encoding of the output string. Examples are
|
|
|
5906 * "UTF-8", "UCS-4", etc.
|
|
|
5907 * \param fromcode the character encoding of data in `inbuf`.
|
|
|
5908 * \param inbuf the string to convert to a different encoding.
|
|
|
5909 * \param inbytesleft the size of the input string _in bytes_.
|
|
|
5910 * \returns a new string, converted to the new encoding, or NULL on error.
|
|
|
5911 *
|
|
|
5912 * \since This function is available since SDL 3.2.0.
|
|
|
5913 *
|
|
|
5914 * \sa SDL_iconv_open
|
|
|
5915 * \sa SDL_iconv_close
|
|
|
5916 * \sa SDL_iconv
|
|
|
5917 */
|
|
|
5918 extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode,
|
|
|
5919 const char *fromcode,
|
|
|
5920 const char *inbuf,
|
|
|
5921 size_t inbytesleft);
|
|
|
5922
|
|
|
5923 /* Some helper macros for common SDL_iconv_string cases... */
|
|
|
5924
|
|
|
5925 /**
|
|
|
5926 * Convert a UTF-8 string to the current locale's character encoding.
|
|
|
5927 *
|
|
|
5928 * This is a helper macro that might be more clear than calling
|
|
|
5929 * SDL_iconv_string directly. However, it double-evaluates its parameter, so
|
|
|
5930 * do not use an expression with side-effects here.
|
|
|
5931 *
|
|
|
5932 * \param S the string to convert.
|
|
|
5933 * \returns a new string, converted to the new encoding, or NULL on error.
|
|
|
5934 *
|
|
|
5935 * \since This macro is available since SDL 3.2.0.
|
|
|
5936 */
|
|
|
5937 #define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1)
|
|
|
5938
|
|
|
5939 /**
|
|
|
5940 * Convert a UTF-8 string to UCS-2.
|
|
|
5941 *
|
|
|
5942 * This is a helper macro that might be more clear than calling
|
|
|
5943 * SDL_iconv_string directly. However, it double-evaluates its parameter, so
|
|
|
5944 * do not use an expression with side-effects here.
|
|
|
5945 *
|
|
|
5946 * \param S the string to convert.
|
|
|
5947 * \returns a new string, converted to the new encoding, or NULL on error.
|
|
|
5948 *
|
|
|
5949 * \since This macro is available since SDL 3.2.0.
|
|
|
5950 */
|
|
|
5951 #define SDL_iconv_utf8_ucs2(S) SDL_reinterpret_cast(Uint16 *, SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1))
|
|
|
5952
|
|
|
5953 /**
|
|
|
5954 * Convert a UTF-8 string to UCS-4.
|
|
|
5955 *
|
|
|
5956 * This is a helper macro that might be more clear than calling
|
|
|
5957 * SDL_iconv_string directly. However, it double-evaluates its parameter, so
|
|
|
5958 * do not use an expression with side-effects here.
|
|
|
5959 *
|
|
|
5960 * \param S the string to convert.
|
|
|
5961 * \returns a new string, converted to the new encoding, or NULL on error.
|
|
|
5962 *
|
|
|
5963 * \since This macro is available since SDL 3.2.0.
|
|
|
5964 */
|
|
|
5965 #define SDL_iconv_utf8_ucs4(S) SDL_reinterpret_cast(Uint32 *, SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1))
|
|
|
5966
|
|
|
5967 /**
|
|
|
5968 * Convert a wchar_t string to UTF-8.
|
|
|
5969 *
|
|
|
5970 * This is a helper macro that might be more clear than calling
|
|
|
5971 * SDL_iconv_string directly. However, it double-evaluates its parameter, so
|
|
|
5972 * do not use an expression with side-effects here.
|
|
|
5973 *
|
|
|
5974 * \param S the string to convert.
|
|
|
5975 * \returns a new string, converted to the new encoding, or NULL on error.
|
|
|
5976 *
|
|
|
5977 * \since This macro is available since SDL 3.2.0.
|
|
|
5978 */
|
|
|
5979 #define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", SDL_reinterpret_cast(const char *, S), (SDL_wcslen(S)+1)*sizeof(wchar_t))
|
|
|
5980
|
|
|
5981
|
|
|
5982 /* force builds using Clang's static analysis tools to use literal C runtime
|
|
|
5983 here, since there are possibly tests that are ineffective otherwise. */
|
|
|
5984 #if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS)
|
|
|
5985
|
|
|
5986 /* The analyzer knows about strlcpy even when the system doesn't provide it */
|
|
|
5987 #if !defined(HAVE_STRLCPY) && !defined(strlcpy)
|
|
|
5988 size_t strlcpy(char *dst, const char *src, size_t size);
|
|
|
5989 #endif
|
|
|
5990
|
|
|
5991 /* The analyzer knows about strlcat even when the system doesn't provide it */
|
|
|
5992 #if !defined(HAVE_STRLCAT) && !defined(strlcat)
|
|
|
5993 size_t strlcat(char *dst, const char *src, size_t size);
|
|
|
5994 #endif
|
|
|
5995
|
|
|
5996 #if !defined(HAVE_WCSLCPY) && !defined(wcslcpy)
|
|
|
5997 size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size);
|
|
|
5998 #endif
|
|
|
5999
|
|
|
6000 #if !defined(HAVE_WCSLCAT) && !defined(wcslcat)
|
|
|
6001 size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size);
|
|
|
6002 #endif
|
|
|
6003
|
|
|
6004 #if !defined(HAVE_STRTOK_R) && !defined(strtok_r)
|
|
|
6005 char *strtok_r(char *str, const char *delim, char **saveptr);
|
|
|
6006 #endif
|
|
|
6007
|
|
|
6008 #ifndef _WIN32
|
|
|
6009 /* strdup is not ANSI but POSIX, and its prototype might be hidden... */
|
|
|
6010 /* not for windows: might conflict with string.h where strdup may have
|
|
|
6011 * dllimport attribute: https://github.com/libsdl-org/SDL/issues/12948 */
|
|
|
6012 char *strdup(const char *str);
|
|
|
6013 #endif
|
|
|
6014
|
|
|
6015 /* Starting LLVM 16, the analyser errors out if these functions do not have
|
|
|
6016 their prototype defined (clang-diagnostic-implicit-function-declaration) */
|
|
|
6017 #include <stdio.h>
|
|
|
6018 #include <stdlib.h>
|
|
|
6019
|
|
|
6020 #define SDL_malloc malloc
|
|
|
6021 #define SDL_calloc calloc
|
|
|
6022 #define SDL_realloc realloc
|
|
|
6023 #define SDL_free free
|
|
|
6024 #ifndef SDL_memcpy
|
|
|
6025 #define SDL_memcpy memcpy
|
|
|
6026 #endif
|
|
|
6027 #ifndef SDL_memmove
|
|
|
6028 #define SDL_memmove memmove
|
|
|
6029 #endif
|
|
|
6030 #ifndef SDL_memset
|
|
|
6031 #define SDL_memset memset
|
|
|
6032 #endif
|
|
|
6033 #define SDL_memcmp memcmp
|
|
|
6034 #define SDL_strlcpy strlcpy
|
|
|
6035 #define SDL_strlcat strlcat
|
|
|
6036 #define SDL_strlen strlen
|
|
|
6037 #define SDL_wcslen wcslen
|
|
|
6038 #define SDL_wcslcpy wcslcpy
|
|
|
6039 #define SDL_wcslcat wcslcat
|
|
|
6040 #define SDL_strdup strdup
|
|
|
6041 #define SDL_wcsdup wcsdup
|
|
|
6042 #define SDL_strchr strchr
|
|
|
6043 #define SDL_strrchr strrchr
|
|
|
6044 #define SDL_strstr strstr
|
|
|
6045 #define SDL_wcsstr wcsstr
|
|
|
6046 #define SDL_strtok_r strtok_r
|
|
|
6047 #define SDL_strcmp strcmp
|
|
|
6048 #define SDL_wcscmp wcscmp
|
|
|
6049 #define SDL_strncmp strncmp
|
|
|
6050 #define SDL_wcsncmp wcsncmp
|
|
|
6051 #define SDL_strcasecmp strcasecmp
|
|
|
6052 #define SDL_strncasecmp strncasecmp
|
|
|
6053 #define SDL_strpbrk strpbrk
|
|
|
6054 #define SDL_sscanf sscanf
|
|
|
6055 #define SDL_vsscanf vsscanf
|
|
|
6056 #define SDL_snprintf snprintf
|
|
|
6057 #define SDL_vsnprintf vsnprintf
|
|
|
6058 #endif
|
|
|
6059
|
|
|
6060 /**
|
|
|
6061 * Multiply two integers, checking for overflow.
|
|
|
6062 *
|
|
|
6063 * If `a * b` would overflow, return false.
|
|
|
6064 *
|
|
|
6065 * Otherwise store `a * b` via ret and return true.
|
|
|
6066 *
|
|
|
6067 * \param a the multiplicand.
|
|
|
6068 * \param b the multiplier.
|
|
|
6069 * \param ret on non-overflow output, stores the multiplication result, may
|
|
|
6070 * not be NULL.
|
|
|
6071 * \returns false on overflow, true if result is multiplied without overflow.
|
|
|
6072 *
|
|
|
6073 * \threadsafety It is safe to call this function from any thread.
|
|
|
6074 *
|
|
|
6075 * \since This function is available since SDL 3.2.0.
|
|
|
6076 */
|
|
|
6077 SDL_FORCE_INLINE bool SDL_size_mul_check_overflow(size_t a, size_t b, size_t *ret)
|
|
|
6078 {
|
|
|
6079 if (a != 0 && b > SDL_SIZE_MAX / a) {
|
|
|
6080 return false;
|
|
|
6081 }
|
|
|
6082 *ret = a * b;
|
|
|
6083 return true;
|
|
|
6084 }
|
|
|
6085
|
|
|
6086 #ifndef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
6087 #if SDL_HAS_BUILTIN(__builtin_mul_overflow)
|
|
|
6088 /* This needs to be wrapped in an inline rather than being a direct #define,
|
|
|
6089 * because __builtin_mul_overflow() is type-generic, but we want to be
|
|
|
6090 * consistent about interpreting a and b as size_t. */
|
|
|
6091 SDL_FORCE_INLINE bool SDL_size_mul_check_overflow_builtin(size_t a, size_t b, size_t *ret)
|
|
|
6092 {
|
|
|
6093 return (__builtin_mul_overflow(a, b, ret) == 0);
|
|
|
6094 }
|
|
|
6095 #define SDL_size_mul_check_overflow(a, b, ret) SDL_size_mul_check_overflow_builtin(a, b, ret)
|
|
|
6096 #endif
|
|
|
6097 #endif
|
|
|
6098
|
|
|
6099 /**
|
|
|
6100 * Add two integers, checking for overflow.
|
|
|
6101 *
|
|
|
6102 * If `a + b` would overflow, return false.
|
|
|
6103 *
|
|
|
6104 * Otherwise store `a + b` via ret and return true.
|
|
|
6105 *
|
|
|
6106 * \param a the first addend.
|
|
|
6107 * \param b the second addend.
|
|
|
6108 * \param ret on non-overflow output, stores the addition result, may not be
|
|
|
6109 * NULL.
|
|
|
6110 * \returns false on overflow, true if result is added without overflow.
|
|
|
6111 *
|
|
|
6112 * \threadsafety It is safe to call this function from any thread.
|
|
|
6113 *
|
|
|
6114 * \since This function is available since SDL 3.2.0.
|
|
|
6115 */
|
|
|
6116 SDL_FORCE_INLINE bool SDL_size_add_check_overflow(size_t a, size_t b, size_t *ret)
|
|
|
6117 {
|
|
|
6118 if (b > SDL_SIZE_MAX - a) {
|
|
|
6119 return false;
|
|
|
6120 }
|
|
|
6121 *ret = a + b;
|
|
|
6122 return true;
|
|
|
6123 }
|
|
|
6124
|
|
|
6125 #ifndef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
6126 #if SDL_HAS_BUILTIN(__builtin_add_overflow)
|
|
|
6127 /* This needs to be wrapped in an inline rather than being a direct #define,
|
|
|
6128 * the same as the call to __builtin_mul_overflow() above. */
|
|
|
6129 SDL_FORCE_INLINE bool SDL_size_add_check_overflow_builtin(size_t a, size_t b, size_t *ret)
|
|
|
6130 {
|
|
|
6131 return (__builtin_add_overflow(a, b, ret) == 0);
|
|
|
6132 }
|
|
|
6133 #define SDL_size_add_check_overflow(a, b, ret) SDL_size_add_check_overflow_builtin(a, b, ret)
|
|
|
6134 #endif
|
|
|
6135 #endif
|
|
|
6136
|
|
|
6137 /* This is a generic function pointer which should be cast to the type you expect */
|
|
|
6138 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
6139
|
|
|
6140 /**
|
|
|
6141 * A generic function pointer.
|
|
|
6142 *
|
|
|
6143 * In theory, generic function pointers should use this, instead of `void *`,
|
|
|
6144 * since some platforms could treat code addresses differently than data
|
|
|
6145 * addresses. Although in current times no popular platforms make this
|
|
|
6146 * distinction, it is more correct and portable to use the correct type for a
|
|
|
6147 * generic pointer.
|
|
|
6148 *
|
|
|
6149 * If for some reason you need to force this typedef to be an actual `void *`,
|
|
|
6150 * perhaps to work around a compiler or existing code, you can define
|
|
|
6151 * `SDL_FUNCTION_POINTER_IS_VOID_POINTER` before including any SDL headers.
|
|
|
6152 *
|
|
|
6153 * \since This datatype is available since SDL 3.2.0.
|
|
|
6154 */
|
|
|
6155 typedef void (*SDL_FunctionPointer)(void);
|
|
|
6156 #elif defined(SDL_FUNCTION_POINTER_IS_VOID_POINTER)
|
|
|
6157 typedef void *SDL_FunctionPointer;
|
|
|
6158 #else
|
|
|
6159 typedef void (*SDL_FunctionPointer)(void);
|
|
|
6160 #endif
|
|
|
6161
|
|
|
6162 /* Ends C function definitions when using C++ */
|
|
|
6163 #ifdef __cplusplus
|
|
|
6164 }
|
|
|
6165 #endif
|
|
|
6166 #include <SDL3/SDL_close_code.h>
|
|
|
6167
|
|
|
6168 #endif /* SDL_stdinc_h_ */
|
