speedate

Fast and simple datetime, date, time and duration parsing for rust.

speedate is a lax† RFC 3339 date and time parser, in other words, it parses common ISO 8601 formats.

† - all relaxations of from RFC 3339 are compliant with ISO 8601.

The following formats are supported:

• Date: YYYY-MM-DD
• Time: HH:MM:SS
• Time: HH:MM:SS.FFFFFF 1 to 6 digits are reflected in the time.microsecond, extra digits are ignored
• Time: HH:MM
• Date time: YYYY-MM-DDTHH:MM:SS - all the above time formats are allowed for the time part
• Date time: YYYY-MM-DD HH:MM:SS - T, t, and _ are allowed as separators
• Date time: YYYY-MM-DDTHH:MM:SSZ - Z or z is allowed as timezone
• Date time: YYYY-MM-DDTHH:MM:SS+08:00- positive and negative timezone are allowed, as per ISO 8601, U+2212 minus − is allowed as well as ascii minus - (U+002D)
• Date time: YYYY-MM-DDTHH:MM:SS+0800 - the colon (:) in the timezone is optional
• Duration: PnYnMnDTnHnMnS - ISO 8601 duration format, see wikipedia for more details, W for weeks is also allowed
• Duration: HH:MM:SS - any of the above time formats are allowed to represent a duration
• Duration: D days, HH:MM:SS - time prefixed by X days, case-insensitive, spaces s and , are all optional
• Duration: D d, HH:MM:SS - time prefixed by X d, case-insensitive, spaces and , are optional
• Duration: ±... - all duration formats shown here can be prefixed with + or - to indicate positive and negative durations respectively

In addition, unix timestamps (both seconds and milliseconds) can be used to create dates and datetimes. The interpretation of numeric timestamps can be controlled via the TimestampUnit configuration. By default the unit is inferred from the length of the number, but you can set it explicitly using a DateConfig or DateTimeConfig.

See the documentation for each struct for more details.

This will be the datetime parsing logic for pydantic-core.

Usage

use speedate::{DateTime, Date, Time};

let dt = DateTime::parse_str("2022-01-01T12:13:14Z").unwrap();
assert_eq!(
    dt,
    DateTime {
        date: Date {
            year: 2022,
            month: 1,
            day: 1,
        },
        time: Time {
            hour: 12,
            minute: 13,
            second: 14,
            microsecond: 0,
            tz_offset: Some(0),
        },
    }
);
assert_eq!(dt.to_string(), "2022-01-01T12:13:14Z");

To control the specifics of time parsing you can use provide a TimeConfig:

use speedate::{
    DateTime, Date, Time, DateTimeConfig, TimeConfig,
    MicrosecondsPrecisionOverflowBehavior, TimestampUnit,
};
let dt = DateTime::parse_bytes_with_config(
    "1689102037.5586429".as_bytes(),
    &DateTimeConfig::builder()
        .time_config(
            TimeConfig::builder()
                .unix_timestamp_offset(Some(0))
                .microseconds_precision_overflow_behavior(MicrosecondsPrecisionOverflowBehavior::Truncate)
                .build(),
        )
        .build(),
).unwrap();
assert_eq!(
    dt,
    DateTime {
        date: Date {
            year: 2023,
            month: 7,
            day: 11,
        },
        time: Time {
            hour: 19,
            minute: 0,
            second: 37,
            microsecond: 558643,
            tz_offset: Some(0),
        },
    }
);
assert_eq!(dt.to_string(), "2023-07-11T19:00:37.558643Z");

The timestamp_unit field on DateConfig and DateTimeConfig controls how numeric timestamps are interpreted. By default, the unit is inferred based on the value's length. You can force seconds or milliseconds parsing:

use speedate::{DateTime, DateTimeConfig, TimestampUnit, TimeConfig};

let cfg = DateTimeConfig::builder()
    .timestamp_unit(TimestampUnit::Millisecond)
    .time_config(TimeConfig::builder().unix_timestamp_offset(Some(0)).build())
    .build();

let dt = DateTime::parse_bytes_with_config(b"1641039194000", &cfg).unwrap();
assert_eq!(dt.to_string(), "2022-01-01T12:13:14Z");

Likewise, you can configure Date parsing:

use speedate::{Date, DateConfig, TimestampUnit};

let cfg = DateConfig::builder()
    .timestamp_unit(TimestampUnit::Second)
    .build();
let d = Date::parse_bytes_with_config(b"1640995200", &cfg).unwrap();
assert_eq!(d.to_string(), "2022-01-01");

Performance

speedate is significantly faster than chrono's parse_from_rfc3339 and iso8601.

Micro-benchmarking from benches/main.rs:

test datetime_error_speedate ... bench:           6 ns/iter (+/- 0)
test datetime_error_chrono   ... bench:          50 ns/iter (+/- 1)
test datetime_error_iso8601  ... bench:         118 ns/iter (+/- 2)
test datetime_ok_speedate    ... bench:           9 ns/iter (+/- 0)
test datetime_ok_chrono      ... bench:         182 ns/iter (+/- 0)
test datetime_ok_iso8601     ... bench:          77 ns/iter (+/- 1)
test duration_ok_speedate    ... bench:          23 ns/iter (+/- 0)
test duration_ok_iso8601     ... bench:          48 ns/iter (+/- 0)
test timestamp_ok_speedate   ... bench:           9 ns/iter (+/- 0)
test timestamp_ok_chrono     ... bench:          10 ns/iter (+/- 0)

Why not full iso8601?

ISO8601 allows many formats, see ijmacd.github.io/rfc3339-iso8601.

Most of these are unknown to most users, and not desired. This library aims to support the most common formats without introducing ambiguity.