Error Handling

Simple error message routines for SDL. More...

Classes
class	SDL::Error
	An exception that returns GetError(). More...

Macros
#define	SDL_Unsupported()
	A macro to standardize error reporting on unsupported operations.
#define	SDL_InvalidParamError(param)
	A macro to standardize error reporting on unsupported operations.

Functions
bool	SDL::SetErrorUnformatted (StringParam message)
	Set the SDL error message for the current thread.
template<class... ARGS>
bool	SDL::SetError (std::string_view fmt, ARGS... args)
	Set the SDL error message for the current thread.
bool	SDL::OutOfMemory ()
	Set an error indicating that memory allocation failed.
const char *	SDL::GetError ()
	Retrieve a message about the last error that occurred on the current thread.
constexpr void	SDL::CheckError (bool result)
	Check and throw if returned value from SDL is an error.
template<class T>
constexpr T	SDL::CheckError (T result)
	Check and throw if returned value from SDL is an error.
template<class T>
constexpr T	SDL::CheckError (T result, T invalidValue)
	Check and throw if returned value from SDL is an error.
template<class T>
constexpr void	SDL::CheckErrorIfNot (T result, T validValue)
	Check and throw if returned value from SDL is an error.
bool	SDL::ClearError ()
	Clear any previous error message for this thread.

Detailed Description

Simple error message routines for SDL.

Most apps will interface with these APIs in exactly one function: when almost any SDL function call reports failure, you can get a human-readable string of the problem from GetError().

These strings are maintained per-thread, and apps are welcome to set their own errors, which is popular when building libraries on top of SDL for other apps to consume. These strings are set by calling SetError().

A common usage pattern is to have a function that returns true for success and false for failure, and do this when something fails:

if (something_went_wrong) {
   return SDL::SetError("The thing broke in this specific way: {}", errcode);
}

It's also common to just return false in this case if the failing thing is known to call SetError(), so errors simply propagate through.

Macro Definition Documentation

SDL_InvalidParamError

#define SDL_InvalidParamError

(

param

)

Value:

SDL_SetError("Parameter '%s' is invalid", (param))

A macro to standardize error reporting on unsupported operations.

This simply calls SetError() with a standardized error string, for convenience, consistency, and clarity.

A common usage pattern inside SDL is this:

bool MyFunction(const char *str) {
    if (!str) {
        return SDL_InvalidParamError("str");  // returns false.
    }
    DoSomething(str);
    return true;
}

Thread safety:

It is safe to call this macro from any thread.

Since

This macro is available since SDL 3.2.0.

SDL_Unsupported

#define SDL_Unsupported

(

)

Value:

SDL_SetError("That operation is not supported")

A macro to standardize error reporting on unsupported operations.

This simply calls SetError() with a standardized error string, for convenience, consistency, and clarity.

Thread safety:

It is safe to call this macro from any thread.

Since

This macro is available since SDL 3.2.0.

Function Documentation

CheckError() [1/3]

void SDL::CheckError ( bool result )

constexpr

Check and throw if returned value from SDL is an error.

This should be called only for things that may set SetError(). If the parameter is false it will throw Error.

Parameters

result

the result returned

CheckError() [2/3]

template<class T>

T SDL::CheckError ( T result )

constexpr

Check and throw if returned value from SDL is an error.

This should be called only for things that may set SetError(). If the parameter is false it will throw Error.

Parameters

result

the result returned

CheckError() [3/3]

template<class T>

T SDL::CheckError ( T result, T invalidValue )

constexpr

Check and throw if returned value from SDL is an error.

This should be called only for things that may set SetError(). If the result parameter is equals to invalidValue it will throw Error.

Parameters

result	the result returned
invalidValue	the value that if equal to result indicates this is invalid.

CheckErrorIfNot()

template<class T>

void SDL::CheckErrorIfNot ( T result, T validValue )

constexpr

Check and throw if returned value from SDL is an error.

This should be called only for things that may set SetError(). If the result parameter is equals to invalidValue it will throw Error.

Parameters

result	the result returned
validValue	the value that if equal to result indicates this is valid.

ClearError()

bool SDL::ClearError ( )

inline

Clear any previous error message for this thread.

Returns

true.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

See also

GetError

SetErrorUnformatted

GetError()

const char * SDL::GetError ( )

inline

Retrieve a message about the last error that occurred on the current thread.

It is possible for multiple errors to occur before calling GetError(). Only the last error is returned.

The message is only applicable when an SDL function has signaled an error. You must check the return values of SDL function calls to determine when to appropriately call GetError(). You should not use the results of GetError() to decide if an error has occurred! Sometimes SDL will set an error string even when reporting success.

SDL will not clear the error string for successful API calls. You must check return values for failure cases before you can assume the error string applies.

Error strings are set per-thread, so an error set in a different thread will not interfere with the current thread's operation.

The returned value is a thread-local string which will remain valid until the current thread's error string is changed. The caller should make a copy if the value is needed after the next SDL API call.

Returns

a message with information about the specific error that occurred, or an empty string if there hasn't been an error message set since the last call to ClearError().

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

See also

ClearError

SetErrorUnformatted

OutOfMemory()

bool SDL::OutOfMemory ( )

inline

Set an error indicating that memory allocation failed.

This function does not do any memory allocation.

Returns

false.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

SetError()

template<class... ARGS>

bool SDL::SetError ( std::string_view fmt, ARGS... args )

inline

Set the SDL error message for the current thread.

Calling this function will replace any previous error message that was set.

This function always returns false, since SDL frequently uses false to signify a failing result, leading to this idiom:

if (error_code) {
    return SetError("This operation has failed: {}", error_code);
}

Template Parameters

ARGS	the formatting parameters

Parameters

fmt	a std::format/fmt style message format string
args	additional parameters matching the {} tokens in the format string, if any.

Returns

false.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

Category:

Formatted string

See also

formatted-string

ClearError

GetError

SetError

Returns

false

SetErrorUnformatted()

bool SDL::SetErrorUnformatted ( StringParam message )

inline

Set the SDL error message for the current thread.

Calling this function will replace any previous error message that was set.

This function always returns false, since SDL frequently uses false to signify a failing result, leading to this idiom:

if (error_code) {
    return SDL::SetError("This operation has failed: {}", error_code);
}

Parameters

message

the error message

Returns

false.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

See also

ClearError

GetError

SetError