SDL provides its own implementation of some of the most important C runtime functions. More...

Classes
class	SDL::Time
	SDL times are signed, 64-bit integers representing nanoseconds since the Unix epoch (Jan 1, 1970). More...

struct	SDL::EnvironmentBase
	A thread-safe set of environment variables. More...

struct	SDL::EnvironmentRef
	Handle to a non owned environment. More...

struct	SDL::Environment
	Handle to an owned environment. More...

class	SDL::Random
	A independent pseudo random state. More...

struct	SDL::IConvBase
	An opaque handle representing string encoding conversion state. More...

struct	SDL::IConvRef
	Handle to a non owned iConv. More...

struct	SDL::IConv
	Handle to an owned iConv. More...

Macros
#define	SDL_NOLONGLONG 1
	Don't let SDL use "long long" C types.

#define	SDL_SIZE_MAX SIZE_MAX
	The largest value that a `size_t` can hold for the target platform.

#define	SDL_STRINGIFY_ARG(arg) #arg
	Macro useful for building other macros with strings in them.

#define	SDL_SINT64_C(c) c##LL /* or whatever the current compiler uses. */
	Append the 64 bit integer suffix to a signed integer literal.

#define	SDL_UINT64_C(c) c##ULL /* or whatever the current compiler uses. */
	Append the 64 bit integer suffix to an unsigned integer literal.

#define	SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */
	Epsilon constant, used for comparing floating-point numbers.

#define	SDL_INIT_INTERFACE(iface)
	A macro to initialize an SDL interface.

#define	SDL_copyp(dst, src)
	A macro to copy memory between objects, with basic type checking.

#define	SDL_ICONV_ERROR (size_t)-1
	Generic error.

#define	SDL_ICONV_E2BIG (size_t)-2
	Output buffer was too small.

#define	SDL_ICONV_EILSEQ (size_t)-3
	Invalid input sequence was encountered.

#define	SDL_ICONV_EINVAL (size_t)-4
	Incomplete input sequence was encountered.

#define	SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S) + 1)
	Convert a UTF-8 string to the current locale's character encoding.

#define	SDL_iconv_utf8_ucs2(S) (Uint16*)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S) + 1)
	Convert a UTF-8 string to UCS-2.

#define	SDL_iconv_utf8_ucs4(S) (Uint32*)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S) + 1)
	Convert a UTF-8 string to UCS-4.

#define	SDL_iconv_wchar_utf8(S)
	Convert a wchar_t string to UTF-8.

Typedefs
using	SDL::Seconds = std::chrono::duration< float >
	Duration in seconds (float).

using	SDL::Nanoseconds = std::chrono::nanoseconds
	Duration in Nanoseconds (Sint64).

using	SDL::malloc_func = SDL_malloc_func
	A callback used to implement malloc().

using	SDL::calloc_func = SDL_calloc_func
	A callback used to implement calloc().

using	SDL::realloc_func = SDL_realloc_func
	A callback used to implement realloc().

using	SDL::free_func = SDL_free_func
	A callback used to implement free().

using	SDL::CompareCallback = SDL_CompareCallback
	A callback used with SDL sorting and binary search functions.

using	SDL::CompareCallback_r = SDL_CompareCallback_r
	A callback used with SDL sorting and binary search functions.

using	SDL::CompareCB = std::function< int(const void , const void )>
	A callback used with SDL sorting and binary search functions.

using	SDL::FunctionPointer = SDL_FunctionPointer
	A generic function pointer.

Functions
template<class T , std::size_t N>
constexpr std::size_t	SDL::arraysize (const T(&array)[N])
	The number of elements in a static array.

constexpr Uint32	SDL::FourCC (Uint8 a, Uint8 b, Uint8 c, Uint8 d)
	Define a four character code as a Uint32.

constexpr float	SDL::ToSeconds (Seconds duration)
	Converts a time duration to seconds (float).

constexpr Seconds	SDL::FromSeconds (float duration)
	Converts a float to seconds representation.

constexpr Sint64	SDL::ToNS (std::chrono::nanoseconds duration)
	Converts a time duration to nanoseconds (Sint64);.

constexpr Nanoseconds	SDL::FromNS (Sint64 duration)
	Converts a Sint64 to nanoseconds representation.

void *	SDL::malloc (size_t size)
	Allocate uninitialized memory.

void *	SDL::calloc (size_t nmemb, size_t size)
	Allocate a zero-initialized array.

void *	SDL::realloc (void *mem, size_t size)
	Change the size of allocated memory.

void	SDL::free (void *mem)
	Free allocated memory.

void	SDL::GetOriginalMemoryFunctions (malloc_func malloc_func, calloc_func calloc_func, realloc_func realloc_func, free_func free_func)
	Get the original set of SDL memory functions.

void	SDL::GetMemoryFunctions (malloc_func malloc_func, calloc_func calloc_func, realloc_func realloc_func, free_func free_func)
	Get the current set of SDL memory functions.

void	SDL::SetMemoryFunctions (malloc_func malloc_func, calloc_func calloc_func, realloc_func realloc_func, free_func free_func)
	Replace SDL's memory allocation functions with a custom set.

void *	SDL::aligned_alloc (size_t alignment, size_t size)
	Allocate memory aligned to a specific alignment.

void	SDL::aligned_free (void *mem)
	Free memory allocated by aligned_alloc().

int	SDL::GetNumAllocations ()
	Get the number of outstanding (unfreed) allocations.

EnvironmentRef	SDL::GetEnvironment ()
	Get the process environment.

const char *	SDL::getenv (StringParam name)
	Get the value of a variable in the environment.

const char *	SDL::getenv_unsafe (StringParam name)
	Get the value of a variable in the environment.

int	SDL::setenv_unsafe (StringParam name, StringParam value, int overwrite)
	Set the value of a variable in the environment.

int	SDL::unsetenv_unsafe (StringParam name)
	Clear a variable from the environment.

void	SDL::qsort (void *base, size_t nmemb, size_t size, CompareCallback compare)
	Sort an array.

void *	SDL::bsearch (const void key, const void base, size_t nmemb, size_t size, CompareCallback compare)
	Perform a binary search on a previously sorted array.

void	SDL::qsort_r (void base, size_t nmemb, size_t size, CompareCallback_r compare, void userdata)
	Sort an array, passing a userdata pointer to the compare function.

void	SDL::qsort_r (void *base, size_t nmemb, size_t size, CompareCB compare)
	Sort an array, passing a userdata pointer to the compare function.

void *	SDL::bsearch_r (const void key, const void base, size_t nmemb, size_t size, CompareCallback_r compare, void *userdata)
	Perform a binary search on a previously sorted array, passing a userdata pointer to the compare function.

void *	SDL::bsearch_r (const void key, const void base, size_t nmemb, size_t size, CompareCB compare)
	Perform a binary search on a previously sorted array, passing a userdata pointer to the compare function.

int	SDL::abs (int x)
	Compute the absolute value of `x`.

double	SDL::abs (double x)
	Compute the absolute value of `x`

float	SDL::abs (float x)
	Compute the absolute value of `x`

template<class T , class U >
constexpr T	SDL::min (T x, U y)
	Return the lesser of two values.

template<class T , class U >
constexpr T	SDL::max (T x, U y)
	Return the greater of two values.

template<class T , class U , class V >
constexpr T	SDL::clamp (T x, U a, V b)
	Return a value clamped to a range.

int	SDL::isalpha (int x)
	Query if a character is alphabetic (a letter).

int	SDL::isalnum (int x)
	Query if a character is alphabetic (a letter) or a number.

int	SDL::isblank (int x)
	Report if a character is blank (a space or tab).

int	SDL::iscntrl (int x)
	Report if a character is a control character.

int	SDL::isdigit (int x)
	Report if a character is a numeric digit.

int	SDL::isxdigit (int x)
	Report if a character is a hexadecimal digit.

int	SDL::ispunct (int x)
	Report if a character is a punctuation mark.

int	SDL::isspace (int x)
	Report if a character is whitespace.

int	SDL::isupper (int x)
	Report if a character is upper case.

int	SDL::islower (int x)
	Report if a character is lower case.

int	SDL::isprint (int x)
	Report if a character is "printable".

int	SDL::isgraph (int x)
	Report if a character is any "printable" except space.

int	SDL::toupper (int x)
	Convert low-ASCII English letters to uppercase.

int	SDL::tolower (int x)
	Convert low-ASCII English letters to lowercase.

Uint16	SDL::crc16 (Uint16 crc, const void *data, size_t len)
	Calculate a CRC-16 value.

Uint32	SDL::crc32 (Uint32 crc, const void *data, size_t len)
	Calculate a CRC-32 value.

Uint32	SDL::murmur3_32 (const void *data, size_t len, Uint32 seed)
	Calculate a 32-bit MurmurHash3 value for a block of data.

void *	SDL::memcpy (void dst, const void src, size_t len)
	Copy non-overlapping memory.

void *	SDL::memmove (void dst, const void src, size_t len)
	Copy memory ranges that might overlap.

void *	SDL::memset (void *dst, int c, size_t len)
	Initialize all bytes of buffer of memory to a specific value.

void *	SDL::memset4 (void *dst, Uint32 val, size_t dwords)
	Initialize all 32-bit words of buffer of memory to a specific value.

template<class T >
void	SDL::zero (T &x)
	Clear an object's memory to zero.

template<class T >
void	SDL::zerop (T *x)
	Clear an object's memory to zero, using a pointer.

template<class T , std::size_t N>
void	SDL::zeroa (T(&x)[N])
	Clear an array's memory to zero.

int	SDL::memcmp (const void s1, const void s2, size_t len)
	Compare two buffers of memory.

size_t	SDL::wcslen (const wchar_t *wstr)
	This works exactly like wcslen() but doesn't require access to a C runtime.

size_t	SDL::wcsnlen (const wchar_t *wstr, size_t maxlen)
	This works exactly like wcsnlen() but doesn't require access to a C runtime.

size_t	SDL::wcslcpy (wchar_t dst, const wchar_t src, size_t maxlen)
	Copy a wide string.

size_t	SDL::wcslcat (wchar_t dst, const wchar_t src, size_t maxlen)
	Concatenate wide strings.

wchar_t *	SDL::wcsdup (const wchar_t *wstr)
	Allocate a copy of a wide string.

wchar_t *	SDL::wcsstr (const wchar_t haystack, const wchar_t needle)
	Search a wide string for the first instance of a specific substring.

wchar_t *	SDL::wcsnstr (const wchar_t haystack, const wchar_t needle, size_t maxlen)
	Search a wide string, up to n wide chars, for the first instance of a specific substring.

int	SDL::wcscmp (const wchar_t str1, const wchar_t str2)
	Compare two null-terminated wide strings.

int	SDL::wcsncmp (const wchar_t str1, const wchar_t str2, size_t maxlen)
	Compare two wide strings up to a number of wchar_t values.

int	SDL::wcscasecmp (const wchar_t str1, const wchar_t str2)
	Compare two null-terminated wide strings, case-insensitively.

int	SDL::wcsncasecmp (const wchar_t str1, const wchar_t str2, size_t maxlen)
	Compare two wide strings, case-insensitively, up to a number of wchar_t.

long	SDL::wcstol (const wchar_t str, wchar_t *endp, int base)
	Parse a `long` from a wide string.

size_t	SDL::strlen (StringParam str)
	This works exactly like strlen() but doesn't require access to a C runtime.

size_t	SDL::strnlen (StringParam str, size_t maxlen)
	This works exactly like strnlen() but doesn't require access to a C runtime.

size_t	SDL::strlcpy (char *dst, StringParam src, size_t maxlen)
	Copy a string.

size_t	SDL::utf8strlcpy (char *dst, StringParam src, size_t dst_bytes)
	Copy an UTF-8 string.

size_t	SDL::strlcat (char *dst, StringParam src, size_t maxlen)
	Concatenate strings.

char *	SDL::strdup (StringParam str)
	Allocate a copy of a string.

char *	SDL::strndup (StringParam str, size_t maxlen)
	Allocate a copy of a string, up to n characters.

char *	SDL::strrev (char *str)
	Reverse a string's contents.

char *	SDL::strupr (char *str)
	Convert a string to uppercase.

char *	SDL::strlwr (char *str)
	Convert a string to lowercase.

char *	SDL::strchr (StringParam str, int c)
	Search a string for the first instance of a specific byte.

char *	SDL::strrchr (StringParam str, int c)
	Search a string for the last instance of a specific byte.

char *	SDL::strstr (StringParam haystack, StringParam needle)
	Search a string for the first instance of a specific substring.

char *	SDL::strnstr (StringParam haystack, StringParam needle, size_t maxlen)
	Search a string, up to n bytes, for the first instance of a specific substring.

char *	SDL::strcasestr (StringParam haystack, StringParam needle)
	Search a UTF-8 string for the first instance of a specific substring, case-insensitively.

char *	SDL::strtok_r (char str, StringParam delim, char *saveptr)
	This works exactly like strtok_r() but doesn't require access to a C runtime.

size_t	SDL::utf8strlen (StringParam str)
	Count the number of codepoints in a UTF-8 string.

size_t	SDL::utf8strnlen (StringParam str, size_t bytes)
	Count the number of codepoints in a UTF-8 string, up to n bytes.

char *	SDL::itoa (int value, char *str, int radix)
	Convert an integer into a string.

char *	SDL::uitoa (unsigned int value, char *str, int radix)
	Convert an unsigned integer into a string.

char *	SDL::ltoa (long value, char *str, int radix)
	Convert a long integer into a string.

char *	SDL::ultoa (unsigned long value, char *str, int radix)
	Convert an unsigned long integer into a string.

int	SDL::atoi (StringParam str)
	Parse an `int` from a string.

double	SDL::atof (StringParam str)
	Parse a `double` from a string.

long	SDL::strtol (StringParam str, char **endp, int base)
	Parse a `long` from a string.

unsigned long	SDL::strtoul (StringParam str, char **endp, int base)
	Parse an `unsigned long` from a string.

double	SDL::strtod (StringParam str, char **endp)
	Parse a `double` from a string.

int	SDL::strcmp (StringParam str1, StringParam str2)
	Compare two null-terminated UTF-8 strings.

int	SDL::strncmp (StringParam str1, StringParam str2, size_t maxlen)
	Compare two UTF-8 strings up to a number of bytes.

int	SDL::strcasecmp (StringParam str1, StringParam str2)
	Compare two null-terminated UTF-8 strings, case-insensitively.

int	SDL::strncasecmp (StringParam str1, StringParam str2, size_t maxlen)
	Compare two UTF-8 strings, case-insensitively, up to a number of bytes.

char *	SDL::strpbrk (StringParam str, StringParam breakset)
	Searches a string for the first occurence of any character contained in a breakset, and returns a pointer from the string to that character.

