SDL realtime clock and date/time routines. More...

Classes
struct	SDL::DateTime
	A structure holding a calendar date and time broken down into its components. More...

Typedefs
using	SDL::DateTimeRaw = SDL_DateTime
	Alias to raw representation for DateTime.
using	SDL::DateFormat = SDL_DateFormat
	The preferred date format of the current system locale.
using	SDL::TimeFormat = SDL_TimeFormat
	The preferred time format of the current system locale.

Functions
void	SDL::GetDateTimeLocalePreferences (DateFormat dateFormat, TimeFormat timeFormat)
	Gets the current preferred date and time format for the system locale.
DateTime	SDL::TimeToDateTime (Time ticks, bool localTime=true)
	Converts an Time in nanoseconds since the epoch to a calendar time in the DateTime format.
Time	SDL::DateTimeToTime (const DateTimeRaw &dt)
	Converts a calendar time to an Time in nanoseconds since the epoch.
int	SDL::GetDaysInMonth (int year, int month)
	Get the number of days in a month for a given year.
int	SDL::GetDayOfYear (int year, int month, int day)
	Get the day of year for a calendar date.
int	SDL::GetDayOfWeek (int year, int month, int day)
	Get the day of week for a calendar date.
static Time	SDL::Time::Current ()
	Gets the current value of the system realtime clock in nanoseconds since Jan 1, 1970 in Universal Coordinated Time (UTC).
	SDL::DateTime::DateTime (Time ticks, bool localTime=true)
	Converts an Time in nanoseconds since the epoch to a calendar time in the DateTime format.
	SDL::DateTime::operator Time () const
	Converts a calendar time to an Time in nanoseconds since the epoch.
void	SDL::Time::ToWindows (Uint32 dwLowDateTime, Uint32 dwHighDateTime) const
	Converts an SDL time into a Windows FILETIME (100-nanosecond intervals since January 1, 1601).
static Time	SDL::Time::FromWindows (Uint32 dwLowDateTime, Uint32 dwHighDateTime)
	Converts a Windows FILETIME (100-nanosecond intervals since January 1, 1601) to an SDL time.

Variables
constexpr DateFormat	SDL::DATE_FORMAT_YYYYMMDD
	Year/Month/Day.
constexpr DateFormat	SDL::DATE_FORMAT_DDMMYYYY
	Day/Month/Year.
constexpr DateFormat	SDL::DATE_FORMAT_MMDDYYYY
	Month/Day/Year.
constexpr TimeFormat	SDL::TIME_FORMAT_24HR = SDL_TIME_FORMAT_24HR
	24 hour time
constexpr TimeFormat	SDL::TIME_FORMAT_12HR = SDL_TIME_FORMAT_12HR
	12 hour time

Detailed Description

SDL realtime clock and date/time routines.

There are two data types that are used in this category: Time, which represents the nanoseconds since a specific moment (an "epoch"), and DateTime, which breaks time down into human-understandable components: years, months, days, hours, etc.

Much of the functionality is involved in converting those two types to other useful forms.

Typedef Documentation

◆ DateFormat

using SDL::DateFormat = SDL_DateFormat

The preferred date format of the current system locale.

Since: This enum is available since SDL 3.2.0.

See also: GetDateTimeLocalePreferences

◆ TimeFormat

using SDL::TimeFormat = SDL_TimeFormat

The preferred time format of the current system locale.

Since: This enum is available since SDL 3.2.0.

See also: GetDateTimeLocalePreferences

Function Documentation

◆ Current()

Time SDL::Time::Current ( )

inlinestatic

Gets the current value of the system realtime clock in nanoseconds since Jan 1, 1970 in Universal Coordinated Time (UTC).

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

◆ DateTime()

SDL::DateTime::DateTime	(	Time	ticks,
		bool	localTime = true )

inline

Converts an Time in nanoseconds since the epoch to a calendar time in the DateTime format.

Parameters

ticks	the Time to be converted.
localTime	the resulting DateTime will be expressed in local time if true, otherwise it will be in Universal Coordinated Time (UTC).

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

◆ DateTimeToTime()

Time SDL::DateTimeToTime ( const DateTimeRaw & dt )

inline

Converts a calendar time to an Time in nanoseconds since the epoch.

This function ignores the day_of_week member of the DateTime struct, so it may remain unset.

Parameters

dt	the source DateTime.

Returns: the resulting Time.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

◆ FromWindows()

