glib/auto/

time_zone.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::{ffi, translate::*, TimeType};

crate::wrapper! {
    /// A `GTimeZone` represents a time zone, at no particular point in time.
    ///
    /// The `GTimeZone` struct is refcounted and immutable.
    ///
    /// Each time zone has an identifier (for example, ‘Europe/London’) which is
    /// platform dependent. See `GLib::TimeZone::new()` for information on the
    /// identifier formats. The identifier of a time zone can be retrieved using
    /// [`identifier()`][Self::identifier()].
    ///
    /// A time zone contains a number of intervals. Each interval has an abbreviation
    /// to describe it (for example, ‘PDT’), an offset to UTC and a flag indicating
    /// if the daylight savings time is in effect during that interval. A time zone
    /// always has at least one interval — interval 0. Note that interval abbreviations
    /// are not the same as time zone identifiers (apart from ‘UTC’), and cannot be
    /// passed to `GLib::TimeZone::new()`.
    ///
    /// Every UTC time is contained within exactly one interval, but a given
    /// local time may be contained within zero, one or two intervals (due to
    /// incontinuities associated with daylight savings time).
    ///
    /// An interval may refer to a specific period of time (eg: the duration
    /// of daylight savings time during 2010) or it may refer to many periods
    /// of time that share the same properties (eg: all periods of daylight
    /// savings time).  It is also possible (usually for political reasons)
    /// that some properties (like the abbreviation) change between intervals
    /// without other properties changing.
    #[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 g_time_zone_new_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
    /// g_time_zone_new_identifier().
    ///
    /// # Deprecated since 2.68
    ///
    /// Use g_time_zone_new_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")]
    #[allow(deprecated)]
    #[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 #GTimeZone 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).
    ///
    /// g_time_zone_new_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(feature = "v2_68")]
    #[cfg_attr(docsrs, 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 #GTimeZone 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 g_time_zone_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 #GTimeZone corresponding to the given constant offset from UTC,
    /// in seconds.
    ///
    /// This is equivalent to calling g_time_zone_new() with a string in the form
    /// `[+|-]hh[:mm[:ss]]`.
    ///
    /// It is possible for this function to fail if @seconds is too big (greater than
    /// 24 hours), in which case this function will return the UTC timezone for
    /// backwards compatibility. To detect failures like this, use
    /// g_time_zone_new_identifier() directly.
    /// ## `seconds`
    /// offset to UTC, in seconds
    ///
    /// # Returns
    ///
    /// a timezone at the given offset from UTC, or UTC on
    ///   failure
    #[cfg(feature = "v2_58")]
    #[cfg_attr(docsrs, 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 #GTimeZone corresponding to UTC.
    ///
    /// This is equivalent to calling g_time_zone_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 #GTimeType 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 #GTimeZone, as passed to g_time_zone_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(feature = "v2_58")]
    #[cfg_attr(docsrs, 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 {}