Uint32	SDL::StepUTF8 (const char *pstr, size_t pslen)
	Decode a UTF-8 string, one Unicode codepoint at a time.

Uint32	SDL::StepBackUTF8 (StringParam start, const char **pstr)
	Decode a UTF-8 string in reverse, one Unicode codepoint at a time.

char *	SDL::UCS4ToUTF8 (Uint32 codepoint, char *dst)
	Convert a single Unicode codepoint to UTF-8.

int	SDL::sscanf (StringParam text, SDL_SCANF_FORMAT_STRING const char *fmt,...)
	This works exactly like sscanf() but doesn't require access to a C runtime.

int	SDL::vsscanf (StringParam text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap)
	This works exactly like vsscanf() but doesn't require access to a C runtime.

int	SDL::snprintf (char text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char fmt,...)
	This works exactly like snprintf() but doesn't require access to a C runtime.

int	SDL::swprintf (wchar_t text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t fmt,...)
	This works exactly like swprintf() but doesn't require access to a C runtime.

int	SDL::vsnprintf (char text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char fmt, va_list ap)
	This works exactly like vsnprintf() but doesn't require access to a C runtime.

int	SDL::vswprintf (wchar_t text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t fmt, va_list ap)
	This works exactly like vswprintf() but doesn't require access to a C runtime.

int	SDL::asprintf (char *strp, SDL_PRINTF_FORMAT_STRING const char fmt,...)
	This works exactly like asprintf() but doesn't require access to a C runtime.

int	SDL::vasprintf (char *strp, SDL_PRINTF_FORMAT_STRING const char fmt, va_list ap)
	This works exactly like vasprintf() but doesn't require access to a C runtime.

void	SDL::srand (Uint64 seed)
	Seeds the pseudo-random number generator.

Sint32	SDL::rand (Sint32 n)
	Generate a pseudo-random number less than n for positive n.

float	SDL::randf ()
	Generate a uniform pseudo-random floating point number less than 1.0.

Uint32	SDL::rand_bits ()
	Generate 32 pseudo-random bits.

double	SDL::acos (double x)
	Compute the arc cosine of `x`.

float	SDL::acos (float x)
	Compute the arc cosine of `x`.

double	SDL::asin (double x)
	Compute the arc sine of `x`.

float	SDL::asin (float x)
	Compute the arc sine of `x`.

double	SDL::atan (double x)
	Compute the arc tangent of `x`.

float	SDL::atan (float x)
	Compute the arc tangent of `x`.

double	SDL::atan2 (double y, double x)
	Compute the arc tangent of `y / x`, using the signs of x and y to adjust the result's quadrant.

float	SDL::atan2 (float y, float x)
	Compute the arc tangent of `y / x`, using the signs of x and y to adjust the result's quadrant.

double	SDL::ceil (double x)
	Compute the ceiling of `x`.

float	SDL::ceil (float x)
	Compute the ceiling of `x`.

double	SDL::copysign (double x, double y)
	Copy the sign of one floating-point value to another.

float	SDL::copysign (float x, float y)
	Copy the sign of one floating-point value to another.

double	SDL::cos (double x)
	Compute the cosine of `x`.

float	SDL::cos (float x)
	Compute the cosine of `x`.

double	SDL::exp (double x)
	Compute the exponential of `x`.

float	SDL::exp (float x)
	Compute the exponential of `x`.

double	SDL::floor (double x)
	Compute the floor of `x`.

float	SDL::floor (float x)
	Compute the floor of `x`.

double	SDL::trunc (double x)
	Truncate `x` to an integer.

float	SDL::trunc (float x)
	Truncate `x` to an integer.

double	SDL::fmod (double x, double y)
	Return the floating-point remainder of `x / y`

float	SDL::fmod (float x, float y)
	Return the floating-point remainder of `x / y`

int	SDL::isinf (double x)
	Return whether the value is infinity.

int	SDL::isinf (float x)
	Return whether the value is infinity.

int	SDL::isnan (double x)
	Return whether the value is NaN.

int	SDL::isnan (float x)
	Return whether the value is NaN.

double	SDL::log (double x)
	Compute the natural logarithm of `x`.

float	SDL::log (float x)
	Compute the natural logarithm of `x`.

double	SDL::log10 (double x)
	Compute the base-10 logarithm of `x`.

float	SDL::log10 (float x)
	Compute the base-10 logarithm of `x`.

double	SDL::modf (double x, double *y)
	Split `x` into integer and fractional parts.

float	SDL::modf (float x, float *y)
	Split `x` into integer and fractional parts.

double	SDL::pow (double x, double y)
	Raise `x` to the power `y`

float	SDL::pow (float x, float y)
	Raise `x` to the power `y`

double	SDL::round (double x)
	Round `x` to the nearest integer.

float	SDL::round (float x)
	Round `x` to the nearest integer.

long	SDL::lround (double x)
	Round `x` to the nearest integer representable as a long.

long	SDL::lround (float x)
	Round `x` to the nearest integer representable as a long.

double	SDL::scalbn (double x, int n)
	Scale `x` by an integer power of two.

float	SDL::scalbn (float x, int n)
	Scale `x` by an integer power of two.

double	SDL::sin (double x)
	Compute the sine of `x`.

float	SDL::sin (float x)
	Compute the sine of `x`.

double	SDL::sqrt (double x)
	Compute the square root of `x`.

float	SDL::sqrt (float x)
	Compute the square root of `x`.

double	SDL::tan (double x)
	Compute the tangent of `x`.

float	SDL::tan (float x)
	Compute the tangent of `x`.

OwnPtr< char >	SDL::iconv_string (StringParam tocode, StringParam fromcode, StringParam inbuf, size_t inbytesleft)
	Helper function to convert a string's encoding in one call.

bool	SDL::size_mul_check_overflow (size_t a, size_t b, size_t *ret)
	Multiply two integers, checking for overflow.

bool	SDL::size_add_check_overflow (size_t a, size_t b, size_t *ret)
	Add two integers, checking for overflow.

Variables
constexpr Sint8	SDL::MAX_SINT8 = SDL_MAX_SINT8

constexpr Sint8	SDL::MIN_SINT8 = SDL_MIN_SINT8

constexpr Uint8	SDL::MAX_UINT8 = SDL_MAX_UINT8

constexpr Uint8	SDL::MIN_UINT8 = SDL_MIN_UINT8

constexpr Sint16	SDL::MAX_SINT16 = SDL_MAX_SINT16

constexpr Sint16	SDL::MIN_SINT16 = SDL_MIN_SINT16

constexpr Uint16	SDL::MAX_UINT16 = SDL_MAX_UINT16

constexpr Uint16	SDL::MIN_UINT16 = SDL_MIN_UINT16

constexpr Sint32	SDL::MAX_SINT32 = SDL_MAX_SINT32

constexpr Sint32	SDL::MIN_SINT32 = SDL_MIN_SINT32

constexpr Uint32	SDL::MAX_UINT32 = SDL_MAX_UINT32

constexpr Uint8	SDL::MIN_UINT32 = SDL_MIN_UINT32

constexpr Sint64	SDL::MAX_SINT64 = SDL_MAX_SINT64

constexpr Sint64	SDL::MIN_SINT64 = SDL_MIN_SINT64

constexpr Uint64	SDL::MAX_UINT64 = SDL_MAX_UINT64

constexpr Uint8	SDL::MIN_UINT64 = SDL_MIN_UINT64

constexpr Time	SDL::MAX_TIME = Time::FromNS(SDL_MAX_TIME)

constexpr Time	SDL::MIN_TIME = Time::FromNS(SDL_MIN_TIME)

constexpr Uint32	SDL::INVALID_UNICODE_CODEPOINT = SDL_INVALID_UNICODE_CODEPOINT
	The Unicode REPLACEMENT CHARACTER codepoint.

constexpr double	SDL::PI_D = SDL_PI_D
	The value of Pi, as a double-precision floating point literal.

constexpr float	SDL::PI_F = SDL_PI_F
	The value of Pi, as a single-precision floating point literal.

Detailed Description

Using these functions allows an app to have access to common C functionality without depending on a specific C runtime (or a C runtime at all). More importantly, the SDL implementations work identically across platforms, so apps can avoid surprises like snprintf() behaving differently between Windows and Linux builds, or itoa() only existing on some platforms.

For many of the most common functions, like SDL_memcpy, SDL might just call through to the usual C runtime behind the scenes, if it makes sense to do so (if it's faster and always available/reliable on a given platform), reducing library size and offering the most optimized option.

SDL also offers other C-runtime-adjacent functionality in this header that either isn't, strictly speaking, part of any C runtime standards, like SDL_crc32() and SDL_reinterpret_cast, etc. It also offers a few better options, like SDL_strlcpy(), which functions as a safer form of strcpy().

Macro Definition Documentation

◆ SDL_copyp

#define SDL_copyp	(	dst,
		src
	)

Value:

  {                                                                            \
    SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof(*(dst)) == sizeof(*(src)));      \
  }                                                                            \
  SDL_memcpy((dst), (src), sizeof(*(src)))

memcpy and memmove do not care where you copy memory to and from, which can lead to bugs. This macro aims to avoid most of those bugs by making sure that the source and destination are both pointers to objects that are the same size. It does not check that the objects are the same type, just that the copy will not overflow either object.

The size check happens at compile time, and the compiler will throw an error if the objects are different sizes.

Generally this is intended to copy a single object, not an array.

This macro looks like it double-evaluates its parameters, but the extras them are in sizeof sections, which generate no code nor side-effects.

Parameters

dst	a pointer to the destination object. Must not be nullptr.
src	a pointer to the source object. Must not be nullptr.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ SDL_FLT_EPSILON

#define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */

Equals by default to platform-defined FLT_EPSILON, or 1.1920928955078125e-07F if that's not available.

Since: This macro is available since SDL 3.2.0.

◆ SDL_ICONV_ERROR

#define SDL_ICONV_ERROR (size_t)-1

Check GetError()?

◆ SDL_iconv_utf8_locale

#define SDL_iconv_utf8_locale ( S ) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S) + 1)

This is a helper macro that might be more clear than calling iconv_string directly. However, it double-evaluates its parameter, so do not use an expression with side-effects here.

Parameters

S	the string to convert.

Returns: a new string, converted to the new encoding, or nullptr on error.

Since: This macro is available since SDL 3.2.0.

◆ SDL_iconv_utf8_ucs2

#define SDL_iconv_utf8_ucs2 ( S ) (Uint16*)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S) + 1)

This is a helper macro that might be more clear than calling iconv_string directly. However, it double-evaluates its parameter, so do not use an expression with side-effects here.

Parameters

S	the string to convert.

Returns: a new string, converted to the new encoding, or nullptr on error.

Since: This macro is available since SDL 3.2.0.

◆ SDL_iconv_utf8_ucs4

#define SDL_iconv_utf8_ucs4 ( S ) (Uint32*)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S) + 1)

This is a helper macro that might be more clear than calling iconv_string directly. However, it double-evaluates its parameter, so do not use an expression with side-effects here.

Parameters

S	the string to convert.

Returns: a new string, converted to the new encoding, or nullptr on error.

Since: This macro is available since SDL 3.2.0.

◆ SDL_iconv_wchar_utf8

#define SDL_iconv_wchar_utf8 ( S )

Value:

SDL_iconv_string( \

"UTF-8", "WCHAR_T", (char*)S, (SDL_wcslen(S) + 1) * sizeof(wchar_t))

This is a helper macro that might be more clear than calling iconv_string directly. However, it double-evaluates its parameter, so do not use an expression with side-effects here.

Parameters

S	the string to convert.

Returns: a new string, converted to the new encoding, or nullptr on error.

Since: This macro is available since SDL 3.2.0.

◆ SDL_INIT_INTERFACE

#define SDL_INIT_INTERFACE ( iface )

Value:

  do {                                                                         \
    SDL_zerop(iface);                                                          \
    (iface)->version = sizeof(*(iface));                                       \
  } while (0)

This macro will initialize an SDL interface structure and should be called before you fill out the fields with your implementation.

You can use it like this:

IOStreamInterface iface;
 
SDL_INIT_INTERFACE(&iface);
 
// Fill in the interface function pointers with your implementation
iface.seek = ...
 
stream = IOStreamBase.IOStreamBase(&iface, nullptr);

If you are using designated initializers, you can use the size of the interface as the version, e.g.

IOStreamInterface iface = {
    .version = sizeof(iface),
    .seek = ...
};
stream = IOStreamBase.IOStreamBase(&iface, nullptr);

Thread safety:: It is safe to call this macro from any thread.

Since: This macro is available since SDL 3.2.0.

See also: IOStreamInterface; StorageInterface; VirtualJoystickDesc

◆ SDL_NOLONGLONG

#define SDL_NOLONGLONG 1

SDL will define this if it believes the compiler doesn't understand the "long long" syntax for C datatypes. This can happen on older compilers.

If your compiler doesn't support "long long" but SDL doesn't know it, it is safe to define this yourself to build against the SDL headers.

If this is defined, it will remove access to some C runtime support functions, like SDL_ulltoa and SDL_strtoll that refer to this datatype explicitly. The rest of SDL will still be available.

SDL's own source code cannot be built with a compiler that has this defined, for various technical reasons.

◆ SDL_SINT64_C

#define SDL_SINT64_C ( c ) c##LL /* or whatever the current compiler uses. */

This helps compilers that might believe a integer literal larger than 0xFFFFFFFF is overflowing a 32-bit value. Use SDL_SINT64_C(0xFFFFFFFF1) instead of 0xFFFFFFFF1 by itself.

Since: This macro is available since SDL 3.2.0.

See also: SDL_UINT64_C

◆ SDL_SIZE_MAX

#define SDL_SIZE_MAX SIZE_MAX

size_t is generally the same size as a pointer in modern times, but this can get weird on very old and very esoteric machines. For example, on a 16-bit Intel 286, you might have a 32-bit "far" pointer (16-bit segment plus 16-bit offset), but size_t is 16 bits, because it can only deal with the offset into an individual segment.

In modern times, it's generally expected to cover an entire linear address space. But be careful!

Since: This macro is available since SDL 3.2.0.

◆ SDL_STRINGIFY_ARG

#define SDL_STRINGIFY_ARG ( arg ) #arg

For example:

#define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X

