spinoso_time/time/tzrs/

timezone.rs

use tz::datetime::DateTime;

use super::{Offset, Result, Time};

// Timezone conversions (returns new Time)
impl Time {
    /// Returns a new Time object representing _time_ based on the provided
    /// offset.
    ///
    /// Can be used to implement [`Time#getlocal`] with a string/number
    /// parameter.
    ///
    /// # Examples
    ///
    /// ```
    /// use tzdb::time_zone::europe::AMSTERDAM;
    /// # use spinoso_time::tzrs::{Offset, Time, TimeError};
    /// # fn example() -> Result<(), TimeError> {
    /// let ams_offset = Offset::from(AMSTERDAM);
    /// let now_utc = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
    /// let now_ams = now_utc.to_offset(ams_offset)?;
    /// assert!(!now_ams.is_utc());
    /// # Ok(())
    /// # }
    /// # example().unwrap()
    /// ```
    ///
    /// # Errors
    ///
    /// Can produce a [`TimeError`], might come as a result of an offset causing
    /// the `unix_time` to exceed `i64::MAX`.
    ///
    /// [`Time#getlocal`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-getlocal
    /// [`TimeError`]: super::TimeError
    #[inline]
    pub fn to_offset(&self, offset: Offset) -> Result<Self> {
        Self::with_timespec_and_offset(self.inner.unix_time(), self.inner.nanoseconds(), offset)
    }

    /// Returns a new _time_ in UTC.
    ///
    /// Can be used to implement [`Time#getutc`] and [`Time#getgm`].
    ///
    /// # Examples
    ///
    /// ```
    /// # use spinoso_time::tzrs::{Time, TimeError};
    /// # fn example() -> Result<(), TimeError> {
    /// let now_local = Time::now()?;
    /// let now_utc = now_local.to_utc()?;
    /// assert_eq!(now_utc.utc_offset(), 0);
    /// assert!(now_utc.is_utc());
    /// # Ok(())
    /// # }
    /// # example().unwrap()
    /// ```
    ///
    /// # Errors
    ///
    /// Can produce a [`TimeError`], might come as a result of an offset causing
    /// the `unix_time` to exceed `i64::MAX`.
    ///
    ///
    /// [`Time#getutc`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-getutc
    /// [`Time#getgm`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-getgm
    /// [`TimeError`]: super::TimeError
    #[inline]
    pub fn to_utc(&self) -> Result<Self> {
        self.to_offset(Offset::utc())
    }

    /// Returns a new Time object representing _time_ in local time (using the
    /// local time zone in effect for this process).
    ///
    /// Can be used to implement [`Time#getlocal`].
    ///
    /// # Examples
    ///
    /// ```
    /// # use spinoso_time::tzrs::{Time, TimeError};
    /// # fn example() -> Result<(), TimeError> {
    /// let now_utc = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
    /// let now_local = Time::local(2022, 7, 8, 12, 34, 56, 0)?;
    /// assert_eq!(now_utc.to_local()?.utc_offset(), now_local.utc_offset());
    /// # Ok(())
    /// # }
    /// # example().unwrap()
    /// ```
    ///
    /// # Errors
    ///
    /// Can produce a [`TimeError`], might come as a result of an offset causing
    /// the `unix_time` to exceed `i64::MAX`.
    ///
    /// [`Time#getlocal`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-getlocal
    /// [`TimeError`]: super::TimeError
    #[inline]
    pub fn to_local(&self) -> Result<Self> {
        self.to_offset(Offset::local())
    }
}

