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)
}
}