"@n")`

Parameters

arg	the text to turn into a string literal.

Since: This macro is available since SDL 3.2.0.

◆ SDL_UINT64_C

#define SDL_UINT64_C ( c ) c##ULL /* or whatever the current compiler uses. */

This helps compilers that might believe a integer literal larger than 0xFFFFFFFF is overflowing a 32-bit value. Use SDL_UINT64_C(0xFFFFFFFF1) instead of 0xFFFFFFFF1 by itself.

Since: This macro is available since SDL 3.2.0.

See also: SDL_SINT64_C

Typedef Documentation

◆ calloc_func

using SDL::calloc_func = typedef SDL_calloc_func

SDL will always ensure that the passed nmemb and size are both greater than 0.

Parameters

nmemb	the number of elements in the array.
size	the size of each element of the array.

Returns: a pointer to the allocated array, or nullptr if allocation failed.

Thread safety:: It should be safe to call this callback from any thread.

Since: This datatype is available since SDL 3.2.0.

See also: calloc; GetOriginalMemoryFunctions; GetMemoryFunctions; SetMemoryFunctions

◆ CompareCallback

using SDL::CompareCallback = typedef SDL_CompareCallback

Parameters

a	a pointer to the first element being compared.
b	a pointer to the second element being compared.

Returns: -1 if a should be sorted before b, 1 if b should be sorted before a, 0 if they are equal. If two elements are equal, their order in the sorted array is undefined.

Since: This callback is available since SDL 3.2.0.

See also: bsearch; qsort

◆ CompareCallback_r

using SDL::CompareCallback_r = typedef SDL_CompareCallback_r

Parameters

userdata	the `userdata` pointer passed to the sort function.
a	a pointer to the first element being compared.
b	a pointer to the second element being compared.

Returns: -1 if a should be sorted before b, 1 if b should be sorted before a, 0 if they are equal. If two elements are equal, their order in the sorted array is undefined.

Since: This callback is available since SDL 3.2.0.

See also: qsort_r; bsearch_r

◆ CompareCB

using SDL::CompareCB = typedef std::function<int(const void*, const void*)>

Parameters

a	a pointer to the first element being compared.
b	a pointer to the second element being compared.

Returns: -1 if a should be sorted before b, 1 if b should be sorted before a, 0 if they are equal. If two elements are equal, their order in the sorted array is undefined.

Since: This callback is available since SDL 3.2.0.

See also: qsort_r; bsearch_r; CompareCallback_r

◆ free_func

using SDL::free_func = typedef SDL_free_func

SDL will always ensure that the passed mem is a non-nullptr pointer.

Parameters

mem	a pointer to allocated memory.

Thread safety:: It should be safe to call this callback from any thread.

Since: This datatype is available since SDL 3.2.0.

See also: free; GetOriginalMemoryFunctions; GetMemoryFunctions; SetMemoryFunctions

◆ FunctionPointer

using SDL::FunctionPointer = typedef SDL_FunctionPointer

In theory, generic function pointers should use this, instead of void *, since some platforms could treat code addresses differently than data addresses. Although in current times no popular platforms make this distinction, it is more correct and portable to use the correct type for a generic pointer.

If for some reason you need to force this typedef to be an actual void *, perhaps to work around a compiler or existing code, you can define SDL_FUNCTION_POINTER_IS_VOID_POINTER before including any SDL headers.

Since: This datatype is available since SDL 3.2.0.

◆ malloc_func

using SDL::malloc_func = typedef SDL_malloc_func

SDL will always ensure that the passed size is greater than 0.

Parameters

size	the size to allocate.

Returns: a pointer to the allocated memory, or nullptr if allocation failed.

Thread safety:: It should be safe to call this callback from any thread.

Since: This datatype is available since SDL 3.2.0.

See also: malloc; GetOriginalMemoryFunctions; GetMemoryFunctions; SetMemoryFunctions

◆ realloc_func

using SDL::realloc_func = typedef SDL_realloc_func

SDL will always ensure that the passed size is greater than 0.

Parameters

mem	a pointer to allocated memory to reallocate, or nullptr.
size	the new size of the memory.

Returns: a pointer to the newly allocated memory, or nullptr if allocation failed.

Thread safety:: It should be safe to call this callback from any thread.

Since: This datatype is available since SDL 3.2.0.

See also: realloc; GetOriginalMemoryFunctions; GetMemoryFunctions; SetMemoryFunctions

Function Documentation

◆ abs() [1/3]

double SDL::abs ( double x )

inline

Domain: -INF <= x <= INF

Range: 0 <= y <= INF

Parameters

x	floating point value to use as the magnitude.

Returns: the absolute value of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: abs

◆ abs() [2/3]

float SDL::abs ( float x )

inline

Domain: -INF <= x <= INF

Range: 0 <= y <= INF

Parameters

x	floating point value to use as the magnitude.

Returns: the absolute value of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: abs

◆ abs() [3/3]

int SDL::abs ( int x )

inline

Parameters

x	an integer value.

Returns: the absolute value of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ acos() [1/2]

double SDL::acos ( double x )

inline

The definition of y = acos(x) is x = cos(y).

Domain: -1 <= x <= 1

Range: 0 <= y <= Pi

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value.

Returns: arc cosine of x, in radians.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: asin; cos

◆ acos() [2/2]

float SDL::acos ( float x )

inline

The definition of y = acos(x) is x = cos(y).

Domain: -1 <= x <= 1

Range: 0 <= y <= Pi

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value.

Returns: arc cosine of x, in radians.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: asin; cos

◆ aligned_alloc()

void * SDL::aligned_alloc	(	size_t	alignment,
		size_t	size
	)

inline

The memory returned by this function must be freed with aligned_free(), not free().

If alignment is less than the size of void *, it will be increased to match that.

The returned memory address will be a multiple of the alignment value, and the size of the memory allocated will be a multiple of the alignment value.

Parameters

alignment	the alignment of the memory.
size	the size to allocate.

Returns: a pointer to the aligned memory, or nullptr if allocation failed.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: aligned_free

◆ aligned_free()

void SDL::aligned_free ( void * mem )

inline

The pointer is no longer valid after this call and cannot be dereferenced anymore.

If mem is nullptr, this function does nothing.

Parameters

mem	a pointer previously returned by aligned_alloc(), or nullptr.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: aligned_alloc

◆ arraysize()

template<class T , std::size_t N>

constexpr std::size_t SDL::arraysize ( const T(&) array[N] )

constexpr

This will compile but return incorrect results for a pointer to an array; it has to be an array the compiler knows the size of.

Since: This function is available since SDL 3.2.0.

◆ asin() [1/2]

double SDL::asin ( double x )

inline

The definition of y = asin(x) is x = sin(y).

Domain: -1 <= x <= 1

Range: -Pi/2 <= y <= Pi/2

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value.

Returns: arc sine of x, in radians.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: acos; sin

◆ asin() [2/2]

float SDL::asin ( float x )

inline

The definition of y = asin(x) is x = sin(y).

Domain: -1 <= x <= 1

Range: -Pi/2 <= y <= Pi/2

This function operates on single-precision floating point values, use asin for double-precision floats.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value.

Returns: arc sine of x, in radians.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: acos; sin

◆ asprintf()

int SDL::asprintf	(	char **	strp,
		SDL_PRINTF_FORMAT_STRING const char *	fmt,
			...
	)

inline

Functions identically to snprintf(), except it allocates a buffer large enough to hold the output string on behalf of the caller.

On success, this function returns the number of bytes (not characters) comprising the output string, not counting the null-terminator character, and sets *strp to the newly-allocated string.

On error, this function returns a negative number, and the value of *strp is undefined.

The returned string is owned by the caller, and should be passed to free when no longer needed.

Parameters

strp	on output, is set to the new string. Must not be nullptr.
fmt	a printf-style format string. Must not be nullptr.
...	a list of values to be used with the format string.

Returns: the number of bytes in the newly-allocated string, not counting the null-terminator char, or a negative value on error.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ atan() [1/2]

double SDL::atan ( double x )

inline

The definition of y = atan(x) is x = tan(y).

Domain: -INF <= x <= INF

Range: -Pi/2 <= y <= Pi/2

To calculate the arc tangent of y / x, use atan2.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value.

Returns: arc tangent of of x in radians, or 0 if x = 0.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: atan2; tan

◆ atan() [2/2]

float SDL::atan ( float x )

inline

The definition of y = atan(x) is x = tan(y).

Domain: -INF <= x <= INF

Range: -Pi/2 <= y <= Pi/2

To calculate the arc tangent of y / x, use atan2f.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value.

Returns: arc tangent of of x in radians, or 0 if x = 0.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: atan2

◆ atan2() [1/2]

double SDL::atan2	(	double	y,
		double	x
	)

inline

The definition of z = atan2(x, y) is y = x tan(z), where the quadrant of z is determined based on the signs of x and y.

Domain: -INF <= x <= INF, -INF <= y <= INF

Range: -Pi/2 <= y <= Pi/2

This function operates on double-precision floating point values, use atan2f for single-precision floats.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

y	floating point value of the numerator (y coordinate).
x	floating point value of the denominator (x coordinate).

Returns: arc tangent of of y / x in radians, or, if x = 0, either -Pi/2, 0, or Pi/2, depending on the value of y.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: atan; tan

◆ atan2() [2/2]

float SDL::atan2	(	float	y,
		float	x
	)

inline

The definition of z = atan2(x, y) is y = x tan(z), where the quadrant of z is determined based on the signs of x and y.

Domain: -INF <= x <= INF, -INF <= y <= INF

Range: -Pi/2 <= y <= Pi/2

This function operates on single-precision floating point values, use atan2 for double-precision floats.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

y	floating point value of the numerator (y coordinate).
x	floating point value of the denominator (x coordinate).

Returns: arc tangent of of y / x in radians, or, if x = 0, either -Pi/2, 0, or Pi/2, depending on the value of y.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: atan; tan

◆ atof()

double SDL::atof ( StringParam str )

inline

The result of calling atof(str) is equivalent to strtod(str, nullptr).

Parameters

str	The null-terminated string to read. Must not be nullptr.

Returns: the parsed double.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: atoi; strtol; strtoul; SDL_strtoll; SDL_strtoull; strtod

◆ atoi()

int SDL::atoi ( StringParam str )

inline

The result of calling atoi(str) is equivalent to (int)strtol(str, nullptr, 10).

Parameters

str	The null-terminated string to read. Must not be nullptr.

Returns: the parsed int.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: atof; strtol; strtoul; SDL_strtoll; SDL_strtoull; strtod; itoa

◆ bsearch()

void * SDL::bsearch	(	const void *	key,
		const void *	base,
		size_t	nmemb,
		size_t	size,
		CompareCallback	compare
	)

inline

For example:

typedef struct {
    int key;
    const char *string;
} data;
 
int SDLCALL compare(const void *a, const void *b)
{
    const data *A = (const data *)a;
    const data *B = (const data *)b;
 
    if (A->n < B->n) {
        return -1;
    } else if (B->n < A->n) {
        return 1;
    } else {
        return 0;
    }
}
 
data values[] = {
    { 1, "first" }, { 2, "second" }, { 3, "third" }
};
data key = { 2, nullptr };
 
data *result = bsearch(&key, values, arraysize(values), sizeof(values[0]),
compare);

Parameters

key	a pointer to a key equal to the element being searched for.
base	a pointer to the start of the array.
nmemb	the number of elements in the array.
size	the size of the elements in the array.
compare	a function used to compare elements in the array.

Returns: a pointer to the matching element in the array, or nullptr if not found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: bsearch_r; qsort

◆ bsearch_r() [1/2]

void * SDL::bsearch_r	(	const void *	key,
		const void *	base,
		size_t	nmemb,
		size_t	size,
		CompareCallback_r	compare,
		void *	userdata
	)

inline

For example:

typedef enum {
    sort_increasing,
    sort_decreasing,
} sort_method;
 
typedef struct {
    int key;
    const char *string;
} data;
 
int SDLCALL compare(const void *userdata, const void *a, const void *b)
{
    sort_method method = (sort_method)(uintptr_t)userdata;
    const data *A = (const data *)a;
    const data *B = (const data *)b;
 
    if (A->key < B->key) {
        return (method == sort_increasing) ? -1 : 1;
    } else if (B->key < A->key) {
        return (method == sort_increasing) ? 1 : -1;
    } else {
        return 0;
    }
}
 
data values[] = {
    { 1, "first" }, { 2, "second" }, { 3, "third" }
};
data key = { 2, nullptr };
 
data *result = bsearch_r(&key, values, arraysize(values), sizeof(values[0]),
compare, (const void *)(uintptr_t)sort_increasing);

Parameters

key	a pointer to a key equal to the element being searched for.
base	a pointer to the start of the array.
nmemb	the number of elements in the array.
size	the size of the elements in the array.
compare	a function used to compare elements in the array.
userdata	a pointer to pass to the compare function.

Returns: a pointer to the matching element in the array, or nullptr if not found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: bsearch; qsort_r

◆ bsearch_r() [2/2]

void * SDL::bsearch_r	(	const void *	key,
		const void *	base,
		size_t	nmemb,
		size_t	size,
		CompareCB	compare
	)

inline

For example:

typedef enum {
    sort_increasing,
    sort_decreasing,
} sort_method;
 
typedef struct {
    int key;
    const char *string;
} data;
 
int SDLCALL compare(const void *userdata, const void *a, const void *b)
{
    sort_method method = (sort_method)(uintptr_t)userdata;
    const data *A = (const data *)a;
    const data *B = (const data *)b;
 
    if (A->key < B->key) {
        return (method == sort_increasing) ? -1 : 1;
    } else if (B->key < A->key) {
        return (method == sort_increasing) ? 1 : -1;
    } else {
        return 0;
    }
}
 
data values[] = {
    { 1, "first" }, { 2, "second" }, { 3, "third" }
};
data key = { 2, nullptr };
 
data *result = bsearch_r(&key, values, arraysize(values), sizeof(values[0]),
compare, (const void *)(uintptr_t)sort_increasing);

Parameters

key	a pointer to a key equal to the element being searched for.
base	a pointer to the start of the array.
nmemb	the number of elements in the array.
size	the size of the elements in the array.
compare	a function used to compare elements in the array.

Returns: a pointer to the matching element in the array, or nullptr if not found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: bsearch; qsort_r

◆ calloc()

void * SDL::calloc	(	size_t	nmemb,
		size_t	size
	)

inline

The memory returned by this function must be freed with free().

If either of nmemb or size is 0, they will both be set to 1.

If the allocation is successful, the returned pointer is guaranteed to be aligned to either the fundamental alignment (alignof(max_align_t) in C11 and later) or 2 * sizeof(void *), whichever is smaller.

Parameters

nmemb	the number of elements in the array.
size	the size of each element of the array.

Returns: a pointer to the allocated array, or nullptr if allocation failed.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: free; malloc; realloc

◆ ceil() [1/2]

double SDL::ceil ( double x )

inline

The ceiling of x is the smallest integer y such that y > x, i.e x rounded up to the nearest integer.

Domain: -INF <= x <= INF

Range: -INF <= y <= INF, y integer

Parameters

x	floating point value.

Returns: the ceiling of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: floor; trunc; round; lround

◆ ceil() [2/2]

float SDL::ceil ( float x )

inline

The ceiling of x is the smallest integer y such that y > x, i.e x rounded up to the nearest integer.

Domain: -INF <= x <= INF

Range: -INF <= y <= INF, y integer

Parameters

x	floating point value.

Returns: the ceiling of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: floor; trunc; round; lround

◆ clamp()

template<class T , class U , class V >

constexpr T SDL::clamp	(	T	x,
		U	a,
		V	b
	)

constexpr

If x is outside the range a values between a and b, the returned value will be a or b as appropriate. Otherwise, x is returned.

This function will produce incorrect results if b is less than a.

This is a helper function that might be more clear than writing out the comparisons directly, and works with any type that can be compared with the < and > operators. However, it double-evaluates all its parameters, so do not use expressions with side-effects here.

Parameters

x	the value to compare.
a	the low end value.
b	the high end value.

Returns: x, clamped between a and b.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ copysign() [1/2]

double SDL::copysign	(	double	x,
		double	y
	)

inline

The definition of copysign is that copysign(x, y) = abs(x) * sign(y).

Domain: -INF <= x <= INF, -INF <= y <= f

Range: -INF <= z <= INF

Parameters

x	floating point value to use as the magnitude.
y	floating point value to use as the sign.

Returns: the floating point value with the sign of y and the magnitude of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: abs

◆ copysign() [2/2]

float SDL::copysign	(	float	x,
		float	y
	)

inline

The definition of copysign is that copysign(x, y) = abs(x) * sign(y).

Domain: -INF <= x <= INF, -INF <= y <= f

Range: -INF <= z <= INF

Parameters

x	floating point value to use as the magnitude.
y	floating point value to use as the sign.

Returns: the floating point value with the sign of y and the magnitude of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: abs

◆ cos() [1/2]

double SDL::cos ( double x )

inline

Domain: -INF <= x <= INF

Range: -1 <= y <= 1

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value, in radians.

Returns: cosine of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: acos; sin

◆ cos() [2/2]

float SDL::cos ( float x )

inline

Domain: -INF <= x <= INF

Range: -1 <= y <= 1

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value, in radians.

Returns: cosine of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: acos; sin

◆ crc16()

Uint16 SDL::crc16	(	Uint16	crc,
		const void *	data,
		size_t	len
	)

inline

https://en.wikipedia.org/wiki/Cyclic_redundancy_check

This function can be called multiple times, to stream data to be checksummed in blocks. Each call must provide the previous CRC-16 return value to be updated with the next block. The first call to this function for a set of blocks should pass in a zero CRC value.

Parameters

crc	the current checksum for this data set, or 0 for a new data set.
data	a new block of data to add to the checksum.
len	the size, in bytes, of the new block of data.

Returns: a CRC-16 checksum value of all blocks in the data set.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ crc32()

Uint32 SDL::crc32	(	Uint32	crc,
		const void *	data,
		size_t	len
	)

inline

https://en.wikipedia.org/wiki/Cyclic_redundancy_check

This function can be called multiple times, to stream data to be checksummed in blocks. Each call must provide the previous CRC-32 return value to be updated with the next block. The first call to this function for a set of blocks should pass in a zero CRC value.

Parameters

crc	the current checksum for this data set, or 0 for a new data set.
data	a new block of data to add to the checksum.
len	the size, in bytes, of the new block of data.

Returns: a CRC-32 checksum value of all blocks in the data set.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ exp() [1/2]

double SDL::exp ( double x )

inline

The definition of y = exp(x) is y = e^x, where e is the base of the natural logarithm. The inverse is the natural logarithm, log().

Domain: -INF <= x <= INF

Range: 0 <= y <= INF

The output will overflow if exp(x) is too large to be represented.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value.

Returns: value of e^x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: log

◆ exp() [2/2]

float SDL::exp ( float x )

inline

The definition of y = exp(x) is y = e^x, where e is the base of the natural logarithm. The inverse is the natural logarithm, log().

Domain: -INF <= x <= INF

Range: 0 <= y <= INF

The output will overflow if exp(x) is too large to be represented.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value.

Returns: value of e^x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: log

◆ floor() [1/2]

double SDL::floor ( double x )

inline

The floor of x is the largest integer y such that y > x, i.e x rounded down to the nearest integer.

Domain: -INF <= x <= INF

Range: -INF <= y <= INF, y integer

Parameters

x	floating point value.

Returns: the floor of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: ceil; trunc; round; lround

◆ floor() [2/2]

float SDL::floor ( float x )

inline

The floor of x is the largest integer y such that y > x, i.e x rounded down to the nearest integer.

Domain: -INF <= x <= INF

Range: -INF <= y <= INF, y integer

Parameters

x	floating point value.

Returns: the floor of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: ceil; trunc; round; lround

◆ fmod() [1/2]

double SDL::fmod	(	double	x,
		double	y
	)

inline

Divides x by y, and returns the remainder.

Domain: -INF <= x <= INF, -INF <= y <= INF, y != 0

Range: -y <= z <= y

Parameters

x	the numerator.
y	the denominator. Must not be 0.

Returns: the remainder of x / y.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: modf; trunc; ceil; floor; round; lround

◆ fmod() [2/2]

float SDL::fmod	(	float	x,
		float	y
	)

inline

Divides x by y, and returns the remainder.

Domain: -INF <= x <= INF, -INF <= y <= INF, y != 0

Range: -y <= z <= y

Parameters

x	the numerator.
y	the denominator. Must not be 0.

Returns: the remainder of x / y.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: trunc; modf; ceil; floor; round; lround

◆ FourCC()

constexpr Uint32 SDL::FourCC	(	Uint8	a,
		Uint8	b,
		Uint8	c,
		Uint8	d
	)

constexpr

Parameters

a	the first ASCII character.
b	the second ASCII character.
c	the third ASCII character.
d	the fourth ASCII character.

Returns: the four characters converted into a Uint32, one character per-byte.

Thread safety:: It is safe to call this macro from any thread.

Since: This function is available since SDL 3.2.0.

◆ free()

void SDL::free ( void * mem )

inline

The pointer is no longer valid after this call and cannot be dereferenced anymore.

If mem is nullptr, this function does nothing.

Parameters

mem	a pointer to allocated memory, or nullptr.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: malloc; calloc; realloc

◆ getenv()

const char * SDL::getenv ( StringParam name )

inline

This function uses SDL's cached copy of the environment and is thread-safe.

Parameters

name	the name of the variable to get.

Returns: a pointer to the value of the variable or nullptr if it can't be found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ getenv_unsafe()

const char * SDL::getenv_unsafe ( StringParam name )

inline

This function bypasses SDL's cached copy of the environment and is not thread-safe.

Parameters

name	the name of the variable to get.

Returns: a pointer to the value of the variable or nullptr if it can't be found.

Thread safety:: This function is not thread safe, consider using getenv() instead.

Since: This function is available since SDL 3.2.0.

See also: getenv

◆ GetEnvironment()

EnvironmentRef SDL::GetEnvironment ( )

inline

This is initialized at application start and is not affected by setenv() and unsetenv() calls after that point. Use EnvironmentBase.SetVariable() and EnvironmentBase.UnsetVariable() if you want to modify this environment, or setenv_unsafe() or unsetenv_unsafe() if you want changes to persist in the C runtime environment after Quit().

Returns: a pointer to the environment for the process or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: EnvironmentBase.GetVariable; EnvironmentBase.GetVariables; EnvironmentBase.SetVariable; EnvironmentBase.UnsetVariable

◆ GetMemoryFunctions()

void SDL::GetMemoryFunctions	(	malloc_func *	malloc_func,
		calloc_func *	calloc_func,
		realloc_func *	realloc_func,
		free_func *	free_func
	)

inline

Parameters

malloc_func	filled with malloc function.
calloc_func	filled with calloc function.
realloc_func	filled with realloc function.
free_func	filled with free function.

Thread safety:: This does not hold a lock, so do not call this in the unlikely event of a background thread calling SetMemoryFunctions simultaneously.

Since: This function is available since SDL 3.2.0.

See also: SetMemoryFunctions; GetOriginalMemoryFunctions

◆ GetNumAllocations()

int SDL::GetNumAllocations ( )

inline

Returns: the number of allocations or -1 if allocation counting is disabled.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetOriginalMemoryFunctions()

void SDL::GetOriginalMemoryFunctions	(	malloc_func *	malloc_func,
		calloc_func *	calloc_func,
		realloc_func *	realloc_func,
		free_func *	free_func
	)

inline

This is what malloc and friends will use by default, if there has been no call to SetMemoryFunctions. This is not necessarily using the C runtime's malloc functions behind the scenes! Different platforms and build configurations might do any number of unexpected things.

Parameters

malloc_func	filled with malloc function.
calloc_func	filled with calloc function.
realloc_func	filled with realloc function.
free_func	filled with free function.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ iconv_string()

OwnPtr< char > SDL::iconv_string	(	StringParam	tocode,
		StringParam	fromcode,
		StringParam	inbuf,
		size_t	inbytesleft
	)

inline

This function converts a buffer or string between encodings in one pass.

The string does not need to be nullptr-terminated; this function operates on the number of bytes specified in inbytesleft whether there is a nullptr character anywhere in the buffer.

Parameters

tocode	the character encoding of the output string. Examples are "UTF-8", "UCS-4", etc.
fromcode	the character encoding of data in `inbuf`.
inbuf	the string to convert to a different encoding.
inbytesleft	the size of the input string in bytes.

Returns: a new string, converted to the new encoding, or nullptr on error.

Since: This function is available since SDL 3.2.0.

See also: IConvBase.IConvBase; IConvBase.iconv

◆ isalnum()

int SDL::isalnum ( int x )

inline

WARNING: Regardless of system locale, this will only treat ASCII values for English 'a-z', 'A-Z', and '0-9' as true.

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ isalpha()

int SDL::isalpha ( int x )

inline

WARNING: Regardless of system locale, this will only treat ASCII values for English 'a-z' and 'A-Z' as true.

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ isblank()

int SDL::isblank ( int x )

inline

WARNING: Regardless of system locale, this will only treat ASCII values 0x20 (space) or 0x9 (tab) as true.

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ iscntrl()

int SDL::iscntrl ( int x )

inline

WARNING: Regardless of system locale, this will only treat ASCII values 0 through 0x1F, and 0x7F, as true.

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ isdigit()

int SDL::isdigit ( int x )

inline

WARNING: Regardless of system locale, this will only treat ASCII values '0' (0x30) through '9' (0x39), as true.

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ isgraph()

int SDL::isgraph ( int x )

inline

Be advised that "printable" has a definition that goes back to text terminals from the dawn of computing, making this a sort of special case function that is not suitable for Unicode (or most any) text management.

WARNING: Regardless of system locale, this is equivalent to ‘(isprint(x)) && ((x) != ’ ')`.

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: isprint

