docs: update crate description to reflect Zoned return type

The crate now returns jiff Zoned objects, not DateTime.

.github/workflows/ci.yml

@@ -3,7 +3,9 @@ on: [push, pull_request]
 name: Basic CI
 
 env:
+  CARGO_INCREMENTAL: "0"
   CARGO_TERM_COLOR: always
+  RUST_MIN_SRV: "1.71.1"
 
 jobs:
   check:
@@ -13,15 +15,8 @@ jobs:
       matrix:
         os: [ubuntu-latest, macOS-latest, windows-latest]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
-          override: true
-      - uses: actions-rs/cargo@v1
-        with:
-          command: check
+      - uses: actions/checkout@v6
+      - run: cargo check
 
   test:
     name: cargo test
@@ -30,31 +25,15 @@ jobs:
       matrix:
         os: [ubuntu-latest, macOS-latest, windows-latest]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
-          override: true
-      - uses: actions-rs/cargo@v1
-        with:
-          command: test
+      - uses: actions/checkout@v6
+      - run: cargo test
 
   fmt:
     name: cargo fmt --all -- --check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
-          override: true
-      - run: rustup component add rustfmt
-      - uses: actions-rs/cargo@v1
-        with:
-          command: fmt
-          args: --all -- --check
+      - uses: actions/checkout@v6
+      - run: cargo fmt --all -- --check
 
   clippy:
     name: cargo clippy -- -D warnings
@@ -63,17 +42,21 @@ jobs:
       matrix:
         os: [ubuntu-latest, macOS-latest, windows-latest]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions-rs/toolchain@v1
+      - uses: actions/checkout@v6
+      - run: cargo clippy --all-targets -- -D warnings
+
+  min_version:
+    name: Minimum Supported Rust Version
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macOS-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
         with:
-          profile: minimal
-          toolchain: stable
-          override: true
-      - run: rustup component add clippy
-      - uses: actions-rs/cargo@v1
-        with:
-          command: clippy
-          args: -- -D warnings
+          toolchain: ${{ env.RUST_MIN_SRV }}
+      - run: cargo check
 
   coverage:
     name: Code Coverage
@@ -86,53 +69,46 @@ jobs:
           - { os: macos-latest   , features: macos }
           - { os: windows-latest , features: windows }
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
+    - name: emulate nightly toolchain
+      run: echo "RUSTC_BOOTSTRAP=1" >> "${GITHUB_ENV}"
     - name: Initialize workflow variables
       id: vars
       shell: bash
       run: |
         ## VARs setup
         outputs() { step_id="vars"; for var in "$@" ; do echo steps.${step_id}.outputs.${var}="${!var}"; echo "${var}=${!var}" >> $GITHUB_OUTPUT; done; }
-        # toolchain
-        TOOLCHAIN="nightly" ## default to "nightly" toolchain (required for certain required unstable compiler flags) ## !maint: refactor when stable channel has needed support
         # * specify gnu-type TOOLCHAIN for windows; `grcov` requires gnu-style code coverage data files
         case ${{ matrix.job.os }} in windows-*) TOOLCHAIN="$TOOLCHAIN-x86_64-pc-windows-gnu" ;; esac;
         # * use requested TOOLCHAIN if specified
         if [ -n "${{ matrix.job.toolchain }}" ]; then TOOLCHAIN="${{ matrix.job.toolchain }}" ; fi
         outputs TOOLCHAIN
         # target-specific options
-        # * CARGO_FEATURES_OPTION
-        CARGO_FEATURES_OPTION='--all -- --check' ;  ## default to '--all-features' for code coverage
         # * CODECOV_FLAGS
         CODECOV_FLAGS=$( echo "${{ matrix.job.os }}" | sed 's/[^[:alnum:]]/_/g' )
         outputs CODECOV_FLAGS
 
     - name: rust toolchain ~ install
-      uses: actions-rs/toolchain@v1
+      uses: dtolnay/rust-toolchain@nightly # this job is not reproducible...
       with:
-        toolchain: ${{ steps.vars.outputs.TOOLCHAIN }}
-        default: true
-        profile: minimal # minimal component installation (ie, no documentation)
+        components: llvm-tools-preview
     - name: Test
-      uses: actions-rs/cargo@v1
-      with:
-        command: test
-        args: ${{ steps.vars.outputs.CARGO_FEATURES_OPTION }} --no-fail-fast
+      run: cargo test --no-fail-fast
       env:
-        CARGO_INCREMENTAL: "0"
         RUSTC_WRAPPER: ""
-        RUSTFLAGS: "-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort"
+        RUSTFLAGS: "-Cinstrument-coverage -Zcoverage-options=branch -Ccodegen-units=1 -Copt-level=0 -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort"
         RUSTDOCFLAGS: "-Cpanic=abort"
+        LLVM_PROFILE_FILE: "parse_datetime-%p-%m.profraw"
     - name: "`grcov` ~ install"
       id: build_grcov
       shell: bash
       run: |
-        git clone https://github.com/mozilla/grcov.git ~/grcov/
+        git clone --depth=1 https://github.com/mozilla/grcov.git ~/grcov/
         cd ~/grcov
         # Hardcode the version of crossbeam-epoch. See
         # https://github.com/uutils/coreutils/issues/3680
         sed -i -e "s|tempfile =|crossbeam-epoch = \"=0.9.8\"\ntempfile =|" Cargo.toml
-        cargo install --path .
+        cargo install --path . --locked
         cd -
 # Uncomment when the upstream issue
 # https://github.com/mozilla/grcov/issues/849 is fixed
@@ -150,20 +126,21 @@ jobs:
         COVERAGE_REPORT_FILE="${COVERAGE_REPORT_DIR}/lcov.info"
         mkdir -p "${COVERAGE_REPORT_DIR}"
         # display coverage files
-        grcov . --output-type files --ignore build.rs --ignore "vendor/*" --ignore "/*" --ignore "[a-zA-Z]:/*" --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?!|#\[derive\()" | sort --unique
+        grcov . --binary-path="${COVERAGE_REPORT_DIR}" --output-type files --ignore build.rs --ignore "vendor/*" --ignore "/*" --ignore "[a-zA-Z]:/*" --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?!|#\[derive\()" | sort --unique
         # generate coverage report
-        grcov . --output-type lcov --output-path "${COVERAGE_REPORT_FILE}" --branch --ignore build.rs --ignore "vendor/*" --ignore "/*" --ignore "[a-zA-Z]:/*" --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?!|#\[derive\()"
+        grcov . --binary-path="${COVERAGE_REPORT_DIR}" --output-type lcov --output-path "${COVERAGE_REPORT_FILE}" --branch --ignore build.rs --ignore "vendor/*" --ignore "/*" --ignore "[a-zA-Z]:/*" --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?!|#\[derive\()" --source-dir .
         echo "report=${COVERAGE_REPORT_FILE}" >> $GITHUB_OUTPUT
     - name: Upload coverage results (to Codecov.io)
-      uses: codecov/codecov-action@v4
-      # if: steps.vars.outputs.HAS_CODECOV_TOKEN
+      uses: codecov/codecov-action@v6
       with:
-        # token: ${{ secrets.CODECOV_TOKEN }}
-        file: ${{ steps.coverage.outputs.report }}
-        ## flags: IntegrationTests, UnitTests, ${{ steps.vars.outputs.CODECOV_FLAGS }}
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: ${{ steps.coverage.outputs.report }}
         flags: ${{ steps.vars.outputs.CODECOV_FLAGS }}
         name: codecov-umbrella
         fail_ci_if_error: false
+        verbose: true
+        directory: ./
+        root_dir: ./
 
   fuzz:
     name: Run the fuzzers