// Timezone mutations
impl Time {
    /// Converts _time_ to the provided time zone, modifying the receiver.
    ///
    /// # Examples
    ///
    /// ```
    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
    /// # fn example() -> Result<(), TimeError> {
    /// let mut now = Time::utc(2022, 6, 8, 12, 0, 0, 0)?;
    /// let gmt_plus_one = Offset::try_from(3600)?;
    /// now.set_offset(gmt_plus_one);
    /// assert_eq!(13, now.hour());
    /// # Ok(())
    /// # }
    /// # example().unwrap()
    /// ```
    ///
    /// # Errors
    ///
    /// Can produce a [`TimeError`], might come as a result of an offset causing
    /// the `unix_time` to exceed `i64::MAX`.
    ///
    /// [`TimeError`]: super::TimeError
    #[inline]
    pub fn set_offset(&mut self, offset: Offset) -> Result<()> {
        let time_zone_ref = offset.time_zone_ref();

        let time = self.inner.project(time_zone_ref)?;
        self.inner = time;
        self.offset = offset;
        Ok(())
    }

    /// Converts _time_ to local time (using the local time zone in effective at
    /// the creation time of _time_), modifying the receiver.
    ///
    /// Can be used to implement [`Time#localtime`] without a parameter.
    ///
    /// # Examples
    ///
    /// ```
    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
    /// # fn example() -> Result<(), TimeError> {
    /// let mut now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
    /// let now_utc_unix = now.to_int();
    /// now.set_local();
    /// assert!(!now.is_utc());
    /// let now_local_unix = now.to_int();
    /// assert_eq!(now_utc_unix, now_local_unix);
    /// # Ok(())
    /// # }
    /// # example().unwrap()
    /// ```
    ///
    /// # Errors
    ///
    /// Can produce a [`TimeError`], might come as a result of an offset causing
    /// the `unix_time` to exceed `i64::MAX`.
    ///
    /// [`Time#localtime`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-localtime
    /// [`TimeError`]: super::TimeError
    #[inline]
    pub fn set_local(&mut self) -> Result<()> {
        self.set_offset(Offset::local())
    }

    /// Converts _time_ to UTC (GMT), modifying the receiver.
    ///
    /// Can be used to implement [`Time#utc`] and [`Time#gmtime`].
    ///
    /// # Examples
    ///
    /// ```
    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
    /// # fn example() -> Result<(), TimeError> {
    /// let mut now = Time::local(2022, 7, 8, 12, 34, 56, 0)?;
    /// let now_local_unix = now.to_int();
    /// now.set_utc();
    /// assert!(now.is_utc());
    /// let now_utc_unix = now.to_int();
    /// assert_eq!(now_local_unix, now_utc_unix);
    /// # Ok(())
    /// # }
    /// # example().unwrap()
    /// ```
    ///
    /// # Errors
    ///
    /// Can produce a [`TimeError`], might come as a result of an offset causing
    /// the `unix_time` to exceed `i64::MAX`.
    ///
    /// [`Time#utc`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-utc
    /// [`Time#gmtime`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-gmtime
    /// [`TimeError`]: super::TimeError
    #[inline]
    pub fn set_utc(&mut self) -> Result<()> {
        self.set_offset(Offset::utc())
    }

    /// Converts _time_ to the GMT time zone with the provided offset.
    ///
    /// Can be used to implement [`Time#localtime`] with an offset parameter.
    ///
    /// # Examples
    ///
    /// ```
    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
    /// # fn example() -> Result<(), TimeError> {
    /// let mut now = Time::utc(2022, 7, 8, 12, 34, 56, 0)?;
    /// assert!(now.is_utc());
    /// let offset = Offset::try_from(3600)?;
    /// now.set_offset_from_utc(offset);
    /// assert!(!now.is_utc());
    /// assert_eq!(now.utc_offset(), 3600);
    /// # Ok(())
    /// # }
    /// # example().unwrap()
    /// ```
    ///
    /// # Errors
    ///
    /// Can produce a [`TimeError`], might come as a result of an offset causing
    /// the `unix_time` to exceed `i64::MAX`.
    ///
    /// [`Time#localtime`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-localtime
    /// [`TimeError`]: super::TimeError
    #[inline]
    pub fn set_offset_from_utc(&mut self, offset: Offset) -> Result<()> {
        let time_zone_ref = offset.time_zone_ref();

        self.inner = DateTime::from_timespec(self.to_int(), self.nanoseconds(), time_zone_ref)?;
        self.offset = offset;

        Ok(())
    }
}