◆ isinf() [1/2]

int SDL::isinf ( double x )

inline

Parameters

x	double-precision floating point value.

Returns: non-zero if the value is infinity, 0 otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ isinf() [2/2]

int SDL::isinf ( float x )

inline

Parameters

x	floating point value.

Returns: non-zero if the value is infinity, 0 otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ islower()

int SDL::islower ( int x )

inline

WARNING: Regardless of system locale, this will only treat ASCII values 'a' through 'z' as true.

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ isnan() [1/2]

int SDL::isnan ( double x )

inline

Parameters

x	double-precision floating point value.

Returns: non-zero if the value is NaN, 0 otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ isnan() [2/2]

int SDL::isnan ( float x )

inline

Parameters

x	floating point value.

Returns: non-zero if the value is NaN, 0 otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ isprint()

int SDL::isprint ( int x )

inline

Be advised that "printable" has a definition that goes back to text terminals from the dawn of computing, making this a sort of special case function that is not suitable for Unicode (or most any) text management.

WARNING: Regardless of system locale, this will only treat ASCII values ' ' (0x20) through '~' (0x7E) as true.

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ ispunct()

int SDL::ispunct ( int x )

inline

WARNING: Regardless of system locale, this is equivalent to ((isgraph(x)) && (!isalnum(x))).

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: isgraph; isalnum

◆ isspace()

int SDL::isspace ( int x )

inline

WARNING: Regardless of system locale, this will only treat the following ASCII values as true:

space (0x20)
tab (0x09)
newline (0x0A)
vertical tab (0x0B)
form feed (0x0C)
return (0x0D)

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ isupper()

int SDL::isupper ( int x )

inline

WARNING: Regardless of system locale, this will only treat ASCII values 'A' through 'Z' as true.

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ isxdigit()

int SDL::isxdigit ( int x )

inline

WARNING: Regardless of system locale, this will only treat ASCII values 'A' through 'F', 'a' through 'f', and '0' through '9', as true.

Parameters

x	character value to check.

Returns: non-zero if x falls within the character class, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ itoa()

char * SDL::itoa	(	int	value,
		char *	str,
		int	radix
	)

inline

This requires a radix to specified for string format. Specifying 10 produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 to 36.