@@ -171,14 +148,21 @@ jobs:
     env:
       RUN_FOR: 60
     steps:
-    - uses: actions/checkout@v4
-    - uses: dtolnay/rust-toolchain@nightly
+    - uses: actions/checkout@v6
+    - name: emulate nightly toolchain
+      run: echo "RUSTC_BOOTSTRAP=1" >> "${GITHUB_ENV}"
     - name: Install `cargo-fuzz`
-      run: cargo install cargo-fuzz
+      run: cargo install cargo-fuzz --locked
     - uses: Swatinem/rust-cache@v2
-    - name: Run from_str for XX seconds
+    - name: Run fuzz_parse_datetime for XX seconds
       shell: bash
       run: |
         ## Run it
         cd fuzz
-        cargo +nightly fuzz run fuzz_parse_datetime -- -max_total_time=${{ env.RUN_FOR }} -detect_leaks=0
+        cargo fuzz run fuzz_parse_datetime -- -max_total_time=${{ env.RUN_FOR }} -detect_leaks=0
+    - name: Run fuzz_large_year for XX seconds
+      shell: bash
+      run: |
+        ## Run it
+        cd fuzz
+        cargo fuzz run fuzz_large_year -- -max_total_time=${{ env.RUN_FOR }} -detect_leaks=0

.github/workflows/codspeed.yml

@@ -0,0 +1,37 @@
+name: CodSpeed
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+  # `workflow_dispatch` allows CodSpeed to trigger backtest
+  # performance analysis in order to generate initial data.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  codspeed:
+    name: Run benchmarks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup rust toolchain, cache and cargo-codspeed binary
+        uses: moonrepo/setup-rust@v1
+        with:
+          channel: stable
+          cache-target: release
+          bins: cargo-codspeed
+
+      - name: Build the benchmark target(s)
+        run: cargo codspeed build
+
+      - name: Run the benchmarks
+        uses: CodSpeedHQ/action@v4
+        with:
+          mode: simulation
+          run: cargo codspeed run

Cargo.toml

@@ -1,12 +1,24 @@
 [package]
 name = "parse_datetime"
-description = "parsing human-readable time strings and converting them to a DateTime"
-version = "0.5.0"
+description = "parsing human-readable time strings and converting them to a Zoned datetime"
+version = "0.15.0"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/uutils/parse_datetime"
 readme = "README.md"
+rust-version = "1.71.1"
 
 [dependencies]
-regex = "1.9"
-chrono = { version="0.4", default-features=false, features=["std", "alloc", "clock"] }
+winnow = "1.0.0"
+num-traits = "0.2.19"
+jiff = { version = "0.2.15", default-features = false, features = ["tz-system", "tzdb-bundle-platform", "tzdb-zoneinfo"] }
+
+[dev-dependencies]
+rstest = "0.26"
+
+[dev-dependencies.codspeed-criterion-compat]
+version = "4.0"
+
+[[bench]]
+name = "parse_datetime"
+harness = false

README.md

