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