Note that this function will overflow a buffer if str is not large enough to hold the output! It may be safer to use snprintf to clamp output, or asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate much more space than you expect to use (and don't forget possible negative signs, null terminator bytes, etc).

Parameters

value	the integer to convert.
str	the buffer to write the string into.
radix	the radix to use for string generation.

Returns: str.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: uitoa; ltoa; SDL_lltoa

◆ log() [1/2]

double SDL::log ( double x )

inline

Domain: 0 < x <= INF

Range: -INF <= y <= INF

It is an error for x to be less than or equal to 0.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value. Must be greater than 0.

Returns: the natural logarithm of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: log10; exp

◆ log() [2/2]

float SDL::log ( float x )

inline

Domain: 0 < x <= INF

Range: -INF <= y <= INF

It is an error for x to be less than or equal to 0.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value. Must be greater than 0.

Returns: the natural logarithm of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: log10; exp

◆ log10() [1/2]

double SDL::log10 ( double x )

inline

Domain: 0 < x <= INF

Range: -INF <= y <= INF

It is an error for x to be less than or equal to 0.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value. Must be greater than 0.

Returns: the logarithm of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: log; pow

◆ log10() [2/2]

float SDL::log10 ( float x )

inline

Domain: 0 < x <= INF

Range: -INF <= y <= INF

It is an error for x to be less than or equal to 0.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value. Must be greater than 0.

Returns: the logarithm of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: log; pow

◆ lround() [1/2]

long SDL::lround ( double x )

inline

Rounds x to the nearest integer. Values halfway between integers will be rounded away from zero.

Domain: -INF <= x <= INF

Range: MIN_LONG <= y <= MAX_LONG

Parameters

x	floating point value.

Returns: the nearest integer to x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: round; floor; ceil; trunc

◆ lround() [2/2]

long SDL::lround ( float x )

inline

Rounds x to the nearest integer. Values halfway between integers will be rounded away from zero.

Domain: -INF <= x <= INF

Range: MIN_LONG <= y <= MAX_LONG

Parameters

x	floating point value.

Returns: the nearest integer to x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: round; floor; ceil; trunc

◆ ltoa()

char * SDL::ltoa	(	long	value,
		char *	str,
		int	radix
	)

inline

This requires a radix to specified for string format. Specifying 10 produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 to 36.

Note that this function will overflow a buffer if str is not large enough to hold the output! It may be safer to use snprintf to clamp output, or asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate much more space than you expect to use (and don't forget possible negative signs, null terminator bytes, etc).

Parameters

value	the long integer to convert.
str	the buffer to write the string into.
radix	the radix to use for string generation.

Returns: str.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: ultoa; itoa; SDL_lltoa

◆ malloc()

void * SDL::malloc ( size_t size )

inline

The allocated memory returned by this function must be freed with free().

If size is 0, it will be set to 1.

If the allocation is successful, the returned pointer is guaranteed to be aligned to either the fundamental alignment (alignof(max_align_t) in C11 and later) or 2 * sizeof(void *), whichever is smaller. Use aligned_alloc() if you need to allocate memory aligned to an alignment greater than this guarantee.

Parameters

size	the size to allocate.

Returns: a pointer to the allocated memory, or nullptr if allocation failed.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: free; calloc; realloc; aligned_alloc

◆ max()

template<class T , class U >

constexpr T SDL::max	(	T	x,
		U	y
	)

constexpr

This is a helper function that might be more clear than writing out the comparisons directly, and works with any type that can be compared with the > operator. However, it double-evaluates both its parameters, so do not use expressions with side-effects here.

Parameters

x	the first value to compare.
y	the second value to compare.

Returns: the lesser of x and y.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ memcmp()

int SDL::memcmp	(	const void *	s1,
		const void *	s2,
		size_t	len
	)

inline

Parameters

s1	the first buffer to compare. nullptr is not permitted!
s2	the second buffer to compare. nullptr is not permitted!
len	the number of bytes to compare between the buffers.

Returns: less than zero if s1 is "less than" s2, greater than zero if s1 is "greater than" s2, and zero if the buffers match exactly for len bytes.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ memcpy()

void * SDL::memcpy	(	void *	dst,
		const void *	src,
		size_t	len
	)

inline

The memory regions must not overlap. If they do, use memmove() instead.

Parameters

dst	The destination memory region. Must not be nullptr, and must not overlap with `src`.
src	The source memory region. Must not be nullptr, and must not overlap with `dst`.
len	The length in bytes of both `dst` and `src`.

Returns: dst.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: memmove

◆ memmove()

void * SDL::memmove	(	void *	dst,
		const void *	src,
		size_t	len
	)

inline

It is okay for the memory regions to overlap. If you are confident that the regions never overlap, using memcpy() may improve performance.

Parameters

dst	The destination memory region. Must not be nullptr.
src	The source memory region. Must not be nullptr.
len	The length in bytes of both `dst` and `src`.

Returns: dst.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: memcpy

◆ memset()

void * SDL::memset	(	void *	dst,
		int	c,
		size_t	len
	)

inline

This function will set len bytes, pointed to by dst, to the value specified in c.

Despite c being an int instead of a char, this only operates on bytes; c must be a value between 0 and 255, inclusive.

Parameters

dst	the destination memory region. Must not be nullptr.
c	the byte value to set.
len	the length, in bytes, to set in `dst`.

Returns: dst.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ memset4()

void * SDL::memset4	(	void *	dst,
		Uint32	val,
		size_t	dwords
	)

inline

This function will set a buffer of dwords Uint32 values, pointed to by dst, to the value specified in val.

Unlike memset, this sets 32-bit values, not bytes, so it's not limited to a range of 0-255.

Parameters

dst	the destination memory region. Must not be nullptr.
val	the Uint32 value to set.
dwords	the number of Uint32 values to set in `dst`.

Returns: dst.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ min()

template<class T , class U >

constexpr T SDL::min	(	T	x,
		U	y
	)

constexpr

This is a helper macro that might be more clear than writing out the comparisons directly, and works with any type that can be compared with the < operator. However, it double-evaluates both its parameters, so do not use expressions with side-effects here.

Parameters

x	the first value to compare.
y	the second value to compare.

Returns: the lesser of x and y.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ modf() [1/2]

double SDL::modf	(	double	x,
		double *	y
	)

inline

Parameters

x	floating point value.
y	output pointer to store the integer part of `x`.

Returns: the fractional part of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: trunc; fmod

◆ modf() [2/2]

float SDL::modf	(	float	x,
		float *	y
	)

inline

Parameters

x	floating point value.
y	output pointer to store the integer part of `x`.

Returns: the fractional part of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: trunc; fmod

◆ murmur3_32()

Uint32 SDL::murmur3_32	(	const void *	data,
		size_t	len,
		Uint32	seed
	)

inline

https://en.wikipedia.org/wiki/MurmurHash

A seed may be specified, which changes the final results consistently, but this does not work like crc16 and crc32: you can't feed a previous result from this function back into itself as the next seed value to calculate a hash in chunks; it won't produce the same hash as it would if the same data was provided in a single call.

If you aren't sure what to provide for a seed, zero is fine. Murmur3 is not cryptographically secure, so it shouldn't be used for hashing top-secret data.

Parameters

data	the data to be hashed.
len	the size of data, in bytes.
seed	a value that alters the final hash value.

Returns: a Murmur3 32-bit hash value.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ pow() [1/2]

double SDL::pow	(	double	x,
		double	y
	)

inline

Domain: -INF <= x <= INF, -INF <= y <= INF

Range: -INF <= z <= INF

If y is the base of the natural logarithm (e), consider using exp instead.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	the base.
y	the exponent.

Returns: x raised to the power y.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: exp; log

◆ pow() [2/2]

float SDL::pow	(	float	x,
		float	y
	)

inline

Domain: -INF <= x <= INF, -INF <= y <= INF

Range: -INF <= z <= INF

If y is the base of the natural logarithm (e), consider using exp instead.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	the base.
y	the exponent.

Returns: x raised to the power y.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: exp; log

◆ qsort()

void SDL::qsort	(	void *	base,
		size_t	nmemb,
		size_t	size,
		CompareCallback	compare
	)

inline

For example:

typedef struct {
    int key;
    const char *string;
} data;
 
int SDLCALL compare(const void *a, const void *b)
{
    const data *A = (const data *)a;
    const data *B = (const data *)b;
 
    if (A->n < B->n) {
        return -1;
    } else if (B->n < A->n) {
        return 1;
    } else {
        return 0;
    }
}
 
data values[] = {
    { 3, "third" }, { 1, "first" }, { 2, "second" }
};
 
qsort(values, arraysize(values), sizeof(values[0]), compare);

Parameters

base	a pointer to the start of the array.
nmemb	the number of elements in the array.
size	the size of the elements in the array.
compare	a function used to compare elements in the array.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: bsearch; qsort_r

◆ qsort_r() [1/2]

void SDL::qsort_r	(	void *	base,
		size_t	nmemb,
		size_t	size,
		CompareCallback_r	compare,
		void *	userdata
	)

inline

For example:

typedef enum {
    sort_increasing,
    sort_decreasing,
} sort_method;
 
typedef struct {
    int key;
    const char *string;
} data;
 
int SDLCALL compare(const void *userdata, const void *a, const void *b)
{
    sort_method method = (sort_method)(uintptr_t)userdata;
    const data *A = (const data *)a;
    const data *B = (const data *)b;
 
    if (A->key < B->key) {
        return (method == sort_increasing) ? -1 : 1;
    } else if (B->key < A->key) {
        return (method == sort_increasing) ? 1 : -1;
    } else {
        return 0;
    }
}
 
data values[] = {
    { 3, "third" }, { 1, "first" }, { 2, "second" }
};
 
qsort_r(values, arraysize(values), sizeof(values[0]), compare, (const void
*)(uintptr_t)sort_increasing);

Parameters

base	a pointer to the start of the array.
nmemb	the number of elements in the array.
size	the size of the elements in the array.
compare	a function used to compare elements in the array.
userdata	a pointer to pass to the compare function.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: bsearch_r; qsort

◆ qsort_r() [2/2]

void SDL::qsort_r	(	void *	base,
		size_t	nmemb,
		size_t	size,
		CompareCB	compare
	)

inline

For example:

typedef enum {
    sort_increasing,
    sort_decreasing,
} sort_method;
 
typedef struct {
    int key;
    const char *string;
} data;
 
int SDLCALL compare(const void *userdata, const void *a, const void *b)
{
    sort_method method = (sort_method)(uintptr_t)userdata;
    const data *A = (const data *)a;
    const data *B = (const data *)b;
 
    if (A->key < B->key) {
        return (method == sort_increasing) ? -1 : 1;
    } else if (B->key < A->key) {
        return (method == sort_increasing) ? 1 : -1;
    } else {
        return 0;
    }
}
 
data values[] = {
    { 3, "third" }, { 1, "first" }, { 2, "second" }
};
 
qsort_r(values, arraysize(values), sizeof(values[0]), compare, (const void
*)(uintptr_t)sort_increasing);

Parameters

base	a pointer to the start of the array.
nmemb	the number of elements in the array.
size	the size of the elements in the array.
compare	a function used to compare elements in the array.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: bsearch_r; qsort

◆ rand()

Sint32 SDL::rand ( Sint32 n )

inline

The method used is faster and of better quality than rand() % n. Odds are roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and much worse as n gets bigger.

Example: to simulate a d6 use rand(6) + 1 The +1 converts 0..5 to 1..6

If you want to generate a pseudo-random number in the full range of Sint32, you should use: (Sint32)rand_bits()

If you want reproducible output, be sure to initialize with srand() first.

There are no guarantees as to the quality of the random sequence produced, and this should not be used for security (cryptography, passwords) or where money is on the line (loot-boxes, casinos). There are many random number libraries available with different characteristics and you should pick one of those to meet any serious needs.

Parameters

n	the number of possible outcomes. n must be positive.

Returns: a random value in the range of [0 .. n-1].

Thread safety:: All calls should be made from a single thread

Since: This function is available since SDL 3.2.0.

See also: srand; randf

◆ rand_bits()

Uint32 SDL::rand_bits ( )

inline

You likely want to use rand() to get a pseudo-random number instead.

There are no guarantees as to the quality of the random sequence produced, and this should not be used for security (cryptography, passwords) or where money is on the line (loot-boxes, casinos). There are many random number libraries available with different characteristics and you should pick one of those to meet any serious needs.

Returns: a random value in the range of [0-MAX_UINT32].

Thread safety:: All calls should be made from a single thread

Since: This function is available since SDL 3.2.0.

See also: rand; randf; srand

◆ randf()

float SDL::randf ( )

inline

If you want reproducible output, be sure to initialize with srand() first.

There are no guarantees as to the quality of the random sequence produced, and this should not be used for security (cryptography, passwords) or where money is on the line (loot-boxes, casinos). There are many random number libraries available with different characteristics and you should pick one of those to meet any serious needs.

Returns: a random value in the range of [0.0, 1.0).

Thread safety:: All calls should be made from a single thread

Since: This function is available since SDL 3.2.0.

See also: srand; rand

◆ realloc()

void * SDL::realloc	(	void *	mem,
		size_t	size
	)

inline

The memory returned by this function must be freed with free().

If size is 0, it will be set to 1. Note that this is unlike some other C runtime realloc implementations, which may treat realloc(mem, 0) the same way as free(mem).

If mem is nullptr, the behavior of this function is equivalent to malloc(). Otherwise, the function can have one of three possible outcomes:

If it returns the same pointer as mem, it means that mem was resized in place without freeing.
If it returns a different non-nullptr pointer, it means that mem was freed and cannot be dereferenced anymore.
If it returns nullptr (indicating failure), then mem will remain valid and must still be freed with free().

If the allocation is successfully resized, the returned pointer is guaranteed to be aligned to either the fundamental alignment (alignof(max_align_t) in C11 and later) or 2 * sizeof(void *), whichever is smaller.

Parameters

mem	a pointer to allocated memory to reallocate, or nullptr.
size	the new size of the memory.

Returns: a pointer to the newly allocated memory, or nullptr if allocation failed.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: free; malloc; calloc

◆ round() [1/2]

double SDL::round ( double x )

inline

Rounds x to the nearest integer. Values halfway between integers will be rounded away from zero.

Domain: -INF <= x <= INF

Range: -INF <= y <= INF, y integer

Parameters

x	floating point value.

Returns: the nearest integer to x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: lround; floor; ceil; trunc

◆ round() [2/2]

float SDL::round ( float x )

inline

Rounds x to the nearest integer. Values halfway between integers will be rounded away from zero.

Domain: -INF <= x <= INF

Range: -INF <= y <= INF, y integer

Parameters

x	floating point value.

Returns: the nearest integer to x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: lround; floor; ceil; trunc

◆ scalbn() [1/2]

double SDL::scalbn	(	double	x,
		int	n
	)

inline

Multiplies x by the nth power of the floating point radix (always 2).

Domain: -INF <= x <= INF, n integer

Range: -INF <= y <= INF

Parameters

x	floating point value to be scaled.
n	integer exponent.

Returns: x * 2^n.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: pow

◆ scalbn() [2/2]

float SDL::scalbn	(	float	x,
		int	n
	)

inline

Multiplies x by the nth power of the floating point radix (always 2).

Domain: -INF <= x <= INF, n integer

Range: -INF <= y <= INF

Parameters

x	floating point value to be scaled.
n	integer exponent.

Returns: x * 2^n.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: pow

◆ setenv_unsafe()

int SDL::setenv_unsafe	(	StringParam	name,
		StringParam	value,
		int	overwrite
	)

inline

Parameters

name	the name of the variable to set.
value	the value of the variable to set.
overwrite	1 to overwrite the variable if it exists, 0 to return success without setting the variable if it already exists.

Returns: 0 on success, -1 on error.

Thread safety:: This function is not thread safe, consider using EnvironmentBase.SetVariable() instead.

Since: This function is available since SDL 3.2.0.

See also: EnvironmentBase.SetVariable

◆ SetMemoryFunctions()

void SDL::SetMemoryFunctions	(	malloc_func	malloc_func,
		calloc_func	calloc_func,
		realloc_func	realloc_func,
		free_func	free_func
	)

inline

It is not safe to call this function once any allocations have been made, as future calls to free will use the new allocator, even if they came from an malloc made with the old one!

If used, usually this needs to be the first call made into the SDL library, if not the very first thing done at program startup time.

Parameters

malloc_func	custom malloc function.
calloc_func	custom calloc function.
realloc_func	custom realloc function.
free_func	custom free function.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread, but one should not replace the memory functions once any allocations are made!

Since: This function is available since SDL 3.2.0.

See also: GetMemoryFunctions; GetOriginalMemoryFunctions

◆ sin() [1/2]

double SDL::sin ( double x )

inline

Domain: -INF <= x <= INF

Range: -1 <= y <= 1

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value, in radians.

Returns: sine of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: asin; cos

◆ sin() [2/2]

float SDL::sin ( float x )

inline

Domain: -INF <= x <= INF

Range: -1 <= y <= 1

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value, in radians.

Returns: sine of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: asin; cos

◆ size_add_check_overflow()

bool SDL::size_add_check_overflow	(	size_t	a,
		size_t	b,
		size_t *	ret
	)

inline

If a + b would overflow, return false.

Otherwise store a + b via ret and return true.

Parameters

a	the first addend.
b	the second addend.
ret	on non-overflow output, stores the addition result, may not be nullptr.

Returns: false on overflow, true if result is added without overflow.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ size_mul_check_overflow()

bool SDL::size_mul_check_overflow	(	size_t	a,
		size_t	b,
		size_t *	ret
	)

inline

If a * b would overflow, return false.

Otherwise store a * b via ret and return true.

Parameters

a	the multiplicand.
b	the multiplier.
ret	on non-overflow output, stores the multiplication result, may not be nullptr.

Returns: false on overflow, true if result is multiplied without overflow.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ snprintf()

int SDL::snprintf	(	char *	text,
		size_t	maxlen,
		SDL_PRINTF_FORMAT_STRING const char *	fmt,
			...
	)

inline

Format a string of up to maxlen-1 bytes, converting each '' item with values provided through variable arguments.

While some C runtimes differ on how to deal with too-large strings, this function null-terminates the output, by treating the null-terminator as part of the maxlen count. Note that if maxlen is zero, however, no bytes will be written at all.

This function returns the number of bytes (not characters) that should be written, excluding the null-terminator character. If this returns a number >= maxlen, it means the output string was truncated. A negative return value means an error occurred.

Referencing the output string's pointer with a format item is undefined behavior.

Parameters

text	the buffer to write the string into. Must not be nullptr.
maxlen	the maximum bytes to write, including the null-terminator.
fmt	a printf-style format string. Must not be nullptr.
...	a list of values to be used with the format string.

Returns: the number of bytes that should be written, not counting the null-terminator char, or a negative value on error.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ sqrt() [1/2]

double SDL::sqrt ( double x )

inline

Domain: 0 <= x <= INF

Range: 0 <= y <= INF

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value. Must be greater than or equal to 0.

Returns: square root of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ sqrt() [2/2]

float SDL::sqrt ( float x )

inline

Domain: 0 <= x <= INF

Range: 0 <= y <= INF

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value. Must be greater than or equal to 0.

Returns: square root of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ srand()

void SDL::srand ( Uint64 seed )

inline

Reusing the seed number will cause rand() to repeat the same stream of 'random' numbers.

Parameters

seed	the value to use as a random number seed, or 0 to use GetPerformanceCounter().

Thread safety:: This should be called on the same thread that calls rand()

Since: This function is available since SDL 3.2.0.

See also: rand; rand_bits; randf

◆ sscanf()

int SDL::sscanf	(	StringParam	text,
		SDL_SCANF_FORMAT_STRING const char *	fmt,
			...
	)

inline

Scan a string, matching a format string, converting each '' item and storing it to pointers provided through variable arguments.

Parameters

text	the string to scan. Must not be nullptr.
fmt	a printf-style format string. Must not be nullptr.
...	a list of pointers to values to be filled in with scanned items.

Returns: the number of items that matched the format string.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ StepBackUTF8()

Uint32 SDL::StepBackUTF8	(	StringParam	start,
		const char **	pstr
	)

inline

This will go to the start of the previous Unicode codepoint in the string, move *pstr to that location and return that codepoint.

If *pstr is already at the start of the string), it will not advance *pstr at all.

Generally this function is called in a loop until it returns zero, adjusting its parameter each iteration.

If an invalid UTF-8 sequence is encountered, this function returns INVALID_UNICODE_CODEPOINT.

Several things can generate invalid UTF-8 sequences, including overlong encodings, the use of UTF-16 surrogate values, and truncated data. Please refer to RFC3629 for details.

Parameters

start	a pointer to the beginning of the UTF-8 string.
pstr	a pointer to a UTF-8 string pointer to be read and adjusted.

Returns: the previous Unicode codepoint in the string.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ StepUTF8()

Uint32 SDL::StepUTF8	(	const char **	pstr,
		size_t *	pslen
	)

inline

This will return the first Unicode codepoint in the UTF-8 encoded string in *pstr, and then advance *pstr past any consumed bytes before returning.

It will not access more than *pslen bytes from the string. *pslen will be adjusted, as well, subtracting the number of bytes consumed.

pslen is allowed to be nullptr, in which case the string must be nullptr-terminated, as the function will blindly read until it sees the nullptr char.

if *pslen is zero, it assumes the end of string is reached and returns a zero codepoint regardless of the contents of the string buffer.

If the resulting codepoint is zero (a nullptr terminator), or *pslen is zero, it will not advance *pstr or *pslen at all.

Generally this function is called in a loop until it returns zero, adjusting its parameters each iteration.

If an invalid UTF-8 sequence is encountered, this function returns INVALID_UNICODE_CODEPOINT and advances the string/length by one byte (which is to say, a multibyte sequence might produce several INVALID_UNICODE_CODEPOINT returns before it syncs to the next valid UTF-8 sequence).

Several things can generate invalid UTF-8 sequences, including overlong encodings, the use of UTF-16 surrogate values, and truncated data. Please refer to RFC3629 for details.

Parameters

pstr	a pointer to a UTF-8 string pointer to be read and adjusted.
pslen	a pointer to the number of bytes in the string, to be read and adjusted. nullptr is allowed.

Returns: the first Unicode codepoint in the string.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strcasecmp()

int SDL::strcasecmp	(	StringParam	str1,
		StringParam	str2
	)

inline

This will work with Unicode strings, using a technique called "case-folding" to handle the vast majority of case-sensitive human languages regardless of system locale. It can deal with expanding values: a German Eszett character can compare against two ASCII 's' chars and be considered a match, for example. A notable exception: it does not handle the Turkish 'i' character; human language is complicated!

Since this handles Unicode, it expects the string to be well-formed UTF-8 and not a null-terminated string of arbitrary bytes. Bytes that are not valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT CHARACTER), which is to say two strings of random bits may turn out to match if they convert to the same amount of replacement characters.

