ixdtf/parsers/
records.rs

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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
// This file is part of ICU4X. For terms of use, please see the file
// called LICENSE at the top level of the ICU4X source tree
// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).

//! The records that `ixdtf`'s contain the resulting values of parsing.

use core::num::NonZeroU8;

/// An `IxdtfParseRecord` is an intermediary record returned by `IxdtfParser`.
#[non_exhaustive]
#[derive(Default, Debug, PartialEq)]
pub struct IxdtfParseRecord<'a> {
    /// Parsed `DateRecord`
    pub date: Option<DateRecord>,
    /// Parsed `TimeRecord`
    pub time: Option<TimeRecord>,
    /// Parsed UtcOffset
    pub offset: Option<UtcOffsetRecordOrZ>,
    /// Parsed `TimeZone` annotation with critical flag and data (UTCOffset | IANA name)
    pub tz: Option<TimeZoneAnnotation<'a>>,
    /// The parsed calendar value.
    pub calendar: Option<&'a [u8]>,
}

#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
/// A record of an annotation.
pub struct Annotation<'a> {
    /// Whether this annotation is flagged as critical
    pub critical: bool,
    /// The parsed key value of the annotation
    pub key: &'a [u8],
    /// The parsed value of the annotation
    pub value: &'a [u8],
}

#[allow(clippy::exhaustive_structs)] // DateRecord only allows for a year, month, and day value.
#[derive(Default, Debug, Clone, Copy, PartialEq)]
/// The record of a parsed date.
pub struct DateRecord {
    /// Date Year
    pub year: i32,
    /// Date Month
    pub month: u8,
    /// Date Day
    pub day: u8,
}

/// Parsed Time info
#[allow(clippy::exhaustive_structs)] // TimeRecord only allows for a hour, minute, second, and sub-second value.
#[derive(Debug, Default, Clone, Copy, PartialEq)]
pub struct TimeRecord {
    /// An hour
    pub hour: u8,
    /// A minute value
    pub minute: u8,
    /// A second value.
    pub second: u8,
    /// A nanosecond value representing all sub-second components.
    pub fraction: Option<Fraction>,
}

/// A `TimeZoneAnnotation` that represents a parsed `TimeZoneRecord` and its critical flag.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub struct TimeZoneAnnotation<'a> {
    /// Critical flag for the `TimeZoneAnnotation`.
    pub critical: bool,
    /// The parsed `TimeZoneRecord` for the annotation.
    pub tz: TimeZoneRecord<'a>,
}

/// Parsed `TimeZone` data, which can be either a UTC Offset value or IANA Time Zone Name value.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub enum TimeZoneRecord<'a> {
    /// TimeZoneIANAName
    Name(&'a [u8]),
    /// TimeZoneOffset
    Offset(UtcOffsetRecord),
}

/// The parsed sign value, representing whether its struct is positive or negative.
#[repr(i8)]
#[allow(clippy::exhaustive_enums)] // Sign can only be positive or negative.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Sign {
    /// A negative value sign, representable as either -1 or false.
    Negative = -1,
    /// A positive value sign, representable as either 1 or true.
    Positive = 1,
}

impl From<bool> for Sign {
    fn from(value: bool) -> Self {
        match value {
            true => Self::Positive,
            false => Self::Negative,
        }
    }
}

/// A full precision `UtcOffsetRecord`
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct UtcOffsetRecord {
    /// The `Sign` value of the `UtcOffsetRecord`.
    pub sign: Sign,
    /// The hour value of the `UtcOffsetRecord`.
    pub hour: u8,
    /// The minute value of the `UtcOffsetRecord`.
    pub minute: u8,
    /// The second value of the `UtcOffsetRecord`.
    pub second: u8,
    /// Any nanosecond value of the `UTCOffsetRecord`.
    pub fraction: Option<Fraction>,
}

