time/formatting/
formattable.rs

Help
1//! A trait that can be used to format an item from its components.
2
3use alloc::string::String;
4use alloc::vec::Vec;
5use core::ops::Deref;
6use std::io;
7
8use num_conv::prelude::*;
9
10use crate::format_description::well_known::iso8601::EncodedConfig;
11use crate::format_description::well_known::{Iso8601, Rfc2822, Rfc3339};
12use crate::format_description::{BorrowedFormatItem, OwnedFormatItem};
13use crate::formatting::{
14    format_component, format_number_pad_zero, iso8601, write, MONTH_NAMES, WEEKDAY_NAMES,
15};
16use crate::{error, Date, Time, UtcOffset};
17
18/// A type that describes a format.
19///
20/// Implementors of [`Formattable`] are [format descriptions](crate::format_description).
21///
22/// [`Date::format`] and [`Time::format`] each use a format description to generate
23/// a String from their data. See the respective methods for usage examples.
24#[cfg_attr(docsrs, doc(notable_trait))]
25pub trait Formattable: sealed::Sealed {}
26impl Formattable for BorrowedFormatItem<'_> {}
27impl Formattable for [BorrowedFormatItem<'_>] {}
28impl Formattable for OwnedFormatItem {}
29impl Formattable for [OwnedFormatItem] {}
30impl Formattable for Rfc3339 {}
31impl Formattable for Rfc2822 {}
32impl<const CONFIG: EncodedConfig> Formattable for Iso8601<CONFIG> {}
33impl<T: Deref> Formattable for T where T::Target: Formattable {}
34
35/// Seal the trait to prevent downstream users from implementing it.
36mod sealed {
37    #[allow(clippy::wildcard_imports)]
38    use super::*;
39
40    /// Format the item using a format description, the intended output, and the various components.
41    pub trait Sealed {
42        /// Format the item into the provided output, returning the number of bytes written.
43        fn format_into(
44            &self,
45            output: &mut (impl io::Write + ?Sized),
46            date: Option<Date>,
47            time: Option<Time>,
48            offset: Option<UtcOffset>,
49        ) -> Result<usize, error::Format>;
50
51        /// Format the item directly to a `String`.
52        fn format(
53            &self,
54            date: Option<Date>,
55            time: Option<Time>,
56            offset: Option<UtcOffset>,
57        ) -> Result<String, error::Format> {
58            let mut buf = Vec::new();
59            self.format_into(&mut buf, date, time, offset)?;
60            Ok(String::from_utf8_lossy(&buf).into_owned())
61        }
62    }
63}
64
65impl sealed::Sealed for BorrowedFormatItem<'_> {
66    fn format_into(
67        &self,
68        output: &mut (impl io::Write + ?Sized),
69        date: Option<Date>,
70        time: Option<Time>,
71        offset: Option<UtcOffset>,
72    ) -> Result<usize, error::Format> {
73        Ok(match *self {
74            Self::Literal(literal) => write(output, literal)?,
75            Self::Component(component) => format_component(output, component, date, time, offset)?,
76            Self::Compound(items) => items.format_into(output, date, time, offset)?,
77            Self::Optional(item) => item.format_into(output, date, time, offset)?,
78            Self::First(items) => match items {
79                [] => 0,
80                [item, ..] => item.format_into(output, date, time, offset)?,
81            },
82        })
83    }
84}
85
86impl sealed::Sealed for [BorrowedFormatItem<'_>] {
87    fn format_into(
88        &self,
89        output: &mut (impl io::Write + ?Sized),
90        date: Option<Date>,
91        time: Option<Time>,
92        offset: Option<UtcOffset>,
93    ) -> Result<usize, error::Format> {
94        let mut bytes = 0;
95        for item in self.iter() {
96            bytes += item.format_into(output, date, time, offset)?;
97        }
98        Ok(bytes)
99    }
100}
101
102impl sealed::Sealed for OwnedFormatItem {
103    fn format_into(
104        &self,
105        output: &mut (impl io::Write + ?Sized),
106        date: Option<Date>,
107        time: Option<Time>,
108        offset: Option<UtcOffset>,
109    ) -> Result<usize, error::Format> {
110        match self {
111            Self::Literal(literal) => Ok(write(output, literal)?),
112            Self::Component(component) => format_component(output, *component, date, time, offset),
113            Self::Compound(items) => items.format_into(output, date, time, offset),
114            Self::Optional(item) => item.format_into(output, date, time, offset),
115            Self::First(items) => match &**items {
116                [] => Ok(0),
117                [item, ..] => item.format_into(output, date, time, offset),
118            },
119        }
120    }
121}
122
123impl sealed::Sealed for [OwnedFormatItem] {
124    fn format_into(
125        &self,
126        output: &mut (impl io::Write + ?Sized),
127        date: Option<Date>,
128        time: Option<Time>,
129        offset: Option<UtcOffset>,
130    ) -> Result<usize, error::Format> {
131        let mut bytes = 0;
132        for item in self.iter() {
133            bytes += item.format_into(output, date, time, offset)?;
134        }
135        Ok(bytes)
136    }
137}
138
139impl<T: Deref> sealed::Sealed for T
140where
141    T::Target: sealed::Sealed,
142{
143    fn format_into(
144        &self,
145        output: &mut (impl io::Write + ?Sized),
146        date: Option<Date>,
147        time: Option<Time>,
148        offset: Option<UtcOffset>,
149    ) -> Result<usize, error::Format> {
150        self.deref().format_into(output, date, time, offset)
151    }
152}
153
154impl sealed::Sealed for Rfc2822 {
155    fn format_into(
156        &self,
157        output: &mut (impl io::Write + ?Sized),
158        date: Option<Date>,
159        time: Option<Time>,
160        offset: Option<UtcOffset>,
161    ) -> Result<usize, error::Format> {
162        let date = date.ok_or(error::Format::InsufficientTypeInformation)?;
163        let time = time.ok_or(error::Format::InsufficientTypeInformation)?;
164        let offset = offset.ok_or(error::Format::InsufficientTypeInformation)?;
165
166        let mut bytes = 0;
167
168        let (year, month, day) = date.to_calendar_date();
169
170        if year < 1900 {
171            return Err(error::Format::InvalidComponent("year"));
172        }
173        if offset.seconds_past_minute() != 0 {
174            return Err(error::Format::InvalidComponent("offset_second"));
175        }
176
177        bytes += write(
178            output,
179            &WEEKDAY_NAMES[date.weekday().number_days_from_monday().extend::<usize>()][..3],
180        )?;
181        bytes += write(output, b", ")?;
182        bytes += format_number_pad_zero::<2>(output, day)?;
183        bytes += write(output, b" ")?;
184        bytes += write(
185            output,
186            &MONTH_NAMES[u8::from(month).extend::<usize>() - 1][..3],
187        )?;
188        bytes += write(output, b" ")?;
189        bytes += format_number_pad_zero::<4>(output, year.cast_unsigned())?;
190        bytes += write(output, b" ")?;
191        bytes += format_number_pad_zero::<2>(output, time.hour())?;
192        bytes += write(output, b":")?;
193        bytes += format_number_pad_zero::<2>(output, time.minute())?;
194        bytes += write(output, b":")?;
195        bytes += format_number_pad_zero::<2>(output, time.second())?;
196        bytes += write(output, b" ")?;
197        bytes += write(output, if offset.is_negative() { b"-" } else { b"+" })?;
198        bytes += format_number_pad_zero::<2>(output, offset.whole_hours().unsigned_abs())?;
199        bytes += format_number_pad_zero::<2>(output, offset.minutes_past_hour().unsigned_abs())?;
200
201        Ok(bytes)
202    }
203}
204
205impl sealed::Sealed for Rfc3339 {
206    fn format_into(
207        &self,
208        output: &mut (impl io::Write + ?Sized),
209        date: Option<Date>,
210        time: Option<Time>,
211        offset: Option<UtcOffset>,
212    ) -> Result<usize, error::Format> {
213        let date = date.ok_or(error::Format::InsufficientTypeInformation)?;
214        let time = time.ok_or(error::Format::InsufficientTypeInformation)?;
215        let offset = offset.ok_or(error::Format::InsufficientTypeInformation)?;
216
217        let mut bytes = 0;
218
219        let year = date.year();
220
221        if !(0..10_000).contains(&year) {
222            return Err(error::Format::InvalidComponent("year"));
223        }
224        if offset.whole_hours().unsigned_abs() > 23 {
225            return Err(error::Format::InvalidComponent("offset_hour"));
226        }
227        if offset.seconds_past_minute() != 0 {
228            return Err(error::Format::InvalidComponent("offset_second"));
229        }
230
231        bytes += format_number_pad_zero::<4>(output, year.cast_unsigned())?;
232        bytes += write(output, b"-")?;
233        bytes += format_number_pad_zero::<2>(output, u8::from(date.month()))?;
234        bytes += write(output, b"-")?;
235        bytes += format_number_pad_zero::<2>(output, date.day())?;
236        bytes += write(output, b"T")?;
237        bytes += format_number_pad_zero::<2>(output, time.hour())?;
238        bytes += write(output, b":")?;
239        bytes += format_number_pad_zero::<2>(output, time.minute())?;
240        bytes += write(output, b":")?;
241        bytes += format_number_pad_zero::<2>(output, time.second())?;
242
243        if time.nanosecond() != 0 {
244            let nanos = time.nanosecond();
245            bytes += write(output, b".")?;
246            bytes += if nanos % 10 != 0 {
247                format_number_pad_zero::<9>(output, nanos)
248            } else if (nanos / 10) % 10 != 0 {
249                format_number_pad_zero::<8>(output, nanos / 10)
250            } else if (nanos / 100) % 10 != 0 {
251                format_number_pad_zero::<7>(output, nanos / 100)
252            } else if (nanos / 1_000) % 10 != 0 {
253                format_number_pad_zero::<6>(output, nanos / 1_000)
254            } else if (nanos / 10_000) % 10 != 0 {
255                format_number_pad_zero::<5>(output, nanos / 10_000)
256            } else if (nanos / 100_000) % 10 != 0 {
257                format_number_pad_zero::<4>(output, nanos / 100_000)
258            } else if (nanos / 1_000_000) % 10 != 0 {
259                format_number_pad_zero::<3>(output, nanos / 1_000_000)
260            } else if (nanos / 10_000_000) % 10 != 0 {
261                format_number_pad_zero::<2>(output, nanos / 10_000_000)
262            } else {
263                format_number_pad_zero::<1>(output, nanos / 100_000_000)
264            }?;
265        }
266
267        if offset == UtcOffset::UTC {
268            bytes += write(output, b"Z")?;
269            return Ok(bytes);
270        }
271
272        bytes += write(output, if offset.is_negative() { b"-" } else { b"+" })?;
273        bytes += format_number_pad_zero::<2>(output, offset.whole_hours().unsigned_abs())?;
274        bytes += write(output, b":")?;
275        bytes += format_number_pad_zero::<2>(output, offset.minutes_past_hour().unsigned_abs())?;
276
277        Ok(bytes)
278    }
279}
280
281impl<const CONFIG: EncodedConfig> sealed::Sealed for Iso8601<CONFIG> {
282    fn format_into(
283        &self,
284        output: &mut (impl io::Write + ?Sized),
285        date: Option<Date>,
286        time: Option<Time>,
287        offset: Option<UtcOffset>,
288    ) -> Result<usize, error::Format> {
289        let mut bytes = 0;
290
291        if Self::FORMAT_DATE {
292            let date = date.ok_or(error::Format::InsufficientTypeInformation)?;
293            bytes += iso8601::format_date::<CONFIG>(output, date)?;
294        }
295        if Self::FORMAT_TIME {
296            let time = time.ok_or(error::Format::InsufficientTypeInformation)?;
297            bytes += iso8601::format_time::<CONFIG>(output, time)?;
298        }
299        if Self::FORMAT_OFFSET {
300            let offset = offset.ok_or(error::Format::InsufficientTypeInformation)?;
301            bytes += iso8601::format_offset::<CONFIG>(output, offset)?;
302        }
303
304        if bytes == 0 {
305            // The only reason there would be no bytes written is if the format was only for
306            // parsing.
307            panic!("attempted to format a parsing-only format description");
308        }
309
310        Ok(bytes)
311    }
312}
time/formatting/formattable.rs

time/formatting/
formattable.rs
