glib/auto/

date_time.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{BoolError, TimeSpan, TimeZone, ffi, translate::*};

crate::wrapper! {
    /// `GDateTime` is a structure that combines a Gregorian date and time
    /// into a single structure.
    ///
    /// `GDateTime` provides many conversion and methods to manipulate dates and times.
    /// Time precision is provided down to microseconds and the time can range
    /// (proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999.
    /// `GDateTime` follows POSIX time in the sense that it is oblivious to leap
    /// seconds.
    ///
    /// `GDateTime` is an immutable object; once it has been created it cannot
    /// be modified further. All modifiers will create a new `GDateTime`.
    /// Nearly all such functions can fail due to the date or time going out
    /// of range, in which case [`None`] will be returned.
    ///
    /// `GDateTime` is reference counted: the reference count is increased by calling
    /// `GLib::DateTime::ref()` and decreased by calling `GLib::DateTime::unref()`.
    /// When the reference count drops to 0, the resources allocated by the `GDateTime`
    /// structure are released.
    ///
    /// Many parts of the API may produce non-obvious results. As an
    /// example, adding two months to January 31st will yield March 31st
    /// whereas adding one month and then one month again will yield either
    /// March 28th or March 29th.  Also note that adding 24 hours is not
    /// always the same as adding one day (since days containing daylight
    /// savings time transitions are either 23 or 25 hours in length).
    #[derive(Debug)]
    pub struct DateTime(Shared<ffi::GDateTime>);

    match fn {
        ref => |ptr| ffi::g_date_time_ref(ptr),
        unref => |ptr| ffi::g_date_time_unref(ptr),
        type_ => || ffi::g_date_time_get_type(),
    }
}