Time SDL::Time::FromWindows	(	Uint32	dwLowDateTime,
		Uint32	dwHighDateTime )

inlinestatic

Converts a Windows FILETIME (100-nanosecond intervals since January 1, 1601) to an SDL time.

This function takes the two 32-bit values of the FILETIME structure as parameters.

Parameters

dwLowDateTime	the low portion of the Windows FILETIME value.
dwHighDateTime	the high portion of the Windows FILETIME value.

Returns: the converted SDL time.

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

Since: This function is available since SDL 3.2.0.

◆ GetDateTimeLocalePreferences()

void SDL::GetDateTimeLocalePreferences	(	DateFormat *	dateFormat,
		TimeFormat *	timeFormat )

inline

Gets the current preferred date and time format for the system locale.

This might be a "slow" call that has to query the operating system. It's best to ask for this once and save the results. However, the preferred formats can change, usually because the user has changed a system preference outside of your program.

Parameters

dateFormat	a pointer to the DateFormat to hold the returned date format, may be nullptr.
timeFormat	a pointer to the TimeFormat to hold the returned time format, may be nullptr.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ GetDayOfWeek()

int SDL::GetDayOfWeek	(	int	year,
		int	month,
		int	day )

inline

Get the day of week for a calendar date.

Parameters

year	the year component of the date.
month	the month component of the date.
day	the day component of the date.

Returns: a value between 0 and 6 (0 being Sunday) if the date is valid.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

◆ GetDayOfYear()

int SDL::GetDayOfYear	(	int	year,
		int	month,
		int	day )

inline

Get the day of year for a calendar date.

Parameters

year	the year component of the date.
month	the month component of the date.
day	the day component of the date.

Returns: the day of year [0-365] if the date is valid.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

◆ GetDaysInMonth()

int SDL::GetDaysInMonth	(	int	year,
		int	month )

inline

Get the number of days in a month for a given year.

Parameters

year	the year.
month	the month [1-12].

Returns: the number of days in the requested month.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

◆ operator Time()

SDL::DateTime::operator Time ( ) const

inline

Converts a calendar time to an Time in nanoseconds since the epoch.

This function ignores the day_of_week member of the DateTime struct, so it may remain unset.

Returns: time on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

◆ TimeToDateTime()

DateTime SDL::TimeToDateTime	(	Time	ticks,
		bool	localTime = true )

inline

Converts an Time in nanoseconds since the epoch to a calendar time in the DateTime format.

Parameters

ticks	the Time to be converted.
localTime	the resulting DateTime will be expressed in local time if true, otherwise it will be in Universal Coordinated Time (UTC).

Returns: the resulting DateTime.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

◆ ToWindows()

void SDL::Time::ToWindows	(	Uint32 *	dwLowDateTime,
		Uint32 *	dwHighDateTime ) const

inline

Converts an SDL time into a Windows FILETIME (100-nanosecond intervals since January 1, 1601).

This function fills in the two 32-bit values of the FILETIME structure.

Parameters

dwLowDateTime	a pointer filled in with the low portion of the Windows FILETIME value.
dwHighDateTime	a pointer filled in with the high portion of the Windows FILETIME value.

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

Since: This function is available since SDL 3.2.0.

Variable Documentation

◆ DATE_FORMAT_DDMMYYYY

DateFormat SDL::DATE_FORMAT_DDMMYYYY

constexpr

Initial value:

=

SDL_DATE_FORMAT_DDMMYYYY

Day/Month/Year.

◆ DATE_FORMAT_MMDDYYYY

DateFormat SDL::DATE_FORMAT_MMDDYYYY

constexpr

Initial value:

=

SDL_DATE_FORMAT_MMDDYYYY

Month/Day/Year.

◆ DATE_FORMAT_YYYYMMDD

DateFormat SDL::DATE_FORMAT_YYYYMMDD

constexpr

Initial value:

=

SDL_DATE_FORMAT_YYYYMMDD

Year/Month/Day.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ DateFormat

◆ TimeFormat

Function Documentation

◆ Current()

◆ DateTime()

◆ DateTimeToTime()

◆ FromWindows()

◆ GetDateTimeLocalePreferences()

◆ GetDayOfWeek()

◆ GetDayOfYear()

◆ GetDaysInMonth()

◆ operator Time()

◆ TimeToDateTime()

◆ ToWindows()

Variable Documentation

◆ DATE_FORMAT_DDMMYYYY

◆ DATE_FORMAT_MMDDYYYY

◆ DATE_FORMAT_YYYYMMDD