time/format_description/
borrowed_format_item.rs

1//! A format item with borrowed data.
2
3#[cfg(feature = "alloc")]
4use alloc::string::String;
5#[cfg(feature = "alloc")]
6use core::fmt;
7
8use crate::error;
9use crate::format_description::Component;
10
11/// A complete description of how to format and parse a type.
12#[non_exhaustive]
13#[cfg_attr(not(feature = "alloc"), derive(Debug))]
14#[derive(Clone, PartialEq, Eq)]
15pub enum BorrowedFormatItem<'a> {
16    /// Bytes that are formatted as-is.
17    ///
18    /// **Note**: These bytes **should** be UTF-8, but are not required to be. The value is passed
19    /// through `String::from_utf8_lossy` when necessary.
20    Literal(&'a [u8]),
21    /// A minimal representation of a single non-literal item.
22    Component(Component),
23    /// A series of literals or components that collectively form a partial or complete
24    /// description.
25    Compound(&'a [Self]),
26    /// A `FormatItem` that may or may not be present when parsing. If parsing fails, there
27    /// will be no effect on the resulting `struct`.
28    ///
29    /// This variant has no effect on formatting, as the value is guaranteed to be present.
30    Optional(&'a Self),
31    /// A series of `FormatItem`s where, when parsing, the first successful parse is used. When
32    /// formatting, the first element of the slice is used.  An empty slice is a no-op when
33    /// formatting or parsing.
34    First(&'a [Self]),
35}
36
37#[cfg(feature = "alloc")]
38impl fmt::Debug for BorrowedFormatItem<'_> {
39    #[inline]
40    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
41        match self {
42            Self::Literal(literal) => f.write_str(&String::from_utf8_lossy(literal)),
43            Self::Component(component) => component.fmt(f),
44            Self::Compound(compound) => compound.fmt(f),
45            Self::Optional(item) => f.debug_tuple("Optional").field(item).finish(),
46            Self::First(items) => f.debug_tuple("First").field(items).finish(),
47        }
48    }
49}
50
51impl From<Component> for BorrowedFormatItem<'_> {
52    #[inline]
53    fn from(component: Component) -> Self {
54        Self::Component(component)
55    }
56}
57
58impl TryFrom<BorrowedFormatItem<'_>> for Component {
59    type Error = error::DifferentVariant;
60
61    #[inline]
62    fn try_from(value: BorrowedFormatItem<'_>) -> Result<Self, Self::Error> {
63        match value {
64            BorrowedFormatItem::Component(component) => Ok(component),
65            _ => Err(error::DifferentVariant),
66        }
67    }
68}
69
70impl<'a> From<&'a [BorrowedFormatItem<'_>]> for BorrowedFormatItem<'a> {
71    #[inline]
72    fn from(items: &'a [BorrowedFormatItem<'_>]) -> Self {
73        Self::Compound(items)
74    }
75}
76
77impl<'a> TryFrom<BorrowedFormatItem<'a>> for &[BorrowedFormatItem<'a>] {
78    type Error = error::DifferentVariant;
79
80    #[inline]
81    fn try_from(value: BorrowedFormatItem<'a>) -> Result<Self, Self::Error> {
82        match value {
83            BorrowedFormatItem::Compound(items) => Ok(items),
84            _ => Err(error::DifferentVariant),
85        }
86    }
87}
88
89impl PartialEq<Component> for BorrowedFormatItem<'_> {
90    #[inline]
91    fn eq(&self, rhs: &Component) -> bool {
92        matches!(self, Self::Component(component) if component == rhs)
93    }
94}
95
96impl PartialEq<BorrowedFormatItem<'_>> for Component {
97    #[inline]
98    fn eq(&self, rhs: &BorrowedFormatItem<'_>) -> bool {
99        rhs == self
100    }
101}
102
103impl PartialEq<&[Self]> for BorrowedFormatItem<'_> {
104    #[inline]
105    fn eq(&self, rhs: &&[Self]) -> bool {
106        matches!(self, Self::Compound(compound) if compound == rhs)
107    }
108}
109
110impl PartialEq<BorrowedFormatItem<'_>> for &[BorrowedFormatItem<'_>] {
111    #[inline]
112    fn eq(&self, rhs: &BorrowedFormatItem<'_>) -> bool {
113        rhs == self
114    }
115}