// 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::translate::*;
use crate::TimeType;

crate::wrapper! {
    /// [`TimeZone`][crate::TimeZone] is an opaque structure whose members cannot be accessed
    /// directly.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct TimeZone(Shared<ffi::GTimeZone>);

    match fn {
        ref => |ptr| ffi::g_time_zone_ref(ptr),
        unref => |ptr| ffi::g_time_zone_unref(ptr),
        type_ => || ffi::g_time_zone_get_type(),
    }
}

impl TimeZone {
    /// A version of [`from_identifier()`][Self::from_identifier()] which returns the UTC time zone
    /// if `identifier` could not be parsed or loaded.
    ///
    /// If you need to check whether `identifier` was loaded successfully, use
    /// [`from_identifier()`][Self::from_identifier()].
    ///
    /// # Deprecated since 2.68
    ///
    /// Use [`from_identifier()`][Self::from_identifier()] instead, as it provides
    ///  error reporting. Change your code to handle a potentially [`None`] return
    ///  value.
    /// ## `identifier`
    /// a timezone identifier
    ///
    /// # Returns
    ///
    /// the requested timezone
    #[cfg_attr(feature = "v2_68", deprecated = "Since 2.68")]
    #[doc(alias = "g_time_zone_new")]
    pub fn new(identifier: Option<&str>) -> TimeZone {
        unsafe { from_glib_full(ffi::g_time_zone_new(identifier.to_glib_none().0)) }
    }

    /// Creates a [`TimeZone`][crate::TimeZone] corresponding to `identifier`. If `identifier` cannot be
    /// parsed or loaded, [`None`] is returned.
    ///
    /// `identifier` can either be an RFC3339/ISO 8601 time offset or
    /// something that would pass as a valid value for the `TZ` environment
    /// variable (including [`None`]).
    ///
    /// In Windows, `identifier` can also be the unlocalized name of a time
    /// zone for standard time, for example "Pacific Standard Time".
    ///
    /// Valid RFC3339 time offsets are `"Z"` (for UTC) or
    /// `"±hh:mm"`. ISO 8601 additionally specifies
    /// `"±hhmm"` and `"±hh"`. Offsets are
    /// time values to be added to Coordinated Universal Time (UTC) to get
    /// the local time.
    ///
    /// In UNIX, the `TZ` environment variable typically corresponds
    /// to the name of a file in the zoneinfo database, an absolute path to a file
    /// somewhere else, or a string in
    /// "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
    /// There are no spaces in the specification. The name of standard
    /// and daylight savings time zone must be three or more alphabetic
    /// characters. Offsets are time values to be added to local time to
    /// get Coordinated Universal Time (UTC) and should be
    /// `"[±]hh[[:]mm[:ss]]"`. Dates are either
    /// `"Jn"` (Julian day with n between 1 and 365, leap
    /// years not counted), `"n"` (zero-based Julian day
    /// with n between 0 and 365) or `"Mm.w.d"` (day d
    /// (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
    /// 0 is a Sunday). Times are in local wall clock time, the default is
    /// 02:00:00.
    ///
    /// In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
    /// accepts POSIX format. The Windows format uses US rules for all time
    /// zones; daylight savings time is 60 minutes behind the standard time
    /// with date and time of change taken from Pacific Standard Time.
    /// Offsets are time values to be added to the local time to get
    /// Coordinated Universal Time (UTC).
    ///
    /// [`local()`][Self::local()] calls this function with the value of the
    /// `TZ` environment variable. This function itself is independent of
    /// the value of `TZ`, but if `identifier` is [`None`] then `/etc/localtime`
    /// will be consulted to discover the correct time zone on UNIX and the
    /// registry will be consulted or GetTimeZoneInformation() will be used
    /// to get the local time zone on Windows.
    ///
    /// If intervals are not available, only time zone rules from `TZ`
    /// environment variable or other means, then they will be computed
    /// from year 1900 to 2037. If the maximum year for the rules is
    /// available and it is greater than 2037, then it will followed
    /// instead.
    ///
    /// See
    /// [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339`section`-5.6)
    /// for a precise definition of valid RFC3339 time offsets
    /// (the `time-offset` expansion) and ISO 8601 for the
    /// full list of valid time offsets. See
    /// [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
    /// for an explanation of the possible
    /// values of the `TZ` environment variable. See
    /// [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391`28v`=winembedded.11`29`)
    /// for the list of time zones on Windows.
    ///
    /// You should release the return value by calling `g_time_zone_unref()`
    /// when you are done with it.
    /// ## `identifier`
    /// a timezone identifier
    ///
    /// # Returns
    ///
    /// the requested timezone, or [`None`] on
    ///  failure
    #[cfg(any(feature = "v2_68", feature = "dox"))]
    #[cfg_attr(feature = "dox", doc(cfg(feature = "v2_68")))]
    #[doc(alias = "g_time_zone_new_identifier")]
    #[doc(alias = "new_identifier")]
    pub fn from_identifier(identifier: Option<&str>) -> Option<TimeZone> {
        unsafe { from_glib_full(ffi::g_time_zone_new_identifier(identifier.to_glib_none().0)) }
    }

