1 /* 2 DSDL 3 Copyright (C) 2025 Inochi2D Project <luna@foxgirls.gay> 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 Aliases for base types declared in the SDL headers. 24 25 Copyright: © 2025 Inochi2D Project, © 1997-2025 Sam Lantinga 26 License: Subject to the terms of the Zlib License, as written in the LICENSE file. 27 Authors: 28 Luna Nielsen 29 */ 30 module sdl.stdc; 31 32 extern (C) nothrow @nogc: 33 34 /** 35 8-bit signed integer 36 */ 37 alias Sint8 = byte; 38 39 /** 40 8-bit unsigned integer 41 */ 42 alias Uint8 = ubyte; 43 44 /** 45 16-bit signed integer 46 */ 47 alias Sint16 = short; 48 49 /** 50 16-bit unsigned integer 51 */ 52 alias Uint16 = ushort; 53 54 /** 55 32-bit signed integer 56 */ 57 alias Sint32 = int; 58 59 /** 60 32-bit unsigned integer 61 */ 62 alias Uint32 = uint; 63 64 /** 65 64-bit signed integer 66 */ 67 alias Sint64 = long; 68 69 /** 70 64-bit unsigned integer 71 */ 72 alias Uint64 = ulong; 73 74 /** 75 SDL times are signed, 64-bit integers representing nanoseconds since the 76 Unix epoch (Jan 1, 1970). 77 78 They can be converted between Windows FILETIME values with 79 $(D SDL_TimeToWindows) and $(D SDL_TimeFromWindows). 80 81 See_Also: 82 $(D SDL_Time.min) 83 $(D SDL_Time.max) 84 85 History: 86 Available since SDL 3.2.0. 87 */ 88 alias SDL_Time = Sint64; 89 90 /** 91 A generic function pointer. 92 93 In theory, generic function pointers should use this, instead of `void *`, 94 since some platforms could treat code addresses differently than data 95 addresses. Although in current times no popular platforms make this 96 distinction, it is more correct and portable to use the correct type for a 97 generic pointer. 98 */ 99 alias SDL_FunctionPointer = void function(); 100 101 /** 102 Allocate uninitialized memory. 103 104 The allocated memory returned by this function must be freed with 105 SDL_free(). 106 107 If `size` is 0, it will be set to 1. 108 109 If you want to allocate memory aligned to a specific alignment, consider 110 using SDL_aligned_alloc(). 111 112 \param size the size to allocate. 113 \returns a pointer to the allocated memory, or NULL if allocation failed. 114 115 \threadsafety It is safe to call this function from any thread. 116 117 \since This function is available since SDL 3.2.0. 118 119 \sa SDL_free 120 \sa SDL_calloc 121 \sa SDL_realloc 122 \sa SDL_aligned_alloc 123 */ 124 extern void* SDL_malloc(size_t size); 125 126 /** 127 Allocate a zero-initialized array. 128 129 The memory returned by this function must be freed with SDL_free(). 130 131 If either of `nmemb` or `size` is 0, they will both be set to 1. 132 133 \param nmemb the number of elements in the array. 134 \param size the size of each element of the array. 135 \returns a pointer to the allocated array, or NULL if allocation failed. 136 137 \threadsafety It is safe to call this function from any thread. 138 139 \since This function is available since SDL 3.2.0. 140 141 \sa SDL_free 142 \sa SDL_malloc 143 \sa SDL_realloc 144 */ 145 extern void* SDL_calloc(size_t nmemb, size_t size); 146 147 /** 148 Change the size of allocated memory. 149 150 The memory returned by this function must be freed with SDL_free(). 151 152 If `size` is 0, it will be set to 1. Note that this is unlike some other C 153 runtime `realloc` implementations, which may treat `realloc(mem, 0)` the 154 same way as `free(mem)`. 155 156 If `mem` is NULL, the behavior of this function is equivalent to 157 SDL_malloc(). Otherwise, the function can have one of three possible 158 outcomes: 159 160 - If it returns the same pointer as `mem`, it means that `mem` was resized 161 in place without freeing. 162 - If it returns a different non-NULL pointer, it means that `mem` was freed 163 and cannot be dereferenced anymore. 164 - If it returns NULL (indicating failure), then `mem` will remain valid and 165 must still be freed with SDL_free(). 166 167 \param mem a pointer to allocated memory to reallocate, or NULL. 168 \param size the new size of the memory. 169 \returns a pointer to the newly allocated memory, or NULL if allocation 170 failed. 171 172 \threadsafety It is safe to call this function from any thread. 173 174 \since This function is available since SDL 3.2.0. 175 176 \sa SDL_free 177 \sa SDL_malloc 178 \sa SDL_calloc 179 */ 180 extern void* SDL_realloc(void* mem, size_t size); 181 182 /** 183 Free allocated memory. 184 185 The pointer is no longer valid after this call and cannot be dereferenced 186 anymore. 187 188 If `mem` is NULL, this function does nothing. 189 190 \param mem a pointer to allocated memory, or NULL. 191 192 \threadsafety It is safe to call this function from any thread. 193 194 \since This function is available since SDL 3.2.0. 195 196 \sa SDL_malloc 197 \sa SDL_calloc 198 \sa SDL_realloc 199 */ 200 extern void SDL_free(void* mem); 201 202 /** 203 A callback used to implement SDL_malloc(). 204 205 SDL will always ensure that the passed `size` is greater than 0. 206 207 \param size the size to allocate. 208 \returns a pointer to the allocated memory, or NULL if allocation failed. 209 210 \threadsafety It should be safe to call this callback from any thread. 211 212 \since This datatype is available since SDL 3.2.0. 213 214 \sa SDL_malloc 215 \sa SDL_GetOriginalMemoryFunctions 216 \sa SDL_GetMemoryFunctions 217 \sa SDL_SetMemoryFunctions 218 */ 219 alias SDL_malloc_func = void* function(size_t size); 220 221 /** 222 A callback used to implement SDL_calloc(). 223 224 SDL will always ensure that the passed `nmemb` and `size` are both greater 225 than 0. 226 227 \param nmemb the number of elements in the array. 228 \param size the size of each element of the array. 229 \returns a pointer to the allocated array, or NULL if allocation failed. 230 231 \threadsafety It should be safe to call this callback from any thread. 232 233 \since This datatype is available since SDL 3.2.0. 234 235 \sa SDL_calloc 236 \sa SDL_GetOriginalMemoryFunctions 237 \sa SDL_GetMemoryFunctions 238 \sa SDL_SetMemoryFunctions 239 */ 240 alias SDL_calloc_func = void* function(size_t nmemb, size_t size); 241 242 /** 243 A callback used to implement SDL_realloc(). 244 245 SDL will always ensure that the passed `size` is greater than 0. 246 247 \param mem a pointer to allocated memory to reallocate, or NULL. 248 \param size the new size of the memory. 249 \returns a pointer to the newly allocated memory, or NULL if allocation 250 failed. 251 252 \threadsafety It should be safe to call this callback from any thread. 253 254 \since This datatype is available since SDL 3.2.0. 255 256 \sa SDL_realloc 257 \sa SDL_GetOriginalMemoryFunctions 258 \sa SDL_GetMemoryFunctions 259 \sa SDL_SetMemoryFunctions 260 */ 261 alias SDL_realloc_func = void* function(void * mem, size_t size); 262 263 /** 264 A callback used to implement SDL_free(). 265 266 SDL will always ensure that the passed `mem` is a non-NULL pointer. 267 268 \param mem a pointer to allocated memory. 269 270 \threadsafety It should be safe to call this callback from any thread. 271 272 \since This datatype is available since SDL 3.2.0. 273 274 \sa SDL_free 275 \sa SDL_GetOriginalMemoryFunctions 276 \sa SDL_GetMemoryFunctions 277 \sa SDL_SetMemoryFunctions 278 */ 279 alias SDL_free_func = void function(void* mem); 280 281 /** 282 Get the original set of SDL memory functions. 283 284 This is what SDL_malloc and friends will use by default, if there has been 285 no call to SDL_SetMemoryFunctions. This is not necessarily using the C 286 runtime's `malloc` functions behind the scenes! Different platforms and 287 build configurations might do any number of unexpected things. 288 289 \param malloc_func filled with malloc function. 290 \param calloc_func filled with calloc function. 291 \param realloc_func filled with realloc function. 292 \param free_func filled with free function. 293 294 \threadsafety It is safe to call this function from any thread. 295 296 \since This function is available since SDL 3.2.0. 297 */ 298 extern void SDL_GetOriginalMemoryFunctions( 299 SDL_malloc_func* malloc_func, 300 SDL_calloc_func* calloc_func, 301 SDL_realloc_func* realloc_func, 302 SDL_free_func* free_func); 303 304 /** 305 Get the current set of SDL memory functions. 306 307 \param malloc_func filled with malloc function. 308 \param calloc_func filled with calloc function. 309 \param realloc_func filled with realloc function. 310 \param free_func filled with free function. 311 312 \threadsafety This does not hold a lock, so do not call this in the 313 unlikely event of a background thread calling 314 SDL_SetMemoryFunctions simultaneously. 315 316 \since This function is available since SDL 3.2.0. 317 318 \sa SDL_SetMemoryFunctions 319 \sa SDL_GetOriginalMemoryFunctions 320 */ 321 extern void SDL_GetMemoryFunctions( 322 SDL_malloc_func* malloc_func, 323 SDL_calloc_func* calloc_func, 324 SDL_realloc_func* realloc_func, 325 SDL_free_func* free_func); 326 327 /** 328 Replace SDL's memory allocation functions with a custom set. 329 330 It is not safe to call this function once any allocations have been made, 331 as future calls to SDL_free will use the new allocator, even if they came 332 from an SDL_malloc made with the old one! 333 334 If used, usually this needs to be the first call made into the SDL library, 335 if not the very first thing done at program startup time. 336 337 \param malloc_func custom malloc function. 338 \param calloc_func custom calloc function. 339 \param realloc_func custom realloc function. 340 \param free_func custom free function. 341 \returns true on success or false on failure; call SDL_GetError() for more 342 information. 343 344 \threadsafety It is safe to call this function from any thread, but one 345 should not replace the memory functions once any allocations 346 are made! 347 348 \since This function is available since SDL 3.2.0. 349 350 \sa SDL_GetMemoryFunctions 351 \sa SDL_GetOriginalMemoryFunctions 352 */ 353 extern bool SDL_SetMemoryFunctions( 354 SDL_malloc_func malloc_func, 355 SDL_calloc_func calloc_func, 356 SDL_realloc_func realloc_func, 357 SDL_free_func free_func); 358 359 /** 360 Allocate memory aligned to a specific alignment. 361 362 The memory returned by this function must be freed with SDL_aligned_free(), 363 _not_ SDL_free(). 364 365 If `alignment` is less than the size of `void *`, it will be increased to 366 match that. 367 368 The returned memory address will be a multiple of the alignment value, and 369 the size of the memory allocated will be a multiple of the alignment value. 370 371 \param alignment the alignment of the memory. 372 \param size the size to allocate. 373 \returns a pointer to the aligned memory, or NULL if allocation failed. 374 375 \threadsafety It is safe to call this function from any thread. 376 377 \since This function is available since SDL 3.2.0. 378 379 \sa SDL_aligned_free 380 */ 381 extern void* SDL_aligned_alloc(size_t alignment, size_t size); 382 383 /** 384 Free memory allocated by SDL_aligned_alloc(). 385 386 The pointer is no longer valid after this call and cannot be dereferenced 387 anymore. 388 389 If `mem` is NULL, this function does nothing. 390 391 \param mem a pointer previously returned by SDL_aligned_alloc(), or NULL. 392 393 \threadsafety It is safe to call this function from any thread. 394 395 \since This function is available since SDL 3.2.0. 396 397 \sa SDL_aligned_alloc 398 */ 399 extern void SDL_aligned_free(void* mem); 400 401 /** 402 Get the number of outstanding (unfreed) allocations. 403 404 \returns the number of allocations or -1 if allocation counting is 405 disabled. 406 407 \threadsafety It is safe to call this function from any thread. 408 409 \since This function is available since SDL 3.2.0. 410 */ 411 extern int SDL_GetNumAllocations(); 412 413 /** 414 A thread-safe set of environment variables 415 416 \since This struct is available since SDL 3.2.0. 417 418 \sa SDL_GetEnvironment 419 \sa SDL_CreateEnvironment 420 \sa SDL_GetEnvironmentVariable 421 \sa SDL_GetEnvironmentVariables 422 \sa SDL_SetEnvironmentVariable 423 \sa SDL_UnsetEnvironmentVariable 424 \sa SDL_DestroyEnvironment 425 */ 426 struct SDL_Environment; 427 428 /** 429 Get the process environment. 430 431 This is initialized at application start and is not affected by setenv() 432 and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and 433 SDL_UnsetEnvironmentVariable() if you want to modify this environment, or 434 SDL_setenv_unsafe() or SDL_unsetenv_unsafe() if you want changes to persist 435 in the C runtime environment after SDL_Quit(). 436 437 \returns a pointer to the environment for the process or NULL on failure; 438 call SDL_GetError() for more information. 439 440 \threadsafety It is safe to call this function from any thread. 441 442 \since This function is available since SDL 3.2.0. 443 444 \sa SDL_GetEnvironmentVariable 445 \sa SDL_GetEnvironmentVariables 446 \sa SDL_SetEnvironmentVariable 447 \sa SDL_UnsetEnvironmentVariable 448 */ 449 extern SDL_Environment* SDL_GetEnvironment(); 450 451 /** 452 Create a set of environment variables 453 454 \param populated true to initialize it from the C runtime environment, 455 false to create an empty environment. 456 \returns a pointer to the new environment or NULL on failure; call 457 SDL_GetError() for more information. 458 459 \threadsafety If `populated` is false, it is safe to call this function 460 from any thread, otherwise it is safe if no other threads are 461 calling setenv() or unsetenv() 462 463 \since This function is available since SDL 3.2.0. 464 465 \sa SDL_GetEnvironmentVariable 466 \sa SDL_GetEnvironmentVariables 467 \sa SDL_SetEnvironmentVariable 468 \sa SDL_UnsetEnvironmentVariable 469 \sa SDL_DestroyEnvironment 470 */ 471 extern SDL_Environment* SDL_CreateEnvironment(bool populated); 472 473 /** 474 Get the value of a variable in the environment. 475 476 \param env the environment to query. 477 \param name the name of the variable to get. 478 \returns a pointer to the value of the variable or NULL if it can't be 479 found. 480 481 \threadsafety It is safe to call this function from any thread. 482 483 \since This function is available since SDL 3.2.0. 484 485 \sa SDL_GetEnvironment 486 \sa SDL_CreateEnvironment 487 \sa SDL_GetEnvironmentVariables 488 \sa SDL_SetEnvironmentVariable 489 \sa SDL_UnsetEnvironmentVariable 490 */ 491 extern const(char)* SDL_GetEnvironmentVariable(SDL_Environment* env, const(char)* name); 492 493 /** 494 Get all variables in the environment. 495 496 \param env the environment to query. 497 \returns a NULL terminated array of pointers to environment variables in 498 the form "variable=value" or NULL on failure; call SDL_GetError() 499 for more information. This is a single allocation that should be 500 freed with SDL_free() when it is no longer needed. 501 502 \threadsafety It is safe to call this function from any thread. 503 504 \since This function is available since SDL 3.2.0. 505 506 \sa SDL_GetEnvironment 507 \sa SDL_CreateEnvironment 508 \sa SDL_GetEnvironmentVariables 509 \sa SDL_SetEnvironmentVariable 510 \sa SDL_UnsetEnvironmentVariable 511 */ 512 extern char** SDL_GetEnvironmentVariables(SDL_Environment* env); 513 514 /** 515 Set the value of a variable in the environment. 516 517 \param env the environment to modify. 518 \param name the name of the variable to set. 519 \param value the value of the variable to set. 520 \param overwrite true to overwrite the variable if it exists, false to 521 return success without setting the variable if it already 522 exists. 523 \returns true on success or false on failure; call SDL_GetError() for more 524 information. 525 526 \threadsafety It is safe to call this function from any thread. 527 528 \since This function is available since SDL 3.2.0. 529 530 \sa SDL_GetEnvironment 531 \sa SDL_CreateEnvironment 532 \sa SDL_GetEnvironmentVariable 533 \sa SDL_GetEnvironmentVariables 534 \sa SDL_UnsetEnvironmentVariable 535 */ 536 extern bool SDL_SetEnvironmentVariable(SDL_Environment* env, const(char)* name, const(char)* value, bool overwrite); 537 538 /** 539 Clear a variable from the environment. 540 541 \param env the environment to modify. 542 \param name the name of the variable to unset. 543 \returns true on success or false on failure; call SDL_GetError() for more 544 information. 545 546 \threadsafety It is safe to call this function from any thread. 547 548 \since This function is available since SDL 3.2.0. 549 550 \sa SDL_GetEnvironment 551 \sa SDL_CreateEnvironment 552 \sa SDL_GetEnvironmentVariable 553 \sa SDL_GetEnvironmentVariables 554 \sa SDL_SetEnvironmentVariable 555 \sa SDL_UnsetEnvironmentVariable 556 */ 557 extern bool SDL_UnsetEnvironmentVariable(SDL_Environment* env, const(char)* name); 558 559 /** 560 Destroy a set of environment variables. 561 562 \param env the environment to destroy. 563 564 \threadsafety It is safe to call this function from any thread, as long as 565 the environment is no longer in use. 566 567 \since This function is available since SDL 3.2.0. 568 569 \sa SDL_CreateEnvironment 570 */ 571 extern void SDL_DestroyEnvironment(SDL_Environment* env); 572 573 /** 574 Get the value of a variable in the environment. 575 576 This function uses SDL's cached copy of the environment and is thread-safe. 577 578 \param name the name of the variable to get. 579 \returns a pointer to the value of the variable or NULL if it can't be 580 found. 581 582 \threadsafety It is safe to call this function from any thread. 583 584 \since This function is available since SDL 3.2.0. 585 */ 586 extern const(char)* SDL_getenv(const(char)* name); 587 588 /** 589 Get the value of a variable in the environment. 590 591 This function bypasses SDL's cached copy of the environment and is not 592 thread-safe. 593 594 \param name the name of the variable to get. 595 \returns a pointer to the value of the variable or NULL if it can't be 596 found. 597 598 \threadsafety This function is not thread safe, consider using SDL_getenv() 599 instead. 600 601 \since This function is available since SDL 3.2.0. 602 603 \sa SDL_getenv 604 */ 605 extern const(char)* SDL_getenv_unsafe(const(char)* name); 606 607 /** 608 Set the value of a variable in the environment. 609 610 \param name the name of the variable to set. 611 \param value the value of the variable to set. 612 \param overwrite 1 to overwrite the variable if it exists, 0 to return 613 success without setting the variable if it already exists. 614 \returns 0 on success, -1 on error. 615 616 \threadsafety This function is not thread safe, consider using 617 SDL_SetEnvironmentVariable() instead. 618 619 \since This function is available since SDL 3.2.0. 620 621 \sa SDL_SetEnvironmentVariable 622 */ 623 extern int SDL_setenv_unsafe(const(char)* name, const(char)* value, int overwrite); 624 625 /** 626 Clear a variable from the environment. 627 628 \param name the name of the variable to unset. 629 \returns 0 on success, -1 on error. 630 631 \threadsafety This function is not thread safe, consider using 632 SDL_UnsetEnvironmentVariable() instead. 633 634 \since This function is available since SDL 3.2.0. 635 636 \sa SDL_UnsetEnvironmentVariable 637 */ 638 extern int SDL_unsetenv_unsafe(const(char)* name); 639 640 /** 641 A callback used with SDL sorting and binary search functions. 642 643 \param a a pointer to the first element being compared. 644 \param b a pointer to the second element being compared. 645 \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted 646 before `a`, 0 if they are equal. If two elements are equal, their 647 order in the sorted array is undefined. 648 649 \since This callback is available since SDL 3.2.0. 650 651 \sa SDL_bsearch 652 \sa SDL_qsort 653 */ 654 alias SDL_CompareCallback = int function(const(void)* a, const(void)* b); 655 656 /** 657 Sort an array. 658 659 For example: 660 661 Examples: 662 $(D_CODE 663 struct data { 664 int key; 665 const(char)* value; 666 } 667 668 int compare(const(data)* a, const(data)* b) { 669 if (a.n < b.n) { 670 return -1; 671 } else if (b.n < a.n) { 672 return 1; 673 } else { 674 return 0; 675 } 676 } 677 678 data[] values[] = [ 679 { 3, "third" }, { 1, "first" }, { 2, "second" } 680 ]; 681 682 SDL_qsort(values.ptr, values.length, data.sizeof, cast(SDL_CompareCallback)&compare); 683 ) 684 685 686 \param base a pointer to the start of the array. 687 \param nmemb the number of elements in the array. 688 \param size the size of the elements in the array. 689 \param compare a function used to compare elements in the array. 690 691 \threadsafety It is safe to call this function from any thread. 692 693 \since This function is available since SDL 3.2.0. 694 695 \sa SDL_bsearch 696 \sa SDL_qsort_r 697 */ 698 extern void SDL_qsort(void* base, size_t nmemb, size_t size, SDL_CompareCallback compare); 699 700 /** 701 Perform a binary search on a previously sorted array. 702 703 Examples: 704 705 $(D_CODE 706 struct data { 707 int key; 708 const(char)* value; 709 } 710 711 int compare(const(data)* a, const(data)* b) { 712 if (a.n < b.n) { 713 return -1; 714 } else if (b.n < a.n) { 715 return 1; 716 } else { 717 return 0; 718 } 719 } 720 721 data[] values = [ 722 { 1, "first" }, { 2, "second" }, { 3, "third" } 723 ]; 724 725 data key = { 2, NULL }; 726 727 data* result = SDL_bsearch(&key, values.ptr, values.length, data.sizeof, cast(SDL_CompareCallback)&compare); 728 ) 729 730 \param key a pointer to a key equal to the element being searched for. 731 \param base a pointer to the start of the array. 732 \param nmemb the number of elements in the array. 733 \param size the size of the elements in the array. 734 \param compare a function used to compare elements in the array. 735 \returns a pointer to the matching element in the array, or NULL if not 736 found. 737 738 \threadsafety It is safe to call this function from any thread. 739 740 \since This function is available since SDL 3.2.0. 741 742 \sa SDL_bsearch_r 743 \sa SDL_qsort 744 */ 745 extern void* SDL_bsearch(const(void)* key, const(void)* base, size_t nmemb, size_t size, SDL_CompareCallback compare); 746 747 /** 748 A callback used with SDL sorting and binary search functions. 749 750 \param userdata the `userdata` pointer passed to the sort function. 751 \param a a pointer to the first element being compared. 752 \param b a pointer to the second element being compared. 753 \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted 754 before `a`, 0 if they are equal. If two elements are equal, their 755 order in the sorted array is undefined. 756 757 \since This callback is available since SDL 3.2.0. 758 759 \sa SDL_qsort_r 760 \sa SDL_bsearch_r 761 */ 762 alias SDL_CompareCallback_r = int function(void* userdata, const(void)* a, const(void)* b); 763 764 /** 765 Sort an array, passing a userdata pointer to the compare function. 766 767 Examples: 768 $(D_CODE 769 enum sort_method { 770 sort_increasing, 771 sort_decreasing, 772 } 773 774 struct data { 775 int key; 776 const(char)* value; 777 } 778 779 int compare(sort_method method, const(data)* a, const(data)* b) { 780 if (a.key < b.key) { 781 return (method == sort_method.sort_increasing) ? -1 : 1; 782 } else if (b.key < a.key) { 783 return (method == sort_method.sort_increasing) ? 1 : -1; 784 } else { 785 return 0; 786 } 787 } 788 789 data[] values = [ 790 { 3, "third" }, { 1, "first" }, { 2, "second" } 791 ]; 792 793 // reinterpret_cast is a part of numem. 794 SDL_qsort_r(values.ptr, values.length, data.sizeof, cast(SDL_CompareCallback_r)&compare, reinterpret_cast!(void*)(sort_method.sort_increasing)); 795 ) 796 797 \param base a pointer to the start of the array. 798 \param nmemb the number of elements in the array. 799 \param size the size of the elements in the array. 800 \param compare a function used to compare elements in the array. 801 \param userdata a pointer to pass to the compare function. 802 803 \threadsafety It is safe to call this function from any thread. 804 805 \since This function is available since SDL 3.2.0. 806 807 \sa SDL_bsearch_r 808 \sa SDL_qsort 809 */ 810 extern void SDL_qsort_r(void* base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void* userdata); 811 812 /** 813 Perform a binary search on a previously sorted array, passing a userdata 814 pointer to the compare function. 815 816 For example: 817 818 $(D_CODE 819 enum sort_method { 820 sort_increasing, 821 sort_decreasing, 822 } 823 824 struct data { 825 int key; 826 const(char)* value; 827 } 828 829 int compare(sort_method method, const(data)* a, const(data)* b) { 830 if (a.key < b.key) { 831 return (method == sort_method.sort_increasing) ? -1 : 1; 832 } else if (b.key < a.key) { 833 return (method == sort_method.sort_increasing) ? 1 : -1; 834 } else { 835 return 0; 836 } 837 } 838 839 data[] values = [ 840 { 1, "first" }, { 2, "second" }, { 3, "third" } 841 ]; 842 data key = { 2, NULL }; 843 844 // reinterpret_cast is a part of numem. 845 data* result = SDL_bsearch_r(&key, values.ptr, values.length, data.sizeof, cast(SDL_CompareCallback_r)&compare, reinterpret_cast!(void*)(sort_method.sort_increasing)); 846 ) 847 848 \param key a pointer to a key equal to the element being searched for. 849 \param base a pointer to the start of the array. 850 \param nmemb the number of elements in the array. 851 \param size the size of the elements in the array. 852 \param compare a function used to compare elements in the array. 853 \param userdata a pointer to pass to the compare function. 854 \returns a pointer to the matching element in the array, or NULL if not 855 found. 856 857 \threadsafety It is safe to call this function from any thread. 858 859 \since This function is available since SDL 3.2.0. 860 861 \sa SDL_bsearch 862 \sa SDL_qsort_r 863 */ 864 extern void* SDL_bsearch_r(const(void)* key, const(void)* base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void* userdata); 865 866 /** 867 Compute the absolute value of `x`. 868 869 \param x an integer value. 870 \returns the absolute value of x. 871 872 \threadsafety It is safe to call this function from any thread. 873 874 \since This function is available since SDL 3.2.0. 875 */ 876 extern int SDL_abs(int x); 877 878 /** 879 Query if a character is alphabetic (a letter). 880 881 **WARNING**: Regardless of system locale, this will only treat ASCII values 882 for English 'a-z' and 'A-Z' as true. 883 884 \param x character value to check. 885 \returns non-zero if x falls within the character class, zero otherwise. 886 887 \threadsafety It is safe to call this function from any thread. 888 889 \since This function is available since SDL 3.2.0. 890 */ 891 extern int SDL_isalpha(int x); 892 893 /** 894 Query if a character is alphabetic (a letter) or a number. 895 896 **WARNING**: Regardless of system locale, this will only treat ASCII values 897 for English 'a-z', 'A-Z', and '0-9' as true. 898 899 \param x character value to check. 900 \returns non-zero if x falls within the character class, zero otherwise. 901 902 \threadsafety It is safe to call this function from any thread. 903 904 \since This function is available since SDL 3.2.0. 905 */ 906 extern int SDL_isalnum(int x); 907 908 /** 909 Report if a character is blank (a space or tab). 910 911 **WARNING**: Regardless of system locale, this will only treat ASCII values 912 0x20 (space) or 0x9 (tab) as true. 913 914 \param x character value to check. 915 \returns non-zero if x falls within the character class, zero otherwise. 916 917 \threadsafety It is safe to call this function from any thread. 918 919 \since This function is available since SDL 3.2.0. 920 */ 921 extern int SDL_isblank(int x); 922 923 /** 924 Report if a character is a control character. 925 926 **WARNING**: Regardless of system locale, this will only treat ASCII values 927 0 through 0x1F, and 0x7F, as true. 928 929 \param x character value to check. 930 \returns non-zero if x falls within the character class, zero otherwise. 931 932 \threadsafety It is safe to call this function from any thread. 933 934 \since This function is available since SDL 3.2.0. 935 */ 936 extern int SDL_iscntrl(int x); 937 938 /** 939 Report if a character is a numeric digit. 940 941 **WARNING**: Regardless of system locale, this will only treat ASCII values 942 '0' (0x30) through '9' (0x39), as true. 943 944 \param x character value to check. 945 \returns non-zero if x falls within the character class, zero otherwise. 946 947 \threadsafety It is safe to call this function from any thread. 948 949 \since This function is available since SDL 3.2.0. 950 */ 951 extern int SDL_isdigit(int x); 952 953 /** 954 Report if a character is a hexadecimal digit. 955 956 **WARNING**: Regardless of system locale, this will only treat ASCII values 957 'A' through 'F', 'a' through 'f', and '0' through '9', as true. 958 959 \param x character value to check. 960 \returns non-zero if x falls within the character class, zero otherwise. 961 962 \threadsafety It is safe to call this function from any thread. 963 964 \since This function is available since SDL 3.2.0. 965 */ 966 extern int SDL_isxdigit(int x); 967 968 /** 969 Report if a character is a punctuation mark. 970 971 **WARNING**: Regardless of system locale, this is equivalent to 972 `((SDL_isgraph(x)) && (!SDL_isalnum(x)))`. 973 974 \param x character value to check. 975 \returns non-zero if x falls within the character class, zero otherwise. 976 977 \threadsafety It is safe to call this function from any thread. 978 979 \since This function is available since SDL 3.2.0. 980 981 \sa SDL_isgraph 982 \sa SDL_isalnum 983 */ 984 extern int SDL_ispunct(int x); 985 986 /** 987 Report if a character is whitespace. 988 989 **WARNING**: Regardless of system locale, this will only treat the 990 following ASCII values as true: 991 992 - space (0x20) 993 - tab (0x09) 994 - newline (0x0A) 995 - vertical tab (0x0B) 996 - form feed (0x0C) 997 - return (0x0D) 998 999 \param x character value to check. 1000 \returns non-zero if x falls within the character class, zero otherwise. 1001 1002 \threadsafety It is safe to call this function from any thread. 1003 1004 \since This function is available since SDL 3.2.0. 1005 */ 1006 extern int SDL_isspace(int x); 1007 1008 /** 1009 Report if a character is upper case. 1010 1011 **WARNING**: Regardless of system locale, this will only treat ASCII values 1012 'A' through 'Z' as true. 1013 1014 \param x character value to check. 1015 \returns non-zero if x falls within the character class, zero otherwise. 1016 1017 \threadsafety It is safe to call this function from any thread. 1018 1019 \since This function is available since SDL 3.2.0. 1020 */ 1021 extern int SDL_isupper(int x); 1022 1023 /** 1024 Report if a character is lower case. 1025 1026 **WARNING**: Regardless of system locale, this will only treat ASCII values 1027 'a' through 'z' as true. 1028 1029 \param x character value to check. 1030 \returns non-zero if x falls within the character class, zero otherwise. 1031 1032 \threadsafety It is safe to call this function from any thread. 1033 1034 \since This function is available since SDL 3.2.0. 1035 */ 1036 extern int SDL_islower(int x); 1037 1038 /** 1039 Report if a character is "printable". 1040 1041 Be advised that "printable" has a definition that goes back to text 1042 terminals from the dawn of computing, making this a sort of special case 1043 function that is not suitable for Unicode (or most any) text management. 1044 1045 **WARNING**: Regardless of system locale, this will only treat ASCII values 1046 ' ' (0x20) through '~' (0x7E) as true. 1047 1048 \param x character value to check. 1049 \returns non-zero if x falls within the character class, zero otherwise. 1050 1051 \threadsafety It is safe to call this function from any thread. 1052 1053 \since This function is available since SDL 3.2.0. 1054 */ 1055 extern int SDL_isprint(int x); 1056 1057 /** 1058 Report if a character is any "printable" except space. 1059 1060 Be advised that "printable" has a definition that goes back to text 1061 terminals from the dawn of computing, making this a sort of special case 1062 function that is not suitable for Unicode (or most any) text management. 1063 1064 **WARNING**: Regardless of system locale, this is equivalent to 1065 `(SDL_isprint(x)) && ((x) != ' ')`. 1066 1067 \param x character value to check. 1068 \returns non-zero if x falls within the character class, zero otherwise. 1069 1070 \threadsafety It is safe to call this function from any thread. 1071 1072 \since This function is available since SDL 3.2.0. 1073 1074 \sa SDL_isprint 1075 */ 1076 extern int SDL_isgraph(int x); 1077 1078 /** 1079 Convert low-ASCII English letters to uppercase. 1080 1081 **WARNING**: Regardless of system locale, this will only convert ASCII 1082 values 'a' through 'z' to uppercase. 1083 1084 This function returns the uppercase equivalent of `x`. If a character 1085 cannot be converted, or is already uppercase, this function returns `x`. 1086 1087 \param x character value to check. 1088 \returns capitalized version of x, or x if no conversion available. 1089 1090 \threadsafety It is safe to call this function from any thread. 1091 1092 \since This function is available since SDL 3.2.0. 1093 */ 1094 extern int SDL_toupper(int x); 1095 1096 /** 1097 Convert low-ASCII English letters to lowercase. 1098 1099 **WARNING**: Regardless of system locale, this will only convert ASCII 1100 values 'A' through 'Z' to lowercase. 1101 1102 This function returns the lowercase equivalent of `x`. If a character 1103 cannot be converted, or is already lowercase, this function returns `x`. 1104 1105 \param x character value to check. 1106 \returns lowercase version of x, or x if no conversion available. 1107 1108 \threadsafety It is safe to call this function from any thread. 1109 1110 \since This function is available since SDL 3.2.0. 1111 */ 1112 extern int SDL_tolower(int x); 1113 1114 /** 1115 Calculate a CRC-16 value. 1116 1117 https://en.wikipedia.org/wiki/Cyclic_redundancy_check 1118 1119 This function can be called multiple times, to stream data to be 1120 checksummed in blocks. Each call must provide the previous CRC-16 return 1121 value to be updated with the next block. The first call to this function 1122 for a set of blocks should pass in a zero CRC value. 1123 1124 \param crc the current checksum for this data set, or 0 for a new data set. 1125 \param data a new block of data to add to the checksum. 1126 \param len the size, in bytes, of the new block of data. 1127 \returns a CRC-16 checksum value of all blocks in the data set. 1128 1129 \threadsafety It is safe to call this function from any thread. 1130 1131 \since This function is available since SDL 3.2.0. 1132 */ 1133 extern Uint16 SDL_crc16(Uint16 crc, const(void)* data, size_t len); 1134 1135 /** 1136 Calculate a CRC-32 value. 1137 1138 https://en.wikipedia.org/wiki/Cyclic_redundancy_check 1139 1140 This function can be called multiple times, to stream data to be 1141 checksummed in blocks. Each call must provide the previous CRC-32 return 1142 value to be updated with the next block. The first call to this function 1143 for a set of blocks should pass in a zero CRC value. 1144 1145 \param crc the current checksum for this data set, or 0 for a new data set. 1146 \param data a new block of data to add to the checksum. 1147 \param len the size, in bytes, of the new block of data. 1148 \returns a CRC-32 checksum value of all blocks in the data set. 1149 1150 \threadsafety It is safe to call this function from any thread. 1151 1152 \since This function is available since SDL 3.2.0. 1153 */ 1154 extern Uint32 SDL_crc32(Uint32 crc, const(void)* data, size_t len); 1155 1156 /** 1157 Calculate a 32-bit MurmurHash3 value for a block of data. 1158 1159 https://en.wikipedia.org/wiki/MurmurHash 1160 1161 A seed may be specified, which changes the final results consistently, but 1162 this does not work like SDL_crc16 and SDL_crc32: you can't feed a previous 1163 result from this function back into itself as the next seed value to 1164 calculate a hash in chunks; it won't produce the same hash as it would if 1165 the same data was provided in a single call. 1166 1167 If you aren't sure what to provide for a seed, zero is fine. Murmur3 is not 1168 cryptographically secure, so it shouldn't be used for hashing top-secret 1169 data. 1170 1171 \param data the data to be hashed. 1172 \param len the size of data, in bytes. 1173 \param seed a value that alters the final hash value. 1174 \returns a Murmur3 32-bit hash value. 1175 1176 \threadsafety It is safe to call this function from any thread. 1177 1178 \since This function is available since SDL 3.2.0. 1179 */ 1180 extern Uint32 SDL_murmur3_32(const(void)* data, size_t len, Uint32 seed); 1181 1182 /** 1183 Copy non-overlapping memory. 1184 1185 The memory regions must not overlap. If they do, use SDL_memmove() instead. 1186 1187 \param dst The destination memory region. Must not be NULL, and must not 1188 overlap with `src`. 1189 \param src The source memory region. Must not be NULL, and must not overlap 1190 with `dst`. 1191 \param len The length in bytes of both `dst` and `src`. 1192 \returns `dst`. 1193 1194 \threadsafety It is safe to call this function from any thread. 1195 1196 \since This function is available since SDL 3.2.0. 1197 1198 \sa SDL_memmove 1199 */ 1200 extern void* SDL_memcpy(void* dst, const(void)* src, size_t len);