impl UtcOffsetRecord {
    /// +0000
    pub const fn zero() -> Self {
        Self {
            sign: Sign::Positive,
            hour: 0,
            minute: 0,
            second: 0,
            fraction: None,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq)]
#[allow(clippy::exhaustive_enums)] // explicitly A or B
pub enum UtcOffsetRecordOrZ {
    Offset(UtcOffsetRecord),
    Z,
}

impl UtcOffsetRecordOrZ {
    /// Resolves to a [`UtcOffsetRecord`] according to RFC9557: "Z" == "-00:00"
    pub fn resolve_rfc_9557(self) -> UtcOffsetRecord {
        match self {
            UtcOffsetRecordOrZ::Offset(o) => o,
            UtcOffsetRecordOrZ::Z => UtcOffsetRecord {
                sign: Sign::Negative,
                hour: 0,
                minute: 0,
                second: 0,
                fraction: None,
            },
        }
    }
}

/// The resulting record of parsing a `Duration` string.
#[allow(clippy::exhaustive_structs)]
// A duration can only be a Sign, a DateDuration part, and a TimeDuration part that users need to match on.
#[cfg(feature = "duration")]
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct DurationParseRecord {
    /// Duration Sign
    pub sign: Sign,
    /// The parsed `DateDurationRecord` if present.
    pub date: Option<DateDurationRecord>,
    /// The parsed `TimeDurationRecord` if present.
    pub time: Option<TimeDurationRecord>,
}

/// A `DateDurationRecord` represents the result of parsing the date component of a Duration string.
#[allow(clippy::exhaustive_structs)]
// A `DateDurationRecord` by spec can only be made up of years, months, weeks, and days parts that users need to match on.
#[cfg(feature = "duration")]
#[derive(Default, Debug, Clone, Copy, PartialEq)]
pub struct DateDurationRecord {
    /// Years value.
    pub years: u32,
    /// Months value.
    pub months: u32,
    /// Weeks value.
    pub weeks: u32,
    /// Days value.
    pub days: u64,
}

/// A `TimeDurationRecord` represents the result of parsing the time component of a Duration string.
#[allow(clippy::exhaustive_enums)]
// A `TimeDurationRecord` by spec can only be made up of the valid parts up to a present fraction that users need to match on.
#[cfg(feature = "duration")]
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum TimeDurationRecord {
    // An hours Time duration record.
    Hours {
        /// Hours value.
        hours: u64,
        /// The parsed fractional digits.
        fraction: Option<Fraction>,
    },
    // A Minutes Time duration record.
    Minutes {
        /// Hours value.
        hours: u64,
        /// Minutes value.
        minutes: u64,
        /// The parsed fractional digits.
        fraction: Option<Fraction>,
    },
    // A Seconds Time duration record.
    Seconds {
        /// Hours value.
        hours: u64,
        /// Minutes value.
        minutes: u64,
        /// Seconds value.
        seconds: u64,
        /// The parsed fractional digits.
        fraction: Option<Fraction>,
    },
}

/// A fraction value in nanoseconds or lower value.
///
/// # Precision note
///
/// `ixdtf` parses a fraction value to a precision of 18 digits of precision, but
/// preserves the fraction's digit length
#[derive(Debug, Clone, Copy, PartialEq)]
#[allow(clippy::exhaustive_structs)] // A fraction is only a value and its digit length.
pub struct Fraction {
    // The count of fraction digits, i.e. the fraction's digit length.
    pub(crate) digits: NonZeroU8,
    // The parsed fraction value.
    pub(crate) value: u64,
}

impl Fraction {
    /// Returns Some(`u32`) representing the `Fraction` as it's computed
    /// nanosecond value or `None` if the digits exceeds 9 digits.
    ///
    /// ```rust
    /// use ixdtf::parsers::IxdtfParser;
    ///
    /// // Fraction is below 9 digits.
    /// let fraction_str = "2025-02-17T05:41:32.12345678";
    /// let result = IxdtfParser::from_str(fraction_str).parse().unwrap();
    ///
    /// let time = result.time.unwrap();
    /// let fraction = time.fraction.unwrap();
    ///
    /// assert_eq!(fraction.to_nanoseconds(), Some(123456780));
    ///
    /// // Fraction is 10 digits.
    /// let fraction_str = "2025-02-17T05:41:32.1234567898";
    /// let result = IxdtfParser::from_str(fraction_str).parse().unwrap();
    /// let time = result.time.unwrap();
    /// let fraction = time.fraction.unwrap();
    ///
    /// assert_eq!(fraction.to_nanoseconds(), None);
    /// ```
    pub fn to_nanoseconds(&self) -> Option<u32> {
        if self.digits.get() <= 9 {
            Some(10u32.pow(9 - u32::from(self.digits.get())) * (self.value as u32))
        } else {
            None
        }
    }

    /// Returns a `u32` representing the `Fraction` as it's computed
    /// nanosecond value, truncating any value beyond 9 digits to
    /// nanoseconds.
    ///
    /// This method will return `None` if the value exceeds a represented
    /// range or the underlying `Fraction` is malformed.
    ///
    /// ```rust
    /// use ixdtf::parsers::IxdtfParser;
    ///
    /// // Fraction is 13 digits.
    /// let fraction_str = "2025-02-17T05:41:32.1234567898765";
    /// let result = IxdtfParser::from_str(fraction_str).parse().unwrap();
    ///
    /// let time = result.time.unwrap();
    /// let fraction = time.fraction.unwrap();
    ///
    /// assert_eq!(fraction.to_truncated_nanoseconds(), 123456789);
    /// assert_eq!(fraction.to_nanoseconds(), None);
    /// ```
    pub fn to_truncated_nanoseconds(&self) -> u32 {
        self.to_nanoseconds()
            .unwrap_or((self.value / 10u64.pow(u32::from(self.digits.get() - 9))) as u32)
    }
}