spinoso_time/time/tzrs/
convert.rs

1use core::fmt;
2
3use super::{Time, ToA};
4
5impl fmt::Display for Time {
6    /// Returns a canonical string representation of _time_.
7    ///
8    /// `Display` uses the same format as [`Time#to_s`].
9    ///
10    /// # Examples
11    ///
12    /// ```
13    /// # use spinoso_time::tzrs::{Time, TimeError};
14    /// # fn example() -> Result<(), TimeError> {
15    /// let now = Time::utc(2022, 05, 26, 13, 16, 22, 0)?;
16    /// assert_eq!(now.to_string(), "2022-05-26 13:16:22 UTC");
17    /// # Ok(())
18    /// # }
19    /// # example().unwrap()
20    /// ```
21    ///
22    /// [`Time#to_s`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-to_s
23    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
24        // https://github.com/ruby/ruby/blob/v3_1_2/time.c#L4007-L4017
25        const UTC_FORMAT: &str = "%Y-%m-%d %H:%M:%S UTC";
26        const FORMAT: &str = "%Y-%m-%d %H:%M:%S %z";
27
28        if self.is_utc() {
29            strftime::fmt::strftime(self, UTC_FORMAT, f).map_err(|_| fmt::Error)
30        } else {
31            strftime::fmt::strftime(self, FORMAT, f).map_err(|_| fmt::Error)
32        }
33    }
34}
35
36// Conversions
37impl Time {
38    /// Formats _time_ according to the directives in the given format string.
39    ///
40    /// Can be used to implement [`Time#strftime`]. The resulting byte string
41    /// will have the same encoding as the format byte slice.
42    ///
43    /// # Examples
44    ///
45    /// ```
46    /// # use spinoso_time::tzrs::{TimeError, Time};
47    /// # #[derive(Debug)]
48    /// # enum Error { Time(TimeError), Strftime(strftime::Error) };
49    /// # impl From<TimeError> for Error { fn from(err: TimeError) -> Self { Self::Time(err) } }
50    /// # impl From<strftime::Error> for Error { fn from(err: strftime::Error) -> Self { Self::Strftime(err) } }
51    /// # fn example() -> Result<(), Error> {
52    /// let now = Time::utc(2022, 05, 26, 13, 16, 22, 276)?;
53    /// assert_eq!(
54    ///     now.strftime("Today is %c 🎉".as_bytes())?,
55    ///     "Today is Thu May 26 13:16:22 2022 🎉".as_bytes(),
56    /// );
57    /// # Ok(())
58    /// # }
59    /// # example().unwrap()
60    /// ```
61    ///
62    /// # Errors
63    ///
64    /// Can return [`strftime::Error`] if formatting fails. See
65    /// [`strftime::bytes::strftime`] for more details.
66    ///
67    /// [`Time#strftime`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-strftime
68    #[inline]
69    pub fn strftime(&self, format: &[u8]) -> Result<Vec<u8>, strftime::Error> {
70        // Requires ASCII-compatible encoding (which rules out things like
71        // UTF-16). ASCII, Binary, and UTF-8 are considered ASCII-compatible.
72        //
73        // ```
74        // [3.1.2] * Time.now.strftime("abc %c")
75        // => "abc Sat Aug 20 12:18:56 2022"
76        // [3.1.2] > Time.now.strftime("abc %c 📦")
77        // => "abc Sat Aug 20 12:19:04 2022 📦"
78        // [3.1.2] > Time.now.strftime("abc %c 📦 \xFF")
79        // => "abc Sat Aug 20 12:19:12 2022 📦 \xFF"
80        // [3.1.2] > Time.now.strftime("abc %c 📦 \xFF".encode(Encoding::UTF_16))
81        // (irb):5:in `encode': "\xFF" on UTF-8 (Encoding::InvalidByteSequenceError)
82        //         from (irb):5:in `<main>'
83        //         from /usr/local/var/rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/irb-1.4.1/exe/irb:11:in `<top (required)>'
84        //         from /usr/local/var/rbenv/versions/3.1.2/bin/irb:25:in `load'
85        //         from /usr/local/var/rbenv/versions/3.1.2/bin/irb:25:in `<main>'
86        // [3.1.2] > Time.now.strftime("abc %c 📦 \xFF".encode(Encoding::UTF_8))
87        // => "abc Sat Aug 20 12:20:10 2022 📦 \xFF"
88        // ```
89        strftime::bytes::strftime(self, format)
90    }
91
92    /// Serialize a `Time` into its components as a [`ToA`].
93    ///
94    /// `ToA` stores a `Time` as a ten-element struct of time components: [sec,
95    /// min, hour, day, month, year, wday, yday, isdst, zone].
96    ///
97    /// The ordering of the properties is important for the Ruby [`Time#to_a`]
98    /// API.
99    ///
100    /// Can be used to implement [`Time#to_a`].
101    ///
102    /// # Examples
103    ///
104    /// ```
105    /// # use spinoso_time::tzrs::{Time, TimeError};
106    /// # fn example() -> Result<(), TimeError> {
107    /// let now = Time::now()?;
108    /// let to_array = now.to_array();
109    /// assert_eq!(to_array.sec, now.second());
110    /// assert_eq!(to_array.wday, now.day_of_week());
111    /// # Ok(())
112    /// # }
113    /// # example().unwrap()
114    /// ```
115    ///
116    /// [`Time#to_a`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-to_a
117    #[inline]
118    #[must_use]
119    pub fn to_array(self) -> ToA {
120        ToA::from(self)
121    }
122}
spinoso_time/time/tzrs/convert.rs

spinoso_time/time/tzrs/
convert.rs