Parameters

str1	the first string to compare. nullptr is not permitted!
str2	the second string to compare. nullptr is not permitted!

Returns: less than zero if str1 is "less than" str2, greater than zero if str1 is "greater than" str2, and zero if the strings match exactly.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strcasestr()

char * SDL::strcasestr	(	StringParam	haystack,
		StringParam	needle
	)

inline

This will work with Unicode strings, using a technique called "case-folding" to handle the vast majority of case-sensitive human languages regardless of system locale. It can deal with expanding values: a German Eszett character can compare against two ASCII 's' chars and be considered a match, for example. A notable exception: it does not handle the Turkish 'i' character; human language is complicated!

Since this handles Unicode, it expects the strings to be well-formed UTF-8 and not a null-terminated string of arbitrary bytes. Bytes that are not valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT CHARACTER), which is to say two strings of random bits may turn out to match if they convert to the same amount of replacement characters.

Parameters

haystack	the string to search. Must not be nullptr.
needle	the string to search for. Must not be nullptr.

Returns: a pointer to the first instance of needle in the string, or nullptr if not found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strchr()

char * SDL::strchr	(	StringParam	str,
		int	c
	)

inline

The search ends once it finds the requested byte value, or a null terminator byte to end the string.

Note that this looks for bytes, not characters, so you cannot match against a Unicode codepoint > 255, regardless of character encoding.

Parameters

str	the string to search. Must not be nullptr.
c	the byte value to search for.

Returns: a pointer to the first instance of c in the string, or nullptr if not found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strcmp()

int SDL::strcmp	(	StringParam	str1,
		StringParam	str2
	)

inline

Due to the nature of UTF-8 encoding, this will work with Unicode strings, since effectively this function just compares bytes until it hits a null-terminating character. Also due to the nature of UTF-8, this can be used with qsort() to put strings in (roughly) alphabetical order.

Parameters

str1	the first string to compare. nullptr is not permitted!
str2	the second string to compare. nullptr is not permitted!

Returns: less than zero if str1 is "less than" str2, greater than zero if str1 is "greater than" str2, and zero if the strings match exactly.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strdup()

char * SDL::strdup ( StringParam str )

inline

This allocates enough space for a null-terminated copy of str, using malloc, and then makes a copy of the string into this space.

The returned string is owned by the caller, and should be passed to free when no longer needed.

Parameters

str	the string to copy.

Returns: a pointer to the newly-allocated string.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strlcat()

size_t SDL::strlcat	(	char *	dst,
		StringParam	src,
		size_t	maxlen
	)

inline

This function appends up to maxlen - strlen(dst) - 1 characters from src to the end of the string in dst, then appends a null terminator.

src and dst must not overlap.

If maxlen - strlen(dst) - 1 is less than or equal to 0, then dst is unmodified.

Parameters

dst	The destination buffer already containing the first null-terminated string. Must not be nullptr and must not overlap with `src`.
src	The second null-terminated string. Must not be nullptr, and must not overlap with `dst`.
maxlen	The length (in characters) of the destination buffer.

Returns: the length (in characters, excluding the null terminator) of the string in dst plus the length of src.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: strlcpy

◆ strlcpy()

size_t SDL::strlcpy	(	char *	dst,
		StringParam	src,
		size_t	maxlen
	)

inline

This function copies up to maxlen - 1 characters from src to dst, then appends a null terminator.

If maxlen is 0, no characters are copied and no null terminator is written.

If you want to copy an UTF-8 string but need to ensure that multi-byte sequences are not truncated, consider using utf8strlcpy().

Parameters

dst	The destination buffer. Must not be nullptr, and must not overlap with `src`.
src	The null-terminated string to copy. Must not be nullptr, and must not overlap with `dst`.
maxlen	The length (in characters) of the destination buffer.

Returns: the length (in characters, excluding the null terminator) of src.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: strlcat; utf8strlcpy

◆ strlen()

size_t SDL::strlen ( StringParam str )

inline

Counts the bytes in str, excluding the null terminator.

If you need the length of a UTF-8 string, consider using utf8strlen().

Parameters

str	The null-terminated string to read. Must not be nullptr.

Returns: the length (in bytes, excluding the null terminator) of src.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: strnlen; utf8strlen; utf8strnlen

◆ strlwr()

char * SDL::strlwr ( char * str )

inline

WARNING: Regardless of system locale, this will only convert ASCII values 'A' through 'Z' to lowercase.

This function operates on a null-terminated string of bytes–even if it is malformed UTF-8!–and converts ASCII characters 'A' through 'Z' to their lowercase equivalents in-place, returning the original str pointer.

Parameters

str	the string to convert in-place. Can not be nullptr.

Returns: the str pointer passed into this function.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: strupr

◆ strncasecmp()

int SDL::strncasecmp	(	StringParam	str1,
		StringParam	str2,
		size_t	maxlen
	)

inline

This will work with Unicode strings, using a technique called "case-folding" to handle the vast majority of case-sensitive human languages regardless of system locale. It can deal with expanding values: a German Eszett character can compare against two ASCII 's' chars and be considered a match, for example. A notable exception: it does not handle the Turkish 'i' character; human language is complicated!

Since this handles Unicode, it expects the string to be well-formed UTF-8 and not a null-terminated string of arbitrary bytes. Bytes that are not valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT CHARACTER), which is to say two strings of random bits may turn out to match if they convert to the same amount of replacement characters.

Note that while this function is intended to be used with UTF-8, maxlen specifies a byte limit! If the limit lands in the middle of a multi-byte UTF-8 sequence, it may convert a portion of the final character to one or more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not to overflow a buffer.

maxlen specifies a maximum number of bytes to compare; if the strings match to this number of bytes (or both have matched to a null-terminator character before this number of bytes), they will be considered equal.

Parameters

str1	the first string to compare. nullptr is not permitted!
str2	the second string to compare. nullptr is not permitted!
maxlen	the maximum number of bytes to compare.

Returns: less than zero if str1 is "less than" str2, greater than zero if str1 is "greater than" str2, and zero if the strings match exactly.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strncmp()

int SDL::strncmp	(	StringParam	str1,
		StringParam	str2,
		size_t	maxlen
	)

inline

Due to the nature of UTF-8 encoding, this will work with Unicode strings, since effectively this function just compares bytes until it hits a null-terminating character. Also due to the nature of UTF-8, this can be used with qsort() to put strings in (roughly) alphabetical order.

Note that while this function is intended to be used with UTF-8, it is doing a bytewise comparison, and maxlen specifies a byte limit! If the limit lands in the middle of a multi-byte UTF-8 sequence, it will only compare a portion of the final character.

maxlen specifies a maximum number of bytes to compare; if the strings match to this number of bytes (or both have matched to a null-terminator character before this number of bytes), they will be considered equal.

Parameters

str1	the first string to compare. nullptr is not permitted!
str2	the second string to compare. nullptr is not permitted!
maxlen	the maximum number of bytes to compare.

Returns: less than zero if str1 is "less than" str2, greater than zero if str1 is "greater than" str2, and zero if the strings match exactly.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strndup()

char * SDL::strndup	(	StringParam	str,
		size_t	maxlen
	)

inline

This allocates enough space for a null-terminated copy of str, up to maxlen bytes, using malloc, and then makes a copy of the string into this space.

If the string is longer than maxlen bytes, the returned string will be maxlen bytes long, plus a null-terminator character that isn't included in the count.

The returned string is owned by the caller, and should be passed to free when no longer needed.

Parameters

str	the string to copy.
maxlen	the maximum length of the copied string, not counting the null-terminator character.

Returns: a pointer to the newly-allocated string.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strnlen()

size_t SDL::strnlen	(	StringParam	str,
		size_t	maxlen
	)

inline

Counts up to a maximum of maxlen bytes in str, excluding the null terminator.

If you need the length of a UTF-8 string, consider using utf8strnlen().

Parameters

str	The null-terminated string to read. Must not be nullptr.
maxlen	The maximum amount of bytes to count.

Returns: the length (in bytes, excluding the null terminator) of src but never more than maxlen.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: strlen; utf8strlen; utf8strnlen

