time 0.3.49

Date and time library. Fully interoperable with the standard library. Mostly compatible with #![no_std].
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

//! A format item with borrowed data.

#[cfg(feature = "alloc")]
use alloc::string::String;
#[cfg(feature = "alloc")]
use core::fmt;

use crate::error;
use crate::format_description::Component;

/// A complete description of how to format and parse a type.
#[non_exhaustive]
#[cfg_attr(not(feature = "alloc"), derive(Debug))]
#[derive(Clone, Eq)]
pub enum BorrowedFormatItem<'a> {
    /// Bytes that are formatted as-is.
    ///
    /// **Note**: These bytes **should** be UTF-8, but are not required to be. The value is passed
    /// through `String::from_utf8_lossy` when necessary.
    #[deprecated(
        since = "0.3.48",
        note = "use `StringLiteral` instead; raw bytes are not recommended"
    )]
    Literal(&'a [u8]),
    /// A string that is formatted as-is.
    StringLiteral(&'a str),
    /// A minimal representation of a single non-literal item.
    Component(Component),
    /// A series of literals or components that collectively form a partial or complete
    /// description.
    Compound(&'a [Self]),
    /// A `FormatItem` that may or may not be present when parsing. If parsing fails, there
    /// will be no effect on the resulting `struct`.
    ///
    /// This variant has no effect on formatting, as the value is guaranteed to be present.
    Optional(&'a Self),
    /// A series of `FormatItem`s where, when parsing, the first successful parse is used. When
    /// formatting, the first element of the slice is used.  An empty slice is a no-op when
    /// formatting or parsing.
    First(&'a [Self]),
}

#[cfg(feature = "alloc")]
impl fmt::Debug for BorrowedFormatItem<'_> {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            #[expect(deprecated)]
            Self::Literal(literal) => f.write_str(&String::from_utf8_lossy(literal)),
            Self::StringLiteral(literal) => f.write_str(literal),
            Self::Component(component) => component.fmt(f),
            Self::Compound(compound) => compound.fmt(f),
            Self::Optional(item) => f.debug_tuple("Optional").field(item).finish(),
            Self::First(items) => f.debug_tuple("First").field(items).finish(),
        }
    }
}

impl PartialEq for BorrowedFormatItem<'_> {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            // trivial equality checks
            #[expect(deprecated)]
            (Self::Literal(a), Self::Literal(b)) => a == b,
            (Self::StringLiteral(a), Self::StringLiteral(b)) => a == b,
            (Self::Component(a), Self::Component(b)) => a == b,
            (Self::Compound(a), Self::Compound(b)) => a == b,
            (Self::Optional(a), Self::Optional(b)) => a == b,
            (Self::First(a), Self::First(b)) => a == b,
            // bytes vs string (back-compatibility)
            #[expect(deprecated)]
            (Self::Literal(a), Self::StringLiteral(b)) => *a == b.as_bytes(),
            #[expect(deprecated)]
            (Self::StringLiteral(a), Self::Literal(b)) => a.as_bytes() == *b,
            _ => false,
        }
    }
}

impl From<Component> for BorrowedFormatItem<'_> {
    #[inline]
    fn from(component: Component) -> Self {
        Self::Component(component)
    }
}

impl TryFrom<BorrowedFormatItem<'_>> for Component {
    type Error = error::DifferentVariant;

    #[inline]
    fn try_from(value: BorrowedFormatItem<'_>) -> Result<Self, Self::Error> {
        match value {
            BorrowedFormatItem::Component(component) => Ok(component),
            _ => Err(error::DifferentVariant),
        }
    }
}

impl<'a> From<&'a [BorrowedFormatItem<'_>]> for BorrowedFormatItem<'a> {
    #[inline]
    fn from(items: &'a [BorrowedFormatItem<'_>]) -> Self {
        Self::Compound(items)
    }
}

impl<'a> TryFrom<BorrowedFormatItem<'a>> for &[BorrowedFormatItem<'a>] {
    type Error = error::DifferentVariant;

    #[inline]
    fn try_from(value: BorrowedFormatItem<'a>) -> Result<Self, Self::Error> {
        match value {
            BorrowedFormatItem::Compound(items) => Ok(items),
            _ => Err(error::DifferentVariant),
        }
    }
}

impl PartialEq<Component> for BorrowedFormatItem<'_> {
    #[inline]
    fn eq(&self, rhs: &Component) -> bool {
        matches!(self, Self::Component(component) if component == rhs)
    }
}

impl PartialEq<BorrowedFormatItem<'_>> for Component {
    #[inline]
    fn eq(&self, rhs: &BorrowedFormatItem<'_>) -> bool {
        rhs == self
    }
}

impl PartialEq<&[Self]> for BorrowedFormatItem<'_> {
    #[inline]
    fn eq(&self, rhs: &&[Self]) -> bool {
        matches!(self, Self::Compound(compound) if compound == rhs)
    }
}

impl PartialEq<BorrowedFormatItem<'_>> for &[BorrowedFormatItem<'_>] {
    #[inline]
    fn eq(&self, rhs: &BorrowedFormatItem<'_>) -> bool {
        rhs == self
    }
}