impl DateTime {
    /// Creates a new #GDateTime corresponding to the given date and time in
    /// the time zone @tz.
    ///
    /// The @year must be between 1 and 9999, @month between 1 and 12 and @day
    /// between 1 and 28, 29, 30 or 31 depending on the month and the year.
    ///
    /// @hour must be between 0 and 23 and @minute must be between 0 and 59.
    ///
    /// @seconds must be at least 0.0 and must be strictly less than 60.0.
    /// It will be rounded down to the nearest microsecond.
    ///
    /// If the given time is not representable in the given time zone (for
    /// example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
    /// time) then the time will be rounded up to the nearest existing time
    /// (in this case, 03:00).  If this matters to you then you should verify
    /// the return value for containing the same as the numbers you gave.
    ///
    /// In the case that the given time is ambiguous in the given time zone
    /// (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
    /// savings time) then the time falling within standard (ie:
    /// non-daylight) time is taken.
    ///
    /// It not considered a programmer error for the values to this function
    /// to be out of range, but in the case that they are, the function will
    /// return [`None`].
    ///
    /// You should release the return value by calling g_date_time_unref()
    /// when you are done with it.
    /// ## `tz`
    /// a #GTimeZone
    /// ## `year`
    /// the year component of the date
    /// ## `month`
    /// the month component of the date
    /// ## `day`
    /// the day component of the date
    /// ## `hour`
    /// the hour component of the date
    /// ## `minute`
    /// the minute component of the date
    /// ## `seconds`
    /// the number of seconds past the minute
    ///
    /// # Returns
    ///
    /// a new #GDateTime, or [`None`]
    #[doc(alias = "g_date_time_new")]
    pub fn new(
        tz: &TimeZone,
        year: i32,
        month: i32,
        day: i32,
        hour: i32,
        minute: i32,
        seconds: f64,
    ) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new(
                tz.to_glib_none().0,
                year,
                month,
                day,
                hour,
                minute,
                seconds,
            ))
            .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a #GDateTime corresponding to the given
    /// [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601)
    /// @text. ISO 8601 strings of the form `<date><sep><time><tz>` are supported, with
    /// some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as
    /// mentioned below.
    ///
    /// Note that as #GDateTime "is oblivious to leap seconds", leap seconds information
    /// in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as
    /// `23:59:59`.
    ///
    /// `<sep>` is the separator and can be either 'T', 't' or ' '. The latter two
    /// separators are an extension from
    /// [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6).
    ///
    /// `<date>` is in the form:
    ///
    /// - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24.
    /// - `YYYYMMDD` - Same as above without dividers.
    /// - `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237.
    /// - `YYYYDDD` - Same as above without dividers.
    /// - `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7,
    ///   e.g. 2016-W34-3.
    /// - `YYYYWwwD` - Same as above without dividers.
    ///
    /// `<time>` is in the form:
    ///
    /// - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
    /// - `hhmmss(.sss)` - Same as above without dividers.
    ///
    /// `<tz>` is an optional timezone suffix of the form:
    ///
    /// - `Z` - UTC.
    /// - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00.
    /// - `+hh` or `-hh` - Offset from UTC in hours, e.g. +12.
    ///
    /// If the timezone is not provided in @text it must be provided in @default_tz
    /// (this field is otherwise ignored).
    ///
    /// This call can fail (returning [`None`]) if @text is not a valid ISO 8601
    /// formatted string.
    ///
    /// You should release the return value by calling g_date_time_unref()
    /// when you are done with it.
    /// ## `text`
    /// an ISO 8601 formatted time string.
    /// ## `default_tz`
    /// a #GTimeZone to use if the text doesn't contain a
    ///                          timezone, or [`None`].
    ///
    /// # Returns
    ///
    /// a new #GDateTime, or [`None`]
    #[doc(alias = "g_date_time_new_from_iso8601")]
    #[doc(alias = "new_from_iso8601")]
    pub fn from_iso8601(text: &str, default_tz: Option<&TimeZone>) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new_from_iso8601(
                text.to_glib_none().0,
                default_tz.to_glib_none().0,
            ))
            .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    //#[cfg_attr(feature = "v2_62", deprecated = "Since 2.62")]
    //#[allow(deprecated)]
    //#[doc(alias = "g_date_time_new_from_timeval_local")]
    //#[doc(alias = "new_from_timeval_local")]
    //pub fn from_timeval_local(tv: /*Ignored*/&TimeVal) -> Result<DateTime, BoolError> {
    //    unsafe { TODO: call ffi:g_date_time_new_from_timeval_local() }
    //}

    //#[cfg_attr(feature = "v2_62", deprecated = "Since 2.62")]
    //#[allow(deprecated)]
    //#[doc(alias = "g_date_time_new_from_timeval_utc")]
    //#[doc(alias = "new_from_timeval_utc")]
    //pub fn from_timeval_utc(tv: /*Ignored*/&TimeVal) -> Result<DateTime, BoolError> {
    //    unsafe { TODO: call ffi:g_date_time_new_from_timeval_utc() }
    //}

    /// Creates a #GDateTime corresponding to the given Unix time @t in the
    /// local time zone.
    ///
    /// Unix time is the number of seconds that have elapsed since 1970-01-01
    /// 00:00:00 UTC, regardless of the local time offset.
    ///
    /// This call can fail (returning [`None`]) if @t represents a time outside
    /// of the supported range of #GDateTime.
    ///
    /// You should release the return value by calling g_date_time_unref()
    /// when you are done with it.
    /// ## `t`
    /// the Unix time
    ///
    /// # Returns
    ///
    /// a new #GDateTime, or [`None`]
    #[doc(alias = "g_date_time_new_from_unix_local")]
    #[doc(alias = "new_from_unix_local")]
    pub fn from_unix_local(t: i64) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_local(t))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a [`DateTime`][crate::DateTime] corresponding to the given Unix time @t in the
    /// local time zone.
    ///
    /// Unix time is the number of microseconds that have elapsed since 1970-01-01
    /// 00:00:00 UTC, regardless of the local time offset.
    ///
    /// This call can fail (returning `NULL`) if @t represents a time outside
    /// of the supported range of #GDateTime.
    ///
    /// You should release the return value by calling `GLib::DateTime::unref()`
    /// when you are done with it.
    /// ## `usecs`
    /// the Unix time in microseconds
    ///
    /// # Returns
    ///
    /// a new [`DateTime`][crate::DateTime], or `NULL`
    #[cfg(feature = "v2_80")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
    #[doc(alias = "g_date_time_new_from_unix_local_usec")]
    #[doc(alias = "new_from_unix_local_usec")]
    pub fn from_unix_local_usec(usecs: i64) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_local_usec(usecs))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a #GDateTime corresponding to the given Unix time @t in UTC.
    ///
    /// Unix time is the number of seconds that have elapsed since 1970-01-01
    /// 00:00:00 UTC.
    ///
    /// This call can fail (returning [`None`]) if @t represents a time outside
    /// of the supported range of #GDateTime.
    ///
    /// You should release the return value by calling g_date_time_unref()
    /// when you are done with it.
    /// ## `t`
    /// the Unix time
    ///
    /// # Returns
    ///
    /// a new #GDateTime, or [`None`]
    #[doc(alias = "g_date_time_new_from_unix_utc")]
    #[doc(alias = "new_from_unix_utc")]
    pub fn from_unix_utc(t: i64) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_utc(t))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a [`DateTime`][crate::DateTime] corresponding to the given Unix time @t in UTC.
    ///
    /// Unix time is the number of microseconds that have elapsed since 1970-01-01
    /// 00:00:00 UTC.
    ///
    /// This call can fail (returning `NULL`) if @t represents a time outside
    /// of the supported range of #GDateTime.
    ///
    /// You should release the return value by calling `GLib::DateTime::unref()`
    /// when you are done with it.
    /// ## `usecs`
    /// the Unix time in microseconds
    ///
    /// # Returns
    ///
    /// a new [`DateTime`][crate::DateTime], or `NULL`
    #[cfg(feature = "v2_80")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
    #[doc(alias = "g_date_time_new_from_unix_utc_usec")]
    #[doc(alias = "new_from_unix_utc_usec")]
    pub fn from_unix_utc_usec(usecs: i64) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_utc_usec(usecs))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a new #GDateTime corresponding to the given date and time in
    /// the local time zone.
    ///
    /// This call is equivalent to calling g_date_time_new() with the time
    /// zone returned by g_time_zone_new_local().
    /// ## `year`
    /// the year component of the date
    /// ## `month`
    /// the month component of the date
    /// ## `day`
    /// the day component of the date
    /// ## `hour`
    /// the hour component of the date
    /// ## `minute`
    /// the minute component of the date
    /// ## `seconds`
    /// the number of seconds past the minute
    ///
    /// # Returns
    ///
    /// a #GDateTime, or [`None`]
    #[doc(alias = "g_date_time_new_local")]
    #[doc(alias = "new_local")]
    pub fn from_local(
        year: i32,
        month: i32,
        day: i32,
        hour: i32,
        minute: i32,
        seconds: f64,
    ) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new_local(
                year, month, day, hour, minute, seconds,
            ))
            .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a #GDateTime corresponding to this exact instant in the given
    /// time zone @tz.  The time is as accurate as the system allows, to a
    /// maximum accuracy of 1 microsecond.
    ///
    /// This function will always succeed unless GLib is still being used after the
    /// year 9999.
    ///
    /// You should release the return value by calling g_date_time_unref()
    /// when you are done with it.
    /// ## `tz`
    /// a #GTimeZone
    ///
    /// # Returns
    ///
    /// a new #GDateTime, or [`None`]
    #[doc(alias = "g_date_time_new_now")]
    #[doc(alias = "new_now")]
    pub fn now(tz: &TimeZone) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new_now(tz.to_glib_none().0))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a #GDateTime corresponding to this exact instant in the local
    /// time zone.
    ///
    /// This is equivalent to calling g_date_time_new_now() with the time
    /// zone returned by g_time_zone_new_local().
    ///
    /// # Returns
    ///
    /// a new #GDateTime, or [`None`]
    #[doc(alias = "g_date_time_new_now_local")]
    #[doc(alias = "new_now_local")]
    pub fn now_local() -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new_now_local())
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a #GDateTime corresponding to this exact instant in UTC.
    ///
    /// This is equivalent to calling g_date_time_new_now() with the time
    /// zone returned by g_time_zone_new_utc().
    ///
    /// # Returns
    ///
    /// a new #GDateTime, or [`None`]
    #[doc(alias = "g_date_time_new_now_utc")]
    #[doc(alias = "new_now_utc")]
    pub fn now_utc() -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new_now_utc())
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a new #GDateTime corresponding to the given date and time in
    /// UTC.
    ///
    /// This call is equivalent to calling g_date_time_new() with the time
    /// zone returned by g_time_zone_new_utc().
    /// ## `year`
    /// the year component of the date
    /// ## `month`
    /// the month component of the date
    /// ## `day`
    /// the day component of the date
    /// ## `hour`
    /// the hour component of the date
    /// ## `minute`
    /// the minute component of the date
    /// ## `seconds`
    /// the number of seconds past the minute
    ///
    /// # Returns
    ///
    /// a #GDateTime, or [`None`]
    #[doc(alias = "g_date_time_new_utc")]
    #[doc(alias = "new_utc")]
    pub fn from_utc(
        year: i32,
        month: i32,
        day: i32,
        hour: i32,
        minute: i32,
        seconds: f64,
    ) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_new_utc(
                year, month, day, hour, minute, seconds,
            ))
            .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a copy of @self and adds the specified timespan to the copy.
    /// ## `timespan`
    /// a #GTimeSpan
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_add")]
    pub fn add(&self, timespan: TimeSpan) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_add(
                self.to_glib_none().0,
                timespan.into_glib(),
            ))
            .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a copy of @self and adds the specified number of days to the
    /// copy. Add negative values to subtract days.
    /// ## `days`
    /// the number of days
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_add_days")]
    pub fn add_days(&self, days: i32) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_add_days(self.to_glib_none().0, days))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a new #GDateTime adding the specified values to the current date and
    /// time in @self. Add negative values to subtract.
    /// ## `years`
    /// the number of years to add
    /// ## `months`
    /// the number of months to add
    /// ## `days`
    /// the number of days to add
    /// ## `hours`
    /// the number of hours to add
    /// ## `minutes`
    /// the number of minutes to add
    /// ## `seconds`
    /// the number of seconds to add
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_add_full")]
    pub fn add_full(
        &self,
        years: i32,
        months: i32,
        days: i32,
        hours: i32,
        minutes: i32,
        seconds: f64,
    ) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_add_full(
                self.to_glib_none().0,
                years,
                months,
                days,
                hours,
                minutes,
                seconds,
            ))
            .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a copy of @self and adds the specified number of hours.
    /// Add negative values to subtract hours.
    /// ## `hours`
    /// the number of hours to add
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_add_hours")]
    pub fn add_hours(&self, hours: i32) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_add_hours(self.to_glib_none().0, hours))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a copy of @self adding the specified number of minutes.
    /// Add negative values to subtract minutes.
    /// ## `minutes`
    /// the number of minutes to add
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_add_minutes")]
    pub fn add_minutes(&self, minutes: i32) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_add_minutes(
                self.to_glib_none().0,
                minutes,
            ))
            .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a copy of @self and adds the specified number of months to the
    /// copy. Add negative values to subtract months.
    ///
    /// The day of the month of the resulting #GDateTime is clamped to the number
    /// of days in the updated calendar month. For example, if adding 1 month to
    /// 31st January 2018, the result would be 28th February 2018. In 2020 (a leap
    /// year), the result would be 29th February.
    /// ## `months`
    /// the number of months
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_add_months")]
    pub fn add_months(&self, months: i32) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_add_months(self.to_glib_none().0, months))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a copy of @self and adds the specified number of seconds.
    /// Add negative values to subtract seconds.
    /// ## `seconds`
    /// the number of seconds to add
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_add_seconds")]
    pub fn add_seconds(&self, seconds: f64) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_add_seconds(
                self.to_glib_none().0,
                seconds,
            ))
            .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a copy of @self and adds the specified number of weeks to the
    /// copy. Add negative values to subtract weeks.
    /// ## `weeks`
    /// the number of weeks
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_add_weeks")]
    pub fn add_weeks(&self, weeks: i32) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_add_weeks(self.to_glib_none().0, weeks))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Creates a copy of @self and adds the specified number of years to the
    /// copy. Add negative values to subtract years.
    ///
    /// As with g_date_time_add_months(), if the resulting date would be 29th
    /// February on a non-leap year, the day will be clamped to 28th February.
    /// ## `years`
    /// the number of years
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_add_years")]
    pub fn add_years(&self, years: i32) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_add_years(self.to_glib_none().0, years))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    #[doc(alias = "g_date_time_compare")]
    fn compare(&self, dt2: &DateTime) -> i32 {
        unsafe {
            ffi::g_date_time_compare(
                ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(self).0 as ffi::gconstpointer,
                ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(dt2).0 as ffi::gconstpointer,
            )
        }
    }

    /// Calculates the difference in time between @self and @begin.
    ///
    /// The time span that is returned is effectively @self - @begin (positive if the
    /// first parameter is larger).
    ///
    /// This effectively converts both date-times to the same time zone before
    /// calculating the difference.
    /// ## `begin`
    /// another date-time
    ///
    /// # Returns
    ///
    /// the difference between the two date-times, as a time
    ///   span expressed in microseconds
    #[doc(alias = "g_date_time_difference")]
    pub fn difference(&self, begin: &DateTime) -> TimeSpan {
        unsafe {
            from_glib(ffi::g_date_time_difference(
                self.to_glib_none().0,
                begin.to_glib_none().0,
            ))
        }
    }

    #[doc(alias = "g_date_time_equal")]
    fn equal(&self, dt2: &DateTime) -> bool {
        unsafe {
            from_glib(ffi::g_date_time_equal(
                ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(self).0 as ffi::gconstpointer,
                ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(dt2).0 as ffi::gconstpointer,
            ))
        }
    }

    /// Creates a newly allocated string representing the requested @format.
    ///
    /// The format strings understood by this function are a subset of the
    /// `strftime()` format language as specified by C99.  The ``D``, ``U`` and ``W``
    /// conversions are not supported, nor is the `E` modifier.  The GNU
    /// extensions ``k``, ``l``, ``s`` and ``P`` are supported, however, as are the
    /// `0`, `_` and `-` modifiers. The Python extension ``f`` is also supported.
    ///
    /// In contrast to `strftime()`, this function always produces a UTF-8
    /// string, regardless of the current locale.  Note that the rendering of
    /// many formats is locale-dependent and may not match the `strftime()`
    /// output exactly.
    ///
    /// The following format specifiers are supported:
    ///
    /// - ``a``: the abbreviated weekday name according to the current locale
    /// - ``A``: the full weekday name according to the current locale
    /// - ``b``: the abbreviated month name according to the current locale
    /// - ``B``: the full month name according to the current locale
    /// - ``c``: the preferred date and time representation for the current locale
    /// - ``C``: the century number (year/100) as a 2-digit integer (00-99)
    /// - ``d``: the day of the month as a decimal number (range 01 to 31)
    /// - ``e``: the day of the month as a decimal number (range 1 to 31);
    ///   single digits are preceded by a figure space (U+2007)
    /// - ``F``: equivalent to ``Y`-`m`-`d`` (the ISO 8601 date format)
    /// - ``g``: the last two digits of the ISO 8601 week-based year as a
    ///   decimal number (00-99). This works well with ``V`` and ``u``.
    /// - ``G``: the ISO 8601 week-based year as a decimal number. This works
    ///   well with ``V`` and ``u``.
    /// - ``h``: equivalent to ``b``
    /// - ``H``: the hour as a decimal number using a 24-hour clock (range 00 to 23)
    /// - ``I``: the hour as a decimal number using a 12-hour clock (range 01 to 12)
    /// - ``j``: the day of the year as a decimal number (range 001 to 366)
    /// - ``k``: the hour (24-hour clock) as a decimal number (range 0 to 23);
    ///   single digits are preceded by a figure space (U+2007)
    /// - ``l``: the hour (12-hour clock) as a decimal number (range 1 to 12);
    ///   single digits are preceded by a figure space (U+2007)
    /// - ``m``: the month as a decimal number (range 01 to 12)
    /// - ``M``: the minute as a decimal number (range 00 to 59)
    /// - ``f``: the microsecond as a decimal number (range 000000 to 999999)
    /// - ``p``: either ‘AM’ or ‘PM’ according to the given time value, or the
    ///   corresponding  strings for the current locale.  Noon is treated as
    ///   ‘PM’ and midnight as ‘AM’. Use of this format specifier is discouraged, as
    ///   many locales have no concept of AM/PM formatting. Use ``c`` or ``X`` instead.
    /// - ``P``: like ``p`` but lowercase: ‘am’ or ‘pm’ or a corresponding string for
    ///   the current locale. Use of this format specifier is discouraged, as
    ///   many locales have no concept of AM/PM formatting. Use ``c`` or ``X`` instead.
    /// - ``r``: the time in a.m. or p.m. notation. Use of this format specifier is
    ///   discouraged, as many locales have no concept of AM/PM formatting. Use ``c``
    ///   or ``X`` instead.
    /// - ``R``: the time in 24-hour notation (``H`:`M``)
    /// - ``s``: the number of seconds since the Epoch, that is, since 1970-01-01
    ///   00:00:00 UTC
    /// - ``S``: the second as a decimal number (range 00 to 60)
    /// - ``t``: a tab character
    /// - ``T``: the time in 24-hour notation with seconds (``H`:`M`:`S``)
    /// - ``u``: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
    ///    Monday being 1. This works well with ``G`` and ``V``.
    /// - ``V``: the ISO 8601 standard week number of the current year as a decimal
    ///   number, range 01 to 53, where week 1 is the first week that has at
    ///   least 4 days in the new year. See g_date_time_get_week_of_year().
    ///   This works well with ``G`` and ``u``.
    /// - ``w``: the day of the week as a decimal, range 0 to 6, Sunday being 0.
    ///   This is not the ISO 8601 standard format — use ``u`` instead.
    /// - ``x``: the preferred date representation for the current locale without
    ///   the time
    /// - ``X``: the preferred time representation for the current locale without
    ///   the date
    /// - ``y``: the year as a decimal number without the century
    /// - ``Y``: the year as a decimal number including the century
    /// - ``z``: the time zone as an offset from UTC (`+hhmm`)
    /// - `%:z`: the time zone as an offset from UTC (`+hh:mm`).
    ///   This is a gnulib `strftime()` extension. Since: 2.38
    /// - `%::z`: the time zone as an offset from UTC (`+hh:mm:ss`). This is a
    ///   gnulib `strftime()` extension. Since: 2.38
    /// - `%:::z`: the time zone as an offset from UTC, with `:` to necessary
    ///   precision (e.g., `-04`, `+05:30`). This is a gnulib `strftime()` extension. Since: 2.38
    /// - ``Z``: the time zone or name or abbreviation
    /// - `%%`: a literal `%` character
    ///
    /// Some conversion specifications can be modified by preceding the
    /// conversion specifier by one or more modifier characters.
    ///
    /// The following modifiers are supported for many of the numeric
    /// conversions:
    ///
    /// - `O`: Use alternative numeric symbols, if the current locale supports those.
    /// - `_`: Pad a numeric result with spaces. This overrides the default padding
    ///   for the specifier.
    /// - `-`: Do not pad a numeric result. This overrides the default padding
    ///   for the specifier.
    /// - `0`: Pad a numeric result with zeros. This overrides the default padding
    ///   for the specifier.
    ///
    /// The following modifiers are supported for many of the alphabetic conversions:
    ///
    /// - `^`: Use upper case if possible. This is a gnulib `strftime()` extension.
    ///   Since: 2.80
    /// - `#`: Use opposite case if possible. This is a gnulib `strftime()`
    ///   extension. Since: 2.80
    ///
    /// Additionally, when `O` is used with `B`, `b`, or `h`, it produces the alternative
    /// form of a month name. The alternative form should be used when the month
    /// name is used without a day number (e.g., standalone). It is required in
    /// some languages (Baltic, Slavic, Greek, and more) due to their grammatical
    /// rules. For other languages there is no difference. ``OB`` is a GNU and BSD
    /// `strftime()` extension expected to be added to the future POSIX specification,
    /// ``Ob`` and ``Oh`` are GNU `strftime()` extensions. Since: 2.56
    ///
    /// Since GLib 2.80, when `E` is used with ``c``, ``C``, ``x``, ``X``, ``y`` or ``Y``,
    /// the date is formatted using an alternate era representation specific to the
    /// locale. This is typically used for the Thai solar calendar or Japanese era
    /// names, for example.
    ///
    /// - ``Ec``: the preferred date and time representation for the current locale,
    ///   using the alternate era representation
    /// - ``EC``: the name of the era
    /// - ``Ex``: the preferred date representation for the current locale without
    ///   the time, using the alternate era representation
    /// - ``EX``: the preferred time representation for the current locale without
    ///   the date, using the alternate era representation
    /// - ``Ey``: the year since the beginning of the era denoted by the ``EC``
    ///   specifier
    /// - ``EY``: the full alternative year representation
    /// ## `format`
    /// a valid UTF-8 string, containing the format for the
    ///          #GDateTime
    ///
    /// # Returns
    ///
    /// a newly allocated string formatted to
    ///    the requested format or [`None`] in the case that there was an error (such
    ///    as a format specifier not being supported in the current locale). The
    ///    string should be freed with g_free().
    #[doc(alias = "g_date_time_format")]
    pub fn format(&self, format: &str) -> Result<crate::GString, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_format(
                self.to_glib_none().0,
                format.to_glib_none().0,
            ))
            .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Format @self in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601),
    /// including the date, time and time zone, and return that as a UTF-8 encoded
    /// string.
    ///
    /// Since GLib 2.66, this will output to sub-second precision if needed.
    ///
    /// # Returns
    ///
    /// a newly allocated string formatted in
    ///   ISO 8601 format or [`None`] in the case that there was an error. The string
    ///   should be freed with g_free().
    #[cfg(feature = "v2_62")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_62")))]
    #[doc(alias = "g_date_time_format_iso8601")]
    pub fn format_iso8601(&self) -> Result<crate::GString, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_format_iso8601(self.to_glib_none().0))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Retrieves the day of the month represented by @self in the gregorian
    /// calendar.
    ///
    /// # Returns
    ///
    /// the day of the month
    #[doc(alias = "g_date_time_get_day_of_month")]
    #[doc(alias = "get_day_of_month")]
    pub fn day_of_month(&self) -> i32 {
        unsafe { ffi::g_date_time_get_day_of_month(self.to_glib_none().0) }
    }

    /// Retrieves the ISO 8601 day of the week on which @self falls (1 is
    /// Monday, 2 is Tuesday... 7 is Sunday).
    ///
    /// # Returns
    ///
    /// the day of the week
    #[doc(alias = "g_date_time_get_day_of_week")]
    #[doc(alias = "get_day_of_week")]
    pub fn day_of_week(&self) -> i32 {
        unsafe { ffi::g_date_time_get_day_of_week(self.to_glib_none().0) }
    }

    /// Retrieves the day of the year represented by @self in the Gregorian
    /// calendar.
    ///
    /// # Returns
    ///
    /// the day of the year
    #[doc(alias = "g_date_time_get_day_of_year")]
    #[doc(alias = "get_day_of_year")]
    pub fn day_of_year(&self) -> i32 {
        unsafe { ffi::g_date_time_get_day_of_year(self.to_glib_none().0) }
    }

    /// Retrieves the hour of the day represented by @self
    ///
    /// # Returns
    ///
    /// the hour of the day
    #[doc(alias = "g_date_time_get_hour")]
    #[doc(alias = "get_hour")]
    pub fn hour(&self) -> i32 {
        unsafe { ffi::g_date_time_get_hour(self.to_glib_none().0) }
    }

    /// Retrieves the microsecond of the date represented by @self
    ///
    /// # Returns
    ///
    /// the microsecond of the second
    #[doc(alias = "g_date_time_get_microsecond")]
    #[doc(alias = "get_microsecond")]
    pub fn microsecond(&self) -> i32 {
        unsafe { ffi::g_date_time_get_microsecond(self.to_glib_none().0) }
    }

    /// Retrieves the minute of the hour represented by @self
    ///
    /// # Returns
    ///
    /// the minute of the hour
    #[doc(alias = "g_date_time_get_minute")]
    #[doc(alias = "get_minute")]
    pub fn minute(&self) -> i32 {
        unsafe { ffi::g_date_time_get_minute(self.to_glib_none().0) }
    }

    /// Retrieves the month of the year represented by @self in the Gregorian
    /// calendar.
    ///
    /// # Returns
    ///
    /// the month represented by @self
    #[doc(alias = "g_date_time_get_month")]
    #[doc(alias = "get_month")]
    pub fn month(&self) -> i32 {
        unsafe { ffi::g_date_time_get_month(self.to_glib_none().0) }
    }

    /// Retrieves the second of the minute represented by @self
    ///
    /// # Returns
    ///
    /// the second represented by @self
    #[doc(alias = "g_date_time_get_second")]
    #[doc(alias = "get_second")]
    pub fn second(&self) -> i32 {
        unsafe { ffi::g_date_time_get_second(self.to_glib_none().0) }
    }

    /// Retrieves the number of seconds since the start of the last minute,
    /// including the fractional part.
    ///
    /// # Returns
    ///
    /// the number of seconds
    #[doc(alias = "g_date_time_get_seconds")]
    #[doc(alias = "get_seconds")]
    pub fn seconds(&self) -> f64 {
        unsafe { ffi::g_date_time_get_seconds(self.to_glib_none().0) }
    }

    /// Get the time zone for this @self.
    ///
    /// # Returns
    ///
    /// the time zone
    #[cfg(feature = "v2_58")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_58")))]
    #[doc(alias = "g_date_time_get_timezone")]
    #[doc(alias = "get_timezone")]
    pub fn timezone(&self) -> TimeZone {
        unsafe { from_glib_none(ffi::g_date_time_get_timezone(self.to_glib_none().0)) }
    }

    /// Determines the time zone abbreviation to be used at the time and in
    /// the time zone of @self.
    ///
    /// For example, in Toronto this is currently "EST" during the winter
    /// months and "EDT" during the summer months when daylight savings
    /// time is in effect.
    ///
    /// # Returns
    ///
    /// the time zone abbreviation. The returned
    ///          string is owned by the #GDateTime and it should not be
    ///          modified or freed
    #[doc(alias = "g_date_time_get_timezone_abbreviation")]
    #[doc(alias = "get_timezone_abbreviation")]
    pub fn timezone_abbreviation(&self) -> crate::GString {
        unsafe {
            from_glib_none(ffi::g_date_time_get_timezone_abbreviation(
                self.to_glib_none().0,
            ))
        }
    }

    /// Determines the offset to UTC in effect at the time and in the time
    /// zone of @self.
    ///
    /// The offset is the number of microseconds that you add to UTC time to
    /// arrive at local time for the time zone (ie: negative numbers for time
    /// zones west of GMT, positive numbers for east).
    ///
    /// If @self represents UTC time, then the offset is always zero.
    ///
    /// # Returns
    ///
    /// the number of microseconds that should be added to UTC to
    ///          get the local time
    #[doc(alias = "g_date_time_get_utc_offset")]
    #[doc(alias = "get_utc_offset")]
    pub fn utc_offset(&self) -> TimeSpan {
        unsafe { from_glib(ffi::g_date_time_get_utc_offset(self.to_glib_none().0)) }
    }

    /// Returns the ISO 8601 week-numbering year in which the week containing
    /// @self falls.
    ///
    /// This function, taken together with g_date_time_get_week_of_year() and
    /// g_date_time_get_day_of_week() can be used to determine the full ISO
    /// week date on which @self falls.
    ///
    /// This is usually equal to the normal Gregorian year (as returned by
    /// g_date_time_get_year()), except as detailed below:
    ///
    /// For Thursday, the week-numbering year is always equal to the usual
    /// calendar year.  For other days, the number is such that every day
    /// within a complete week (Monday to Sunday) is contained within the
    /// same week-numbering year.
    ///
    /// For Monday, Tuesday and Wednesday occurring near the end of the year,
    /// this may mean that the week-numbering year is one greater than the
    /// calendar year (so that these days have the same week-numbering year
    /// as the Thursday occurring early in the next year).
    ///
    /// For Friday, Saturday and Sunday occurring near the start of the year,
    /// this may mean that the week-numbering year is one less than the
    /// calendar year (so that these days have the same week-numbering year
    /// as the Thursday occurring late in the previous year).
    ///
    /// An equivalent description is that the week-numbering year is equal to
    /// the calendar year containing the majority of the days in the current
    /// week (Monday to Sunday).
    ///
    /// Note that January 1 0001 in the proleptic Gregorian calendar is a
    /// Monday, so this function never returns 0.
    ///
    /// # Returns
    ///
    /// the ISO 8601 week-numbering year for @self
    #[doc(alias = "g_date_time_get_week_numbering_year")]
    #[doc(alias = "get_week_numbering_year")]
    pub fn week_numbering_year(&self) -> i32 {
        unsafe { ffi::g_date_time_get_week_numbering_year(self.to_glib_none().0) }
    }

    /// Returns the ISO 8601 week number for the week containing @self.
    /// The ISO 8601 week number is the same for every day of the week (from
    /// Moday through Sunday).  That can produce some unusual results
    /// (described below).
    ///
    /// The first week of the year is week 1.  This is the week that contains
    /// the first Thursday of the year.  Equivalently, this is the first week
    /// that has more than 4 of its days falling within the calendar year.
    ///
    /// The value 0 is never returned by this function.  Days contained
    /// within a year but occurring before the first ISO 8601 week of that
    /// year are considered as being contained in the last week of the
    /// previous year.  Similarly, the final days of a calendar year may be
    /// considered as being part of the first ISO 8601 week of the next year
    /// if 4 or more days of that week are contained within the new year.
    ///
    /// # Returns
    ///
    /// the ISO 8601 week number for @self.
    #[doc(alias = "g_date_time_get_week_of_year")]
    #[doc(alias = "get_week_of_year")]
    pub fn week_of_year(&self) -> i32 {
        unsafe { ffi::g_date_time_get_week_of_year(self.to_glib_none().0) }
    }

    /// Retrieves the year represented by @self in the Gregorian calendar.
    ///
    /// # Returns
    ///
    /// the year represented by @self
    #[doc(alias = "g_date_time_get_year")]
    #[doc(alias = "get_year")]
    pub fn year(&self) -> i32 {
        unsafe { ffi::g_date_time_get_year(self.to_glib_none().0) }
    }

    /// Retrieves the Gregorian day, month, and year of a given #GDateTime.
    ///
    /// # Returns
    ///
    ///
    /// ## `year`
    /// the return location for the gregorian year, or [`None`].
    ///
    /// ## `month`
    /// the return location for the month of the year, or [`None`].
    ///
    /// ## `day`
    /// the return location for the day of the month, or [`None`].
    #[doc(alias = "g_date_time_get_ymd")]
    #[doc(alias = "get_ymd")]
    pub fn ymd(&self) -> (i32, i32, i32) {
        unsafe {
            let mut year = std::mem::MaybeUninit::uninit();
            let mut month = std::mem::MaybeUninit::uninit();
            let mut day = std::mem::MaybeUninit::uninit();
            ffi::g_date_time_get_ymd(
                self.to_glib_none().0,
                year.as_mut_ptr(),
                month.as_mut_ptr(),
                day.as_mut_ptr(),
            );
            (year.assume_init(), month.assume_init(), day.assume_init())
        }
    }

    #[doc(alias = "g_date_time_hash")]
    fn hash(&self) -> u32 {
        unsafe {
            ffi::g_date_time_hash(
                ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(self).0 as ffi::gconstpointer,
            )
        }
    }

    /// Determines if daylight savings time is in effect at the time and in
    /// the time zone of @self.
    ///
    /// # Returns
    ///
    /// [`true`] if daylight savings time is in effect
    #[doc(alias = "g_date_time_is_daylight_savings")]
    pub fn is_daylight_savings(&self) -> bool {
        unsafe { from_glib(ffi::g_date_time_is_daylight_savings(self.to_glib_none().0)) }
    }

    /// Creates a new #GDateTime corresponding to the same instant in time as
    /// @self, but in the local time zone.
    ///
    /// This call is equivalent to calling g_date_time_to_timezone() with the
    /// time zone returned by g_time_zone_new_local().
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_to_local")]
    pub fn to_local(&self) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_to_local(self.to_glib_none().0))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    //#[cfg_attr(feature = "v2_62", deprecated = "Since 2.62")]
    //#[allow(deprecated)]
    //#[doc(alias = "g_date_time_to_timeval")]
    //pub fn to_timeval(&self, tv: /*Ignored*/&mut TimeVal) -> bool {
    //    unsafe { TODO: call ffi:g_date_time_to_timeval() }
    //}

    /// Create a new #GDateTime corresponding to the same instant in time as
    /// @self, but in the time zone @tz.
    ///
    /// This call can fail in the case that the time goes out of bounds.  For
    /// example, converting 0001-01-01 00:00:00 UTC to a time zone west of
    /// Greenwich will fail (due to the year 0 being out of range).
    /// ## `tz`
    /// the new #GTimeZone
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_to_timezone")]
    pub fn to_timezone(&self, tz: &TimeZone) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_to_timezone(
                self.to_glib_none().0,
                tz.to_glib_none().0,
            ))
            .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }

    /// Gives the Unix time corresponding to @self, rounding down to the
    /// nearest second.
    ///
    /// Unix time is the number of seconds that have elapsed since 1970-01-01
    /// 00:00:00 UTC, regardless of the time zone associated with @self.
    ///
    /// # Returns
    ///
    /// the Unix time corresponding to @self
    #[doc(alias = "g_date_time_to_unix")]
    pub fn to_unix(&self) -> i64 {
        unsafe { ffi::g_date_time_to_unix(self.to_glib_none().0) }
    }

    /// Gives the Unix time corresponding to @self, in microseconds.
    ///
    /// Unix time is the number of microseconds that have elapsed since 1970-01-01
    /// 00:00:00 UTC, regardless of the time zone associated with @self.
    ///
    /// # Returns
    ///
    /// the Unix time corresponding to @self
    #[cfg(feature = "v2_80")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
    #[doc(alias = "g_date_time_to_unix_usec")]
    pub fn to_unix_usec(&self) -> i64 {
        unsafe { ffi::g_date_time_to_unix_usec(self.to_glib_none().0) }
    }

    /// Creates a new #GDateTime corresponding to the same instant in time as
    /// @self, but in UTC.
    ///
    /// This call is equivalent to calling g_date_time_to_timezone() with the
    /// time zone returned by g_time_zone_new_utc().
    ///
    /// # Returns
    ///
    /// the newly created #GDateTime which
    ///   should be freed with g_date_time_unref(), or [`None`]
    #[doc(alias = "g_date_time_to_utc")]
    pub fn to_utc(&self) -> Result<DateTime, BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::g_date_time_to_utc(self.to_glib_none().0))
                .ok_or_else(|| crate::bool_error!("Invalid date"))
        }
    }
}

impl PartialOrd for DateTime {
    #[inline]
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for DateTime {
    #[inline]
    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
        self.compare(other).cmp(&0)
    }
}

impl PartialEq for DateTime {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.equal(other)
    }
}

impl Eq for DateTime {}

impl std::hash::Hash for DateTime {
    #[inline]
    fn hash<H>(&self, state: &mut H)
    where
        H: std::hash::Hasher,
    {
        std::hash::Hash::hash(&self.hash(), state)
    }
}

unsafe impl Send for DateTime {}
unsafe impl Sync for DateTime {}