SDL 3.0
SDL_time.h
Go to the documentation of this file.
1/*
2Simple DirectMedia Layer
3Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5This software is provided 'as-is', without any express or implied
6warranty. In no event will the authors be held liable for any damages
7arising from the use of this software.
8
9Permission is granted to anyone to use this software for any purpose,
10including commercial applications, and to alter it and redistribute it
11freely, subject to the following restrictions:
12
131. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
172. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
193. This notice may not be removed or altered from any source distribution.
20*/
21
22#ifndef SDL_time_h_
23#define SDL_time_h_
24
25/**
26 * \file SDL_time.h
27 *
28 * Header for the SDL realtime clock and date/time routines.
29 */
30
31#include <SDL3/SDL_error.h>
32#include <SDL3/SDL_stdinc.h>
33
34#include <SDL3/SDL_begin_code.h>
35/* Set up for C function definitions, even when using C++ */
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/**
41 * A structure holding a calendar date and time broken down into its
42 * components.
43 *
44 * \since This struct is available since SDL 3.0.0.
45 */
46typedef struct SDL_DateTime
47{
48 int year; /**< Year */
49 int month; /**< Month [01-12] */
50 int day; /**< Day of the month [01-31] */
51 int hour; /**< Hour [0-23] */
52 int minute; /**< Minute [0-59] */
53 int second; /**< Seconds [0-60] */
54 int nanosecond; /**< Nanoseconds [0-999999999] */
55 int day_of_week; /**< Day of the week [0-6] (0 being Sunday) */
56 int utc_offset; /**< Seconds east of UTC */
58
59/**
60 * The preferred date format of the current system locale.
61 *
62 * \since This enum is available since SDL 3.0.0.
63 *
64 * \sa SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER
65 */
66typedef enum SDL_DateFormat
67{
68 SDL_DATE_FORMAT_YYYYMMDD = 0, /**< Year/Month/Day */
69 SDL_DATE_FORMAT_DDMMYYYY = 1, /**< Day/Month/Year */
70 SDL_DATE_FORMAT_MMDDYYYY = 2 /**< Month/Day/Year */
72
73/**
74 * The preferred time format of the current system locale.
75 *
76 * \since This enum is available since SDL 3.0.0.
77 *
78 * \sa SDL_PROP_GLOBAL_SYSTEM_TIME_FORMAT_NUMBER
79 */
80typedef enum SDL_TimeFormat
81{
82 SDL_TIME_FORMAT_24HR = 0, /**< 24 hour time */
83 SDL_TIME_FORMAT_12HR = 1 /**< 12 hour time */
85
86/*
87 * Global date/time properties.
88 *
89 * - `SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER`: the SDL_DateFormat to use as the preferred date display format
90 * for the current system locale.
91 * - `SDL_PROP_GLOBAL_SYSTEM_TIME_FORMAT_NUMBER`: the SDL_TimeFormat to use as the preferred time display format
92 * for the current system locale.
93 */
94#define SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER "SDL.time.date_format"
95#define SDL_PROP_GLOBAL_SYSTEM_TIME_FORMAT_NUMBER "SDL.time.time_format"
96
97/**
98 * Gets the current value of the system realtime clock in nanoseconds since
99 * Jan 1, 1970 in Universal Coordinated Time (UTC).
100 *
101 * \param ticks the SDL_Time to hold the returned tick count
102 * \returns 0 on success or -1 on error; call SDL_GetError() for more
103 * information.
104 *
105 * \since This function is available since SDL 3.0.0.
106 */
107extern DECLSPEC int SDLCALL SDL_GetCurrentTime(SDL_Time *ticks);
108
109/**
110 * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in
111 * the SDL_DateTime format.
112 *
113 * \param ticks the SDL_Time to be converted
114 * \param dt the resulting SDL_DateTime
115 * \param localTime the resulting SDL_DateTime will be expressed in local time
116 * if true, otherwise it will be in Universal Coordinated
117 * Time (UTC)
118 * \returns 0 on success or -1 on error; call SDL_GetError() for more
119 * information.
120 *
121 * \since This function is available since SDL 3.0.0.
122 */
123extern DECLSPEC int SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, SDL_bool localTime);
124
125/**
126 * Converts a calendar time to an SDL_Time in nanoseconds since the epoch.
127 *
128 * This function ignores the day_of_week member of the SDL_DateTime struct, so
129 * it may remain unset.
130 *
131 * \param dt the source SDL_DateTime
132 * \param ticks the resulting SDL_Time
133 * \returns 0 on success or -1 on error; call SDL_GetError() for more
134 * information.
135 *
136 * \since This function is available since SDL 3.0.0.
137 */
138extern DECLSPEC int SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks);
139
140/**
141 * Converts an SDL time into a Windows FILETIME (100-nanosecond intervals
142 * since January 1, 1601).
143 *
144 * This function fills in the two 32-bit values of the FILETIME structure.
145 *
146 * \param ticks the time to convert
147 * \param dwLowDateTime a pointer filled in with the low portion of the
148 * Windows FILETIME value
149 * \param dwHighDateTime a pointer filled in with the high portion of the
150 * Windows FILETIME value
151 *
152 * \since This function is available since SDL 3.0.0.
153 */
154extern DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDateTime, Uint32 *dwHighDateTime);
155
156/**
157 * Converts a Windows FILETIME (100-nanosecond intervals since January 1,
158 * 1601) to an SDL time.
159 *
160 * This function takes the two 32-bit values of the FILETIME structure as
161 * parameters.
162 *
163 * \param dwLowDateTime the low portion of the Windows FILETIME value
164 * \param dwHighDateTime the high portion of the Windows FILETIME value
165 * \returns the converted SDL time
166 *
167 * \since This function is available since SDL 3.0.0.
168 */
169extern DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime);
170
171/**
172 * Get the number of days in a month for a given year.
173 *
174 * \param year the year
175 * \param month the month [1-12]
176 * \returns the number of days in the requested month, otherwise -1; call
177 * SDL_GetError() for more information.
178 *
179 * \since This function is available since SDL 3.0.0.
180 */
181extern DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month);
182
183/**
184 * Get the day of year for a calendar date.
185 *
186 * \param year the year component of the date
187 * \param month the month component of the date
188 * \param day the day component of the date
189 * \returns the day of year [0-365] if the date is valid, otherwise -1; call
190 * SDL_GetError() for more information.
191 *
192 * \since This function is available since SDL 3.0.0.
193 */
194extern DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day);
195
196/**
197 * Get the day of week for a calendar date.
198 *
199 * \param year the year component of the date
200 * \param month the month component of the date
201 * \param day the day component of the date
202 * \returns a value between 0 and 6 (0 being Sunday) if the date is valid,
203 * otherwise -1; call SDL_GetError() for more information.
204 *
205 * \since This function is available since SDL 3.0.0.
206 */
207extern DECLSPEC int SDLCALL SDL_GetDayOfWeek(int year, int month, int day);
208
209/* Ends C function definitions when using C++ */
210#ifdef __cplusplus
211}
212#endif
213#include <SDL3/SDL_close_code.h>
214
215#endif /* SDL_time_h_ */
int SDL_bool
Definition SDL_stdinc.h:170
uint32_t Uint32
Definition SDL_stdinc.h:224
Sint64 SDL_Time
Definition SDL_stdinc.h:256
int SDL_GetDayOfWeek(int year, int month, int day)
int SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, SDL_bool localTime)
SDL_DateFormat
Definition SDL_time.h:67
@ SDL_DATE_FORMAT_DDMMYYYY
Definition SDL_time.h:69
@ SDL_DATE_FORMAT_YYYYMMDD
Definition SDL_time.h:68
@ SDL_DATE_FORMAT_MMDDYYYY
Definition SDL_time.h:70
void SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDateTime, Uint32 *dwHighDateTime)
int SDL_GetDayOfYear(int year, int month, int day)
SDL_TimeFormat
Definition SDL_time.h:81
@ SDL_TIME_FORMAT_12HR
Definition SDL_time.h:83
@ SDL_TIME_FORMAT_24HR
Definition SDL_time.h:82
int SDL_GetCurrentTime(SDL_Time *ticks)
int SDL_GetDaysInMonth(int year, int month)
SDL_Time SDL_TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime)
int SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks)
int nanosecond
Definition SDL_time.h:54
int utc_offset
Definition SDL_time.h:56
int day_of_week
Definition SDL_time.h:55