temporal parser imlementation

Author: blarfoon

src/iso.rs

@@ -44,6 +44,34 @@ use crate::{
 use icu_calendar::{Date as IcuDate, Iso};
 use num_traits::{cast::FromPrimitive, Euclid};
 
+// ISO/Temporal specification limits
+//
+// Year limits are defined by the ECMAScript Temporal specification:
+// https://tc39.es/proposal-temporal/#sec-temporal-date-objects
+// These limits ensure compatibility with ISO 8601 extended year format
+// and avoid issues with JavaScript's Date object limitations.
+//
+// Time component limits follow ISO 8601 standard:
+// https://www.iso.org/iso-8601-date-and-time-format.html
+// See also RFC 3339: https://tools.ietf.org/html/rfc3339
+
+/// Minimum supported year (-271821-04-19T00:00:00Z corresponds to ECMAScript's minimum time value)
+pub(crate) const MIN_ISO_YEAR: i32 = -271821;
+/// Maximum supported year (275760-09-13T00:00:00Z corresponds to ECMAScript's maximum time value)
+pub(crate) const MAX_ISO_YEAR: i32 = 275760;
+/// Minimum month value per ISO 8601
+pub(crate) const MIN_ISO_MONTH: u8 = 1;
+/// Maximum month value per ISO 8601
+pub(crate) const MAX_ISO_MONTH: u8 = 12;
+/// Minimum day value per ISO 8601
+pub(crate) const MIN_ISO_DAY: u8 = 1;
+/// Maximum hour value per ISO 8601 (24-hour format, 0-23)
+pub(crate) const MAX_ISO_HOUR: u8 = 23;
+/// Maximum minute value per ISO 8601
+pub(crate) const MAX_ISO_MINUTE: u8 = 59;
+/// Maximum second value per ISO 8601
+pub(crate) const MAX_ISO_SECOND: u8 = 59;
+
 /// `IsoDateTime` is the record of the `IsoDate` and `IsoTime` internal slots.
 #[non_exhaustive]
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]

src/lib.rs

@@ -48,6 +48,39 @@
 //!
 //! ```
 //!
+//! ### Parse timestamps with the public `TemporalParser` API
+//!
+//! The `TemporalParser` provides a high-level, public API for parsing IXDTF strings
+//! with built-in validation and invariant checking.
+//!
+//! ```rust
+//! use temporal_rs::parsers::TemporalParser;
+//!
+//! let parser = TemporalParser::new();
+//!
+//! // Parse a PlainDateTime with validation
+//! let dt_result = parser.parse_date_time("2025-01-15T14:30:00[u-ca=gregory]");
+//! assert!(dt_result.is_ok());
+//! let parsed = dt_result.unwrap();
+//! assert_eq!(parsed.iso.date.year, 2025);
+//! assert_eq!(parsed.iso.time.hour, 14);
+//! assert!(parsed.calendar.is_some());
+//!
+//! // Parse an Instant
+//! let instant_result = parser.parse_instant("2025-01-15T14:30:00Z");
+//! assert!(instant_result.is_ok());
+//!
+//! // Parse a ZonedDateTime
+//! let zdt_result = parser.parse_zoned_date_time("2025-01-15T14:30:00Z[America/New_York]");
+//! assert!(zdt_result.is_ok());
+//! let zdt_parsed = zdt_result.unwrap();
+//! assert_eq!(zdt_parsed.timezone(), "America/New_York");
+//!
+//! // Invalid dates are properly rejected
+//! let invalid_result = parser.parse_date_time("2025-02-30T14:30:00"); // Feb 30th doesn't exist
+//! assert!(invalid_result.is_err());
+//! ```
+//!
 //! ### Create a `ZonedDateTime` for a RFC9557 IXDTF string.
 //!
 //! **Important Note:** The below API is enabled with the