    /// Creates a [`TimeZone`][crate::TimeZone] corresponding to local time. The local time
    /// zone may change between invocations to this function; for example,
    /// if the system administrator changes it.
    ///
    /// This is equivalent to calling [`new()`][Self::new()] with the value of
    /// the `TZ` environment variable (including the possibility of [`None`]).
    ///
    /// You should release the return value by calling `g_time_zone_unref()`
    /// when you are done with it.
    ///
    /// # Returns
    ///
    /// the local timezone
    #[doc(alias = "g_time_zone_new_local")]
    #[doc(alias = "new_local")]
    pub fn local() -> TimeZone {
        unsafe { from_glib_full(ffi::g_time_zone_new_local()) }
    }

    /// Creates a [`TimeZone`][crate::TimeZone] corresponding to the given constant offset from UTC,
    /// in seconds.
    ///
    /// This is equivalent to calling [`new()`][Self::new()] with a string in the form
    /// `[+|-]hh[:mm[:ss]]`.
    /// ## `seconds`
    /// offset to UTC, in seconds
    ///
    /// # Returns
    ///
    /// a timezone at the given offset from UTC
    #[cfg(any(feature = "v2_58", feature = "dox"))]
    #[cfg_attr(feature = "dox", doc(cfg(feature = "v2_58")))]
    #[doc(alias = "g_time_zone_new_offset")]
    #[doc(alias = "new_offset")]
    pub fn from_offset(seconds: i32) -> TimeZone {
        unsafe { from_glib_full(ffi::g_time_zone_new_offset(seconds)) }
    }

    /// Creates a [`TimeZone`][crate::TimeZone] corresponding to UTC.
    ///
    /// This is equivalent to calling [`new()`][Self::new()] with a value like
    /// "Z", "UTC", "+00", etc.
    ///
    /// You should release the return value by calling `g_time_zone_unref()`
    /// when you are done with it.
    ///
    /// # Returns
    ///
    /// the universal timezone
    #[doc(alias = "g_time_zone_new_utc")]
    #[doc(alias = "new_utc")]
    pub fn utc() -> TimeZone {
        unsafe { from_glib_full(ffi::g_time_zone_new_utc()) }
    }

