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
113#[cfg(feature = "metadata")]
114impl sdl3_sys::metadata::GroupMetadata for SDL_DateFormat {
115    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
116        &crate::metadata::time::METADATA_SDL_DateFormat;
117}
118
119/// The preferred time format of the current system locale.
120///
121/// ## Availability
122/// This enum is available since SDL 3.2.0.
123///
124/// ## See also
125/// - [`SDL_GetDateTimeLocalePreferences`]
126///
127/// ## Known values (`sdl3-sys`)
128/// | Associated constant | Global constant | Description |
129/// | ------------------- | --------------- | ----------- |
130/// | [`_24HR`](SDL_TimeFormat::_24HR) | [`SDL_TIME_FORMAT_24HR`] | 24 hour time |
131/// | [`_12HR`](SDL_TimeFormat::_12HR) | [`SDL_TIME_FORMAT_12HR`] | 12 hour time |
132#[repr(transparent)]
133#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
134pub struct SDL_TimeFormat(pub ::core::ffi::c_int);
135
136impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_TimeFormat {
137    #[inline(always)]
138    fn eq(&self, other: &::core::ffi::c_int) -> bool {
139        &self.0 == other
140    }
141}
142
143impl ::core::cmp::PartialEq<SDL_TimeFormat> for ::core::ffi::c_int {
144    #[inline(always)]
145    fn eq(&self, other: &SDL_TimeFormat) -> bool {
146        self == &other.0
147    }
148}
149
150impl From<SDL_TimeFormat> for ::core::ffi::c_int {
151    #[inline(always)]
152    fn from(value: SDL_TimeFormat) -> Self {
153        value.0
154    }
155}
156
157#[cfg(feature = "debug-impls")]
158impl ::core::fmt::Debug for SDL_TimeFormat {
159    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
160        #[allow(unreachable_patterns)]
161        f.write_str(match *self {
162            Self::_24HR => "SDL_TIME_FORMAT_24HR",
163            Self::_12HR => "SDL_TIME_FORMAT_12HR",
164
165            _ => return write!(f, "SDL_TimeFormat({})", self.0),
166        })
167    }
168}
169
170impl SDL_TimeFormat {
171    /// 24 hour time
172    pub const _24HR: Self = Self((0 as ::core::ffi::c_int));
173    /// 12 hour time
174    pub const _12HR: Self = Self((1 as ::core::ffi::c_int));
175}
176
177/// 24 hour time
178pub const SDL_TIME_FORMAT_24HR: SDL_TimeFormat = SDL_TimeFormat::_24HR;
179/// 12 hour time
180pub const SDL_TIME_FORMAT_12HR: SDL_TimeFormat = SDL_TimeFormat::_12HR;
181
182#[cfg(feature = "metadata")]
183impl sdl3_sys::metadata::GroupMetadata for SDL_TimeFormat {
184    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
185        &crate::metadata::time::METADATA_SDL_TimeFormat;
186}
187
188unsafe extern "C" {
189    /// Gets the current preferred date and time format for the system locale.
190    ///
191    /// This might be a "slow" call that has to query the operating system. It's
192    /// best to ask for this once and save the results. However, the preferred
193    /// formats can change, usually because the user has changed a system
194    /// preference outside of your program.
195    ///
196    /// ## Parameters
197    /// - `dateFormat`: a pointer to the [`SDL_DateFormat`] to hold the returned date
198    ///   format, may be NULL.
199    /// - `timeFormat`: a pointer to the [`SDL_TimeFormat`] to hold the returned time
200    ///   format, may be NULL.
201    ///
202    /// ## Return value
203    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
204    ///   information.
205    ///
206    /// ## Availability
207    /// This function is available since SDL 3.2.0.
208    pub fn SDL_GetDateTimeLocalePreferences(
209        dateFormat: *mut SDL_DateFormat,
210        timeFormat: *mut SDL_TimeFormat,
211    ) -> ::core::primitive::bool;
212}
213
214unsafe extern "C" {
215    /// Gets the current value of the system realtime clock in nanoseconds since
216    /// Jan 1, 1970 in Universal Coordinated Time (UTC).
217    ///
218    /// ## Parameters
219    /// - `ticks`: the [`SDL_Time`] to hold the returned tick count.
220    ///
221    /// ## Return value
222    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
223    ///   information.
224    ///
225    /// ## Availability
226    /// This function is available since SDL 3.2.0.
227    pub fn SDL_GetCurrentTime(ticks: *mut SDL_Time) -> ::core::primitive::bool;
228}
229
230unsafe extern "C" {
231    /// Converts an [`SDL_Time`] in nanoseconds since the epoch to a calendar time in
232    /// the [`SDL_DateTime`] format.
233    ///
234    /// ## Parameters
235    /// - `ticks`: the [`SDL_Time`] to be converted.
236    /// - `dt`: the resulting [`SDL_DateTime`].
237    /// - `localTime`: the resulting [`SDL_DateTime`] will be expressed in local time
238    ///   if true, otherwise it will be in Universal Coordinated
239    ///   Time (UTC).
240    ///
241    /// ## Return value
242    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
243    ///   information.
244    ///
245    /// ## Availability
246    /// This function is available since SDL 3.2.0.
247    pub fn SDL_TimeToDateTime(
248        ticks: SDL_Time,
249        dt: *mut SDL_DateTime,
250        localTime: ::core::primitive::bool,
251    ) -> ::core::primitive::bool;
252}
253
254unsafe extern "C" {
255    /// Converts a calendar time to an [`SDL_Time`] in nanoseconds since the epoch.
256    ///
257    /// This function ignores the day_of_week member of the [`SDL_DateTime`] struct, so
258    /// it may remain unset.
259    ///
260    /// ## Parameters
261    /// - `dt`: the source [`SDL_DateTime`].
262    /// - `ticks`: the resulting [`SDL_Time`].
263    ///
264    /// ## Return value
265    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
266    ///   information.
267    ///
268    /// ## Availability
269    /// This function is available since SDL 3.2.0.
270    pub fn SDL_DateTimeToTime(
271        dt: *const SDL_DateTime,
272        ticks: *mut SDL_Time,
273    ) -> ::core::primitive::bool;
274}
275
276unsafe extern "C" {
277    /// Converts an SDL time into a Windows FILETIME (100-nanosecond intervals
278    /// since January 1, 1601).
279    ///
280    /// This function fills in the two 32-bit values of the FILETIME structure.
281    ///
282    /// ## Parameters
283    /// - `ticks`: the time to convert.
284    /// - `dwLowDateTime`: a pointer filled in with the low portion of the
285    ///   Windows FILETIME value.
286    /// - `dwHighDateTime`: a pointer filled in with the high portion of the
287    ///   Windows FILETIME value.
288    ///
289    /// ## Availability
290    /// This function is available since SDL 3.2.0.
291    pub fn SDL_TimeToWindows(
292        ticks: SDL_Time,
293        dwLowDateTime: *mut Uint32,
294        dwHighDateTime: *mut Uint32,
295    );
296}
297
298unsafe extern "C" {
299    /// Converts a Windows FILETIME (100-nanosecond intervals since January 1,
300    /// 1601) to an SDL time.
301    ///
302    /// This function takes the two 32-bit values of the FILETIME structure as
303    /// parameters.
304    ///
305    /// ## Parameters
306    /// - `dwLowDateTime`: the low portion of the Windows FILETIME value.
307    /// - `dwHighDateTime`: the high portion of the Windows FILETIME value.
308    ///
309    /// ## Return value
310    /// Returns the converted SDL time.
311    ///
312    /// ## Availability
313    /// This function is available since SDL 3.2.0.
314    pub safe fn SDL_TimeFromWindows(dwLowDateTime: Uint32, dwHighDateTime: Uint32) -> SDL_Time;
315}
316
317unsafe extern "C" {
318    /// Get the number of days in a month for a given year.
319    ///
320    /// ## Parameters
321    /// - `year`: the year.
322    /// - `month`: the month \[1-12\].
323    ///
324    /// ## Return value
325    /// Returns the number of days in the requested month or -1 on failure; call
326    ///   [`SDL_GetError()`] for more information.
327    ///
328    /// ## Availability
329    /// This function is available since SDL 3.2.0.
330    pub safe fn SDL_GetDaysInMonth(
331        year: ::core::ffi::c_int,
332        month: ::core::ffi::c_int,
333    ) -> ::core::ffi::c_int;
334}
335
336unsafe extern "C" {
337    /// Get the day of year for a calendar date.
338    ///
339    /// ## Parameters
340    /// - `year`: the year component of the date.
341    /// - `month`: the month component of the date.
342    /// - `day`: the day component of the date.
343    ///
344    /// ## Return value
345    /// Returns the day of year \[0-365\] if the date is valid or -1 on failure;
346    ///   call [`SDL_GetError()`] for more information.
347    ///
348    /// ## Availability
349    /// This function is available since SDL 3.2.0.
350    pub safe fn SDL_GetDayOfYear(
351        year: ::core::ffi::c_int,
352        month: ::core::ffi::c_int,
353        day: ::core::ffi::c_int,
354    ) -> ::core::ffi::c_int;
355}
356
357unsafe extern "C" {
358    /// Get the day of week for a calendar date.
359    ///
360    /// ## Parameters
361    /// - `year`: the year component of the date.
362    /// - `month`: the month component of the date.
363    /// - `day`: the day component of the date.
364    ///
365    /// ## Return value
366    /// Returns a value between 0 and 6 (0 being Sunday) if the date is valid or
367    ///   -1 on failure; call [`SDL_GetError()`] for more information.
368    ///
369    /// ## Availability
370    /// This function is available since SDL 3.2.0.
371    pub safe fn SDL_GetDayOfWeek(
372        year: ::core::ffi::c_int,
373        month: ::core::ffi::c_int,
374        day: ::core::ffi::c_int,
375    ) -> ::core::ffi::c_int;
376}
377
378#[cfg(doc)]
379use crate::everything::*;
sdl3_sys/generated/time.rs

sdl3_sys/generated/
time.rs