◆ strnstr()

char * SDL::strnstr	(	StringParam	haystack,
		StringParam	needle,
		size_t	maxlen
	)

inline

The search ends once it finds the requested substring, or a null terminator byte to end the string, or maxlen bytes have been examined. It is possible to use this function on a string without a null terminator.

Note that this looks for strings of bytes, not characters, so it's legal to search for malformed and incomplete UTF-8 sequences.

Parameters

haystack	the string to search. Must not be nullptr.
needle	the string to search for. Must not be nullptr.
maxlen	the maximum number of bytes to search in `haystack`.

Returns: a pointer to the first instance of needle in the string, or nullptr if not found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strpbrk()

char * SDL::strpbrk	(	StringParam	str,
		StringParam	breakset
	)

inline

Parameters

str	The null-terminated string to be searched. Must not be nullptr, and must not overlap with `breakset`.
breakset	A null-terminated string containing the list of characters to look for. Must not be nullptr, and must not overlap with `str`.

Returns: A pointer to the location, in str, of the first occurence of a character present in the breakset, or nullptr if none is found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strrchr()

char * SDL::strrchr	(	StringParam	str,
		int	c
	)

inline

The search must go until it finds a null terminator byte to end the string.

Note that this looks for bytes, not characters, so you cannot match against a Unicode codepoint > 255, regardless of character encoding.

Parameters

str	the string to search. Must not be nullptr.
c	the byte value to search for.

Returns: a pointer to the last instance of c in the string, or nullptr if not found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strrev()

char * SDL::strrev ( char * str )

inline

This reverses a null-terminated string in-place. Only the content of the string is reversed; the null-terminator character remains at the end of the reversed string.

WARNING: This function reverses the bytes of the string, not the codepoints. If str is a UTF-8 string with Unicode codepoints > 127, this will ruin the string data. You should only use this function on strings that are completely comprised of low ASCII characters.

Parameters

str	the string to reverse.

Returns: str.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strstr()

char * SDL::strstr	(	StringParam	haystack,
		StringParam	needle
	)

inline

The search ends once it finds the requested substring, or a null terminator byte to end the string.

Note that this looks for strings of bytes, not characters, so it's legal to search for malformed and incomplete UTF-8 sequences.

Parameters

haystack	the string to search. Must not be nullptr.
needle	the string to search for. Must not be nullptr.

Returns: a pointer to the first instance of needle in the string, or nullptr if not found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strtod()

double SDL::strtod	(	StringParam	str,
		char **	endp
	)

inline

This function makes fewer guarantees than the C runtime strtod:

Only decimal notation is guaranteed to be supported. The handling of scientific and hexadecimal notation is unspecified.
Whether or not INF and NAN can be parsed is unspecified.
The precision of the result is unspecified.

Parameters

str	the null-terminated string to read. Must not be nullptr.
endp	if not nullptr, the address of the first invalid character (i.e. the next character after the parsed number) will be written to this pointer.

Returns: the parsed double, or 0 if no number could be parsed.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: atoi; atof; strtol; SDL_strtoll; strtoul; SDL_strtoull

◆ strtok_r()

char * SDL::strtok_r	(	char *	str,
		StringParam	delim,
		char **	saveptr
	)

inline

Break a string up into a series of tokens.

To start tokenizing a new string, str should be the non-nullptr address of the string to start tokenizing. Future calls to get the next token from the same string should specify a nullptr.

Note that this function will overwrite pieces of str with null chars to split it into tokens. This function cannot be used with const/read-only strings!

saveptr just needs to point to a char * that can be overwritten; SDL will use this to save tokenizing state between calls. It is initialized if str is non-nullptr, and used to resume tokenizing when str is nullptr.

Parameters

str	the string to tokenize, or nullptr to continue tokenizing.
delim	the delimiter string that separates tokens.
saveptr	pointer to a char *, used for ongoing state.

Returns: A pointer to the next token, or nullptr if no tokens remain.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ strtol()

long SDL::strtol	(	StringParam	str,
		char **	endp,
		int	base
	)

inline

If str starts with whitespace, then those whitespace characters are skipped before attempting to parse the number.

If the parsed number does not fit inside a long, the result is clamped to the minimum and maximum representable long values.

Parameters

str	The null-terminated string to read. Must not be nullptr.
endp	If not nullptr, the address of the first invalid character (i.e. the next character after the parsed number) will be written to this pointer.
base	The base of the integer to read. Supported values are 0 and 2 to 36 inclusive. If 0, the base will be inferred from the number's prefix (0x for hexadecimal, 0 for octal, decimal otherwise).

Returns: the parsed long, or 0 if no number could be parsed.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: atoi; atof; strtoul; SDL_strtoll; SDL_strtoull; strtod; ltoa; wcstol

◆ strtoul()

unsigned long SDL::strtoul	(	StringParam	str,
		char **	endp,
		int	base
	)

inline

If str starts with whitespace, then those whitespace characters are skipped before attempting to parse the number.

If the parsed number does not fit inside an unsigned long, the result is clamped to the maximum representable unsigned long value.

Parameters

str	The null-terminated string to read. Must not be nullptr.
endp	If not nullptr, the address of the first invalid character (i.e. the next character after the parsed number) will be written to this pointer.
base	The base of the integer to read. Supported values are 0 and 2 to 36 inclusive. If 0, the base will be inferred from the number's prefix (0x for hexadecimal, 0 for octal, decimal otherwise).

Returns: the parsed unsigned long, or 0 if no number could be parsed.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: atoi; atof; strtol; SDL_strtoll; SDL_strtoull; strtod; ultoa

◆ strupr()

char * SDL::strupr ( char * str )

inline

WARNING: Regardless of system locale, this will only convert ASCII values 'A' through 'Z' to uppercase.

This function operates on a null-terminated string of bytes–even if it is malformed UTF-8!–and converts ASCII characters 'a' through 'z' to their uppercase equivalents in-place, returning the original str pointer.

Parameters

str	the string to convert in-place. Can not be nullptr.

Returns: the str pointer passed into this function.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: strlwr

◆ swprintf()

int SDL::swprintf	(	wchar_t *	text,
		size_t	maxlen,
		SDL_PRINTF_FORMAT_STRING const wchar_t *	fmt,
			...
	)

inline

Format a wide string of up to maxlen-1 wchar_t values, converting each '' item with values provided through variable arguments.

While some C runtimes differ on how to deal with too-large strings, this function null-terminates the output, by treating the null-terminator as part of the maxlen count. Note that if maxlen is zero, however, no wide characters will be written at all.

This function returns the number of wide characters (not codepoints) that should be written, excluding the null-terminator character. If this returns a number >= maxlen, it means the output string was truncated. A negative return value means an error occurred.

Referencing the output string's pointer with a format item is undefined behavior.

Parameters

text	the buffer to write the wide string into. Must not be nullptr.
maxlen	the maximum wchar_t values to write, including the null-terminator.
fmt	a printf-style format string. Must not be nullptr.
...	a list of values to be used with the format string.

Returns: the number of wide characters that should be written, not counting the null-terminator char, or a negative value on error.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ tan() [1/2]

double SDL::tan ( double x )

inline

Domain: -INF <= x <= INF

Range: -INF <= y <= INF

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value, in radians.

Returns: tangent of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: sin; cos; atan; atan2

◆ tan() [2/2]

float SDL::tan ( float x )

inline

Domain: -INF <= x <= INF

Range: -INF <= y <= INF

This function operates on single-precision floating point values, use tan for double-precision floats.

This function may use a different approximation across different versions, platforms and configurations. i.e, it can return a different value given the same input on different machines or operating systems, or if SDL is updated.

Parameters

x	floating point value, in radians.

Returns: tangent of x.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: sin; cos; atan; atan2

◆ tolower()

int SDL::tolower ( int x )

inline

WARNING: Regardless of system locale, this will only convert ASCII values 'A' through 'Z' to lowercase.

This function returns the lowercase equivalent of x. If a character cannot be converted, or is already lowercase, this function returns x.

Parameters

x	character value to check.

Returns: lowercase version of x, or x if no conversion available.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ toupper()

int SDL::toupper ( int x )

inline

WARNING: Regardless of system locale, this will only convert ASCII values 'a' through 'z' to uppercase.

This function returns the uppercase equivalent of x. If a character cannot be converted, or is already uppercase, this function returns x.

Parameters

x	character value to check.

Returns: capitalized version of x, or x if no conversion available.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ trunc() [1/2]

double SDL::trunc ( double x )

inline

Rounds x to the next closest integer to 0. This is equivalent to removing the fractional part of x, leaving only the integer part.

Domain: -INF <= x <= INF

Range: -INF <= y <= INF, y integer

Parameters

x	floating point value.

Returns: x truncated to an integer.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: fmod; ceil; floor; round; lround

◆ trunc() [2/2]

float SDL::trunc ( float x )

inline

Rounds x to the next closest integer to 0. This is equivalent to removing the fractional part of x, leaving only the integer part.

Domain: -INF <= x <= INF

Range: -INF <= y <= INF, y integer

Parameters

x	floating point value.

Returns: x truncated to an integer.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: fmod; ceil; floor; round; lround

◆ UCS4ToUTF8()

char * SDL::UCS4ToUTF8	(	Uint32	codepoint,
		char *	dst
	)

inline

The buffer pointed to by dst must be at least 4 bytes long, as this function may generate between 1 and 4 bytes of output.

This function returns the first byte after the newly-written UTF-8 sequence, which is useful for encoding multiple codepoints in a loop, or knowing where to write a nullptr-terminator character to end the string (in either case, plan to have a buffer of more than 4 bytes!).

If codepoint is an invalid value (outside the Unicode range, or a UTF-16 surrogate value, etc), this will use U+FFFD (REPLACEMENT CHARACTER) for the codepoint instead, and not set an error.

If dst is nullptr, this returns nullptr immediately without writing to the pointer and without setting an error.

Parameters

codepoint	a Unicode codepoint to convert to UTF-8.
dst	the location to write the encoded UTF-8. Must point to at least 4 bytes!

Returns: the first byte past the newly-written UTF-8 sequence.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ uitoa()

char * SDL::uitoa	(	unsigned int	value,
		char *	str,
		int	radix
	)

inline

This requires a radix to specified for string format. Specifying 10 produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 to 36.