@@ -3,49 +3,69 @@
 [![Crates.io](https://img.shields.io/crates/v/parse_datetime.svg)](https://crates.io/crates/parse_datetime)
 [![License](http://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/uutils/parse_datetime/blob/main/LICENSE)
 [![CodeCov](https://codecov.io/gh/uutils/parse_datetime/branch/main/graph/badge.svg)](https://codecov.io/gh/uutils/parse_datetime)
+[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/uutils/parse_datetime?utm_source=badge)
 
-A Rust crate for parsing human-readable relative time strings and human-readable datetime strings and converting them to a `DateTime`.
+A Rust crate for parsing human-readable relative time strings and
+human-readable datetime strings.
 
 ## Features
 
 - Parses a variety of human-readable and standard time formats.
 - Supports positive and negative durations.
-- Allows for chaining time units (e.g., "1 hour 2 minutes" or "2 days and 2 hours").
+- Allows for chaining time units (e.g., "1 hour 2 minutes" or "2 days 2 hours ago").
 - Calculate durations relative to a specified date.
-- Relies on Chrono
+- Relies on Jiff
 
 ## Usage
 
-Add this to your `Cargo.toml`:
+Add `parse_datetime` to your `Cargo.toml` with:
 
-```toml
-[dependencies]
-parse_datetime = "0.4.0"
+```
+cargo add parse_datetime
 ```
 
 Then, import the crate and use the `parse_datetime_at_date` function:
 
 ```rs
-use chrono::{Duration, Local};
-use parse_datetime::parse_datetime_at_date;
+use jiff::{ToSpan, Zoned};
+use parse_datetime::{parse_datetime_at_date, ParsedDateTime};
 
-let now = Local::now();
-let after = parse_datetime_at_date(now, "+3 days");
+let now = Zoned::now();
+let after = parse_datetime_at_date(now.clone(), "+3 days");
 
-assert_eq!(
-  (now + Duration::days(3)).naive_utc(),
-  after.unwrap().naive_utc()
-);
+match after.unwrap() {
+  ParsedDateTime::InRange(z) => assert_eq!(now.checked_add(3.days()).unwrap(), z),
+  ParsedDateTime::Extended(_) => unreachable!("unexpected for this input"),
+}
 ```
 
-For DateTime parsing, import the `parse_datetime` module:
+For DateTime parsing, import the `parse_datetime` function:
 
 ```rs
-use parse_datetime::parse_datetime::from_str;
-use chrono::{Local, TimeZone};
+use jiff::{civil::{date, time} ,Zoned};
+use parse_datetime::{parse_datetime, ParsedDateTime};
 
-let dt = from_str("2021-02-14 06:37:47");
-assert_eq!(dt.unwrap(), Local.with_ymd_and_hms(2021, 2, 14, 6, 37, 47).unwrap());
+let dt = parse_datetime("2021-02-14 06:37:47");
+match dt.unwrap() {
+  ParsedDateTime::InRange(z) => assert_eq!(z, Zoned::now().with().date(date(2021, 2, 14)).time(time(6, 37, 47, 0)).build().unwrap()),
+  ParsedDateTime::Extended(_) => unreachable!("unexpected for this input"),
+}
+```
+
+For years beyond jiff's representable range (e.g., year 10000+), the result is an `ExtendedDateTime`:
+
+```rs
+use parse_datetime::{parse_datetime, ParsedDateTime};
+
+let dt = parse_datetime("12000-01-01").unwrap();
+match dt {
+  ParsedDateTime::Extended(ext) => {
+    assert_eq!(ext.year, 12000);
+    assert_eq!(ext.month, 1);
+    assert_eq!(ext.day, 1);
+  }
+  ParsedDateTime::InRange(_) => unreachable!("year 12000 is out of jiff range"),
+}
 ```
 
 ### Supported Formats
@@ -59,7 +79,6 @@ The `parse_datetime` and `parse_datetime_at_date` functions support absolute dat
 - "tomorrow"
 - use "ago" for the past
 - use "next" or "last" with `unit` (e.g., "next week", "last year")
-- combined units with "and" or "," (e.g., "2 years and 1 month", "1 day, 2 hours" or "2 weeks 1 second")
 - unix timestamps (for example "@0" "@1344000")
 
 `num` can be a positive or negative integer.
@@ -71,7 +90,9 @@ The `parse_datetime` and `parse_datetime_at_date` functions support absolute dat
 
 The `parse_datetime` and `parse_datetime_at_date` function return:
 
-- `Ok(DateTime<FixedOffset>)` - If the input string can be parsed as a datetime
+- `Ok(ParsedDateTime)` - If the input string can be parsed
+  - `ParsedDateTime::InRange(Zoned)` for years supported by `jiff::Zoned`
+  - `ParsedDateTime::Extended(ExtendedDateTime)` for out-of-range years (for example `>9999`)
 - `Err(ParseDateTimeError::InvalidInput)` - If the input string cannot be parsed
 
 ## Fuzzer

benches/parse_datetime.rs

@@ -0,0 +1,146 @@
+use codspeed_criterion_compat::{criterion_group, criterion_main, Criterion};
+use jiff::Zoned;
+use parse_datetime::{parse_datetime, parse_datetime_at_date};
+
+fn bench_iso_datetime(c: &mut Criterion) {
+    c.bench_function("parse_iso_datetime", |b| {
+        b.iter(|| parse_datetime("2021-02-14 06:37:47 +0000"))
+    });
+}
+
+fn bench_iso_datetime_t_sep(c: &mut Criterion) {
+    c.bench_function("parse_iso_datetime_t_separator", |b| {
+        b.iter(|| parse_datetime("2021-02-14T22:37:47-0800"))
+    });
+}
+
+fn bench_date_only(c: &mut Criterion) {
+    c.bench_function("parse_date_only", |b| {
+        b.iter(|| parse_datetime("1997-01-01"))
+    });
+}
+
+fn bench_date_slash_format(c: &mut Criterion) {
+    c.bench_function("parse_date_slash_format", |b| {
+        b.iter(|| parse_datetime("05/07/1987"))
+    });
+}
+
+fn bench_epoch_timestamp(c: &mut Criterion) {
+    c.bench_function("parse_epoch_timestamp", |b| {
+        b.iter(|| parse_datetime("@1613371067"))
+    });
+}
+
+fn bench_relative_time(c: &mut Criterion) {
+    let now = Zoned::now();
+    c.bench_function("parse_relative_time", |b| {
+        b.iter(|| parse_datetime_at_date(now.clone(), "+3 days"))
+    });
+}
+
+fn bench_relative_time_complex(c: &mut Criterion) {
+    let now = Zoned::now();
+    c.bench_function("parse_relative_time_complex", |b| {
+        b.iter(|| parse_datetime_at_date(now.clone(), "1 year 3 months 2 days ago"))
+    });
+}
+
+fn bench_relative_keywords(c: &mut Criterion) {
+    c.bench_function("parse_yesterday", |b| {
+        b.iter(|| parse_datetime("yesterday"))
+    });
+    c.bench_function("parse_tomorrow", |b| b.iter(|| parse_datetime("tomorrow")));
+    c.bench_function("parse_now", |b| b.iter(|| parse_datetime("now")));
+}
+
+fn bench_weekday(c: &mut Criterion) {
+    c.bench_function("parse_weekday", |b| b.iter(|| parse_datetime("wednesday")));
+}
+
+fn bench_timezone_offset(c: &mut Criterion) {
+    c.bench_function("parse_timezone_offset", |b| {
+        b.iter(|| parse_datetime("UTC+07:00"))
+    });
+}
+
+fn bench_datetime_with_delta(c: &mut Criterion) {
+    c.bench_function("parse_datetime_with_delta", |b| {
+        b.iter(|| parse_datetime("1997-01-01 00:00:00 +0000 +1 year"))
+    });
+}
+
+fn bench_ctime_format(c: &mut Criterion) {
+    c.bench_function("parse_ctime_format", |b| {
+        b.iter(|| parse_datetime("Wed Jan  1 00:00:00 1997"))
+    });
+}
+
+fn bench_datetime_with_timezone_name(c: &mut Criterion) {
+    c.bench_function("parse_datetime_with_tz_name", |b| {
+        b.iter(|| parse_datetime("1997-01-19 08:17:48 BRT"))
+    });
+}
+
+fn bench_datetime_ending_in_z(c: &mut Criterion) {
+    c.bench_function("parse_datetime_ending_in_z", |b| {
+        b.iter(|| parse_datetime("2023-06-03 12:00:01Z"))
+    });
+}
+
+fn bench_invalid_input(c: &mut Criterion) {
+    c.bench_function("parse_invalid_input", |b| {
+        b.iter(|| parse_datetime("NotADate"))
+    });
+}
+
+fn bench_extended_year(c: &mut Criterion) {
+    c.bench_function("parse_extended_year", |b| {
+        b.iter(|| parse_datetime("10000-01-01"))
+    });
+}
+
+fn bench_extended_year_rollover(c: &mut Criterion) {
+    c.bench_function("parse_extended_year_rollover", |b| {
+        b.iter(|| parse_datetime("9999-12-31 +1 day"))
+    });
+}
+
+fn bench_extended_year_relative(c: &mut Criterion) {
+    let base = jiff::civil::DateTime::from(jiff::civil::date(2000, 1, 1))
+        .to_zoned(jiff::tz::TimeZone::UTC)
+        .unwrap();
+    c.bench_function("parse_extended_year_relative", |b| {
+        b.iter(|| parse_datetime_at_date(base.clone(), "10000-01-01 +1 day"))
+    });
+}
+
+fn bench_extended_large_year(c: &mut Criterion) {
+    c.bench_function("parse_extended_large_year", |b| {
+        b.iter(|| parse_datetime("999999-06-15"))
+    });
+}
+
+criterion_group!(
+    benches,
+    bench_iso_datetime,
+    bench_iso_datetime_t_sep,
+    bench_date_only,
+    bench_date_slash_format,
+    bench_epoch_timestamp,
+    bench_relative_time,
+    bench_relative_time_complex,
+    bench_relative_keywords,
+    bench_weekday,
+    bench_timezone_offset,
+    bench_datetime_with_delta,
+    bench_ctime_format,
+    bench_datetime_with_timezone_name,
+    bench_datetime_ending_in_z,
+    bench_invalid_input,
+    bench_extended_year,
+    bench_extended_year_rollover,
+    bench_extended_year_relative,
+    bench_extended_large_year,
+);
+criterion_main!(benches);

fuzz/Cargo.toml

@@ -7,10 +7,9 @@ edition = "2021"
 cargo-fuzz = true
 
 [dependencies]
-rand = "0.8.5"
-libfuzzer-sys = "0.4"
-regex = "1.9.5"
-chrono = { version="0.4", default-features=false, features=["std", "alloc", "clock"] }
+libfuzzer-sys = "0.4.7"
+arbitrary = { version = "1", features = ["derive"] }
+jiff = "0.2"
 
 [dependencies.parse_datetime]
 path = "../"
@@ -20,3 +19,9 @@ name = "fuzz_parse_datetime"
 path = "fuzz_targets/parse_datetime.rs"
 test = false
 doc = false
+
+[[bin]]
+name = "fuzz_large_year"
+path = "fuzz_targets/large_year.rs"
+test = false
+doc = false

fuzz/fuzz_targets/large_year.rs

@@ -0,0 +1,64 @@
+#![no_main]
+
+use arbitrary::Arbitrary;
+use jiff::{civil::DateTime, tz::TimeZone};
+use libfuzzer_sys::fuzz_target;
+
+#[derive(Arbitrary, Debug)]
+struct Input {
+    /// Year for the base date (biased toward boundary years).
+    base_year_selector: u8,
+    /// Year to embed in a constructed large-year input string.
+    input_year: u32,
+    month: u8,
+    day: u8,
+    /// Suffix appended after the constructed date (e.g. relative items).
+    suffix: String,
+    /// Whether to also call parse_datetime (no base).
+    try_no_base: bool,
+}
+
+fn base_year(selector: u8) -> i16 {
+    match selector % 6 {
+        0 => 2024,
+        1 => 9998,
+        2 => 9999,
+        3 => 1,
+        4 => 100,
+        _ => (selector as i16) * 40,
+    }
+}
+
+fn clamp_year(y: u32) -> u32 {
+    // Focus on the interesting range: 9990..=100_000 and 0..=20_000
+    match y % 4 {
+        0 => 9990 + (y % 20),          // near boundary
+        1 => 10000 + (y % 90_000),     // large years
+        2 => y % 20_000,               // general range
+        _ => 2_147_485_540 + (y % 10), // near GNU_MAX_YEAR
+    }
+}
+
+fuzz_target!(|input: Input| {
+    let year = clamp_year(input.input_year);
+    let month = (input.month % 12) + 1;
+    let day = (input.day % 28) + 1;
+    let date_str = format!("{year:04}-{month:02}-{day:02} {}", input.suffix);
+
+    // Test parse_datetime (uses current time as base).
+    if input.try_no_base {
+        let _ = parse_datetime::parse_datetime(&date_str);
+    }
+
+    // Test parse_datetime_at_date with a controlled base.
+    let by = base_year(input.base_year_selector);
+    if let Ok(base) = DateTime::new(by, 1, 1, 0, 0, 0, 0) {
+        if let Ok(base) = base.to_zoned(TimeZone::UTC) {
+            let _ = parse_datetime::parse_datetime_at_date(base, &date_str);
+        }
+    }
+
+    // Also try a bare large year as a pure number.
+    let bare = format!("{year}");
+    let _ = parse_datetime::parse_datetime(&bare);
+});

renovate.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": [
-    "config:base"
+    "config:recommended"
   ]
 }

src/items/combined.rs

@@ -0,0 +1,76 @@
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+//! Parse an ISO 8601 date and time item
+//!
+//! The GNU docs state:
+//!
+//! > The ISO 8601 date and time of day extended format consists of an ISO 8601
+//! > date, a ‘T’ character separator, and an ISO 8601 time of day. This format
+//! > is also recognized if the ‘T’ is replaced by a space.
+//! >
+//! > In this format, the time of day should use 24-hour notation. Fractional
+//! > seconds are allowed, with either comma or period preceding the fraction.
+//! > ISO 8601 fractional minutes and hours are not supported. Typically, hosts
+//! > support nanosecond timestamp resolution; excess precision is silently
+//! > discarded.
+use winnow::{
+    combinator::{alt, trace},
+    seq, ModalResult, Parser,
+};
+
+use crate::items::space;
+
+use super::{date, primitive::s, time};
+
+#[derive(PartialEq, Debug, Clone, Default)]
+pub(crate) struct DateTime {
+    pub(crate) date: date::Date,
+    pub(crate) time: time::Time,
+}
+
+pub(crate) fn parse(input: &mut &str) -> ModalResult<DateTime> {
+    seq!(DateTime {
+        date: trace("iso_date", alt((date::iso1, date::iso2))),
+        // Note: the `T` is lowercased by the main parse function
+        _: alt((s('t').void(), (' ', space).void())),
+        time: trace("iso_time", time::iso),
+    })
+    .parse_next(input)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{parse, DateTime};
+    use crate::items::{date::Date, time::Time};
+
+    #[test]
+    fn some_date() {
+        let reference = Some(DateTime {
+            date: Date {
+                day: 10,
+                month: 10,
+                year: Some(2022),
+            },
+            time: Time {
+                hour: 10,
+                minute: 10,
+                second: 55,
+                nanosecond: 0,
+                offset: None,
+            },
+        });
+
+        for mut s in [
+            "2022-10-10t10:10:55",
+            "2022-10-10 10:10:55",
+            "2022-10-10    t   10:10:55",
+            "2022-10-10       10:10:55",
+            "2022-10-10  (A comment!) t   10:10:55",
+            "2022-10-10  (A comment!)   10:10:55",
+        ] {
+            let old_s = s.to_owned();
+            assert_eq!(parse(&mut s).ok(), reference, "Failed string: {old_s}")
+        }
+    }
+}

src/items/epoch.rs

@@ -0,0 +1,137 @@
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+//! Parse a timestamp item.
+//!
+//! From the GNU docs:
+//!
+//! > If you precede a number with ‘@’, it represents an internal timestamp as
+//! > a count of seconds.  The number can contain an internal decimal point
+//! > (either ‘.’ or ‘,’); any excess precision not supported by the internal
+//! > representation is truncated toward minus infinity.  Such a number cannot
+//! > be combined with any other date item, as it specifies a complete
+//! > timestamp.
+//! >
+//! >    On most hosts, these counts ignore the presence of leap seconds.  For
+//! > example, on most hosts ‘@1483228799’ represents 2016-12-31 23:59:59 UTC,
+//! > ‘@1483228800’ represents 2017-01-01 00:00:00 UTC, and there is no way to
+//! > represent the intervening leap second 2016-12-31 23:59:60 UTC.
+
+use winnow::{
+    ascii::digit1,
+    combinator::{opt, preceded},
+    token::one_of,
+    ModalResult, Parser,
+};
+
+use super::primitive::{dec_uint, plus_or_minus, s};
+
+/// Represents a timestamp with nanosecond accuracy.
+///
+/// # Invariants
+///
+/// - `nanosecond` is always in the range of `0..1_000_000_000`.
+/// - Negative timestamps are represented by a negative `second` value and a
+///   positive `nanosecond` value.
+#[derive(Debug, PartialEq, Clone, Copy)]
+pub(super) struct Timestamp {
+    second: i64,
+    nanosecond: u32,
+}
+
+impl TryFrom<Timestamp> for jiff::Timestamp {
+    type Error = &'static str;
+
+    fn try_from(ts: Timestamp) -> Result<Self, Self::Error> {
+        jiff::Timestamp::new(
+            ts.second,
+            i32::try_from(ts.nanosecond).map_err(|_| "nanosecond in timestamp exceeds i32::MAX")?,
+        )
+        .map_err(|_| "timestamp value is out of valid range")
+    }
+}
+
+/// Parse a timestamp in the form of `@1234567890` or `@-1234567890.12345` or
+/// `@1234567890,12345`.
+pub(super) fn parse(input: &mut &str) -> ModalResult<Timestamp> {
+    (s("@"), opt(plus_or_minus), s(sec_and_nsec))
+        .verify_map(|(_, sign, (sec, nsec))| {
+            let sec = i64::try_from(sec).ok()?;
+            let (second, nanosecond) = match (sign, nsec) {
+                (Some('-'), 0) => (-sec, 0),
+                // Truncate towards minus infinity.
+                (Some('-'), _) => ((-sec).checked_sub(1)?, 1_000_000_000 - nsec),
+                _ => (sec, nsec),
+            };
+            Some(Timestamp { second, nanosecond })
+        })
+        .parse_next(input)
+}
+
+/// Parse a second value in the form of `1234567890` or `1234567890.12345` or
+/// `1234567890,12345`.
+///
+/// The first part represents whole seconds. The optional second part represents
+/// fractional seconds, parsed as a nanosecond value from up to 9 digits
+/// (padded with zeros on the right if fewer digits are present). If the second
+/// part is omitted, it defaults to 0 nanoseconds.
+pub(super) fn sec_and_nsec(input: &mut &str) -> ModalResult<(u64, u32)> {
+    (dec_uint, opt(preceded(one_of(['.', ',']), digit1)))
+        .verify_map(|(sec, opt_nsec_str)| match opt_nsec_str {
+            Some(nsec_str) if nsec_str.len() >= 9 => Some((sec, nsec_str[..9].parse().ok()?)),
+            Some(nsec_str) => {
+                let multiplier = 10_u32.pow(9 - nsec_str.len() as u32);
+                Some((sec, nsec_str.parse::<u32>().ok()?.checked_mul(multiplier)?))
+            }
+            None => Some((sec, 0)),
+        })
+        .parse_next(input)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn ts(second: i64, nanosecond: u32) -> Timestamp {
+        Timestamp { second, nanosecond }
+    }
+
+    #[test]
+    fn parse_sec_and_nsec() {
+        for (input, expected) in [
+            ("1234567890", (1234567890, 0)),                       // only seconds
+            ("1234567890.12345", (1234567890, 123450000)), // seconds and nanoseconds, '.' as floating point
+            ("1234567890,12345", (1234567890, 123450000)), // seconds and nanoseconds, ',' as floating point
+            ("1234567890.1234567890123", (1234567890, 123456789)), // nanoseconds with more than 9 digits, truncated
+        ] {
+            let mut s = input;
+            assert_eq!(sec_and_nsec(&mut s).unwrap(), expected, "{input}");
+        }
+
+        for input in [
+            ".1234567890", // invalid: no leading seconds
+            "-1234567890", // invalid: negative input not allowed
+        ] {
+            let mut s = input;
+            assert!(sec_and_nsec(&mut s).is_err(), "{input}");
+        }
+    }
+
+    #[test]
+    fn timestamp() {
+        for (input, expected) in [
+            ("@1234567890", ts(1234567890, 0)), // positive seconds, no nanoseconds
+            ("@ 1234567890", ts(1234567890, 0)), // space after '@', positive seconds, no nanoseconds
+            ("@-1234567890", ts(-1234567890, 0)), // negative seconds, no nanoseconds
+            ("@ -1234567890", ts(-1234567890, 0)), // space after '@', negative seconds, no nanoseconds
+            ("@ - 1234567890", ts(-1234567890, 0)), // space after '@' and after '-', negative seconds, no nanoseconds
+            ("@1234567890.12345", ts(1234567890, 123450000)), // positive seconds with nanoseconds, '.' as floating point
+            ("@1234567890,12345", ts(1234567890, 123450000)), // positive seconds with nanoseconds, ',' as floating point
+            ("@-1234567890.12345", ts(-1234567891, 876550000)), // negative seconds with nanoseconds, '.' as floating point
+            ("@1234567890.1234567890123", ts(1234567890, 123456789)), // nanoseconds with more than 9 digits, truncated
+        ] {
+            let mut s = input;
+            assert_eq!(parse(&mut s).unwrap(), expected, "{input}");
+        }
+    }
+}

src/items/error.rs

@@ -0,0 +1,38 @@
+use std::fmt;
+
+use winnow::error::{ContextError, ErrMode};
+
+#[derive(Debug)]
+pub(crate) enum Error {
+    ParseError(String),
+}
+
+impl std::error::Error for Error {}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Error::ParseError(reason) => {
+                write!(f, "{reason}")
+            }
+        }
+    }
+}
+
+impl From<&'static str> for Error {
+    fn from(reason: &'static str) -> Self {
+        Error::ParseError(reason.to_owned())
+    }
+}
+
+impl From<ErrMode<ContextError>> for Error {
+    fn from(err: ErrMode<ContextError>) -> Self {
+        Error::ParseError(err.to_string())
+    }
+}
+
+impl From<jiff::Error> for Error {
+    fn from(err: jiff::Error) -> Self {
+        Error::ParseError(err.to_string())
+    }
+}

src/items/offset.rs

@@ -0,0 +1,485 @@
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+//! Parse an offset item.
+//!
+//! From the GNU docs:
+//!
+//! > A “time zone item” specifies an international time zone, indicated by a
+//! > small set of letters, e.g., ‘UTC’ or ‘Z’ for Coordinated Universal Time.
+//! > Any included periods are ignored.  By following a non-daylight-saving
+//! > time zone by the string ‘DST’ in a separate word (that is, separated by
+//! > some white space), the corresponding daylight saving time zone may be
+//! > specified.  Alternatively, a non-daylight-saving time zone can be
+//! > followed by a time zone correction, to add the two values.  This is
+//! > normally done only for ‘UTC’; for example, ‘UTC+05:30’ is equivalent to
+//! > ‘+05:30’.
+//! >
+//! >    Time zone items other than ‘UTC’ and ‘Z’ are obsolescent and are not
+//! > recommended, because they are ambiguous; for example, ‘EST’ has a
+//! > different meaning in Australia than in the United States, and ‘A’ has
+//! > different meaning as a military time zone than as an obsolete RFC 822
+//! > time zone.  Instead, it's better to use unambiguous numeric time zone
+//! > corrections like ‘-0500’, as described in the previous section.
+//! >
+//! >    If neither a time zone item nor a time zone correction is supplied,
+//! > timestamps are interpreted using the rules of the default time zone.
+
+use std::fmt::Display;
+
+use winnow::{
+    combinator::{alt, peek},
+    error::{ContextError, ErrMode},
+    stream::{AsChar, Stream},
+    token::take_while,
+    ModalResult, Parser,
+};
+
+use super::{
+    primitive::{colon, ctx_err, dec_uint, dec_uint_str, plus_or_minus, s},
+    relative,
+};
+
+/// Represents a time zone offset from UTC.
+///
+/// This struct is used to represent a time zone offset in hours and minutes,
+/// with a boolean indicating whether the offset is negative (i.e., west of
+/// UTC).
+#[derive(PartialEq, Debug, Clone, Default)]
+pub(super) struct Offset {
+    negative: bool,
+    hours: u8,
+    minutes: u8,
+}
+
+impl Offset {
+    /// Merge two timezone offsets.
+    ///
+    /// Note: when parsing an offset from a string (e.g., "+08:00"), the hours
+    /// and minutes are validated to ensure they fall within valid bounds. In
+    /// contrast, merging two offsets does not perform such validation. This
+    /// behavior is intentional to match GNU date.
+    fn merge(self, offset: Offset) -> Offset {
+        fn combine(a: u16, neg_a: bool, b: u16, neg_b: bool) -> (u16, bool) {
+            if neg_a == neg_b {
+                (a + b, neg_a)
+            } else if a > b {
+                (a - b, neg_a)
+            } else {
+                (b - a, neg_b)
+            }
+        }
+        let (total_minutes, negative) = combine(
+            (self.hours as u16) * 60 + (self.minutes as u16),
+            self.negative,
+            (offset.hours as u16) * 60 + (offset.minutes as u16),
+            offset.negative,
+        );
+        let hours = (total_minutes / 60) as u8;
+        let minutes = (total_minutes % 60) as u8;
+
+        Offset {
+            negative,
+            hours,
+            minutes,
+        }
+    }
+
+    /// Normalize the offset so that the hour field is within the accepted range.
+    ///
+    /// - If the hour field is less than 24, or exactly 24 with a zero minute,
+    ///   the offset is already normalized, and the function returns the offset
+    ///   itself along with a zero hour adjustment.
+    /// - Otherwise, the hour field is reduced to 23 while preserving the minute
+    ///   field, and the function returns the normalized offset along with the
+    ///   hour adjustment needed to reach the original offset.
+    pub(super) fn normalize(self) -> (Offset, i8) {
+        if self.hours < 24 || (self.hours == 24 && self.minutes == 0) {
+            return (self, 0);
+        }
+
+        let hour_adjustment = (self.hours as i8 - 23) * if self.negative { 1 } else { -1 };
+        (
+            Offset {
+                negative: self.negative,
+                hours: 23,
+                minutes: self.minutes,
+            },
+            hour_adjustment,
+        )
+    }
+
+    pub(super) fn total_seconds(&self) -> i32 {
+        let secs = (self.hours as i32) * 3600 + (self.minutes as i32) * 60;
+        if self.negative {
+            -secs
+        } else {
+            secs
+        }
+    }
+}
+
+impl TryFrom<(bool, u8, u8)> for Offset {
+    type Error = &'static str;
+
+    fn try_from((negative, hours, minutes): (bool, u8, u8)) -> Result<Self, Self::Error> {
+        if hours > 24 {
+            return Err("timezone hour must be between 0 and 24");
+        }
+        if minutes > 60 || (hours == 24 && minutes != 0) {
+            return Err("timezone minute must be between 0 and 60");
+        }
+
+        Ok(Offset {
+            negative,
+            hours,
+            minutes,
+        })
+    }
+}
+
+impl TryFrom<&Offset> for jiff::tz::TimeZone {
+    type Error = &'static str;
+
+    fn try_from(
+        Offset {
+            negative,
+            hours,
+            minutes,
+        }: &Offset,
+    ) -> Result<Self, Self::Error> {
+        let secs = (*hours as i32) * 3600 + (*minutes as i32) * 60;
+        let secs = if *negative { -secs } else { secs };
+
+        let offset = jiff::tz::Offset::from_seconds(secs).map_err(|_| "offset is invalid")?;
+        Ok(jiff::tz::TimeZone::fixed(offset))
+    }
+}
+
+impl Display for Offset {
+    fn fmt(&self, fmt: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> {
+        write!(
+            fmt,
+            "{}{:02}:{:02}",
+            if self.negative { "-" } else { "+" },
+            self.hours,
+            self.minutes
+        )
+    }
+}
+
+pub(super) fn parse(input: &mut &str) -> ModalResult<Offset> {
+    timezone_name_offset.parse_next(input)
+}
+
+/// Parse a timezone starting with `+` or `-`.
+pub(super) fn timezone_offset(input: &mut &str) -> ModalResult<Offset> {
+    // Strings like "+8 years" are ambiguous, they can either be parsed as a
+    // timezone offset "+8" and a relative time "years", or just a relative time
+    // "+8 years". GNU date parses them the second way, so we do the same here.
+    //
+    // Return early if the input can be parsed as a relative time.
+    if peek(relative::parse).parse_next(input).is_ok() {
+        return Err(ErrMode::Backtrack(ContextError::new()));
+    }
+
+    alt((timezone_offset_colon, timezone_offset_colonless)).parse_next(input)
+}
+
+/// Parse a timezone by name, with an optional numeric offset appended.
+fn timezone_name_offset(input: &mut &str) -> ModalResult<Offset> {
+    /// I'm assuming there are no timezone abbreviations with more
+    /// than 6 charactres
+    const MAX_TZ_SIZE: usize = 6;
+    let nextword = s(take_while(1..=MAX_TZ_SIZE, AsChar::is_alpha)).parse_next(input)?;
+    let tz = timezone_name_to_offset(nextword)?;
+
+    // Strings like "UTC +8 years" are ambiguous, they can either be parsed as
+    // "UTC+8" and "years", or "UTC" and "+8 years". GNU date parses them the
+    // second way, so we do the same here.
+    //
+    // Only process if the input cannot be parsed as a relative time.
+    if peek(relative::parse).parse_next(input).is_err() {
+        let start = input.checkpoint();
+        if let Ok(other_tz) = timezone_offset.parse_next(input) {
+            let new_tz = tz.merge(other_tz);
+
+            return Ok(new_tz);
+        };
+        input.reset(&start);
+    }
+
+    Ok(tz)
+}
+
+/// Parse a timezone offset with a colon separating hours and minutes, e.g.,
+/// `+08:00`, `+8:00`, `+8:0`.
+fn timezone_offset_colon(input: &mut &str) -> ModalResult<Offset> {
+    (plus_or_minus, s(dec_uint), s(colon), s(dec_uint))
+        .parse_next(input)
+        .and_then(|(sign, hours, _, minutes)| {
+            (sign == '-', hours, minutes)
+                .try_into()
+                .map_err(|e| ErrMode::Cut(ctx_err(e)))
+        })
+}
+
+/// Parse a timezone offset without colon, e.g., `+0800`, `+800`, `+08`, `+8`.
+fn timezone_offset_colonless(input: &mut &str) -> ModalResult<Offset> {
+    (plus_or_minus, s(dec_uint_str))
+        .verify_map(|(sign, s)| {
+            // GNU date accepts numeric offset strings with leading zeroes. For
+            // example, `+000000110` is valid. In such cases, the string is
+            // truncated to the last four characters. Thus, `+000000110` becomes
+            // `+0110` (note that one leading zero is kept).
+            let s = if s.len() > 4 && s.trim_start_matches('0').len() <= 4 {
+                &s[s.len() - 4..]
+            } else {
+                s
+            };
+
+            // Hour and minute values are dependent on the length of the string.
+            // For example:
+            //
+            // - "5"   -> 05:00
+            // - "05"  -> 05:00
+            // - "530" -> 05:30 (the minute is the last two characters here)
+            // - "0530"-> 05:30
+            // - "0000530" -> 05:30
+            let (h_str, m_str) = match s.len() {
+                1 | 2 => (s, "0"),
+                3 => s.split_at(1),
+                4 => s.split_at(2),
+                _ => return None,
+            };
+
+            let hours = h_str.parse::<u8>().ok()?;
+            let minutes = m_str.parse::<u8>().ok()?;
+            Some((sign, hours, minutes))
+        })
+        .parse_next(input)
+        .and_then(|(sign, hours, minutes)| {
+            (sign == '-', hours, minutes)
+                .try_into()
+                .map_err(|e| ErrMode::Cut(ctx_err(e)))
+        })
+}
+
+/// Named timezone list.
+///
+/// The full list of timezones can be extracted from
+/// https://www.timeanddate.com/time/zones/. GNU date only supports a subset of
+/// these. We support the same subset as GNU date.
+fn timezone_name_to_offset(input: &str) -> ModalResult<Offset> {
+    let mut offset_str = match input {
+        "z" => Ok("+0"),
+        "y" => Ok("-12"),
+        "x" => Ok("-11"),
+        "wet" => Ok("+0"),
+        "west" => Ok("+1"),
+        "wat" => Ok("+1"),
+        "w" => Ok("-10"),
+        "v" => Ok("-9"),
+        "utc" => Ok("+0"),
+        "u" => Ok("-8"),
+        "t" => Ok("-7"),
+        "sst" => Ok("-11"),
+        "sgt" => Ok("+8"),
+        "sast" => Ok("+2"),
+        "s" => Ok("-6"),
+        "r" => Ok("-5"),
+        "q" => Ok("-4"),
+        "pst" => Ok("-8"),
+        "pdt" => Ok("-7"),
+        "p" => Ok("-3"),
+        "o" => Ok("-2"),
+        "nzst" => Ok("+12"),
+        "nzdt" => Ok("+13"),
+        "nst" => Ok("-3:30"),
+        "ndt" => Ok("-2:30"),
+        "n" => Ok("-1"),
+        "mst" => Ok("-7"),
+        "msk" => Ok("+3"),
+        "msd" => Ok("+4"),
+        "mdt" => Ok("-6"),
+        "m" => Ok("+12"),
+        "l" => Ok("+11"),
+        "k" => Ok("+10"),
+        "jst" => Ok("+9"),
+        "ist" => Ok("+5:30"),
+        "i" => Ok("+9"),
+        "hst" => Ok("-10"),
+        "h" => Ok("+8"),
+        "gst" => Ok("+4"),
+        "gmt" => Ok("+0"),
+        "g" => Ok("+7"),
+        "f" => Ok("+6"),
+        "est" => Ok("-5"),
+        "eet" => Ok("+2"),
+        "eest" => Ok("+3"),
+        "edt" => Ok("-4"),
+        "eat" => Ok("+3"),
+        "e" => Ok("+5"),
+        "d" => Ok("+4"),
+        "cst" => Ok("-6"),
+        "clt" => Ok("-4"),
+        "clst" => Ok("-3"),
+        "cet" => Ok("+1"),
+        "cest" => Ok("+2"),
+        "cdt" => Ok("-5"),
+        "cat" => Ok("+2"),
+        "c" => Ok("+3"),
+        "bst" => Ok("+6"),
+        "brt" => Ok("-3"),
+        "brst" => Ok("-2"),
+        "b" => Ok("+2"),
+        "ast" => Ok("-3"),
+        "art" => Ok("-3"),
+        "akst" => Ok("-9"),
+        "akdt" => Ok("-8"),
+        "adt" => Ok("+4"),
+        "a" => Ok("+1"),
+        _ => Err(ErrMode::Backtrack(ContextError::new())),
+    }?;
+
+    timezone_offset(&mut offset_str)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn off(negative: bool, hours: u8, minutes: u8) -> Offset {
+        Offset {
+            negative,
+            hours,
+            minutes,
+        }
+    }
+
+    #[test]
+    fn timezone_offset_with_colon() {
+        for (input, expected) in [
+            ("+00:00", off(false, 0, 0)),        // UTC
+            ("-00:00", off(true, 0, 0)),         // UTC
+            ("+01:00", off(false, 1, 0)),        // positive offset
+            ("-06:00", off(true, 6, 0)),         // negative offset
+            ("+05:30", off(false, 5, 30)),       // positive offset with non-zero minutes
+            ("-03:30", off(true, 3, 30)),        // negative offset with non-zero minutes
+            ("- 06:00", off(true, 6, 0)),        // space after sign
+            ("- 06 : 00", off(true, 6, 0)),      // space around colon
+            ("+5:3", off(false, 5, 3)),          // single-digit hours and single-digit minutes
+            ("+5:03", off(false, 5, 3)),         // single-digit hours
+            ("+05:3", off(false, 5, 3)),         // single-digit minutes
+            ("+00005:00030", off(false, 5, 30)), // leading zeroes in hours and minutes
+            ("+00:00abc", off(false, 0, 0)), // space separator can be ignored if immediately followed by alphas (GNU date behavior)
+        ] {
+            let mut s = input;
+            assert_eq!(timezone_offset(&mut s).unwrap(), expected, "{input}");
+        }
+
+        for input in [
+            "+25:00", // invalid: hours > 24
+            "-23:61", // invalid: minutes > 60
+            "+24:01", // invalid: minutes > 0 when hours == 24
+        ] {
+            let mut s = input;
+            assert!(timezone_offset(&mut s).is_err(), "{input}");
+        }
+    }
+
+    #[test]
+    fn timezone_offset_without_colon() {
+        for (input, expected) in [
+            ("+0000", off(false, 0, 0)),      // UTC
+            ("-0000", off(true, 0, 0)),       // UTC
+            ("+0100", off(false, 1, 0)),      // positive offset
+            ("-0600", off(true, 6, 0)),       // negative offset
+            ("+0530", off(false, 5, 30)),     // positive offset with non-zero minutes
+            ("-0330", off(true, 3, 30)),      // negative offset with non-zero minutes
+            ("- 0330", off(true, 3, 30)),     // space after sign
+            ("+530", off(false, 5, 30)),      // single-digit hours
+            ("+05", off(false, 5, 0)),        // double-digit hours and no minutes
+            ("+5", off(false, 5, 0)),         // single-digit hours and no minutes
+            ("+00000530", off(false, 5, 30)), // leading zeroes
+            ("+0000abc", off(false, 0, 0)), // space separator can be ignored if immediately followed by alphas (GNU date behavior)
+        ] {
+            let mut s = input;
+            assert_eq!(timezone_offset(&mut s).unwrap(), expected, "{input}");
+        }
+
+        for input in [
+            "+2500",    // invalid: hours > 24
+            "-2361",    // invalid: minutes > 60
+            "+2401",    // invalid: minutes > 0 when hours == 24
+            "+23 days", // invalid: ambiguous with relative time parsing
+        ] {
+            let mut s = input;
+            assert!(timezone_offset(&mut s).is_err(), "{input}");
+        }
+    }
+
+    #[test]
+    fn timezone_name_without_offset() {
+        for (input, expected) in [
+            ("utc", off(false, 0, 0)),  // UTC
+            ("gmt", off(false, 0, 0)),  // UTC
+            ("z", off(false, 0, 0)),    // UTC
+            ("west", off(false, 1, 0)), // positive offset
+            ("cst", off(true, 6, 0)),   // negative offset
+            ("ist", off(false, 5, 30)), // positive offset with non-zero minutes
+            ("nst", off(true, 3, 30)),  // negative offset with non-zero minutes
+            ("z123", off(false, 0, 0)), // space separator can be ignored if immediately followed by digits (GNU date behavior)
+        ] {
+            let mut s = input;
+            assert_eq!(timezone_name_offset(&mut s).unwrap(), expected, "{input}");
+        }
+
+        for input in [
+            "abc",    // invalid: non-existent timezone
+            "utcabc", // invalid: non-existent timezone
+        ] {
+            let mut s = input;
+            assert!(timezone_name_offset(&mut s).is_err(), "{input}");
+        }
+    }
+
+    #[test]
+    fn timezone_name_with_offset() {
+        for (input, expected) in [
+            ("utc+5:30", off(false, 5, 30)),     // UTC with possitive offset
+            ("utc-5:30", off(true, 5, 30)),      // UTC with negative offset
+            ("utc +5:30", off(false, 5, 30)),    // space after timezone name
+            ("utc + 5 : 30", off(false, 5, 30)), // spaces
+            ("a+5:30", off(false, 6, 30)),       // merge two positive offsets (a=+1)
+            ("a-5:30", off(true, 4, 30)),        // merge positive and negative offsets (a=+1)
+            ("n-5:30", off(true, 6, 30)),        // merge two negative offsets (n=-1)
+            ("n+5:30", off(false, 4, 30)),       // merge negative and positive offsets (n=-1)
+            ("m+24", off(false, 36, 0)),         // maximum possible positive offset (m=+12)
+            ("y-24", off(true, 36, 0)),          // maximum possible negative offset (y=-12)
+        ] {
+            let mut s = input;
+            assert_eq!(timezone_name_offset(&mut s).unwrap(), expected, "{input}");
+        }
+
+        for input in [
+            "abc+08:00",   // invalid: non-existent timezone
+            "utc+25",      // invalid: invalid offset
+            "utc+23 days", // invalid: ambiguous with relative time parsing
+        ] {
+            let mut s = input;
+            assert!(
+                timezone_name_offset(&mut s).is_err() || !s.is_empty(),
+                "{input}"
+            );
+        }
+    }
+
+    #[test]
+    fn total_seconds() {
+        assert_eq!(off(false, 0, 0).total_seconds(), 0);
+        assert_eq!(off(false, 5, 30).total_seconds(), 19_800);
+        assert_eq!(off(true, 5, 30).total_seconds(), -19_800);
+        assert_eq!(off(false, 24, 0).total_seconds(), 86_400);
+    }
+}

src/items/ordinal.rs

@@ -0,0 +1,47 @@
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use winnow::{
+    ascii::alpha1,
+    combinator::{alt, opt},
+    ModalResult, Parser,
+};
+
+use super::primitive::{dec_uint, s};
+
+pub(super) fn ordinal(input: &mut &str) -> ModalResult<i32> {
+    alt((text_ordinal, number_ordinal)).parse_next(input)
+}
+
+fn number_ordinal(input: &mut &str) -> ModalResult<i32> {
+    let sign = opt(alt(('+'.value(1), '-'.value(-1)))).map(|s| s.unwrap_or(1));
+    (s(sign), s(dec_uint))
+        .verify_map(|(s, u): (i32, u32)| {
+            let i: i32 = u.try_into().ok()?;
+            Some(s * i)
+        })
+        .parse_next(input)
+}
+
+fn text_ordinal(input: &mut &str) -> ModalResult<i32> {
+    s(alpha1)
+        .verify_map(|s: &str| {
+            Some(match s {
+                "last" => -1,
+                "this" => 0,
+                "next" | "first" => 1,
+                "third" => 3,
+                "fourth" => 4,
+                "fifth" => 5,
+                "sixth" => 6,
+                "seventh" => 7,
+                "eight" => 8,
+                "ninth" => 9,
+                "tenth" => 10,
+                "eleventh" => 11,
+                "twelfth" => 12,
+                _ => return None,
+            })
+        })
+        .parse_next(input)
+}

src/items/primitive.rs

@@ -0,0 +1,205 @@
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+//! Primitive combinators.
+
+use std::str::FromStr;
+
+use winnow::{
+    ascii::{digit1, multispace0, Uint},
+    combinator::{alt, delimited, not, opt, peek, preceded, repeat, separated},
+    error::{ContextError, ParserError, StrContext, StrContextValue},
+    stream::AsChar,
+    token::{none_of, one_of, take_while},
+    Parser,
+};
+
+/// Allow spaces and comments before a parser
+///
+/// Every token parser should be wrapped in this to allow spaces and comments.
+/// It is only preceding, because that allows us to check mandatory whitespace
+/// after running the parser.
+pub(super) fn s<'a, O, E>(p: impl Parser<&'a str, O, E>) -> impl Parser<&'a str, O, E>
+where
+    E: ParserError<&'a str>,
+{
+    preceded(space, p)
+}
+
+/// Parse the space in-between tokens
+///
+/// You probably want to use the [`s`] combinator instead.
+pub(super) fn space<'a, E>(input: &mut &'a str) -> winnow::Result<(), E>
+where
+    E: ParserError<&'a str>,
+{
+    separated(0.., multispace0, alt((comment, ignored_hyphen_or_plus))).parse_next(input)
+}
+
+/// A hyphen or plus is ignored when it is not followed by a digit
+///
+/// This includes being followed by a comment! Compare these inputs:
+/// ```txt
+/// - 12 weeks
+/// - (comment) 12 weeks
+/// ```
+/// The last comment should be ignored.
+///
+/// The plus is undocumented, but it seems to be ignored.
+fn ignored_hyphen_or_plus<'a, E>(input: &mut &'a str) -> winnow::Result<(), E>
+where
+    E: ParserError<&'a str>,
+{
+    (
+        alt(('-', '+')),
+        multispace0,
+        peek(not(take_while(1, AsChar::is_dec_digit))),
+    )
+        .void()
+        .parse_next(input)
+}
+
+/// Parse a comment
+///
+/// A comment is given between parentheses, which must be balanced. Any other
+/// tokens can be within the comment.
+fn comment<'a, E>(input: &mut &'a str) -> winnow::Result<(), E>
+where
+    E: ParserError<&'a str>,
+{
+    delimited(
+        '(',
+        repeat(0.., alt((none_of(['(', ')']).void(), comment))),
+        ')',
+    )
+    .parse_next(input)
+}
+
+/// Parse a signed decimal integer.
+///
+/// Rationale for not using `winnow::ascii::dec_int`: When upgrading winnow from
+/// 0.5 to 0.7, we discovered that `winnow::ascii::dec_int` now accepts only the
+/// following two forms:
+///
+/// - 0
+/// - [+-]?[1-9][0-9]*
+///
+/// Inputs like [+-]?0[0-9]* (e.g., `+012`) are therefore rejected. We provide a
+/// custom implementation to support such zero-prefixed integers.
+#[allow(unused)]
+pub(super) fn dec_int<'a, E>(input: &mut &'a str) -> winnow::Result<i32, E>
+where
+    E: ParserError<&'a str>,
+{
+    (opt(one_of(['+', '-'])), digit1)
+        .void()
+        .take()
+        .verify_map(|s: &str| s.parse().ok())
+        .parse_next(input)
+}
+
+/// Parse an unsigned decimal integer.
+///
+/// See the rationale for `dec_int` for why we don't use
+/// `winnow::ascii::dec_uint`.
+pub(super) fn dec_uint<'a, O, E>(input: &mut &'a str) -> winnow::Result<O, E>
+where
+    O: Uint + FromStr,
+    E: ParserError<&'a str>,
+{
+    dec_uint_str
+        .verify_map(|s: &str| s.parse().ok())
+        .parse_next(input)
+}
+
+/// Parse an unsigned decimal integer as a string slice.
+pub(super) fn dec_uint_str<'a, E>(input: &mut &'a str) -> winnow::Result<&'a str, E>
+where
+    E: ParserError<&'a str>,
+{
+    digit1.void().take().parse_next(input)
+}
+
+/// Parse a colon preceded by whitespace.
+pub(super) fn colon<'a, E>(input: &mut &'a str) -> winnow::Result<(), E>
+where
+    E: ParserError<&'a str>,
+{
+    s(':').void().parse_next(input)
+}
+
+/// Parse a plus or minus character optionally preceeded by whitespace.
+pub(super) fn plus_or_minus<'a, E>(input: &mut &'a str) -> winnow::Result<char, E>
+where
+    E: ParserError<&'a str>,
+{
+    s(alt(('+', '-'))).parse_next(input)
+}
+
+/// Create a context error with a reason.
+pub(super) fn ctx_err(reason: &'static str) -> ContextError {
+    let mut err = ContextError::new();
+    err.push(StrContext::Expected(StrContextValue::Description(reason)));
+    err
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_dec_int() {
+        for (input, expected) in [
+            ("123", 123),                 // positive without sign
+            ("+123", 123),                // positive with '+' sign
+            ("-123", -123),               // negative with '-' sign
+            ("0", 0),                     // zero
+            ("+0", 0),                    // zero with '+' sign
+            ("-0", 0),                    // zero with '-' sign (parses as 0)
+            ("012", 12),                  // zero-prefixed (the main reason for this function)
+            ("+012", 12),                 // zero-prefixed with '+' sign
+            ("-012", -12),                // zero-prefixed with '-' sign
+            ("00123", 123),               // multiple leading zeros
+            ("2147483647", 2147483647),   // i32::MAX
+            ("-2147483648", -2147483648), // i32::MIN
+        ] {
+            let mut s = input;
+            assert_eq!(
+                dec_int::<ContextError>(&mut s).unwrap(),
+                expected,
+                "{input}"
+            );
+        }
+
+        for input in [
+            "",    // empty string
+            "+",   // sign without digits
+            "-",   // sign without digits
+            "abc", // non-numeric
+            "12a", // starts with digits but has non-digit after (but should parse "12" successfully)
+        ] {
+            let mut s = input;
+            let result = dec_int::<ContextError>(&mut s);
+            // Note: "12a" will actually succeed and parse "12", leaving "a" unparsed
+            if input == "12a" {
+                assert_eq!(result.unwrap(), 12, "{input}");
+                assert_eq!(s, "a", "Should leave 'a' unparsed");
+            } else {
+                assert!(result.is_err(), "{input} should fail");
+            }
+        }
+
+        // Test overflow cases
+        for input in [
+            "2147483648",  // i32::MAX + 1
+            "-2147483649", // i32::MIN - 1
+            "99999999999", // way too large
+        ] {
+            let mut s = input;
+            assert!(
+                dec_int::<ContextError>(&mut s).is_err(),
+                "{input} should overflow"
+            );
+        }
+    }
+}