    /// Finds an interval within `self` that corresponds to the given `time_`.
    /// The meaning of `time_` depends on `type_`.
    ///
    /// If `type_` is [`TimeType::Universal`][crate::TimeType::Universal] then this function will always
    /// succeed (since universal time is monotonic and continuous).
    ///
    /// Otherwise `time_` is treated as local time. The distinction between
    /// [`TimeType::Standard`][crate::TimeType::Standard] and [`TimeType::Daylight`][crate::TimeType::Daylight] is ignored except in
    /// the case that the given `time_` is ambiguous. In Toronto, for example,
    /// 01:30 on November 7th 2010 occurred twice (once inside of daylight
    /// savings time and the next, an hour later, outside of daylight savings
    /// time). In this case, the different value of `type_` would result in a
    /// different interval being returned.
    ///
    /// It is still possible for this function to fail. In Toronto, for
    /// example, 02:00 on March 14th 2010 does not exist (due to the leap
    /// forward to begin daylight savings time). -1 is returned in that
    /// case.
    /// ## `type_`
    /// the [`TimeType`][crate::TimeType] of `time_`
    /// ## `time_`
    /// a number of seconds since January 1, 1970
    ///
    /// # Returns
    ///
    /// the interval containing `time_`, or -1 in case of failure
    #[doc(alias = "g_time_zone_find_interval")]
    pub fn find_interval(&self, type_: TimeType, time_: i64) -> i32 {
        unsafe { ffi::g_time_zone_find_interval(self.to_glib_none().0, type_.into_glib(), time_) }
    }

    /// Determines the time zone abbreviation to be used during a particular
    /// `interval` of time in the time zone `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.
    /// ## `interval`
    /// an interval within the timezone
    ///
    /// # Returns
    ///
    /// the time zone abbreviation, which belongs to `self`
    #[doc(alias = "g_time_zone_get_abbreviation")]
    #[doc(alias = "get_abbreviation")]
    pub fn abbreviation(&self, interval: i32) -> crate::GString {
        unsafe {
            from_glib_none(ffi::g_time_zone_get_abbreviation(
                self.to_glib_none().0,
                interval,
            ))
        }
    }

    /// Get the identifier of this [`TimeZone`][crate::TimeZone], as passed to [`new()`][Self::new()].
    /// If the identifier passed at construction time was not recognised, `UTC` will
    /// be returned. If it was [`None`], the identifier of the local timezone at
    /// construction time will be returned.
    ///
    /// The identifier will be returned in the same format as provided at
    /// construction time: if provided as a time offset, that will be returned by
    /// this function.
    ///
    /// # Returns
    ///
    /// identifier for this timezone
    #[cfg(any(feature = "v2_58", feature = "dox"))]
    #[cfg_attr(feature = "dox", doc(cfg(feature = "v2_58")))]
    #[doc(alias = "g_time_zone_get_identifier")]
    #[doc(alias = "get_identifier")]
    pub fn identifier(&self) -> crate::GString {
        unsafe { from_glib_none(ffi::g_time_zone_get_identifier(self.to_glib_none().0)) }
    }

    /// Determines the offset to UTC in effect during a particular `interval`
    /// of time in the time zone `self`.
    ///
    /// The offset is the number of seconds that you add to UTC time to
    /// arrive at local time for `self` (ie: negative numbers for time zones
    /// west of GMT, positive numbers for east).
    /// ## `interval`
    /// an interval within the timezone
    ///
    /// # Returns
    ///
    /// the number of seconds that should be added to UTC to get the
    ///  local time in `self`
    #[doc(alias = "g_time_zone_get_offset")]
    #[doc(alias = "get_offset")]
    pub fn offset(&self, interval: i32) -> i32 {
        unsafe { ffi::g_time_zone_get_offset(self.to_glib_none().0, interval) }
    }

    /// Determines if daylight savings time is in effect during a particular
    /// `interval` of time in the time zone `self`.
    /// ## `interval`
    /// an interval within the timezone
    ///
    /// # Returns
    ///
    /// [`true`] if daylight savings time is in effect
    #[doc(alias = "g_time_zone_is_dst")]
    pub fn is_dst(&self, interval: i32) -> bool {
        unsafe { from_glib(ffi::g_time_zone_is_dst(self.to_glib_none().0, interval)) }
    }
}

unsafe impl Send for TimeZone {}
unsafe impl Sync for TimeZone {}