glib/auto/
date_time.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, translate::*, BoolError, TimeSpan, TimeZone};
6
7crate::wrapper! {
8    /// `GDateTime` is a structure that combines a Gregorian date and time
9    /// into a single structure.
10    ///
11    /// `GDateTime` provides many conversion and methods to manipulate dates and times.
12    /// Time precision is provided down to microseconds and the time can range
13    /// (proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999.
14    /// `GDateTime` follows POSIX time in the sense that it is oblivious to leap
15    /// seconds.
16    ///
17    /// `GDateTime` is an immutable object; once it has been created it cannot
18    /// be modified further. All modifiers will create a new `GDateTime`.
19    /// Nearly all such functions can fail due to the date or time going out
20    /// of range, in which case [`None`] will be returned.
21    ///
22    /// `GDateTime` is reference counted: the reference count is increased by calling
23    /// `GLib::DateTime::ref()` and decreased by calling `GLib::DateTime::unref()`.
24    /// When the reference count drops to 0, the resources allocated by the `GDateTime`
25    /// structure are released.
26    ///
27    /// Many parts of the API may produce non-obvious results. As an
28    /// example, adding two months to January 31st will yield March 31st
29    /// whereas adding one month and then one month again will yield either
30    /// March 28th or March 29th.  Also note that adding 24 hours is not
31    /// always the same as adding one day (since days containing daylight
32    /// savings time transitions are either 23 or 25 hours in length).
33    // rustdoc-stripper-ignore-next-stop
34    /// `GDateTime` is a structure that combines a Gregorian date and time
35    /// into a single structure.
36    ///
37    /// `GDateTime` provides many conversion and methods to manipulate dates and times.
38    /// Time precision is provided down to microseconds and the time can range
39    /// (proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999.
40    /// `GDateTime` follows POSIX time in the sense that it is oblivious to leap
41    /// seconds.
42    ///
43    /// `GDateTime` is an immutable object; once it has been created it cannot
44    /// be modified further. All modifiers will create a new `GDateTime`.
45    /// Nearly all such functions can fail due to the date or time going out
46    /// of range, in which case [`None`] will be returned.
47    ///
48    /// `GDateTime` is reference counted: the reference count is increased by calling
49    /// `GLib::DateTime::ref()` and decreased by calling `GLib::DateTime::unref()`.
50    /// When the reference count drops to 0, the resources allocated by the `GDateTime`
51    /// structure are released.
52    ///
53    /// Many parts of the API may produce non-obvious results. As an
54    /// example, adding two months to January 31st will yield March 31st
55    /// whereas adding one month and then one month again will yield either
56    /// March 28th or March 29th.  Also note that adding 24 hours is not
57    /// always the same as adding one day (since days containing daylight
58    /// savings time transitions are either 23 or 25 hours in length).
59    #[derive(Debug)]
60    pub struct DateTime(Shared<ffi::GDateTime>);
61
62    match fn {
63        ref => |ptr| ffi::g_date_time_ref(ptr),
64        unref => |ptr| ffi::g_date_time_unref(ptr),
65        type_ => || ffi::g_date_time_get_type(),
66    }
67}
68
69impl DateTime {
70    /// Creates a new #GDateTime corresponding to the given date and time in
71    /// the time zone @tz.
72    ///
73    /// The @year must be between 1 and 9999, @month between 1 and 12 and @day
74    /// between 1 and 28, 29, 30 or 31 depending on the month and the year.
75    ///
76    /// @hour must be between 0 and 23 and @minute must be between 0 and 59.
77    ///
78    /// @seconds must be at least 0.0 and must be strictly less than 60.0.
79    /// It will be rounded down to the nearest microsecond.
80    ///
81    /// If the given time is not representable in the given time zone (for
82    /// example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
83    /// time) then the time will be rounded up to the nearest existing time
84    /// (in this case, 03:00).  If this matters to you then you should verify
85    /// the return value for containing the same as the numbers you gave.
86    ///
87    /// In the case that the given time is ambiguous in the given time zone
88    /// (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
89    /// savings time) then the time falling within standard (ie:
90    /// non-daylight) time is taken.
91    ///
92    /// It not considered a programmer error for the values to this function
93    /// to be out of range, but in the case that they are, the function will
94    /// return [`None`].
95    ///
96    /// You should release the return value by calling g_date_time_unref()
97    /// when you are done with it.
98    /// ## `tz`
99    /// a #GTimeZone
100    /// ## `year`
101    /// the year component of the date
102    /// ## `month`
103    /// the month component of the date
104    /// ## `day`
105    /// the day component of the date
106    /// ## `hour`
107    /// the hour component of the date
108    /// ## `minute`
109    /// the minute component of the date
110    /// ## `seconds`
111    /// the number of seconds past the minute
112    ///
113    /// # Returns
114    ///
115    /// a new #GDateTime, or [`None`]
116    // rustdoc-stripper-ignore-next-stop
117    /// Creates a new #GDateTime corresponding to the given date and time in
118    /// the time zone @tz.
119    ///
120    /// The @year must be between 1 and 9999, @month between 1 and 12 and @day
121    /// between 1 and 28, 29, 30 or 31 depending on the month and the year.
122    ///
123    /// @hour must be between 0 and 23 and @minute must be between 0 and 59.
124    ///
125    /// @seconds must be at least 0.0 and must be strictly less than 60.0.
126    /// It will be rounded down to the nearest microsecond.
127    ///
128    /// If the given time is not representable in the given time zone (for
129    /// example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
130    /// time) then the time will be rounded up to the nearest existing time
131    /// (in this case, 03:00).  If this matters to you then you should verify
132    /// the return value for containing the same as the numbers you gave.
133    ///
134    /// In the case that the given time is ambiguous in the given time zone
135    /// (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
136    /// savings time) then the time falling within standard (ie:
137    /// non-daylight) time is taken.
138    ///
139    /// It not considered a programmer error for the values to this function
140    /// to be out of range, but in the case that they are, the function will
141    /// return [`None`].
142    ///
143    /// You should release the return value by calling g_date_time_unref()
144    /// when you are done with it.
145    /// ## `tz`
146    /// a #GTimeZone
147    /// ## `year`
148    /// the year component of the date
149    /// ## `month`
150    /// the month component of the date
151    /// ## `day`
152    /// the day component of the date
153    /// ## `hour`
154    /// the hour component of the date
155    /// ## `minute`
156    /// the minute component of the date
157    /// ## `seconds`
158    /// the number of seconds past the minute
159    ///
160    /// # Returns
161    ///
162    /// a new #GDateTime, or [`None`]
163    #[doc(alias = "g_date_time_new")]
164    pub fn new(
165        tz: &TimeZone,
166        year: i32,
167        month: i32,
168        day: i32,
169        hour: i32,
170        minute: i32,
171        seconds: f64,
172    ) -> Result<DateTime, BoolError> {
173        unsafe {
174            Option::<_>::from_glib_full(ffi::g_date_time_new(
175                tz.to_glib_none().0,
176                year,
177                month,
178                day,
179                hour,
180                minute,
181                seconds,
182            ))
183            .ok_or_else(|| crate::bool_error!("Invalid date"))
184        }
185    }
186
187    /// Creates a #GDateTime corresponding to the given
188    /// [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601)
189    /// @text. ISO 8601 strings of the form `<date><sep><time><tz>` are supported, with
190    /// some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as
191    /// mentioned below.
192    ///
193    /// Note that as #GDateTime "is oblivious to leap seconds", leap seconds information
194    /// in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as
195    /// `23:59:59`.
196    ///
197    /// `<sep>` is the separator and can be either 'T', 't' or ' '. The latter two
198    /// separators are an extension from
199    /// [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6).
200    ///
201    /// `<date>` is in the form:
202    ///
203    /// - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24.
204    /// - `YYYYMMDD` - Same as above without dividers.
205    /// - `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237.
206    /// - `YYYYDDD` - Same as above without dividers.
207    /// - `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7,
208    ///   e.g. 2016-W34-3.
209    /// - `YYYYWwwD` - Same as above without dividers.
210    ///
211    /// `<time>` is in the form:
212    ///
213    /// - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
214    /// - `hhmmss(.sss)` - Same as above without dividers.
215    ///
216    /// `<tz>` is an optional timezone suffix of the form:
217    ///
218    /// - `Z` - UTC.
219    /// - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00.
220    /// - `+hh` or `-hh` - Offset from UTC in hours, e.g. +12.
221    ///
222    /// If the timezone is not provided in @text it must be provided in @default_tz
223    /// (this field is otherwise ignored).
224    ///
225    /// This call can fail (returning [`None`]) if @text is not a valid ISO 8601
226    /// formatted string.
227    ///
228    /// You should release the return value by calling g_date_time_unref()
229    /// when you are done with it.
230    /// ## `text`
231    /// an ISO 8601 formatted time string.
232    /// ## `default_tz`
233    /// a #GTimeZone to use if the text doesn't contain a
234    ///                          timezone, or [`None`].
235    ///
236    /// # Returns
237    ///
238    /// a new #GDateTime, or [`None`]
239    // rustdoc-stripper-ignore-next-stop
240    /// Creates a #GDateTime corresponding to the given
241    /// [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601)
242    /// @text. ISO 8601 strings of the form `<date><sep><time><tz>` are supported, with
243    /// some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as
244    /// mentioned below.
245    ///
246    /// Note that as #GDateTime "is oblivious to leap seconds", leap seconds information
247    /// in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as
248    /// `23:59:59`.
249    ///
250    /// `<sep>` is the separator and can be either 'T', 't' or ' '. The latter two
251    /// separators are an extension from
252    /// [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6).
253    ///
254    /// `<date>` is in the form:
255    ///
256    /// - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24.
257    /// - `YYYYMMDD` - Same as above without dividers.
258    /// - `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237.
259    /// - `YYYYDDD` - Same as above without dividers.
260    /// - `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7,
261    ///   e.g. 2016-W34-3.
262    /// - `YYYYWwwD` - Same as above without dividers.
263    ///
264    /// `<time>` is in the form:
265    ///
266    /// - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
267    /// - `hhmmss(.sss)` - Same as above without dividers.
268    ///
269    /// `<tz>` is an optional timezone suffix of the form:
270    ///
271    /// - `Z` - UTC.
272    /// - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00.
273    /// - `+hh` or `-hh` - Offset from UTC in hours, e.g. +12.
274    ///
275    /// If the timezone is not provided in @text it must be provided in @default_tz
276    /// (this field is otherwise ignored).
277    ///
278    /// This call can fail (returning [`None`]) if @text is not a valid ISO 8601
279    /// formatted string.
280    ///
281    /// You should release the return value by calling g_date_time_unref()
282    /// when you are done with it.
283    /// ## `text`
284    /// an ISO 8601 formatted time string.
285    /// ## `default_tz`
286    /// a #GTimeZone to use if the text doesn't contain a
287    ///                          timezone, or [`None`].
288    ///
289    /// # Returns
290    ///
291    /// a new #GDateTime, or [`None`]
292    #[doc(alias = "g_date_time_new_from_iso8601")]
293    #[doc(alias = "new_from_iso8601")]
294    pub fn from_iso8601(text: &str, default_tz: Option<&TimeZone>) -> Result<DateTime, BoolError> {
295        unsafe {
296            Option::<_>::from_glib_full(ffi::g_date_time_new_from_iso8601(
297                text.to_glib_none().0,
298                default_tz.to_glib_none().0,
299            ))
300            .ok_or_else(|| crate::bool_error!("Invalid date"))
301        }
302    }
303
304    //#[cfg_attr(feature = "v2_62", deprecated = "Since 2.62")]
305    //#[allow(deprecated)]
306    //#[doc(alias = "g_date_time_new_from_timeval_local")]
307    //#[doc(alias = "new_from_timeval_local")]
308    //pub fn from_timeval_local(tv: /*Ignored*/&TimeVal) -> Result<DateTime, BoolError> {
309    //    unsafe { TODO: call ffi:g_date_time_new_from_timeval_local() }
310    //}
311
312    //#[cfg_attr(feature = "v2_62", deprecated = "Since 2.62")]
313    //#[allow(deprecated)]
314    //#[doc(alias = "g_date_time_new_from_timeval_utc")]
315    //#[doc(alias = "new_from_timeval_utc")]
316    //pub fn from_timeval_utc(tv: /*Ignored*/&TimeVal) -> Result<DateTime, BoolError> {
317    //    unsafe { TODO: call ffi:g_date_time_new_from_timeval_utc() }
318    //}
319
320    /// Creates a #GDateTime corresponding to the given Unix time @t in the
321    /// local time zone.
322    ///
323    /// Unix time is the number of seconds that have elapsed since 1970-01-01
324    /// 00:00:00 UTC, regardless of the local time offset.
325    ///
326    /// This call can fail (returning [`None`]) if @t represents a time outside
327    /// of the supported range of #GDateTime.
328    ///
329    /// You should release the return value by calling g_date_time_unref()
330    /// when you are done with it.
331    /// ## `t`
332    /// the Unix time
333    ///
334    /// # Returns
335    ///
336    /// a new #GDateTime, or [`None`]
337    // rustdoc-stripper-ignore-next-stop
338    /// Creates a #GDateTime corresponding to the given Unix time @t in the
339    /// local time zone.
340    ///
341    /// Unix time is the number of seconds that have elapsed since 1970-01-01
342    /// 00:00:00 UTC, regardless of the local time offset.
343    ///
344    /// This call can fail (returning [`None`]) if @t represents a time outside
345    /// of the supported range of #GDateTime.
346    ///
347    /// You should release the return value by calling g_date_time_unref()
348    /// when you are done with it.
349    /// ## `t`
350    /// the Unix time
351    ///
352    /// # Returns
353    ///
354    /// a new #GDateTime, or [`None`]
355    #[doc(alias = "g_date_time_new_from_unix_local")]
356    #[doc(alias = "new_from_unix_local")]
357    pub fn from_unix_local(t: i64) -> Result<DateTime, BoolError> {
358        unsafe {
359            Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_local(t))
360                .ok_or_else(|| crate::bool_error!("Invalid date"))
361        }
362    }
363
364    /// Creates a [`DateTime`][crate::DateTime] corresponding to the given Unix time @t in the
365    /// local time zone.
366    ///
367    /// Unix time is the number of microseconds that have elapsed since 1970-01-01
368    /// 00:00:00 UTC, regardless of the local time offset.
369    ///
370    /// This call can fail (returning `NULL`) if @t represents a time outside
371    /// of the supported range of #GDateTime.
372    ///
373    /// You should release the return value by calling `GLib::DateTime::unref()`
374    /// when you are done with it.
375    /// ## `usecs`
376    /// the Unix time in microseconds
377    ///
378    /// # Returns
379    ///
380    /// a new [`DateTime`][crate::DateTime], or `NULL`
381    // rustdoc-stripper-ignore-next-stop
382    /// Creates a [`DateTime`][crate::DateTime] corresponding to the given Unix time @t in the
383    /// local time zone.
384    ///
385    /// Unix time is the number of microseconds that have elapsed since 1970-01-01
386    /// 00:00:00 UTC, regardless of the local time offset.
387    ///
388    /// This call can fail (returning `NULL`) if @t represents a time outside
389    /// of the supported range of #GDateTime.
390    ///
391    /// You should release the return value by calling `GLib::DateTime::unref()`
392    /// when you are done with it.
393    /// ## `usecs`
394    /// the Unix time in microseconds
395    ///
396    /// # Returns
397    ///
398    /// a new [`DateTime`][crate::DateTime], or `NULL`
399    #[cfg(feature = "v2_80")]
400    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
401    #[doc(alias = "g_date_time_new_from_unix_local_usec")]
402    #[doc(alias = "new_from_unix_local_usec")]
403    pub fn from_unix_local_usec(usecs: i64) -> Result<DateTime, BoolError> {
404        unsafe {
405            Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_local_usec(usecs))
406                .ok_or_else(|| crate::bool_error!("Invalid date"))
407        }
408    }
409
410    /// Creates a #GDateTime corresponding to the given Unix time @t in UTC.
411    ///
412    /// Unix time is the number of seconds that have elapsed since 1970-01-01
413    /// 00:00:00 UTC.
414    ///
415    /// This call can fail (returning [`None`]) if @t represents a time outside
416    /// of the supported range of #GDateTime.
417    ///
418    /// You should release the return value by calling g_date_time_unref()
419    /// when you are done with it.
420    /// ## `t`
421    /// the Unix time
422    ///
423    /// # Returns
424    ///
425    /// a new #GDateTime, or [`None`]
426    // rustdoc-stripper-ignore-next-stop
427    /// Creates a #GDateTime corresponding to the given Unix time @t in UTC.
428    ///
429    /// Unix time is the number of seconds that have elapsed since 1970-01-01
430    /// 00:00:00 UTC.
431    ///
432    /// This call can fail (returning [`None`]) if @t represents a time outside
433    /// of the supported range of #GDateTime.
434    ///
435    /// You should release the return value by calling g_date_time_unref()
436    /// when you are done with it.
437    /// ## `t`
438    /// the Unix time
439    ///
440    /// # Returns
441    ///
442    /// a new #GDateTime, or [`None`]
443    #[doc(alias = "g_date_time_new_from_unix_utc")]
444    #[doc(alias = "new_from_unix_utc")]
445    pub fn from_unix_utc(t: i64) -> Result<DateTime, BoolError> {
446        unsafe {
447            Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_utc(t))
448                .ok_or_else(|| crate::bool_error!("Invalid date"))
449        }
450    }
451
452    /// Creates a [`DateTime`][crate::DateTime] corresponding to the given Unix time @t in UTC.
453    ///
454    /// Unix time is the number of microseconds that have elapsed since 1970-01-01
455    /// 00:00:00 UTC.
456    ///
457    /// This call can fail (returning `NULL`) if @t represents a time outside
458    /// of the supported range of #GDateTime.
459    ///
460    /// You should release the return value by calling `GLib::DateTime::unref()`
461    /// when you are done with it.
462    /// ## `usecs`
463    /// the Unix time in microseconds
464    ///
465    /// # Returns
466    ///
467    /// a new [`DateTime`][crate::DateTime], or `NULL`
468    // rustdoc-stripper-ignore-next-stop
469    /// Creates a [`DateTime`][crate::DateTime] corresponding to the given Unix time @t in UTC.
470    ///
471    /// Unix time is the number of microseconds that have elapsed since 1970-01-01
472    /// 00:00:00 UTC.
473    ///
474    /// This call can fail (returning `NULL`) if @t represents a time outside
475    /// of the supported range of #GDateTime.
476    ///
477    /// You should release the return value by calling `GLib::DateTime::unref()`
478    /// when you are done with it.
479    /// ## `usecs`
480    /// the Unix time in microseconds
481    ///
482    /// # Returns
483    ///
484    /// a new [`DateTime`][crate::DateTime], or `NULL`
485    #[cfg(feature = "v2_80")]
486    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
487    #[doc(alias = "g_date_time_new_from_unix_utc_usec")]
488    #[doc(alias = "new_from_unix_utc_usec")]
489    pub fn from_unix_utc_usec(usecs: i64) -> Result<DateTime, BoolError> {
490        unsafe {
491            Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_utc_usec(usecs))
492                .ok_or_else(|| crate::bool_error!("Invalid date"))
493        }
494    }
495
496    /// Creates a new #GDateTime corresponding to the given date and time in
497    /// the local time zone.
498    ///
499    /// This call is equivalent to calling g_date_time_new() with the time
500    /// zone returned by g_time_zone_new_local().
501    /// ## `year`
502    /// the year component of the date
503    /// ## `month`
504    /// the month component of the date
505    /// ## `day`
506    /// the day component of the date
507    /// ## `hour`
508    /// the hour component of the date
509    /// ## `minute`
510    /// the minute component of the date
511    /// ## `seconds`
512    /// the number of seconds past the minute
513    ///
514    /// # Returns
515    ///
516    /// a #GDateTime, or [`None`]
517    // rustdoc-stripper-ignore-next-stop
518    /// Creates a new #GDateTime corresponding to the given date and time in
519    /// the local time zone.
520    ///
521    /// This call is equivalent to calling g_date_time_new() with the time
522    /// zone returned by g_time_zone_new_local().
523    /// ## `year`
524    /// the year component of the date
525    /// ## `month`
526    /// the month component of the date
527    /// ## `day`
528    /// the day component of the date
529    /// ## `hour`
530    /// the hour component of the date
531    /// ## `minute`
532    /// the minute component of the date
533    /// ## `seconds`
534    /// the number of seconds past the minute
535    ///
536    /// # Returns
537    ///
538    /// a #GDateTime, or [`None`]
539    #[doc(alias = "g_date_time_new_local")]
540    #[doc(alias = "new_local")]
541    pub fn from_local(
542        year: i32,
543        month: i32,
544        day: i32,
545        hour: i32,
546        minute: i32,
547        seconds: f64,
548    ) -> Result<DateTime, BoolError> {
549        unsafe {
550            Option::<_>::from_glib_full(ffi::g_date_time_new_local(
551                year, month, day, hour, minute, seconds,
552            ))
553            .ok_or_else(|| crate::bool_error!("Invalid date"))
554        }
555    }
556
557    /// Creates a #GDateTime corresponding to this exact instant in the given
558    /// time zone @tz.  The time is as accurate as the system allows, to a
559    /// maximum accuracy of 1 microsecond.
560    ///
561    /// This function will always succeed unless GLib is still being used after the
562    /// year 9999.
563    ///
564    /// You should release the return value by calling g_date_time_unref()
565    /// when you are done with it.
566    /// ## `tz`
567    /// a #GTimeZone
568    ///
569    /// # Returns
570    ///
571    /// a new #GDateTime, or [`None`]
572    // rustdoc-stripper-ignore-next-stop
573    /// Creates a #GDateTime corresponding to this exact instant in the given
574    /// time zone @tz.  The time is as accurate as the system allows, to a
575    /// maximum accuracy of 1 microsecond.
576    ///
577    /// This function will always succeed unless GLib is still being used after the
578    /// year 9999.
579    ///
580    /// You should release the return value by calling g_date_time_unref()
581    /// when you are done with it.
582    /// ## `tz`
583    /// a #GTimeZone
584    ///
585    /// # Returns
586    ///
587    /// a new #GDateTime, or [`None`]
588    #[doc(alias = "g_date_time_new_now")]
589    #[doc(alias = "new_now")]
590    pub fn now(tz: &TimeZone) -> Result<DateTime, BoolError> {
591        unsafe {
592            Option::<_>::from_glib_full(ffi::g_date_time_new_now(tz.to_glib_none().0))
593                .ok_or_else(|| crate::bool_error!("Invalid date"))
594        }
595    }
596
597    /// Creates a #GDateTime corresponding to this exact instant in the local
598    /// time zone.
599    ///
600    /// This is equivalent to calling g_date_time_new_now() with the time
601    /// zone returned by g_time_zone_new_local().
602    ///
603    /// # Returns
604    ///
605    /// a new #GDateTime, or [`None`]
606    // rustdoc-stripper-ignore-next-stop
607    /// Creates a #GDateTime corresponding to this exact instant in the local
608    /// time zone.
609    ///
610    /// This is equivalent to calling g_date_time_new_now() with the time
611    /// zone returned by g_time_zone_new_local().
612    ///
613    /// # Returns
614    ///
615    /// a new #GDateTime, or [`None`]
616    #[doc(alias = "g_date_time_new_now_local")]
617    #[doc(alias = "new_now_local")]
618    pub fn now_local() -> Result<DateTime, BoolError> {
619        unsafe {
620            Option::<_>::from_glib_full(ffi::g_date_time_new_now_local())
621                .ok_or_else(|| crate::bool_error!("Invalid date"))
622        }
623    }
624
625    /// Creates a #GDateTime corresponding to this exact instant in UTC.
626    ///
627    /// This is equivalent to calling g_date_time_new_now() with the time
628    /// zone returned by g_time_zone_new_utc().
629    ///
630    /// # Returns
631    ///
632    /// a new #GDateTime, or [`None`]
633    // rustdoc-stripper-ignore-next-stop
634    /// Creates a #GDateTime corresponding to this exact instant in UTC.
635    ///
636    /// This is equivalent to calling g_date_time_new_now() with the time
637    /// zone returned by g_time_zone_new_utc().
638    ///
639    /// # Returns
640    ///
641    /// a new #GDateTime, or [`None`]
642    #[doc(alias = "g_date_time_new_now_utc")]
643    #[doc(alias = "new_now_utc")]
644    pub fn now_utc() -> Result<DateTime, BoolError> {
645        unsafe {
646            Option::<_>::from_glib_full(ffi::g_date_time_new_now_utc())
647                .ok_or_else(|| crate::bool_error!("Invalid date"))
648        }
649    }
650
651    /// Creates a new #GDateTime corresponding to the given date and time in
652    /// UTC.
653    ///
654    /// This call is equivalent to calling g_date_time_new() with the time
655    /// zone returned by g_time_zone_new_utc().
656    /// ## `year`
657    /// the year component of the date
658    /// ## `month`
659    /// the month component of the date
660    /// ## `day`
661    /// the day component of the date
662    /// ## `hour`
663    /// the hour component of the date
664    /// ## `minute`
665    /// the minute component of the date
666    /// ## `seconds`
667    /// the number of seconds past the minute
668    ///
669    /// # Returns
670    ///
671    /// a #GDateTime, or [`None`]
672    // rustdoc-stripper-ignore-next-stop
673    /// Creates a new #GDateTime corresponding to the given date and time in
674    /// UTC.
675    ///
676    /// This call is equivalent to calling g_date_time_new() with the time
677    /// zone returned by g_time_zone_new_utc().
678    /// ## `year`
679    /// the year component of the date
680    /// ## `month`
681    /// the month component of the date
682    /// ## `day`
683    /// the day component of the date
684    /// ## `hour`
685    /// the hour component of the date
686    /// ## `minute`
687    /// the minute component of the date
688    /// ## `seconds`
689    /// the number of seconds past the minute
690    ///
691    /// # Returns
692    ///
693    /// a #GDateTime, or [`None`]
694    #[doc(alias = "g_date_time_new_utc")]
695    #[doc(alias = "new_utc")]
696    pub fn from_utc(
697        year: i32,
698        month: i32,
699        day: i32,
700        hour: i32,
701        minute: i32,
702        seconds: f64,
703    ) -> Result<DateTime, BoolError> {
704        unsafe {
705            Option::<_>::from_glib_full(ffi::g_date_time_new_utc(
706                year, month, day, hour, minute, seconds,
707            ))
708            .ok_or_else(|| crate::bool_error!("Invalid date"))
709        }
710    }
711
712    /// Creates a copy of @self and adds the specified timespan to the copy.
713    /// ## `timespan`
714    /// a #GTimeSpan
715    ///
716    /// # Returns
717    ///
718    /// the newly created #GDateTime which
719    ///   should be freed with g_date_time_unref(), or [`None`]
720    // rustdoc-stripper-ignore-next-stop
721    /// Creates a copy of @self and adds the specified timespan to the copy.
722    /// ## `timespan`
723    /// a #GTimeSpan
724    ///
725    /// # Returns
726    ///
727    /// the newly created #GDateTime which
728    ///   should be freed with g_date_time_unref(), or [`None`]
729    #[doc(alias = "g_date_time_add")]
730    pub fn add(&self, timespan: TimeSpan) -> Result<DateTime, BoolError> {
731        unsafe {
732            Option::<_>::from_glib_full(ffi::g_date_time_add(
733                self.to_glib_none().0,
734                timespan.into_glib(),
735            ))
736            .ok_or_else(|| crate::bool_error!("Invalid date"))
737        }
738    }
739
740    /// Creates a copy of @self and adds the specified number of days to the
741    /// copy. Add negative values to subtract days.
742    /// ## `days`
743    /// the number of days
744    ///
745    /// # Returns
746    ///
747    /// the newly created #GDateTime which
748    ///   should be freed with g_date_time_unref(), or [`None`]
749    // rustdoc-stripper-ignore-next-stop
750    /// Creates a copy of @self and adds the specified number of days to the
751    /// copy. Add negative values to subtract days.
752    /// ## `days`
753    /// the number of days
754    ///
755    /// # Returns
756    ///
757    /// the newly created #GDateTime which
758    ///   should be freed with g_date_time_unref(), or [`None`]
759    #[doc(alias = "g_date_time_add_days")]
760    pub fn add_days(&self, days: i32) -> Result<DateTime, BoolError> {
761        unsafe {
762            Option::<_>::from_glib_full(ffi::g_date_time_add_days(self.to_glib_none().0, days))
763                .ok_or_else(|| crate::bool_error!("Invalid date"))
764        }
765    }
766
767    /// Creates a new #GDateTime adding the specified values to the current date and
768    /// time in @self. Add negative values to subtract.
769    /// ## `years`
770    /// the number of years to add
771    /// ## `months`
772    /// the number of months to add
773    /// ## `days`
774    /// the number of days to add
775    /// ## `hours`
776    /// the number of hours to add
777    /// ## `minutes`
778    /// the number of minutes to add
779    /// ## `seconds`
780    /// the number of seconds to add
781    ///
782    /// # Returns
783    ///
784    /// the newly created #GDateTime which
785    ///   should be freed with g_date_time_unref(), or [`None`]
786    // rustdoc-stripper-ignore-next-stop
787    /// Creates a new #GDateTime adding the specified values to the current date and
788    /// time in @self. Add negative values to subtract.
789    /// ## `years`
790    /// the number of years to add
791    /// ## `months`
792    /// the number of months to add
793    /// ## `days`
794    /// the number of days to add
795    /// ## `hours`
796    /// the number of hours to add
797    /// ## `minutes`
798    /// the number of minutes to add
799    /// ## `seconds`
800    /// the number of seconds to add
801    ///
802    /// # Returns
803    ///
804    /// the newly created #GDateTime which
805    ///   should be freed with g_date_time_unref(), or [`None`]
806    #[doc(alias = "g_date_time_add_full")]
807    pub fn add_full(
808        &self,
809        years: i32,
810        months: i32,
811        days: i32,
812        hours: i32,
813        minutes: i32,
814        seconds: f64,
815    ) -> Result<DateTime, BoolError> {
816        unsafe {
817            Option::<_>::from_glib_full(ffi::g_date_time_add_full(
818                self.to_glib_none().0,
819                years,
820                months,
821                days,
822                hours,
823                minutes,
824                seconds,
825            ))
826            .ok_or_else(|| crate::bool_error!("Invalid date"))
827        }
828    }
829
830    /// Creates a copy of @self and adds the specified number of hours.
831    /// Add negative values to subtract hours.
832    /// ## `hours`
833    /// the number of hours to add
834    ///
835    /// # Returns
836    ///
837    /// the newly created #GDateTime which
838    ///   should be freed with g_date_time_unref(), or [`None`]
839    // rustdoc-stripper-ignore-next-stop
840    /// Creates a copy of @self and adds the specified number of hours.
841    /// Add negative values to subtract hours.
842    /// ## `hours`
843    /// the number of hours to add
844    ///
845    /// # Returns
846    ///
847    /// the newly created #GDateTime which
848    ///   should be freed with g_date_time_unref(), or [`None`]
849    #[doc(alias = "g_date_time_add_hours")]
850    pub fn add_hours(&self, hours: i32) -> Result<DateTime, BoolError> {
851        unsafe {
852            Option::<_>::from_glib_full(ffi::g_date_time_add_hours(self.to_glib_none().0, hours))
853                .ok_or_else(|| crate::bool_error!("Invalid date"))
854        }
855    }
856
857    /// Creates a copy of @self adding the specified number of minutes.
858    /// Add negative values to subtract minutes.
859    /// ## `minutes`
860    /// the number of minutes to add
861    ///
862    /// # Returns
863    ///
864    /// the newly created #GDateTime which
865    ///   should be freed with g_date_time_unref(), or [`None`]
866    // rustdoc-stripper-ignore-next-stop
867    /// Creates a copy of @self adding the specified number of minutes.
868    /// Add negative values to subtract minutes.
869    /// ## `minutes`
870    /// the number of minutes to add
871    ///
872    /// # Returns
873    ///
874    /// the newly created #GDateTime which
875    ///   should be freed with g_date_time_unref(), or [`None`]
876    #[doc(alias = "g_date_time_add_minutes")]
877    pub fn add_minutes(&self, minutes: i32) -> Result<DateTime, BoolError> {
878        unsafe {
879            Option::<_>::from_glib_full(ffi::g_date_time_add_minutes(
880                self.to_glib_none().0,
881                minutes,
882            ))
883            .ok_or_else(|| crate::bool_error!("Invalid date"))
884        }
885    }
886
887    /// Creates a copy of @self and adds the specified number of months to the
888    /// copy. Add negative values to subtract months.
889    ///
890    /// The day of the month of the resulting #GDateTime is clamped to the number
891    /// of days in the updated calendar month. For example, if adding 1 month to
892    /// 31st January 2018, the result would be 28th February 2018. In 2020 (a leap
893    /// year), the result would be 29th February.
894    /// ## `months`
895    /// the number of months
896    ///
897    /// # Returns
898    ///
899    /// the newly created #GDateTime which
900    ///   should be freed with g_date_time_unref(), or [`None`]
901    // rustdoc-stripper-ignore-next-stop
902    /// Creates a copy of @self and adds the specified number of months to the
903    /// copy. Add negative values to subtract months.
904    ///
905    /// The day of the month of the resulting #GDateTime is clamped to the number
906    /// of days in the updated calendar month. For example, if adding 1 month to
907    /// 31st January 2018, the result would be 28th February 2018. In 2020 (a leap
908    /// year), the result would be 29th February.
909    /// ## `months`
910    /// the number of months
911    ///
912    /// # Returns
913    ///
914    /// the newly created #GDateTime which
915    ///   should be freed with g_date_time_unref(), or [`None`]
916    #[doc(alias = "g_date_time_add_months")]
917    pub fn add_months(&self, months: i32) -> Result<DateTime, BoolError> {
918        unsafe {
919            Option::<_>::from_glib_full(ffi::g_date_time_add_months(self.to_glib_none().0, months))
920                .ok_or_else(|| crate::bool_error!("Invalid date"))
921        }
922    }
923
924    /// Creates a copy of @self and adds the specified number of seconds.
925    /// Add negative values to subtract seconds.
926    /// ## `seconds`
927    /// the number of seconds to add
928    ///
929    /// # Returns
930    ///
931    /// the newly created #GDateTime which
932    ///   should be freed with g_date_time_unref(), or [`None`]
933    // rustdoc-stripper-ignore-next-stop
934    /// Creates a copy of @self and adds the specified number of seconds.
935    /// Add negative values to subtract seconds.
936    /// ## `seconds`
937    /// the number of seconds to add
938    ///
939    /// # Returns
940    ///
941    /// the newly created #GDateTime which
942    ///   should be freed with g_date_time_unref(), or [`None`]
943    #[doc(alias = "g_date_time_add_seconds")]
944    pub fn add_seconds(&self, seconds: f64) -> Result<DateTime, BoolError> {
945        unsafe {
946            Option::<_>::from_glib_full(ffi::g_date_time_add_seconds(
947                self.to_glib_none().0,
948                seconds,
949            ))
950            .ok_or_else(|| crate::bool_error!("Invalid date"))
951        }
952    }
953
954    /// Creates a copy of @self and adds the specified number of weeks to the
955    /// copy. Add negative values to subtract weeks.
956    /// ## `weeks`
957    /// the number of weeks
958    ///
959    /// # Returns
960    ///
961    /// the newly created #GDateTime which
962    ///   should be freed with g_date_time_unref(), or [`None`]
963    // rustdoc-stripper-ignore-next-stop
964    /// Creates a copy of @self and adds the specified number of weeks to the
965    /// copy. Add negative values to subtract weeks.
966    /// ## `weeks`
967    /// the number of weeks
968    ///
969    /// # Returns
970    ///
971    /// the newly created #GDateTime which
972    ///   should be freed with g_date_time_unref(), or [`None`]
973    #[doc(alias = "g_date_time_add_weeks")]
974    pub fn add_weeks(&self, weeks: i32) -> Result<DateTime, BoolError> {
975        unsafe {
976            Option::<_>::from_glib_full(ffi::g_date_time_add_weeks(self.to_glib_none().0, weeks))
977                .ok_or_else(|| crate::bool_error!("Invalid date"))
978        }
979    }
980
981    /// Creates a copy of @self and adds the specified number of years to the
982    /// copy. Add negative values to subtract years.
983    ///
984    /// As with g_date_time_add_months(), if the resulting date would be 29th
985    /// February on a non-leap year, the day will be clamped to 28th February.
986    /// ## `years`
987    /// the number of years
988    ///
989    /// # Returns
990    ///
991    /// the newly created #GDateTime which
992    ///   should be freed with g_date_time_unref(), or [`None`]
993    // rustdoc-stripper-ignore-next-stop
994    /// Creates a copy of @self and adds the specified number of years to the
995    /// copy. Add negative values to subtract years.
996    ///
997    /// As with g_date_time_add_months(), if the resulting date would be 29th
998    /// February on a non-leap year, the day will be clamped to 28th February.
999    /// ## `years`
1000    /// the number of years
1001    ///
1002    /// # Returns
1003    ///
1004    /// the newly created #GDateTime which
1005    ///   should be freed with g_date_time_unref(), or [`None`]
1006    #[doc(alias = "g_date_time_add_years")]
1007    pub fn add_years(&self, years: i32) -> Result<DateTime, BoolError> {
1008        unsafe {
1009            Option::<_>::from_glib_full(ffi::g_date_time_add_years(self.to_glib_none().0, years))
1010                .ok_or_else(|| crate::bool_error!("Invalid date"))
1011        }
1012    }
1013
1014    #[doc(alias = "g_date_time_compare")]
1015    fn compare(&self, dt2: &DateTime) -> i32 {
1016        unsafe {
1017            ffi::g_date_time_compare(
1018                ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(self).0 as ffi::gconstpointer,
1019                ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(dt2).0 as ffi::gconstpointer,
1020            )
1021        }
1022    }
1023
1024    /// Calculates the difference in time between @self and @begin.  The
1025    /// #GTimeSpan that is returned is effectively @self - @begin (ie:
1026    /// positive if the first parameter is larger).
1027    /// ## `begin`
1028    /// a #GDateTime
1029    ///
1030    /// # Returns
1031    ///
1032    /// the difference between the two #GDateTime, as a time
1033    ///   span expressed in microseconds.
1034    // rustdoc-stripper-ignore-next-stop
1035    /// Calculates the difference in time between @self and @begin.  The
1036    /// #GTimeSpan that is returned is effectively @self - @begin (ie:
1037    /// positive if the first parameter is larger).
1038    /// ## `begin`
1039    /// a #GDateTime
1040    ///
1041    /// # Returns
1042    ///
1043    /// the difference between the two #GDateTime, as a time
1044    ///   span expressed in microseconds.
1045    #[doc(alias = "g_date_time_difference")]
1046    pub fn difference(&self, begin: &DateTime) -> TimeSpan {
1047        unsafe {
1048            from_glib(ffi::g_date_time_difference(
1049                self.to_glib_none().0,
1050                begin.to_glib_none().0,
1051            ))
1052        }
1053    }
1054
1055    #[doc(alias = "g_date_time_equal")]
1056    fn equal(&self, dt2: &DateTime) -> bool {
1057        unsafe {
1058            from_glib(ffi::g_date_time_equal(
1059                ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(self).0 as ffi::gconstpointer,
1060                ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(dt2).0 as ffi::gconstpointer,
1061            ))
1062        }
1063    }
1064
1065    /// Creates a newly allocated string representing the requested @format.
1066    ///
1067    /// The format strings understood by this function are a subset of the
1068    /// `strftime()` format language as specified by C99.  The ``D``, ``U`` and ``W``
1069    /// conversions are not supported, nor is the `E` modifier.  The GNU
1070    /// extensions ``k``, ``l``, ``s`` and ``P`` are supported, however, as are the
1071    /// `0`, `_` and `-` modifiers. The Python extension ``f`` is also supported.
1072    ///
1073    /// In contrast to `strftime()`, this function always produces a UTF-8
1074    /// string, regardless of the current locale.  Note that the rendering of
1075    /// many formats is locale-dependent and may not match the `strftime()`
1076    /// output exactly.
1077    ///
1078    /// The following format specifiers are supported:
1079    ///
1080    /// - ``a``: the abbreviated weekday name according to the current locale
1081    /// - ``A``: the full weekday name according to the current locale
1082    /// - ``b``: the abbreviated month name according to the current locale
1083    /// - ``B``: the full month name according to the current locale
1084    /// - ``c``: the preferred date and time representation for the current locale
1085    /// - ``C``: the century number (year/100) as a 2-digit integer (00-99)
1086    /// - ``d``: the day of the month as a decimal number (range 01 to 31)
1087    /// - ``e``: the day of the month as a decimal number (range 1 to 31);
1088    ///   single digits are preceded by a figure space (U+2007)
1089    /// - ``F``: equivalent to ``Y`-`m`-`d`` (the ISO 8601 date format)
1090    /// - ``g``: the last two digits of the ISO 8601 week-based year as a
1091    ///   decimal number (00-99). This works well with ``V`` and ``u``.
1092    /// - ``G``: the ISO 8601 week-based year as a decimal number. This works
1093    ///   well with ``V`` and ``u``.
1094    /// - ``h``: equivalent to ``b``
1095    /// - ``H``: the hour as a decimal number using a 24-hour clock (range 00 to 23)
1096    /// - ``I``: the hour as a decimal number using a 12-hour clock (range 01 to 12)
1097    /// - ``j``: the day of the year as a decimal number (range 001 to 366)
1098    /// - ``k``: the hour (24-hour clock) as a decimal number (range 0 to 23);
1099    ///   single digits are preceded by a figure space (U+2007)
1100    /// - ``l``: the hour (12-hour clock) as a decimal number (range 1 to 12);
1101    ///   single digits are preceded by a figure space (U+2007)
1102    /// - ``m``: the month as a decimal number (range 01 to 12)
1103    /// - ``M``: the minute as a decimal number (range 00 to 59)
1104    /// - ``f``: the microsecond as a decimal number (range 000000 to 999999)
1105    /// - ``p``: either ‘AM’ or ‘PM’ according to the given time value, or the
1106    ///   corresponding  strings for the current locale.  Noon is treated as
1107    ///   ‘PM’ and midnight as ‘AM’. Use of this format specifier is discouraged, as
1108    ///   many locales have no concept of AM/PM formatting. Use ``c`` or ``X`` instead.
1109    /// - ``P``: like ``p`` but lowercase: ‘am’ or ‘pm’ or a corresponding string for
1110    ///   the current locale. Use of this format specifier is discouraged, as
1111    ///   many locales have no concept of AM/PM formatting. Use ``c`` or ``X`` instead.
1112    /// - ``r``: the time in a.m. or p.m. notation. Use of this format specifier is
1113    ///   discouraged, as many locales have no concept of AM/PM formatting. Use ``c``
1114    ///   or ``X`` instead.
1115    /// - ``R``: the time in 24-hour notation (``H`:`M``)
1116    /// - ``s``: the number of seconds since the Epoch, that is, since 1970-01-01
1117    ///   00:00:00 UTC
1118    /// - ``S``: the second as a decimal number (range 00 to 60)
1119    /// - ``t``: a tab character
1120    /// - ``T``: the time in 24-hour notation with seconds (``H`:`M`:`S``)
1121    /// - ``u``: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
1122    ///    Monday being 1. This works well with ``G`` and ``V``.
1123    /// - ``V``: the ISO 8601 standard week number of the current year as a decimal
1124    ///   number, range 01 to 53, where week 1 is the first week that has at
1125    ///   least 4 days in the new year. See g_date_time_get_week_of_year().
1126    ///   This works well with ``G`` and ``u``.
1127    /// - ``w``: the day of the week as a decimal, range 0 to 6, Sunday being 0.
1128    ///   This is not the ISO 8601 standard format — use ``u`` instead.
1129    /// - ``x``: the preferred date representation for the current locale without
1130    ///   the time
1131    /// - ``X``: the preferred time representation for the current locale without
1132    ///   the date
1133    /// - ``y``: the year as a decimal number without the century
1134    /// - ``Y``: the year as a decimal number including the century
1135    /// - ``z``: the time zone as an offset from UTC (`+hhmm`)
1136    /// - `%:z`: the time zone as an offset from UTC (`+hh:mm`).
1137    ///   This is a gnulib `strftime()` extension. Since: 2.38
1138    /// - `%::z`: the time zone as an offset from UTC (`+hh:mm:ss`). This is a
1139    ///   gnulib `strftime()` extension. Since: 2.38
1140    /// - `%:::z`: the time zone as an offset from UTC, with `:` to necessary
1141    ///   precision (e.g., `-04`, `+05:30`). This is a gnulib `strftime()` extension. Since: 2.38
1142    /// - ``Z``: the time zone or name or abbreviation
1143    /// - `%%`: a literal `%` character
1144    ///
1145    /// Some conversion specifications can be modified by preceding the
1146    /// conversion specifier by one or more modifier characters.
1147    ///
1148    /// The following modifiers are supported for many of the numeric
1149    /// conversions:
1150    ///
1151    /// - `O`: Use alternative numeric symbols, if the current locale supports those.
1152    /// - `_`: Pad a numeric result with spaces. This overrides the default padding
1153    ///   for the specifier.
1154    /// - `-`: Do not pad a numeric result. This overrides the default padding
1155    ///   for the specifier.
1156    /// - `0`: Pad a numeric result with zeros. This overrides the default padding
1157    ///   for the specifier.
1158    ///
1159    /// The following modifiers are supported for many of the alphabetic conversions:
1160    ///
1161    /// - `^`: Use upper case if possible. This is a gnulib `strftime()` extension.
1162    ///   Since: 2.80
1163    /// - `#`: Use opposite case if possible. This is a gnulib `strftime()`
1164    ///   extension. Since: 2.80
1165    ///
1166    /// Additionally, when `O` is used with `B`, `b`, or `h`, it produces the alternative
1167    /// form of a month name. The alternative form should be used when the month
1168    /// name is used without a day number (e.g., standalone). It is required in
1169    /// some languages (Baltic, Slavic, Greek, and more) due to their grammatical
1170    /// rules. For other languages there is no difference. ``OB`` is a GNU and BSD
1171    /// `strftime()` extension expected to be added to the future POSIX specification,
1172    /// ``Ob`` and ``Oh`` are GNU `strftime()` extensions. Since: 2.56
1173    ///
1174    /// Since GLib 2.80, when `E` is used with ``c``, ``C``, ``x``, ``X``, ``y`` or ``Y``,
1175    /// the date is formatted using an alternate era representation specific to the
1176    /// locale. This is typically used for the Thai solar calendar or Japanese era
1177    /// names, for example.
1178    ///
1179    /// - ``Ec``: the preferred date and time representation for the current locale,
1180    ///   using the alternate era representation
1181    /// - ``EC``: the name of the era
1182    /// - ``Ex``: the preferred date representation for the current locale without
1183    ///   the time, using the alternate era representation
1184    /// - ``EX``: the preferred time representation for the current locale without
1185    ///   the date, using the alternate era representation
1186    /// - ``Ey``: the year since the beginning of the era denoted by the ``EC``
1187    ///   specifier
1188    /// - ``EY``: the full alternative year representation
1189    /// ## `format`
1190    /// a valid UTF-8 string, containing the format for the
1191    ///          #GDateTime
1192    ///
1193    /// # Returns
1194    ///
1195    /// a newly allocated string formatted to
1196    ///    the requested format or [`None`] in the case that there was an error (such
1197    ///    as a format specifier not being supported in the current locale). The
1198    ///    string should be freed with g_free().
1199    // rustdoc-stripper-ignore-next-stop
1200    /// Creates a newly allocated string representing the requested @format.
1201    ///
1202    /// The format strings understood by this function are a subset of the
1203    /// `strftime()` format language as specified by C99.  The ``D``, ``U`` and ``W``
1204    /// conversions are not supported, nor is the `E` modifier.  The GNU
1205    /// extensions ``k``, ``l``, ``s`` and ``P`` are supported, however, as are the
1206    /// `0`, `_` and `-` modifiers. The Python extension ``f`` is also supported.
1207    ///
1208    /// In contrast to `strftime()`, this function always produces a UTF-8
1209    /// string, regardless of the current locale.  Note that the rendering of
1210    /// many formats is locale-dependent and may not match the `strftime()`
1211    /// output exactly.
1212    ///
1213    /// The following format specifiers are supported:
1214    ///
1215    /// - ``a``: the abbreviated weekday name according to the current locale
1216    /// - ``A``: the full weekday name according to the current locale
1217    /// - ``b``: the abbreviated month name according to the current locale
1218    /// - ``B``: the full month name according to the current locale
1219    /// - ``c``: the preferred date and time representation for the current locale
1220    /// - ``C``: the century number (year/100) as a 2-digit integer (00-99)
1221    /// - ``d``: the day of the month as a decimal number (range 01 to 31)
1222    /// - ``e``: the day of the month as a decimal number (range 1 to 31);
1223    ///   single digits are preceded by a figure space (U+2007)
1224    /// - ``F``: equivalent to ``Y`-`m`-`d`` (the ISO 8601 date format)
1225    /// - ``g``: the last two digits of the ISO 8601 week-based year as a
1226    ///   decimal number (00-99). This works well with ``V`` and ``u``.
1227    /// - ``G``: the ISO 8601 week-based year as a decimal number. This works
1228    ///   well with ``V`` and ``u``.
1229    /// - ``h``: equivalent to ``b``
1230    /// - ``H``: the hour as a decimal number using a 24-hour clock (range 00 to 23)
1231    /// - ``I``: the hour as a decimal number using a 12-hour clock (range 01 to 12)
1232    /// - ``j``: the day of the year as a decimal number (range 001 to 366)
1233    /// - ``k``: the hour (24-hour clock) as a decimal number (range 0 to 23);
1234    ///   single digits are preceded by a figure space (U+2007)
1235    /// - ``l``: the hour (12-hour clock) as a decimal number (range 1 to 12);
1236    ///   single digits are preceded by a figure space (U+2007)
1237    /// - ``m``: the month as a decimal number (range 01 to 12)
1238    /// - ``M``: the minute as a decimal number (range 00 to 59)
1239    /// - ``f``: the microsecond as a decimal number (range 000000 to 999999)
1240    /// - ``p``: either ‘AM’ or ‘PM’ according to the given time value, or the
1241    ///   corresponding  strings for the current locale.  Noon is treated as
1242    ///   ‘PM’ and midnight as ‘AM’. Use of this format specifier is discouraged, as
1243    ///   many locales have no concept of AM/PM formatting. Use ``c`` or ``X`` instead.
1244    /// - ``P``: like ``p`` but lowercase: ‘am’ or ‘pm’ or a corresponding string for
1245    ///   the current locale. Use of this format specifier is discouraged, as
1246    ///   many locales have no concept of AM/PM formatting. Use ``c`` or ``X`` instead.
1247    /// - ``r``: the time in a.m. or p.m. notation. Use of this format specifier is
1248    ///   discouraged, as many locales have no concept of AM/PM formatting. Use ``c``
1249    ///   or ``X`` instead.
1250    /// - ``R``: the time in 24-hour notation (``H`:`M``)
1251    /// - ``s``: the number of seconds since the Epoch, that is, since 1970-01-01
1252    ///   00:00:00 UTC
1253    /// - ``S``: the second as a decimal number (range 00 to 60)
1254    /// - ``t``: a tab character
1255    /// - ``T``: the time in 24-hour notation with seconds (``H`:`M`:`S``)
1256    /// - ``u``: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
1257    ///    Monday being 1. This works well with ``G`` and ``V``.
1258    /// - ``V``: the ISO 8601 standard week number of the current year as a decimal
1259    ///   number, range 01 to 53, where week 1 is the first week that has at
1260    ///   least 4 days in the new year. See g_date_time_get_week_of_year().
1261    ///   This works well with ``G`` and ``u``.
1262    /// - ``w``: the day of the week as a decimal, range 0 to 6, Sunday being 0.
1263    ///   This is not the ISO 8601 standard format — use ``u`` instead.
1264    /// - ``x``: the preferred date representation for the current locale without
1265    ///   the time
1266    /// - ``X``: the preferred time representation for the current locale without
1267    ///   the date
1268    /// - ``y``: the year as a decimal number without the century
1269    /// - ``Y``: the year as a decimal number including the century
1270    /// - ``z``: the time zone as an offset from UTC (`+hhmm`)
1271    /// - `%:z`: the time zone as an offset from UTC (`+hh:mm`).
1272    ///   This is a gnulib `strftime()` extension. Since: 2.38
1273    /// - `%::z`: the time zone as an offset from UTC (`+hh:mm:ss`). This is a
1274    ///   gnulib `strftime()` extension. Since: 2.38
1275    /// - `%:::z`: the time zone as an offset from UTC, with `:` to necessary
1276    ///   precision (e.g., `-04`, `+05:30`). This is a gnulib `strftime()` extension. Since: 2.38
1277    /// - ``Z``: the time zone or name or abbreviation
1278    /// - `%%`: a literal `%` character
1279    ///
1280    /// Some conversion specifications can be modified by preceding the
1281    /// conversion specifier by one or more modifier characters.
1282    ///
1283    /// The following modifiers are supported for many of the numeric
1284    /// conversions:
1285    ///
1286    /// - `O`: Use alternative numeric symbols, if the current locale supports those.
1287    /// - `_`: Pad a numeric result with spaces. This overrides the default padding
1288    ///   for the specifier.
1289    /// - `-`: Do not pad a numeric result. This overrides the default padding
1290    ///   for the specifier.
1291    /// - `0`: Pad a numeric result with zeros. This overrides the default padding
1292    ///   for the specifier.
1293    ///
1294    /// The following modifiers are supported for many of the alphabetic conversions:
1295    ///
1296    /// - `^`: Use upper case if possible. This is a gnulib `strftime()` extension.
1297    ///   Since: 2.80
1298    /// - `#`: Use opposite case if possible. This is a gnulib `strftime()`
1299    ///   extension. Since: 2.80
1300    ///
1301    /// Additionally, when `O` is used with `B`, `b`, or `h`, it produces the alternative
1302    /// form of a month name. The alternative form should be used when the month
1303    /// name is used without a day number (e.g., standalone). It is required in
1304    /// some languages (Baltic, Slavic, Greek, and more) due to their grammatical
1305    /// rules. For other languages there is no difference. ``OB`` is a GNU and BSD
1306    /// `strftime()` extension expected to be added to the future POSIX specification,
1307    /// ``Ob`` and ``Oh`` are GNU `strftime()` extensions. Since: 2.56
1308    ///
1309    /// Since GLib 2.80, when `E` is used with ``c``, ``C``, ``x``, ``X``, ``y`` or ``Y``,
1310    /// the date is formatted using an alternate era representation specific to the
1311    /// locale. This is typically used for the Thai solar calendar or Japanese era
1312    /// names, for example.
1313    ///
1314    /// - ``Ec``: the preferred date and time representation for the current locale,
1315    ///   using the alternate era representation
1316    /// - ``EC``: the name of the era
1317    /// - ``Ex``: the preferred date representation for the current locale without
1318    ///   the time, using the alternate era representation
1319    /// - ``EX``: the preferred time representation for the current locale without
1320    ///   the date, using the alternate era representation
1321    /// - ``Ey``: the year since the beginning of the era denoted by the ``EC``
1322    ///   specifier
1323    /// - ``EY``: the full alternative year representation
1324    /// ## `format`
1325    /// a valid UTF-8 string, containing the format for the
1326    ///          #GDateTime
1327    ///
1328    /// # Returns
1329    ///
1330    /// a newly allocated string formatted to
1331    ///    the requested format or [`None`] in the case that there was an error (such
1332    ///    as a format specifier not being supported in the current locale). The
1333    ///    string should be freed with g_free().
1334    #[doc(alias = "g_date_time_format")]
1335    pub fn format(&self, format: &str) -> Result<crate::GString, BoolError> {
1336        unsafe {
1337            Option::<_>::from_glib_full(ffi::g_date_time_format(
1338                self.to_glib_none().0,
1339                format.to_glib_none().0,
1340            ))
1341            .ok_or_else(|| crate::bool_error!("Invalid date"))
1342        }
1343    }
1344
1345    /// Format @self in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601),
1346    /// including the date, time and time zone, and return that as a UTF-8 encoded
1347    /// string.
1348    ///
1349    /// Since GLib 2.66, this will output to sub-second precision if needed.
1350    ///
1351    /// # Returns
1352    ///
1353    /// a newly allocated string formatted in
1354    ///   ISO 8601 format or [`None`] in the case that there was an error. The string
1355    ///   should be freed with g_free().
1356    // rustdoc-stripper-ignore-next-stop
1357    /// Format @self in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601),
1358    /// including the date, time and time zone, and return that as a UTF-8 encoded
1359    /// string.
1360    ///
1361    /// Since GLib 2.66, this will output to sub-second precision if needed.
1362    ///
1363    /// # Returns
1364    ///
1365    /// a newly allocated string formatted in
1366    ///   ISO 8601 format or [`None`] in the case that there was an error. The string
1367    ///   should be freed with g_free().
1368    #[cfg(feature = "v2_62")]
1369    #[cfg_attr(docsrs, doc(cfg(feature = "v2_62")))]
1370    #[doc(alias = "g_date_time_format_iso8601")]
1371    pub fn format_iso8601(&self) -> Result<crate::GString, BoolError> {
1372        unsafe {
1373            Option::<_>::from_glib_full(ffi::g_date_time_format_iso8601(self.to_glib_none().0))
1374                .ok_or_else(|| crate::bool_error!("Invalid date"))
1375        }
1376    }
1377
1378    /// Retrieves the day of the month represented by @self in the gregorian
1379    /// calendar.
1380    ///
1381    /// # Returns
1382    ///
1383    /// the day of the month
1384    // rustdoc-stripper-ignore-next-stop
1385    /// Retrieves the day of the month represented by @self in the gregorian
1386    /// calendar.
1387    ///
1388    /// # Returns
1389    ///
1390    /// the day of the month
1391    #[doc(alias = "g_date_time_get_day_of_month")]
1392    #[doc(alias = "get_day_of_month")]
1393    pub fn day_of_month(&self) -> i32 {
1394        unsafe { ffi::g_date_time_get_day_of_month(self.to_glib_none().0) }
1395    }
1396
1397    /// Retrieves the ISO 8601 day of the week on which @self falls (1 is
1398    /// Monday, 2 is Tuesday... 7 is Sunday).
1399    ///
1400    /// # Returns
1401    ///
1402    /// the day of the week
1403    // rustdoc-stripper-ignore-next-stop
1404    /// Retrieves the ISO 8601 day of the week on which @self falls (1 is
1405    /// Monday, 2 is Tuesday... 7 is Sunday).
1406    ///
1407    /// # Returns
1408    ///
1409    /// the day of the week
1410    #[doc(alias = "g_date_time_get_day_of_week")]
1411    #[doc(alias = "get_day_of_week")]
1412    pub fn day_of_week(&self) -> i32 {
1413        unsafe { ffi::g_date_time_get_day_of_week(self.to_glib_none().0) }
1414    }
1415
1416    /// Retrieves the day of the year represented by @self in the Gregorian
1417    /// calendar.
1418    ///
1419    /// # Returns
1420    ///
1421    /// the day of the year
1422    // rustdoc-stripper-ignore-next-stop
1423    /// Retrieves the day of the year represented by @self in the Gregorian
1424    /// calendar.
1425    ///
1426    /// # Returns
1427    ///
1428    /// the day of the year
1429    #[doc(alias = "g_date_time_get_day_of_year")]
1430    #[doc(alias = "get_day_of_year")]
1431    pub fn day_of_year(&self) -> i32 {
1432        unsafe { ffi::g_date_time_get_day_of_year(self.to_glib_none().0) }
1433    }
1434
1435    /// Retrieves the hour of the day represented by @self
1436    ///
1437    /// # Returns
1438    ///
1439    /// the hour of the day
1440    // rustdoc-stripper-ignore-next-stop
1441    /// Retrieves the hour of the day represented by @self
1442    ///
1443    /// # Returns
1444    ///
1445    /// the hour of the day
1446    #[doc(alias = "g_date_time_get_hour")]
1447    #[doc(alias = "get_hour")]
1448    pub fn hour(&self) -> i32 {
1449        unsafe { ffi::g_date_time_get_hour(self.to_glib_none().0) }
1450    }
1451
1452    /// Retrieves the microsecond of the date represented by @self
1453    ///
1454    /// # Returns
1455    ///
1456    /// the microsecond of the second
1457    // rustdoc-stripper-ignore-next-stop
1458    /// Retrieves the microsecond of the date represented by @self
1459    ///
1460    /// # Returns
1461    ///
1462    /// the microsecond of the second
1463    #[doc(alias = "g_date_time_get_microsecond")]
1464    #[doc(alias = "get_microsecond")]
1465    pub fn microsecond(&self) -> i32 {
1466        unsafe { ffi::g_date_time_get_microsecond(self.to_glib_none().0) }
1467    }
1468
1469    /// Retrieves the minute of the hour represented by @self
1470    ///
1471    /// # Returns
1472    ///
1473    /// the minute of the hour
1474    // rustdoc-stripper-ignore-next-stop
1475    /// Retrieves the minute of the hour represented by @self
1476    ///
1477    /// # Returns
1478    ///
1479    /// the minute of the hour
1480    #[doc(alias = "g_date_time_get_minute")]
1481    #[doc(alias = "get_minute")]
1482    pub fn minute(&self) -> i32 {
1483        unsafe { ffi::g_date_time_get_minute(self.to_glib_none().0) }
1484    }
1485
1486    /// Retrieves the month of the year represented by @self in the Gregorian
1487    /// calendar.
1488    ///
1489    /// # Returns
1490    ///
1491    /// the month represented by @self
1492    // rustdoc-stripper-ignore-next-stop
1493    /// Retrieves the month of the year represented by @self in the Gregorian
1494    /// calendar.
1495    ///
1496    /// # Returns
1497    ///
1498    /// the month represented by @self
1499    #[doc(alias = "g_date_time_get_month")]
1500    #[doc(alias = "get_month")]
1501    pub fn month(&self) -> i32 {
1502        unsafe { ffi::g_date_time_get_month(self.to_glib_none().0) }
1503    }
1504
1505    /// Retrieves the second of the minute represented by @self
1506    ///
1507    /// # Returns
1508    ///
1509    /// the second represented by @self
1510    // rustdoc-stripper-ignore-next-stop
1511    /// Retrieves the second of the minute represented by @self
1512    ///
1513    /// # Returns
1514    ///
1515    /// the second represented by @self
1516    #[doc(alias = "g_date_time_get_second")]
1517    #[doc(alias = "get_second")]
1518    pub fn second(&self) -> i32 {
1519        unsafe { ffi::g_date_time_get_second(self.to_glib_none().0) }
1520    }
1521
1522    /// Retrieves the number of seconds since the start of the last minute,
1523    /// including the fractional part.
1524    ///
1525    /// # Returns
1526    ///
1527    /// the number of seconds
1528    // rustdoc-stripper-ignore-next-stop
1529    /// Retrieves the number of seconds since the start of the last minute,
1530    /// including the fractional part.
1531    ///
1532    /// # Returns
1533    ///
1534    /// the number of seconds
1535    #[doc(alias = "g_date_time_get_seconds")]
1536    #[doc(alias = "get_seconds")]
1537    pub fn seconds(&self) -> f64 {
1538        unsafe { ffi::g_date_time_get_seconds(self.to_glib_none().0) }
1539    }
1540
1541    /// Get the time zone for this @self.
1542    ///
1543    /// # Returns
1544    ///
1545    /// the time zone
1546    // rustdoc-stripper-ignore-next-stop
1547    /// Get the time zone for this @self.
1548    ///
1549    /// # Returns
1550    ///
1551    /// the time zone
1552    #[cfg(feature = "v2_58")]
1553    #[cfg_attr(docsrs, doc(cfg(feature = "v2_58")))]
1554    #[doc(alias = "g_date_time_get_timezone")]
1555    #[doc(alias = "get_timezone")]
1556    pub fn timezone(&self) -> TimeZone {
1557        unsafe { from_glib_none(ffi::g_date_time_get_timezone(self.to_glib_none().0)) }
1558    }
1559
1560    /// Determines the time zone abbreviation to be used at the time and in
1561    /// the time zone of @self.
1562    ///
1563    /// For example, in Toronto this is currently "EST" during the winter
1564    /// months and "EDT" during the summer months when daylight savings
1565    /// time is in effect.
1566    ///
1567    /// # Returns
1568    ///
1569    /// the time zone abbreviation. The returned
1570    ///          string is owned by the #GDateTime and it should not be
1571    ///          modified or freed
1572    // rustdoc-stripper-ignore-next-stop
1573    /// Determines the time zone abbreviation to be used at the time and in
1574    /// the time zone of @self.
1575    ///
1576    /// For example, in Toronto this is currently "EST" during the winter
1577    /// months and "EDT" during the summer months when daylight savings
1578    /// time is in effect.
1579    ///
1580    /// # Returns
1581    ///
1582    /// the time zone abbreviation. The returned
1583    ///          string is owned by the #GDateTime and it should not be
1584    ///          modified or freed
1585    #[doc(alias = "g_date_time_get_timezone_abbreviation")]
1586    #[doc(alias = "get_timezone_abbreviation")]
1587    pub fn timezone_abbreviation(&self) -> crate::GString {
1588        unsafe {
1589            from_glib_none(ffi::g_date_time_get_timezone_abbreviation(
1590                self.to_glib_none().0,
1591            ))
1592        }
1593    }
1594
1595    /// Determines the offset to UTC in effect at the time and in the time
1596    /// zone of @self.
1597    ///
1598    /// The offset is the number of microseconds that you add to UTC time to
1599    /// arrive at local time for the time zone (ie: negative numbers for time
1600    /// zones west of GMT, positive numbers for east).
1601    ///
1602    /// If @self represents UTC time, then the offset is always zero.
1603    ///
1604    /// # Returns
1605    ///
1606    /// the number of microseconds that should be added to UTC to
1607    ///          get the local time
1608    // rustdoc-stripper-ignore-next-stop
1609    /// Determines the offset to UTC in effect at the time and in the time
1610    /// zone of @self.
1611    ///
1612    /// The offset is the number of microseconds that you add to UTC time to
1613    /// arrive at local time for the time zone (ie: negative numbers for time
1614    /// zones west of GMT, positive numbers for east).
1615    ///
1616    /// If @self represents UTC time, then the offset is always zero.
1617    ///
1618    /// # Returns
1619    ///
1620    /// the number of microseconds that should be added to UTC to
1621    ///          get the local time
1622    #[doc(alias = "g_date_time_get_utc_offset")]
1623    #[doc(alias = "get_utc_offset")]
1624    pub fn utc_offset(&self) -> TimeSpan {
1625        unsafe { from_glib(ffi::g_date_time_get_utc_offset(self.to_glib_none().0)) }
1626    }
1627
1628    /// Returns the ISO 8601 week-numbering year in which the week containing
1629    /// @self falls.
1630    ///
1631    /// This function, taken together with g_date_time_get_week_of_year() and
1632    /// g_date_time_get_day_of_week() can be used to determine the full ISO
1633    /// week date on which @self falls.
1634    ///
1635    /// This is usually equal to the normal Gregorian year (as returned by
1636    /// g_date_time_get_year()), except as detailed below:
1637    ///
1638    /// For Thursday, the week-numbering year is always equal to the usual
1639    /// calendar year.  For other days, the number is such that every day
1640    /// within a complete week (Monday to Sunday) is contained within the
1641    /// same week-numbering year.
1642    ///
1643    /// For Monday, Tuesday and Wednesday occurring near the end of the year,
1644    /// this may mean that the week-numbering year is one greater than the
1645    /// calendar year (so that these days have the same week-numbering year
1646    /// as the Thursday occurring early in the next year).
1647    ///
1648    /// For Friday, Saturday and Sunday occurring near the start of the year,
1649    /// this may mean that the week-numbering year is one less than the
1650    /// calendar year (so that these days have the same week-numbering year
1651    /// as the Thursday occurring late in the previous year).
1652    ///
1653    /// An equivalent description is that the week-numbering year is equal to
1654    /// the calendar year containing the majority of the days in the current
1655    /// week (Monday to Sunday).
1656    ///
1657    /// Note that January 1 0001 in the proleptic Gregorian calendar is a
1658    /// Monday, so this function never returns 0.
1659    ///
1660    /// # Returns
1661    ///
1662    /// the ISO 8601 week-numbering year for @self
1663    // rustdoc-stripper-ignore-next-stop
1664    /// Returns the ISO 8601 week-numbering year in which the week containing
1665    /// @self falls.
1666    ///
1667    /// This function, taken together with g_date_time_get_week_of_year() and
1668    /// g_date_time_get_day_of_week() can be used to determine the full ISO
1669    /// week date on which @self falls.
1670    ///
1671    /// This is usually equal to the normal Gregorian year (as returned by
1672    /// g_date_time_get_year()), except as detailed below:
1673    ///
1674    /// For Thursday, the week-numbering year is always equal to the usual
1675    /// calendar year.  For other days, the number is such that every day
1676    /// within a complete week (Monday to Sunday) is contained within the
1677    /// same week-numbering year.
1678    ///
1679    /// For Monday, Tuesday and Wednesday occurring near the end of the year,
1680    /// this may mean that the week-numbering year is one greater than the
1681    /// calendar year (so that these days have the same week-numbering year
1682    /// as the Thursday occurring early in the next year).
1683    ///
1684    /// For Friday, Saturday and Sunday occurring near the start of the year,
1685    /// this may mean that the week-numbering year is one less than the
1686    /// calendar year (so that these days have the same week-numbering year
1687    /// as the Thursday occurring late in the previous year).
1688    ///
1689    /// An equivalent description is that the week-numbering year is equal to
1690    /// the calendar year containing the majority of the days in the current
1691    /// week (Monday to Sunday).
1692    ///
1693    /// Note that January 1 0001 in the proleptic Gregorian calendar is a
1694    /// Monday, so this function never returns 0.
1695    ///
1696    /// # Returns
1697    ///
1698    /// the ISO 8601 week-numbering year for @self
1699    #[doc(alias = "g_date_time_get_week_numbering_year")]
1700    #[doc(alias = "get_week_numbering_year")]
1701    pub fn week_numbering_year(&self) -> i32 {
1702        unsafe { ffi::g_date_time_get_week_numbering_year(self.to_glib_none().0) }
1703    }
1704
1705    /// Returns the ISO 8601 week number for the week containing @self.
1706    /// The ISO 8601 week number is the same for every day of the week (from
1707    /// Moday through Sunday).  That can produce some unusual results
1708    /// (described below).
1709    ///
1710    /// The first week of the year is week 1.  This is the week that contains
1711    /// the first Thursday of the year.  Equivalently, this is the first week
1712    /// that has more than 4 of its days falling within the calendar year.
1713    ///
1714    /// The value 0 is never returned by this function.  Days contained
1715    /// within a year but occurring before the first ISO 8601 week of that
1716    /// year are considered as being contained in the last week of the
1717    /// previous year.  Similarly, the final days of a calendar year may be
1718    /// considered as being part of the first ISO 8601 week of the next year
1719    /// if 4 or more days of that week are contained within the new year.
1720    ///
1721    /// # Returns
1722    ///
1723    /// the ISO 8601 week number for @self.
1724    // rustdoc-stripper-ignore-next-stop
1725    /// Returns the ISO 8601 week number for the week containing @self.
1726    /// The ISO 8601 week number is the same for every day of the week (from
1727    /// Moday through Sunday).  That can produce some unusual results
1728    /// (described below).
1729    ///
1730    /// The first week of the year is week 1.  This is the week that contains
1731    /// the first Thursday of the year.  Equivalently, this is the first week
1732    /// that has more than 4 of its days falling within the calendar year.
1733    ///
1734    /// The value 0 is never returned by this function.  Days contained
1735    /// within a year but occurring before the first ISO 8601 week of that
1736    /// year are considered as being contained in the last week of the
1737    /// previous year.  Similarly, the final days of a calendar year may be
1738    /// considered as being part of the first ISO 8601 week of the next year
1739    /// if 4 or more days of that week are contained within the new year.
1740    ///
1741    /// # Returns
1742    ///
1743    /// the ISO 8601 week number for @self.
1744    #[doc(alias = "g_date_time_get_week_of_year")]
1745    #[doc(alias = "get_week_of_year")]
1746    pub fn week_of_year(&self) -> i32 {
1747        unsafe { ffi::g_date_time_get_week_of_year(self.to_glib_none().0) }
1748    }
1749
1750    /// Retrieves the year represented by @self in the Gregorian calendar.
1751    ///
1752    /// # Returns
1753    ///
1754    /// the year represented by @self
1755    // rustdoc-stripper-ignore-next-stop
1756    /// Retrieves the year represented by @self in the Gregorian calendar.
1757    ///
1758    /// # Returns
1759    ///
1760    /// the year represented by @self
1761    #[doc(alias = "g_date_time_get_year")]
1762    #[doc(alias = "get_year")]
1763    pub fn year(&self) -> i32 {
1764        unsafe { ffi::g_date_time_get_year(self.to_glib_none().0) }
1765    }
1766
1767    /// Retrieves the Gregorian day, month, and year of a given #GDateTime.
1768    ///
1769    /// # Returns
1770    ///
1771    ///
1772    /// ## `year`
1773    /// the return location for the gregorian year, or [`None`].
1774    ///
1775    /// ## `month`
1776    /// the return location for the month of the year, or [`None`].
1777    ///
1778    /// ## `day`
1779    /// the return location for the day of the month, or [`None`].
1780    // rustdoc-stripper-ignore-next-stop
1781    /// Retrieves the Gregorian day, month, and year of a given #GDateTime.
1782    ///
1783    /// # Returns
1784    ///
1785    ///
1786    /// ## `year`
1787    /// the return location for the gregorian year, or [`None`].
1788    ///
1789    /// ## `month`
1790    /// the return location for the month of the year, or [`None`].
1791    ///
1792    /// ## `day`
1793    /// the return location for the day of the month, or [`None`].
1794    #[doc(alias = "g_date_time_get_ymd")]
1795    #[doc(alias = "get_ymd")]
1796    pub fn ymd(&self) -> (i32, i32, i32) {
1797        unsafe {
1798            let mut year = std::mem::MaybeUninit::uninit();
1799            let mut month = std::mem::MaybeUninit::uninit();
1800            let mut day = std::mem::MaybeUninit::uninit();
1801            ffi::g_date_time_get_ymd(
1802                self.to_glib_none().0,
1803                year.as_mut_ptr(),
1804                month.as_mut_ptr(),
1805                day.as_mut_ptr(),
1806            );
1807            (year.assume_init(), month.assume_init(), day.assume_init())
1808        }
1809    }
1810
1811    #[doc(alias = "g_date_time_hash")]
1812    fn hash(&self) -> u32 {
1813        unsafe {
1814            ffi::g_date_time_hash(
1815                ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(self).0 as ffi::gconstpointer,
1816            )
1817        }
1818    }
1819
1820    /// Determines if daylight savings time is in effect at the time and in
1821    /// the time zone of @self.
1822    ///
1823    /// # Returns
1824    ///
1825    /// [`true`] if daylight savings time is in effect
1826    // rustdoc-stripper-ignore-next-stop
1827    /// Determines if daylight savings time is in effect at the time and in
1828    /// the time zone of @self.
1829    ///
1830    /// # Returns
1831    ///
1832    /// [`true`] if daylight savings time is in effect
1833    #[doc(alias = "g_date_time_is_daylight_savings")]
1834    pub fn is_daylight_savings(&self) -> bool {
1835        unsafe { from_glib(ffi::g_date_time_is_daylight_savings(self.to_glib_none().0)) }
1836    }
1837
1838    /// Creates a new #GDateTime corresponding to the same instant in time as
1839    /// @self, but in the local time zone.
1840    ///
1841    /// This call is equivalent to calling g_date_time_to_timezone() with the
1842    /// time zone returned by g_time_zone_new_local().
1843    ///
1844    /// # Returns
1845    ///
1846    /// the newly created #GDateTime which
1847    ///   should be freed with g_date_time_unref(), or [`None`]
1848    // rustdoc-stripper-ignore-next-stop
1849    /// Creates a new #GDateTime corresponding to the same instant in time as
1850    /// @self, but in the local time zone.
1851    ///
1852    /// This call is equivalent to calling g_date_time_to_timezone() with the
1853    /// time zone returned by g_time_zone_new_local().
1854    ///
1855    /// # Returns
1856    ///
1857    /// the newly created #GDateTime which
1858    ///   should be freed with g_date_time_unref(), or [`None`]
1859    #[doc(alias = "g_date_time_to_local")]
1860    pub fn to_local(&self) -> Result<DateTime, BoolError> {
1861        unsafe {
1862            Option::<_>::from_glib_full(ffi::g_date_time_to_local(self.to_glib_none().0))
1863                .ok_or_else(|| crate::bool_error!("Invalid date"))
1864        }
1865    }
1866
1867    //#[cfg_attr(feature = "v2_62", deprecated = "Since 2.62")]
1868    //#[allow(deprecated)]
1869    //#[doc(alias = "g_date_time_to_timeval")]
1870    //pub fn to_timeval(&self, tv: /*Ignored*/&mut TimeVal) -> bool {
1871    //    unsafe { TODO: call ffi:g_date_time_to_timeval() }
1872    //}
1873
1874    /// Create a new #GDateTime corresponding to the same instant in time as
1875    /// @self, but in the time zone @tz.
1876    ///
1877    /// This call can fail in the case that the time goes out of bounds.  For
1878    /// example, converting 0001-01-01 00:00:00 UTC to a time zone west of
1879    /// Greenwich will fail (due to the year 0 being out of range).
1880    /// ## `tz`
1881    /// the new #GTimeZone
1882    ///
1883    /// # Returns
1884    ///
1885    /// the newly created #GDateTime which
1886    ///   should be freed with g_date_time_unref(), or [`None`]
1887    // rustdoc-stripper-ignore-next-stop
1888    /// Create a new #GDateTime corresponding to the same instant in time as
1889    /// @self, but in the time zone @tz.
1890    ///
1891    /// This call can fail in the case that the time goes out of bounds.  For
1892    /// example, converting 0001-01-01 00:00:00 UTC to a time zone west of
1893    /// Greenwich will fail (due to the year 0 being out of range).
1894    /// ## `tz`
1895    /// the new #GTimeZone
1896    ///
1897    /// # Returns
1898    ///
1899    /// the newly created #GDateTime which
1900    ///   should be freed with g_date_time_unref(), or [`None`]
1901    #[doc(alias = "g_date_time_to_timezone")]
1902    pub fn to_timezone(&self, tz: &TimeZone) -> Result<DateTime, BoolError> {
1903        unsafe {
1904            Option::<_>::from_glib_full(ffi::g_date_time_to_timezone(
1905                self.to_glib_none().0,
1906                tz.to_glib_none().0,
1907            ))
1908            .ok_or_else(|| crate::bool_error!("Invalid date"))
1909        }
1910    }
1911
1912    /// Gives the Unix time corresponding to @self, rounding down to the
1913    /// nearest second.
1914    ///
1915    /// Unix time is the number of seconds that have elapsed since 1970-01-01
1916    /// 00:00:00 UTC, regardless of the time zone associated with @self.
1917    ///
1918    /// # Returns
1919    ///
1920    /// the Unix time corresponding to @self
1921    // rustdoc-stripper-ignore-next-stop
1922    /// Gives the Unix time corresponding to @self, rounding down to the
1923    /// nearest second.
1924    ///
1925    /// Unix time is the number of seconds that have elapsed since 1970-01-01
1926    /// 00:00:00 UTC, regardless of the time zone associated with @self.
1927    ///
1928    /// # Returns
1929    ///
1930    /// the Unix time corresponding to @self
1931    #[doc(alias = "g_date_time_to_unix")]
1932    pub fn to_unix(&self) -> i64 {
1933        unsafe { ffi::g_date_time_to_unix(self.to_glib_none().0) }
1934    }
1935
1936    /// Gives the Unix time corresponding to @self, in microseconds.
1937    ///
1938    /// Unix time is the number of microseconds that have elapsed since 1970-01-01
1939    /// 00:00:00 UTC, regardless of the time zone associated with @self.
1940    ///
1941    /// # Returns
1942    ///
1943    /// the Unix time corresponding to @self
1944    // rustdoc-stripper-ignore-next-stop
1945    /// Gives the Unix time corresponding to @self, in microseconds.
1946    ///
1947    /// Unix time is the number of microseconds that have elapsed since 1970-01-01
1948    /// 00:00:00 UTC, regardless of the time zone associated with @self.
1949    ///
1950    /// # Returns
1951    ///
1952    /// the Unix time corresponding to @self
1953    #[cfg(feature = "v2_80")]
1954    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
1955    #[doc(alias = "g_date_time_to_unix_usec")]
1956    pub fn to_unix_usec(&self) -> i64 {
1957        unsafe { ffi::g_date_time_to_unix_usec(self.to_glib_none().0) }
1958    }
1959
1960    /// Creates a new #GDateTime corresponding to the same instant in time as
1961    /// @self, but in UTC.
1962    ///
1963    /// This call is equivalent to calling g_date_time_to_timezone() with the
1964    /// time zone returned by g_time_zone_new_utc().
1965    ///
1966    /// # Returns
1967    ///
1968    /// the newly created #GDateTime which
1969    ///   should be freed with g_date_time_unref(), or [`None`]
1970    // rustdoc-stripper-ignore-next-stop
1971    /// Creates a new #GDateTime corresponding to the same instant in time as
1972    /// @self, but in UTC.
1973    ///
1974    /// This call is equivalent to calling g_date_time_to_timezone() with the
1975    /// time zone returned by g_time_zone_new_utc().
1976    ///
1977    /// # Returns
1978    ///
1979    /// the newly created #GDateTime which
1980    ///   should be freed with g_date_time_unref(), or [`None`]
1981    #[doc(alias = "g_date_time_to_utc")]
1982    pub fn to_utc(&self) -> Result<DateTime, BoolError> {
1983        unsafe {
1984            Option::<_>::from_glib_full(ffi::g_date_time_to_utc(self.to_glib_none().0))
1985                .ok_or_else(|| crate::bool_error!("Invalid date"))
1986        }
1987    }
1988}
1989
1990impl PartialOrd for DateTime {
1991    #[inline]
1992    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
1993        Some(self.cmp(other))
1994    }
1995}
1996
1997impl Ord for DateTime {
1998    #[inline]
1999    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
2000        self.compare(other).cmp(&0)
2001    }
2002}
2003
2004impl PartialEq for DateTime {
2005    #[inline]
2006    fn eq(&self, other: &Self) -> bool {
2007        self.equal(other)
2008    }
2009}
2010
2011impl Eq for DateTime {}
2012
2013impl std::hash::Hash for DateTime {
2014    #[inline]
2015    fn hash<H>(&self, state: &mut H)
2016    where
2017        H: std::hash::Hasher,
2018    {
2019        std::hash::Hash::hash(&self.hash(), state)
2020    }
2021}
2022
2023unsafe impl Send for DateTime {}
2024unsafe impl Sync for DateTime {}