Source code
Revision control
Copy as Markdown
Other Tools
// 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 parser module contains the implementation details for `IxdtfParser` and `IsoDurationParser`
use crate::core::{EncodingType, Utf16, Utf8};
use crate::{core::Cursor, ParserResult};
#[cfg(feature = "duration")]
use crate::records::DurationParseRecord;
use crate::records::{IxdtfParseRecord, TimeZoneRecord, UtcOffsetRecord};
use crate::records::Annotation;
mod annotations;
pub(crate) mod datetime;
#[cfg(feature = "duration")]
pub(crate) mod duration;
mod grammar;
mod time;
pub(crate) mod timezone;
#[cfg(test)]
mod tests;
/// `assert_syntax!` is a parser specific utility macro for asserting a syntax test, and returning the
/// the provided provided error if the assertion fails.
#[macro_export]
macro_rules! assert_syntax {
($cond:expr, $err:ident $(,)?) => {
if !$cond {
return Err(ParseError::$err);
}
};
}
/// `IxdtfParser` is the primary parser implementation of `ixdtf`.
///
/// This parser provides various options for parsing date/time strings with the extended notation
/// laid out in [RFC9557][rfc9557] along with other variations laid out in the [`Temporal`][temporal-proposal].
///
/// ```rust
/// use ixdtf::{
/// parsers::IxdtfParser,
/// records::{Sign, TimeZoneRecord, UtcOffsetRecord},
/// };
///
/// let ixdtf_str = "2024-03-02T08:48:00-05:00[America/New_York]";
///
/// let result = IxdtfParser::from_str(ixdtf_str).parse().unwrap();
///
/// let date = result.date.unwrap();
/// let time = result.time.unwrap();
/// let offset = result.offset.unwrap().resolve_rfc_9557();
/// let tz_annotation = result.tz.unwrap();
///
/// assert_eq!(date.year, 2024);
/// assert_eq!(date.month, 3);
/// assert_eq!(date.day, 2);
/// assert_eq!(time.hour, 8);
/// assert_eq!(time.minute, 48);
/// assert_eq!(offset.sign(), Sign::Negative);
/// assert_eq!(offset.hour(), 5);
/// assert_eq!(offset.minute(), 0);
/// assert_eq!(offset.second(), None);
/// assert_eq!(offset.fraction(), None);
/// assert!(!tz_annotation.critical);
/// assert_eq!(
/// tz_annotation.tz,
/// TimeZoneRecord::Name("America/New_York".as_bytes())
/// );
/// ```
///
/// [rfc9557]: https://datatracker.ietf.org/doc/rfc9557/
/// [temporal-proposal]: https://tc39.es/proposal-temporal/
#[derive(Debug)]
pub struct IxdtfParser<'a, T: EncodingType> {
cursor: Cursor<'a, T>,
}
impl<'a> IxdtfParser<'a, Utf8> {
/// Creates a new `IxdtfParser` from a source `&str`.
#[inline]
#[must_use]
#[expect(clippy::should_implement_trait)]
pub fn from_str(source: &'a str) -> Self {
Self::from_utf8(source.as_bytes())
}
/// Creates a new `IxdtfParser` from a slice of utf-8 bytes.
#[inline]
#[must_use]
pub fn from_utf8(source: &'a [u8]) -> Self {
Self::new(source)
}
}
impl<'a> IxdtfParser<'a, Utf16> {
/// Creates a new `IxdtfParser` from a slice of utf-16 bytes.
pub fn from_utf16(source: &'a [u16]) -> Self {
Self::new(source)
}
}
impl<'a, T: EncodingType> IxdtfParser<'a, T> {
/// Create a new `IxdtfParser` for the specified encoding.
#[inline]
#[must_use]
pub fn new(source: &'a [T::CodeUnit]) -> Self {
Self {
cursor: Cursor::new(source),
}
}
/// Parses the source as an [extended Date/Time string][rfc9557].
///
/// This is the baseline parse method for `ixdtf`. For this method, the
/// TimeRecord, UTCOffsetRecord, and all annotations are optional.
///
/// # Example
///
/// [rfc9557]: https://datatracker.ietf.org/doc/rfc9557/
pub fn parse(&mut self) -> ParserResult<IxdtfParseRecord<'a, T>> {
self.parse_with_annotation_handler(Some)
}
/// Parses the source as an extended Date/Time string with an Annotation handler.
///
/// For more, see [Implementing Annotation Handlers](crate#implementing-annotation-handlers)
pub fn parse_with_annotation_handler(
&mut self,
handler: impl FnMut(Annotation<'a, T>) -> Option<Annotation<'a, T>>,
) -> ParserResult<IxdtfParseRecord<'a, T>> {
datetime::parse_annotated_date_time(&mut self.cursor, handler)
}
/// Parses the source as an extended [YearMonth string][temporal-ym].
///
/// # Example
///
/// ```rust
/// # use ixdtf::parsers::IxdtfParser;
///
/// let extended_year_month = "2020-11[u-ca=iso8601]";
///
/// let result = IxdtfParser::from_str(extended_year_month)
/// .parse_year_month()
/// .unwrap();
///
/// let date = result.date.unwrap();
///
/// assert_eq!(date.year, 2020);
/// assert_eq!(date.month, 11);
/// ```
///
/// [temporal-ym]: https://tc39.es/proposal-temporal/#prod-TemporalYearMonthString
pub fn parse_year_month(&mut self) -> ParserResult<IxdtfParseRecord<'a, T>> {
self.parse_year_month_with_annotation_handler(Some)
}
/// Parses the source as an extended YearMonth string with an Annotation handler.
///
/// For more, see [Implementing Annotation Handlers](crate#implementing-annotation-handlers)
pub fn parse_year_month_with_annotation_handler(
&mut self,
handler: impl FnMut(Annotation<'a, T>) -> Option<Annotation<'a, T>>,
) -> ParserResult<IxdtfParseRecord<'a, T>> {
datetime::parse_annotated_year_month(&mut self.cursor, handler)
}
/// Parses the source as an extended [MonthDay string][temporal-md].
///
/// # Example
///
/// ```rust
/// # use ixdtf::parsers::IxdtfParser;
/// let extended_month_day = "1107[+04:00]";
///
/// let result = IxdtfParser::from_str(extended_month_day)
/// .parse_month_day()
/// .unwrap();
///
/// let date = result.date.unwrap();
///
/// assert_eq!(date.month, 11);
/// assert_eq!(date.day, 7);
/// ```
///
/// [temporal-md]: https://tc39.es/proposal-temporal/#prod-TemporalMonthDayString
pub fn parse_month_day(&mut self) -> ParserResult<IxdtfParseRecord<'a, T>> {
self.parse_month_day_with_annotation_handler(Some)
}
/// Parses the source as an extended MonthDay string with an Annotation handler.
///
/// For more, see [Implementing Annotation Handlers](crate#implementing-annotation-handlers)
pub fn parse_month_day_with_annotation_handler(
&mut self,
handler: impl FnMut(Annotation<'a, T>) -> Option<Annotation<'a, T>>,
) -> ParserResult<IxdtfParseRecord<'a, T>> {
datetime::parse_annotated_month_day(&mut self.cursor, handler)
}
/// Parses the source as an extended [Time string][temporal-time].
///
/// # Example
///
/// ```rust
/// # use ixdtf::{parsers::IxdtfParser, records::{Sign, TimeZoneRecord}};
/// let extended_time = "12:01:04-05:00[America/New_York][u-ca=iso8601]";
///
/// let result = IxdtfParser::from_str(extended_time).parse_time().unwrap();
///
/// let time = result.time.unwrap();
/// let offset = result.offset.unwrap().resolve_rfc_9557();
/// let tz_annotation = result.tz.unwrap();
///
/// assert_eq!(time.hour, 12);
/// assert_eq!(time.minute, 1);
/// assert_eq!(time.second, 4);
/// assert_eq!(offset.sign(), Sign::Negative);
/// assert_eq!(offset.hour(), 5);
/// assert_eq!(offset.minute(), 0);
/// assert!(!tz_annotation.critical);
/// assert_eq!(
/// tz_annotation.tz,
/// TimeZoneRecord::Name("America/New_York".as_bytes())
/// );
/// ```
///
/// [temporal-time]: https://tc39.es/proposal-temporal/#prod-TemporalTimeString
pub fn parse_time(&mut self) -> ParserResult<IxdtfParseRecord<'a, T>> {
self.parse_time_with_annotation_handler(Some)
}
/// Parses the source as an extended Time string with an Annotation handler.
///
/// For more, see [Implementing Annotation Handlers](crate#implementing-annotation-handlers)
pub fn parse_time_with_annotation_handler(
&mut self,
handler: impl FnMut(Annotation<'a, T>) -> Option<Annotation<'a, T>>,
) -> ParserResult<IxdtfParseRecord<'a, T>> {
time::parse_annotated_time_record(&mut self.cursor, handler)
}
}
/// A parser for time zone offset and IANA identifier strings.
///
/// ✨ *Enabled with the `timezone` Cargo feature.*
#[derive(Debug)]
pub struct TimeZoneParser<'a, T: EncodingType> {
cursor: Cursor<'a, T>,
}
impl<'a> TimeZoneParser<'a, Utf8> {
/// Creates a new `TimeZoneParser` from a source `&str`.
#[inline]
#[must_use]
#[expect(clippy::should_implement_trait)]
pub fn from_str(source: &'a str) -> Self {
Self::from_utf8(source.as_bytes())
}
/// Creates a new `TimeZoneParser` from a slice of utf-8 bytes.
#[inline]
#[must_use]
pub fn from_utf8(source: &'a [u8]) -> Self {
Self::new(source)
}
}
impl<'a> TimeZoneParser<'a, Utf16> {
/// Creates a new `TimeZoneParser` from a slice of utf-16 bytes.
pub fn from_utf16(source: &'a [u16]) -> Self {
Self::new(source)
}
}
impl<'a, T: EncodingType> TimeZoneParser<'a, T> {
/// Creates a new `TimeZoneParser` for the provided encoding.
#[inline]
#[must_use]
pub fn new(source: &'a [T::CodeUnit]) -> Self {
Self {
cursor: Cursor::new(source),
}
}
/// Parse a time zone identifier that can be either an
/// IANA identifer name or minute precision offset.
///
/// ## IANA identifier example
///
/// ```rust
/// use ixdtf::{parsers::TimeZoneParser, records::TimeZoneRecord};
///
/// let identifier = "Europe/London";
/// let record = TimeZoneParser::from_str(identifier)
/// .parse_identifier()
/// .unwrap();
/// assert_eq!(record, TimeZoneRecord::Name(identifier.as_bytes()))
/// ```
///
/// ## Minute precision offset example
///
/// ```rust
/// use ixdtf::{
/// parsers::TimeZoneParser,
/// records::{MinutePrecisionOffset, Sign, TimeZoneRecord},
/// };
///
/// let identifier = "+00:00";
/// let offset = match TimeZoneParser::from_str(identifier).parse_identifier() {
/// Ok(TimeZoneRecord::Offset(o)) => o,
/// _ => unreachable!(),
/// };
///
/// assert_eq!(offset.sign, Sign::Positive);
/// assert_eq!(offset.hour, 0);
/// assert_eq!(offset.minute, 0);
/// ```
///
/// ## Errors
///
/// It is an error to provide a full precision offset as a
/// time zone identifier.
///
/// **NOTE**: To parse either a full or minute precision,
/// use [`Self::parse_offset`].
///
/// ```rust
/// use ixdtf::{parsers::TimeZoneParser, ParseError};
///
/// let identifier = "+00:00:00";
/// let err = TimeZoneParser::from_str(identifier)
/// .parse_identifier()
/// .unwrap_err();
/// assert_eq!(err, ParseError::InvalidMinutePrecisionOffset);
///
/// let identifier = "+00:00.1";
/// let err = TimeZoneParser::from_str(identifier)
/// .parse_identifier()
/// .unwrap_err();
/// assert_eq!(err, ParseError::InvalidEnd);
/// ```
pub fn parse_identifier(&mut self) -> ParserResult<TimeZoneRecord<'a, T>> {
let result = timezone::parse_time_zone(&mut self.cursor)?;
self.cursor.close()?;
Ok(result)
}
/// Parse a UTC offset from the provided source.
///
/// This method can parse both a minute precision and full
/// precision offset.
///
/// ## Minute precision offset example
///
/// ```rust
/// use ixdtf::{parsers::TimeZoneParser, records::Sign};
///
/// let offset_src = "-05:00";
/// let parse_result =
/// TimeZoneParser::from_str(offset_src).parse_offset().unwrap();
/// assert_eq!(parse_result.sign(), Sign::Negative);
/// assert_eq!(parse_result.hour(), 5);
/// assert_eq!(parse_result.minute(), 0);
/// assert_eq!(parse_result.second(), None);
/// assert_eq!(parse_result.fraction(), None);
/// ```
///
/// ## Full precision offset example
///
/// ```rust
/// use ixdtf::{parsers::TimeZoneParser, records::Sign};
///
/// let offset_src = "-05:00:30.123456789";
/// let parse_result =
/// TimeZoneParser::from_str(offset_src).parse_offset().unwrap();
/// assert_eq!(parse_result.sign(), Sign::Negative);
/// assert_eq!(parse_result.hour(), 5);
/// assert_eq!(parse_result.minute(), 0);
/// assert_eq!(parse_result.second(), Some(30));
/// let fraction = parse_result.fraction().unwrap();
/// assert_eq!(fraction.to_nanoseconds(), Some(123456789));
/// ```
#[inline]
pub fn parse_offset(&mut self) -> ParserResult<UtcOffsetRecord> {
let result = timezone::parse_utc_offset(&mut self.cursor)?;
self.cursor.close()?;
Ok(result)
}
/// Parse an IANA identifier name.
///
///
/// ```rust
/// use ixdtf::{parsers::TimeZoneParser, records::Sign};
///
/// let iana_identifier = "America/Chicago";
/// let parse_result = TimeZoneParser::from_str(iana_identifier)
/// .parse_iana_identifier()
/// .unwrap();
/// assert_eq!(parse_result, iana_identifier.as_bytes());
///
/// let iana_identifier = "Europe/Berlin";
/// let parse_result = TimeZoneParser::from_str(iana_identifier)
/// .parse_iana_identifier()
/// .unwrap();
/// assert_eq!(parse_result, iana_identifier.as_bytes());
/// ```
#[inline]
pub fn parse_iana_identifier(&mut self) -> ParserResult<&'a [T::CodeUnit]> {
let result = timezone::parse_tz_iana_name(&mut self.cursor)?;
self.cursor.close()?;
Ok(result)
}
}
/// A parser for ISO8601 Duration strings.
///
/// ✨ *Enabled with the `duration` Cargo feature.*
///
/// # Example
///
/// ```rust
/// use ixdtf::{parsers::IsoDurationParser, records::{Sign, DurationParseRecord, TimeDurationRecord}};
///
/// let duration_str = "P1Y2M1DT2H10M30S";
///
/// let result = IsoDurationParser::from_str(duration_str).parse().unwrap();
///
/// let date_duration = result.date.unwrap();
///
/// let (hours, minutes, seconds, fraction) = match result.time {
/// // Hours variant is defined as { hours: u32, fraction: Option<Fraction> }
/// Some(TimeDurationRecord::Hours{ hours, fraction }) => (hours, 0, 0, fraction),
/// // Minutes variant is defined as { hours: u32, minutes: u32, fraction: Option<Fraction> }
/// Some(TimeDurationRecord::Minutes{ hours, minutes, fraction }) => (hours, minutes, 0, fraction),
/// // Seconds variant is defined as { hours: u32, minutes: u32, seconds: u32, fraction: Option<Fraction> }
/// Some(TimeDurationRecord::Seconds{ hours, minutes, seconds, fraction }) => (hours, minutes, seconds, fraction),
/// None => (0,0,0, None),
/// };
///
/// assert_eq!(result.sign, Sign::Positive);
/// assert_eq!(date_duration.years, 1);
/// assert_eq!(date_duration.months, 2);
/// assert_eq!(date_duration.weeks, 0);
/// assert_eq!(date_duration.days, 1);//
/// assert_eq!(hours, 2);
/// assert_eq!(minutes, 10);
/// assert_eq!(seconds, 30);
/// assert_eq!(fraction, None);
/// ```
#[cfg(feature = "duration")]
#[derive(Debug)]
pub struct IsoDurationParser<'a, T: EncodingType> {
cursor: Cursor<'a, T>,
}
#[cfg(feature = "duration")]
impl<'a> IsoDurationParser<'a, Utf8> {
/// Creates a new `IsoDurationParser` from a source `&str`.
#[inline]
#[must_use]
#[expect(clippy::should_implement_trait)]
pub fn from_str(source: &'a str) -> Self {
Self::from_utf8(source.as_bytes())
}
/// Creates a new `IsoDurationParser` from a slice of utf-8 bytes.
#[inline]
#[must_use]
pub fn from_utf8(source: &'a [u8]) -> Self {
Self::new(source)
}
}
#[cfg(feature = "duration")]
impl<'a> IsoDurationParser<'a, Utf16> {
/// Creates a new `IsoDurationParser` from a slice of utf-16 bytes.
#[inline]
#[must_use]
pub fn from_utf8(source: &'a [u16]) -> Self {
Self::new(source)
}
}
#[cfg(feature = "duration")]
impl<'a, T: EncodingType> IsoDurationParser<'a, T> {
/// Creates a new `IsoDurationParser` for the provided encoding.
#[inline]
#[must_use]
pub fn new(source: &'a [T::CodeUnit]) -> Self {
Self {
cursor: Cursor::new(source),
}
}
/// Parse the contents of this `IsoDurationParser` into a `DurationParseRecord`.
///
/// # Examples
///
/// ## Parsing a date duration
///
/// ```
/// # use ixdtf::{parsers::IsoDurationParser, records::DurationParseRecord };
/// let date_duration = "P1Y2M3W1D";
///
/// let result = IsoDurationParser::from_str(date_duration).parse().unwrap();
///
/// let date_duration = result.date.unwrap();
///
/// assert!(result.time.is_none());
/// assert_eq!(date_duration.years, 1);
/// assert_eq!(date_duration.months, 2);
/// assert_eq!(date_duration.weeks, 3);
/// assert_eq!(date_duration.days, 1);
/// ```
///
/// ## Parsing a time duration
///
/// ```rust
/// # use ixdtf::{parsers::IsoDurationParser, records::{DurationParseRecord, TimeDurationRecord }};
/// let time_duration = "PT2H10M30S";
///
/// let result = IsoDurationParser::from_str(time_duration).parse().unwrap();
///
/// let (hours, minutes, seconds, fraction) = match result.time {
/// // Hours variant is defined as { hours: u32, fraction: Option<Fraction> }
/// Some(TimeDurationRecord::Hours{ hours, fraction }) => (hours, 0, 0, fraction),
/// // Minutes variant is defined as { hours: u32, minutes: u32, fraction: Option<Fraction> }
/// Some(TimeDurationRecord::Minutes{ hours, minutes, fraction }) => (hours, minutes, 0, fraction),
/// // Seconds variant is defined as { hours: u32, minutes: u32, seconds: u32, fraction: Option<Fraction> }
/// Some(TimeDurationRecord::Seconds{ hours, minutes, seconds, fraction }) => (hours, minutes, seconds, fraction),
/// None => (0,0,0, None),
/// };
/// assert!(result.date.is_none());
/// assert_eq!(hours, 2);
/// assert_eq!(minutes, 10);
/// assert_eq!(seconds, 30);
/// assert_eq!(fraction, None);
/// ```
pub fn parse(&mut self) -> ParserResult<DurationParseRecord> {
duration::parse_duration(&mut self.cursor)
}
}