Note that this function will overflow a buffer if str is not large enough to hold the output! It may be safer to use snprintf to clamp output, or asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate much more space than you expect to use (and don't forget null terminator bytes, etc).

Parameters

value	the unsigned integer to convert.
str	the buffer to write the string into.
radix	the radix to use for string generation.

Returns: str.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: itoa; ultoa; SDL_ulltoa

◆ ultoa()

char * SDL::ultoa	(	unsigned long	value,
		char *	str,
		int	radix
	)

inline

This requires a radix to specified for string format. Specifying 10 produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 to 36.

Note that this function will overflow a buffer if str is not large enough to hold the output! It may be safer to use snprintf to clamp output, or asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate much more space than you expect to use (and don't forget null terminator bytes, etc).

Parameters

value	the unsigned long integer to convert.
str	the buffer to write the string into.
radix	the radix to use for string generation.

Returns: str.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: ltoa; uitoa; SDL_ulltoa

◆ unsetenv_unsafe()

int SDL::unsetenv_unsafe ( StringParam name )

inline

Parameters

name	the name of the variable to unset.

Returns: 0 on success, -1 on error.

Thread safety:: This function is not thread safe, consider using EnvironmentBase.UnsetVariable() instead.

Since: This function is available since SDL 3.2.0.

See also: EnvironmentBase.UnsetVariable

◆ utf8strlcpy()

size_t SDL::utf8strlcpy	(	char *	dst,
		StringParam	src,
		size_t	dst_bytes
	)

inline

This function copies up to dst_bytes - 1 bytes from src to dst while also ensuring that the string written to dst does not end in a truncated multi-byte sequence. Finally, it appends a null terminator.

src and dst must not overlap.

Note that unlike strlcpy(), this function returns the number of bytes written, not the length of src.

Parameters

dst	The destination buffer. Must not be nullptr, and must not overlap with `src`.
src	The null-terminated UTF-8 string to copy. Must not be nullptr, and must not overlap with `dst`.
dst_bytes	The length (in bytes) of the destination buffer. Must not be 0.

Returns: the number of bytes written, excluding the null terminator.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: strlcpy

◆ utf8strlen()

size_t SDL::utf8strlen ( StringParam str )

inline

Counts the codepoints, not bytes, in str, excluding the null terminator.

If you need to count the bytes in a string instead, consider using strlen().

Since this handles Unicode, it expects the strings to be well-formed UTF-8 and not a null-terminated string of arbitrary bytes. Bytes that are not valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the count by several replacement characters.

Parameters

str	The null-terminated UTF-8 string to read. Must not be nullptr.

Returns: The length (in codepoints, excluding the null terminator) of src.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: utf8strnlen; strlen

◆ utf8strnlen()

size_t SDL::utf8strnlen	(	StringParam	str,
		size_t	bytes
	)

inline

Counts the codepoints, not bytes, in str, excluding the null terminator.

If you need to count the bytes in a string instead, consider using strnlen().

The counting stops at bytes bytes (not codepoints!). This seems counterintuitive, but makes it easy to express the total size of the string's buffer.

Since this handles Unicode, it expects the strings to be well-formed UTF-8 and not a null-terminated string of arbitrary bytes. Bytes that are not valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the count by several replacement characters.

Parameters

str	The null-terminated UTF-8 string to read. Must not be nullptr.
bytes	The maximum amount of bytes to count.

Returns: The length (in codepoints, excluding the null terminator) of src but never more than maxlen.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: utf8strlen; strnlen

◆ vasprintf()

int SDL::vasprintf	(	char **	strp,
		SDL_PRINTF_FORMAT_STRING const char *	fmt,
		va_list	ap
	)

inline

Functions identically to asprintf(), except it takes a va_list instead of using ... variable arguments.

Parameters

strp	on output, is set to the new string. Must not be nullptr.
fmt	a printf-style format string. Must not be nullptr.
ap	a `va_list` values to be used with the format string.

Returns: the number of bytes in the newly-allocated string, not counting the null-terminator char, or a negative value on error.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ vsnprintf()

int SDL::vsnprintf	(	char *	text,
		size_t	maxlen,
		SDL_PRINTF_FORMAT_STRING const char *	fmt,
		va_list	ap
	)

inline

Functions identically to snprintf(), except it takes a va_list instead of using ... variable arguments.

Parameters

text	the buffer to write the string into. Must not be nullptr.
maxlen	the maximum bytes to write, including the null-terminator.
fmt	a printf-style format string. Must not be nullptr.
ap	a `va_list` values to be used with the format string.

Returns: the number of bytes that should be written, not counting the null-terminator char, or a negative value on error.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ vsscanf()

int SDL::vsscanf	(	StringParam	text,
		SDL_SCANF_FORMAT_STRING const char *	fmt,
		va_list	ap
	)

inline

Functions identically to sscanf(), except it takes a va_list instead of using ... variable arguments.

Parameters

text	the string to scan. Must not be nullptr.
fmt	a printf-style format string. Must not be nullptr.
ap	a `va_list` of pointers to values to be filled in with scanned items.

Returns: the number of items that matched the format string.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ vswprintf()

int SDL::vswprintf	(	wchar_t *	text,
		size_t	maxlen,
		SDL_PRINTF_FORMAT_STRING const wchar_t *	fmt,
		va_list	ap
	)

inline

Functions identically to swprintf(), except it takes a va_list instead of using ... variable arguments.

Parameters

text	the buffer to write the string into. Must not be nullptr.
maxlen	the maximum wide characters to write, including the null-terminator.
fmt	a printf-style format wide string. Must not be nullptr.
ap	a `va_list` values to be used with the format string.

Returns: the number of wide characters that should be written, not counting the null-terminator char, or a negative value on error.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ wcscasecmp()

int SDL::wcscasecmp	(	const wchar_t *	str1,
		const wchar_t *	str2
	)

inline

This will work with Unicode strings, using a technique called "case-folding" to handle the vast majority of case-sensitive human languages regardless of system locale. It can deal with expanding values: a German Eszett character can compare against two ASCII 's' chars and be considered a match, for example. A notable exception: it does not handle the Turkish 'i' character; human language is complicated!

Depending on your platform, "wchar_t" might be 2 bytes, and expected to be UTF-16 encoded (like Windows), or 4 bytes in UTF-32 format. Since this handles Unicode, it expects the string to be well-formed and not a null-terminated string of arbitrary bytes. Characters that are not valid UTF-16 (or UTF-32) are treated as Unicode character U+FFFD (REPLACEMENT CHARACTER), which is to say two strings of random bits may turn out to match if they convert to the same amount of replacement characters.

Parameters

str1	the first string to compare. nullptr is not permitted!
str2	the second string to compare. nullptr is not permitted!

Returns: less than zero if str1 is "less than" str2, greater than zero if str1 is "greater than" str2, and zero if the strings match exactly.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ wcscmp()

int SDL::wcscmp	(	const wchar_t *	str1,
		const wchar_t *	str2
	)

inline

This only compares wchar_t values until it hits a null-terminating character; it does not care if the string is well-formed UTF-16 (or UTF-32, depending on your platform's wchar_t size), or uses valid Unicode values.

Parameters

str1	the first string to compare. nullptr is not permitted!
str2	the second string to compare. nullptr is not permitted!

Returns: less than zero if str1 is "less than" str2, greater than zero if str1 is "greater than" str2, and zero if the strings match exactly.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ wcsdup()

wchar_t * SDL::wcsdup ( const wchar_t * wstr )

inline

This allocates enough space for a null-terminated copy of wstr, using malloc, and then makes a copy of the string into this space.

The returned string is owned by the caller, and should be passed to free when no longer needed.

Parameters

wstr	the string to copy.

Returns: a pointer to the newly-allocated wide string.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ wcslcat()

size_t SDL::wcslcat	(	wchar_t *	dst,
		const wchar_t *	src,
		size_t	maxlen
	)

inline

This function appends up to maxlen - wcslen(dst) - 1 wide characters from src to the end of the wide string in dst, then appends a null terminator.

src and dst must not overlap.

If maxlen - wcslen(dst) - 1 is less than or equal to 0, then dst is unmodified.

Parameters

dst	The destination buffer already containing the first null-terminated wide string. Must not be nullptr and must not overlap with `src`.
src	The second null-terminated wide string. Must not be nullptr, and must not overlap with `dst`.
maxlen	The length (in wide characters) of the destination buffer.

Returns: the length (in wide characters, excluding the null terminator) of the string in dst plus the length of src.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: wcslcpy

◆ wcslcpy()

size_t SDL::wcslcpy	(	wchar_t *	dst,
		const wchar_t *	src,
		size_t	maxlen
	)

inline

This function copies maxlen - 1 wide characters from src to dst, then appends a null terminator.

src and dst must not overlap.

If maxlen is 0, no wide characters are copied and no null terminator is written.

Parameters

dst	The destination buffer. Must not be nullptr, and must not overlap with `src`.
src	The null-terminated wide string to copy. Must not be nullptr, and must not overlap with `dst`.
maxlen	The length (in wide characters) of the destination buffer.

Returns: the length (in wide characters, excluding the null terminator) of src.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: wcslcat

◆ wcslen()

size_t SDL::wcslen ( const wchar_t * wstr )

inline

Counts the number of wchar_t values in wstr, excluding the null terminator.

Like strlen only counts bytes and not codepoints in a UTF-8 string, this counts wchar_t values in a string, even if the string's encoding is of variable width, like UTF-16.

Also be aware that wchar_t is different sizes on different platforms (4 bytes on Linux, 2 on Windows, etc).

Parameters

wstr	The null-terminated wide string to read. Must not be nullptr.

Returns: the length (in wchar_t values, excluding the null terminator) of wstr.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: wcsnlen; utf8strlen; utf8strnlen

◆ wcsncasecmp()

int SDL::wcsncasecmp	(	const wchar_t *	str1,
		const wchar_t *	str2,
		size_t	maxlen
	)

inline

This will work with Unicode strings, using a technique called "case-folding" to handle the vast majority of case-sensitive human languages regardless of system locale. It can deal with expanding values: a German Eszett character can compare against two ASCII 's' chars and be considered a match, for example. A notable exception: it does not handle the Turkish 'i' character; human language is complicated!

Depending on your platform, "wchar_t" might be 2 bytes, and expected to be UTF-16 encoded (like Windows), or 4 bytes in UTF-32 format. Since this handles Unicode, it expects the string to be well-formed and not a null-terminated string of arbitrary bytes. Characters that are not valid UTF-16 (or UTF-32) are treated as Unicode character U+FFFD (REPLACEMENT CHARACTER), which is to say two strings of random bits may turn out to match if they convert to the same amount of replacement characters.

Note that while this function might deal with variable-sized characters, maxlen specifies a wchar limit! If the limit lands in the middle of a multi-byte UTF-16 sequence, it may convert a portion of the final character to one or more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not to overflow a buffer.

maxlen specifies a maximum number of wchar_t values to compare; if the strings match to this number of wchar_t (or both have matched to a null-terminator character before this number of bytes), they will be considered equal.

Parameters

str1	the first string to compare. nullptr is not permitted!
str2	the second string to compare. nullptr is not permitted!
maxlen	the maximum number of wchar_t values to compare.

Returns: less than zero if str1 is "less than" str2, greater than zero if str1 is "greater than" str2, and zero if the strings match exactly.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ wcsncmp()

int SDL::wcsncmp	(	const wchar_t *	str1,
		const wchar_t *	str2,
		size_t	maxlen
	)

inline

This only compares wchar_t values; it does not care if the string is well-formed UTF-16 (or UTF-32, depending on your platform's wchar_t size), or uses valid Unicode values.

Note that while this function is intended to be used with UTF-16 (or UTF-32, depending on your platform's definition of wchar_t), it is comparing raw wchar_t values and not Unicode codepoints: maxlen specifies a wchar_t limit! If the limit lands in the middle of a multi-wchar UTF-16 sequence, it will only compare a portion of the final character.

maxlen specifies a maximum number of wchar_t to compare; if the strings match to this number of wide chars (or both have matched to a null-terminator character before this count), they will be considered equal.

Parameters

str1	the first string to compare. nullptr is not permitted!
str2	the second string to compare. nullptr is not permitted!
maxlen	the maximum number of wchar_t to compare.

Returns: less than zero if str1 is "less than" str2, greater than zero if str1 is "greater than" str2, and zero if the strings match exactly.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ wcsnlen()

size_t SDL::wcsnlen	(	const wchar_t *	wstr,
		size_t	maxlen
	)

inline

Counts up to a maximum of maxlen wchar_t values in wstr, excluding the null terminator.

Like strnlen only counts bytes and not codepoints in a UTF-8 string, this counts wchar_t values in a string, even if the string's encoding is of variable width, like UTF-16.

Also be aware that wchar_t is different sizes on different platforms (4 bytes on Linux, 2 on Windows, etc).

Also, maxlen is a count of wide characters, not bytes!

Parameters

wstr	The null-terminated wide string to read. Must not be nullptr.
maxlen	The maximum amount of wide characters to count.

Returns: the length (in wide characters, excluding the null terminator) of wstr but never more than maxlen.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: wcslen; utf8strlen; utf8strnlen

◆ wcsnstr()

wchar_t * SDL::wcsnstr	(	const wchar_t *	haystack,
		const wchar_t *	needle,
		size_t	maxlen
	)

inline

The search ends once it finds the requested substring, or a null terminator value to end the string, or maxlen wide character have been examined. It is possible to use this function on a wide string without a null terminator.

Note that this looks for strings of wide characters, not codepoints, so it's legal to search for malformed and incomplete UTF-16 sequences.

Parameters

haystack	the wide string to search. Must not be nullptr.
needle	the wide string to search for. Must not be nullptr.
maxlen	the maximum number of wide characters to search in `haystack`.

Returns: a pointer to the first instance of needle in the string, or nullptr if not found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ wcsstr()

wchar_t * SDL::wcsstr	(	const wchar_t *	haystack,
		const wchar_t *	needle
	)

inline

The search ends once it finds the requested substring, or a null terminator byte to end the string.

Note that this looks for strings of wide characters, not codepoints, so it's legal to search for malformed and incomplete UTF-16 sequences.

Parameters

haystack	the wide string to search. Must not be nullptr.
needle	the wide string to search for. Must not be nullptr.

Returns: a pointer to the first instance of needle in the string, or nullptr if not found.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ wcstol()

long SDL::wcstol	(	const wchar_t *	str,
		wchar_t **	endp,
		int	base
	)

inline

If str starts with whitespace, then those whitespace characters are skipped before attempting to parse the number.

If the parsed number does not fit inside a long, the result is clamped to the minimum and maximum representable long values.

Parameters

str	The null-terminated wide string to read. Must not be nullptr.
endp	If not nullptr, the address of the first invalid wide character (i.e. the next character after the parsed number) will be written to this pointer.
base	The base of the integer to read. Supported values are 0 and 2 to 36 inclusive. If 0, the base will be inferred from the number's prefix (0x for hexadecimal, 0 for octal, decimal otherwise).

Returns: the parsed long, or 0 if no number could be parsed.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: strtol

◆ zero()

template<class T >

void SDL::zero ( T & x )

inline

This is wrapper over memset that handles calculating the object size, so there's no chance of copy/paste errors, and the code is cleaner.

This requires an object, not a pointer to an object, nor an array.

Parameters

x	the object to clear.

Thread safety:: It is safe to call this macro from any thread.

Since: This macro is available since SDL 3.2.0.

See also: zerop; zeroa

◆ zeroa()

template<class T , std::size_t N>

void SDL::zeroa ( T(&) x[N] )

inline

This is wrapper over memset that handles calculating the array size, so there's no chance of copy/paste errors, and the code is cleaner.

This requires an array, not an object, nor a pointer to an object.

Parameters

x	an array to clear.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: zero; zeroa

◆ zerop()

template<class T >

void SDL::zerop ( T * x )

inline

This is wrapper over memset that handles calculating the object size, so there's no chance of copy/paste errors, and the code is cleaner.

This requires a pointer to an object, not an object itself, nor an array.

Parameters

x	a pointer to the object to clear.

Thread safety:: It is safe to call this macro from any thread.

Since: This macro is available since SDL 3.2.0.

See also: zero; zeroa

Variable Documentation

◆ INVALID_UNICODE_CODEPOINT

constexpr Uint32 SDL::INVALID_UNICODE_CODEPOINT = SDL_INVALID_UNICODE_CODEPOINT

constexpr

StepUTF8() and StepBackUTF8() report this codepoint when they encounter a UTF-8 string with encoding errors.

This tends to render as something like a question mark in most places.

Since: This macro is available since SDL 3.2.0.

See also: StepBackUTF8; StepUTF8

◆ PI_D

constexpr double SDL::PI_D = SDL_PI_D

constexpr

Since: This macro is available since SDL 3.2.0.

See also: PI_F

◆ PI_F

constexpr float SDL::PI_F = SDL_PI_F

constexpr

Since: This macro is available since SDL 3.2.0.

See also: PI_D

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SDL_copyp

◆ SDL_FLT_EPSILON

◆ SDL_ICONV_ERROR

◆ SDL_iconv_utf8_locale

◆ SDL_iconv_utf8_ucs2

◆ SDL_iconv_utf8_ucs4

◆ SDL_iconv_wchar_utf8

◆ SDL_INIT_INTERFACE

◆ SDL_NOLONGLONG

◆ SDL_SINT64_C

◆ SDL_SIZE_MAX

◆ SDL_STRINGIFY_ARG

◆ SDL_UINT64_C

Typedef Documentation

◆ calloc_func

◆ CompareCallback

◆ CompareCallback_r

◆ CompareCB

◆ free_func

◆ FunctionPointer

◆ malloc_func

◆ realloc_func

Function Documentation

◆ abs() [1/3]

◆ abs() [2/3]

◆ abs() [3/3]

◆ acos() [1/2]

◆ acos() [2/2]

◆ aligned_alloc()

◆ aligned_free()

◆ arraysize()

◆ asin() [1/2]

◆ asin() [2/2]

◆ asprintf()

◆ atan() [1/2]

◆ atan() [2/2]

◆ atan2() [1/2]

◆ atan2() [2/2]

◆ atof()

◆ atoi()

◆ bsearch()

◆ bsearch_r() [1/2]

◆ bsearch_r() [2/2]

◆ calloc()

◆ ceil() [1/2]

◆ ceil() [2/2]

◆ clamp()

◆ copysign() [1/2]

◆ copysign() [2/2]

◆ cos() [1/2]

◆ cos() [2/2]

◆ crc16()

◆ crc32()

◆ exp() [1/2]

◆ exp() [2/2]

◆ floor() [1/2]

◆ floor() [2/2]

◆ fmod() [1/2]

◆ fmod() [2/2]

◆ FourCC()

◆ free()

◆ getenv()

◆ getenv_unsafe()

◆ GetEnvironment()

◆ GetMemoryFunctions()

◆ GetNumAllocations()

◆ GetOriginalMemoryFunctions()

◆ iconv_string()

◆ isalnum()

◆ isalpha()

◆ isblank()

◆ iscntrl()

◆ isdigit()