sdl3_sys/generated/
time.rs

1//! SDL realtime clock and date/time routines.
2//!
3//! There are two data types that are used in this category: [`SDL_Time`], which
4//! represents the nanoseconds since a specific moment (an "epoch"), and
5//! [`SDL_DateTime`], which breaks time down into human-understandable components:
6//! years, months, days, hours, etc.
7//!
8//! Much of the functionality is involved in converting those two types to
9//! other useful forms.
10
11use super::error::*;
12
13use super::stdinc::*;
14
15/// A structure holding a calendar date and time broken down into its
16/// components.
17///
18/// ## Availability
19/// This struct is available since SDL 3.2.0.
20#[repr(C)]
21#[derive(Clone, Copy, Default, PartialEq, Eq, Hash)]
22#[cfg_attr(feature = "debug-impls", derive(Debug))]
23pub struct SDL_DateTime {
24    /// Year
25    pub year: ::core::ffi::c_int,
26    /// Month \[01-12\]
27    pub month: ::core::ffi::c_int,
28    /// Day of the month \[01-31\]
29    pub day: ::core::ffi::c_int,
30    /// Hour \[0-23\]
31    pub hour: ::core::ffi::c_int,
32    /// Minute \[0-59\]
33    pub minute: ::core::ffi::c_int,
34    /// Seconds \[0-60\]
35    pub second: ::core::ffi::c_int,
36    /// Nanoseconds \[0-999999999\]
37    pub nanosecond: ::core::ffi::c_int,
38    /// Day of the week \[0-6\] (0 being Sunday)
39    pub day_of_week: ::core::ffi::c_int,
40    /// Seconds east of UTC
41    pub utc_offset: ::core::ffi::c_int,
42}
43
44/// The preferred date format of the current system locale.
45///
46/// ## Availability
47/// This enum is available since SDL 3.2.0.
48///
49/// ## See also
50/// - [`SDL_GetDateTimeLocalePreferences`]
51///
52/// ## Known values (`sdl3-sys`)
53/// | Associated constant | Global constant | Description |
54/// | ------------------- | --------------- | ----------- |
55/// | [`YYYYMMDD`](SDL_DateFormat::YYYYMMDD) | [`SDL_DATE_FORMAT_YYYYMMDD`] | Year/Month/Day |
56/// | [`DDMMYYYY`](SDL_DateFormat::DDMMYYYY) | [`SDL_DATE_FORMAT_DDMMYYYY`] | Day/Month/Year |
57/// | [`MMDDYYYY`](SDL_DateFormat::MMDDYYYY) | [`SDL_DATE_FORMAT_MMDDYYYY`] | Month/Day/Year |
58#[repr(transparent)]
59#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
60pub struct SDL_DateFormat(pub ::core::ffi::c_int);
61
62impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_DateFormat {
63    #[inline(always)]
64    fn eq(&self, other: &::core::ffi::c_int) -> bool {
65        &self.0 == other
66    }
67}
68
69impl ::core::cmp::PartialEq<SDL_DateFormat> for ::core::ffi::c_int {
70    #[inline(always)]
71    fn eq(&self, other: &SDL_DateFormat) -> bool {
72        self == &other.0
73    }
74}
75
76impl From<SDL_DateFormat> for ::core::ffi::c_int {
77    #[inline(always)]
78    fn from(value: SDL_DateFormat) -> Self {
79        value.0
80    }
81}
82
83#[cfg(feature = "debug-impls")]
84impl ::core::fmt::Debug for SDL_DateFormat {
85    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
86        #[allow(unreachable_patterns)]
87        f.write_str(match *self {
88            Self::YYYYMMDD => "SDL_DATE_FORMAT_YYYYMMDD",
89            Self::DDMMYYYY => "SDL_DATE_FORMAT_DDMMYYYY",
90            Self::MMDDYYYY => "SDL_DATE_FORMAT_MMDDYYYY",
91
92            _ => return write!(f, "SDL_DateFormat({})", self.0),
93        })
94    }
95}
96
97impl SDL_DateFormat {
98    /// Year/Month/Day
99    pub const YYYYMMDD: Self = Self((0 as ::core::ffi::c_int));
100    /// Day/Month/Year
101    pub const DDMMYYYY: Self = Self((1 as ::core::ffi::c_int));
102    /// Month/Day/Year
103    pub const MMDDYYYY: Self = Self((2 as ::core::ffi::c_int));
104}
105
106/// Year/Month/Day
107pub const SDL_DATE_FORMAT_YYYYMMDD: SDL_DateFormat = SDL_DateFormat::YYYYMMDD;
108/// Day/Month/Year
109pub const SDL_DATE_FORMAT_DDMMYYYY: SDL_DateFormat = SDL_DateFormat::DDMMYYYY;
110/// Month/Day/Year
111pub const SDL_DATE_FORMAT_MMDDYYYY: SDL_DateFormat = SDL_DateFormat::MMDDYYYY;
112
113impl SDL_DateFormat {
114    /// Initialize a `SDL_DateFormat` from a raw value.
115    #[inline(always)]
116    pub const fn new(value: ::core::ffi::c_int) -> Self {
117        Self(value)
118    }
119}
120
121impl SDL_DateFormat {
122    /// Get a copy of the inner raw value.
123    #[inline(always)]
124    pub const fn value(&self) -> ::core::ffi::c_int {
125        self.0
126    }
127}
128
129#[cfg(feature = "metadata")]
130impl sdl3_sys::metadata::GroupMetadata for SDL_DateFormat {
131    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
132        &crate::metadata::time::METADATA_SDL_DateFormat;
133}
134
135/// The preferred time format of the current system locale.
136///
137/// ## Availability
138/// This enum is available since SDL 3.2.0.
139///
140/// ## See also
141/// - [`SDL_GetDateTimeLocalePreferences`]
142///
143/// ## Known values (`sdl3-sys`)
144/// | Associated constant | Global constant | Description |
145/// | ------------------- | --------------- | ----------- |
146/// | [`_24HR`](SDL_TimeFormat::_24HR) | [`SDL_TIME_FORMAT_24HR`] | 24 hour time |
147/// | [`_12HR`](SDL_TimeFormat::_12HR) | [`SDL_TIME_FORMAT_12HR`] | 12 hour time |
148#[repr(transparent)]
149#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
150pub struct SDL_TimeFormat(pub ::core::ffi::c_int);
151
152impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_TimeFormat {
153    #[inline(always)]
154    fn eq(&self, other: &::core::ffi::c_int) -> bool {
155        &self.0 == other
156    }
157}
158
159impl ::core::cmp::PartialEq<SDL_TimeFormat> for ::core::ffi::c_int {
160    #[inline(always)]
161    fn eq(&self, other: &SDL_TimeFormat) -> bool {
162        self == &other.0
163    }
164}
165
166impl From<SDL_TimeFormat> for ::core::ffi::c_int {
167    #[inline(always)]
168    fn from(value: SDL_TimeFormat) -> Self {
169        value.0
170    }
171}
172
173#[cfg(feature = "debug-impls")]
174impl ::core::fmt::Debug for SDL_TimeFormat {
175    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
176        #[allow(unreachable_patterns)]
177        f.write_str(match *self {
178            Self::_24HR => "SDL_TIME_FORMAT_24HR",
179            Self::_12HR => "SDL_TIME_FORMAT_12HR",
180
181            _ => return write!(f, "SDL_TimeFormat({})", self.0),
182        })
183    }
184}
185
186impl SDL_TimeFormat {
187    /// 24 hour time
188    pub const _24HR: Self = Self((0 as ::core::ffi::c_int));
189    /// 12 hour time
190    pub const _12HR: Self = Self((1 as ::core::ffi::c_int));
191}
192
193/// 24 hour time
194pub const SDL_TIME_FORMAT_24HR: SDL_TimeFormat = SDL_TimeFormat::_24HR;
195/// 12 hour time
196pub const SDL_TIME_FORMAT_12HR: SDL_TimeFormat = SDL_TimeFormat::_12HR;
197
198impl SDL_TimeFormat {
199    /// Initialize a `SDL_TimeFormat` from a raw value.
200    #[inline(always)]
201    pub const fn new(value: ::core::ffi::c_int) -> Self {
202        Self(value)
203    }
204}
205
206impl SDL_TimeFormat {
207    /// Get a copy of the inner raw value.
208    #[inline(always)]
209    pub const fn value(&self) -> ::core::ffi::c_int {
210        self.0
211    }
212}
213
214#[cfg(feature = "metadata")]
215impl sdl3_sys::metadata::GroupMetadata for SDL_TimeFormat {
216    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
217        &crate::metadata::time::METADATA_SDL_TimeFormat;
218}
219
220unsafe extern "C" {
221    /// Gets the current preferred date and time format for the system locale.
222    ///
223    /// This might be a "slow" call that has to query the operating system. It's
224    /// best to ask for this once and save the results. However, the preferred
225    /// formats can change, usually because the user has changed a system
226    /// preference outside of your program.
227    ///
228    /// ## Parameters
229    /// - `dateFormat`: a pointer to the [`SDL_DateFormat`] to hold the returned date
230    ///   format, may be NULL.
231    /// - `timeFormat`: a pointer to the [`SDL_TimeFormat`] to hold the returned time
232    ///   format, may be NULL.
233    ///
234    /// ## Return value
235    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
236    ///   information.
237    ///
238    /// ## Thread safety
239    /// This function is not thread safe.
240    ///
241    /// ## Availability
242    /// This function is available since SDL 3.2.0.
243    pub fn SDL_GetDateTimeLocalePreferences(
244        dateFormat: *mut SDL_DateFormat,
245        timeFormat: *mut SDL_TimeFormat,
246    ) -> ::core::primitive::bool;
247}
248
249unsafe extern "C" {
250    /// Gets the current value of the system realtime clock in nanoseconds since
251    /// Jan 1, 1970 in Universal Coordinated Time (UTC).
252    ///
253    /// ## Parameters
254    /// - `ticks`: the [`SDL_Time`] to hold the returned tick count.
255    ///
256    /// ## Return value
257    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
258    ///   information.
259    ///
260    /// ## Thread safety
261    /// It is safe to call this function from any thread.
262    ///
263    /// ## Availability
264    /// This function is available since SDL 3.2.0.
265    pub fn SDL_GetCurrentTime(ticks: *mut SDL_Time) -> ::core::primitive::bool;
266}
267
268unsafe extern "C" {
269    /// Converts an [`SDL_Time`] in nanoseconds since the epoch to a calendar time in
270    /// the [`SDL_DateTime`] format.
271    ///
272    /// ## Parameters
273    /// - `ticks`: the [`SDL_Time`] to be converted.
274    /// - `dt`: the resulting [`SDL_DateTime`].
275    /// - `localTime`: the resulting [`SDL_DateTime`] will be expressed in local time
276    ///   if true, otherwise it will be in Universal Coordinated
277    ///   Time (UTC).
278    ///
279    /// ## Return value
280    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
281    ///   information.
282    ///
283    /// ## Thread safety
284    /// It is safe to call this function from any thread.
285    ///
286    /// ## Availability
287    /// This function is available since SDL 3.2.0.
288    pub fn SDL_TimeToDateTime(
289        ticks: SDL_Time,
290        dt: *mut SDL_DateTime,
291        localTime: ::core::primitive::bool,
292    ) -> ::core::primitive::bool;
293}
294
295unsafe extern "C" {
296    /// Converts a calendar time to an [`SDL_Time`] in nanoseconds since the epoch.
297    ///
298    /// This function ignores the day_of_week member of the [`SDL_DateTime`] struct, so
299    /// it may remain unset.
300    ///
301    /// ## Parameters
302    /// - `dt`: the source [`SDL_DateTime`].
303    /// - `ticks`: the resulting [`SDL_Time`].
304    ///
305    /// ## Return value
306    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
307    ///   information.
308    ///
309    /// ## Thread safety
310    /// It is safe to call this function from any thread.
311    ///
312    /// ## Availability
313    /// This function is available since SDL 3.2.0.
314    pub fn SDL_DateTimeToTime(
315        dt: *const SDL_DateTime,
316        ticks: *mut SDL_Time,
317    ) -> ::core::primitive::bool;
318}
319
320unsafe extern "C" {
321    /// Converts an SDL time into a Windows FILETIME (100-nanosecond intervals
322    /// since January 1, 1601).
323    ///
324    /// This function fills in the two 32-bit values of the FILETIME structure.
325    ///
326    /// ## Parameters
327    /// - `ticks`: the time to convert.
328    /// - `dwLowDateTime`: a pointer filled in with the low portion of the
329    ///   Windows FILETIME value.
330    /// - `dwHighDateTime`: a pointer filled in with the high portion of the
331    ///   Windows FILETIME value.
332    ///
333    /// ## Thread safety
334    /// It is safe to call this function from any thread.
335    ///
336    /// ## Availability
337    /// This function is available since SDL 3.2.0.
338    pub fn SDL_TimeToWindows(
339        ticks: SDL_Time,
340        dwLowDateTime: *mut Uint32,
341        dwHighDateTime: *mut Uint32,
342    );
343}
344
345unsafe extern "C" {
346    /// Converts a Windows FILETIME (100-nanosecond intervals since January 1,
347    /// 1601) to an SDL time.
348    ///
349    /// This function takes the two 32-bit values of the FILETIME structure as
350    /// parameters.
351    ///
352    /// ## Parameters
353    /// - `dwLowDateTime`: the low portion of the Windows FILETIME value.
354    /// - `dwHighDateTime`: the high portion of the Windows FILETIME value.
355    ///
356    /// ## Return value
357    /// Returns the converted SDL time.
358    ///
359    /// ## Thread safety
360    /// It is safe to call this function from any thread.
361    ///
362    /// ## Availability
363    /// This function is available since SDL 3.2.0.
364    pub safe fn SDL_TimeFromWindows(dwLowDateTime: Uint32, dwHighDateTime: Uint32) -> SDL_Time;
365}
366
367unsafe extern "C" {
368    /// Get the number of days in a month for a given year.
369    ///
370    /// ## Parameters
371    /// - `year`: the year.
372    /// - `month`: the month \[1-12\].
373    ///
374    /// ## Return value
375    /// Returns the number of days in the requested month or -1 on failure; call
376    ///   [`SDL_GetError()`] for more information.
377    ///
378    /// ## Thread safety
379    /// It is safe to call this function from any thread.
380    ///
381    /// ## Availability
382    /// This function is available since SDL 3.2.0.
383    pub safe fn SDL_GetDaysInMonth(
384        year: ::core::ffi::c_int,
385        month: ::core::ffi::c_int,
386    ) -> ::core::ffi::c_int;
387}
388
389unsafe extern "C" {
390    /// Get the day of year for a calendar date.
391    ///
392    /// ## Parameters
393    /// - `year`: the year component of the date.
394    /// - `month`: the month component of the date.
395    /// - `day`: the day component of the date.
396    ///
397    /// ## Return value
398    /// Returns the day of year \[0-365\] if the date is valid or -1 on failure;
399    ///   call [`SDL_GetError()`] for more information.
400    ///
401    /// ## Thread safety
402    /// It is safe to call this function from any thread.
403    ///
404    /// ## Availability
405    /// This function is available since SDL 3.2.0.
406    pub safe fn SDL_GetDayOfYear(
407        year: ::core::ffi::c_int,
408        month: ::core::ffi::c_int,
409        day: ::core::ffi::c_int,
410    ) -> ::core::ffi::c_int;
411}
412
413unsafe extern "C" {
414    /// Get the day of week for a calendar date.
415    ///
416    /// ## Parameters
417    /// - `year`: the year component of the date.
418    /// - `month`: the month component of the date.
419    /// - `day`: the day component of the date.
420    ///
421    /// ## Return value
422    /// Returns a value between 0 and 6 (0 being Sunday) if the date is valid or
423    ///   -1 on failure; call [`SDL_GetError()`] for more information.
424    ///
425    /// ## Thread safety
426    /// It is safe to call this function from any thread.
427    ///
428    /// ## Availability
429    /// This function is available since SDL 3.2.0.
430    pub safe fn SDL_GetDayOfWeek(
431        year: ::core::ffi::c_int,
432        month: ::core::ffi::c_int,
433        day: ::core::ffi::c_int,
434    ) -> ::core::ffi::c_int;
435}
436
437#[cfg(doc)]
438use crate::everything::*;
sdl3_sys/generated/time.rs

sdl3_sys/generated/
time.rs
