Struct DateTimeParser

pub struct DateTimeParser { /* private fields */ }

Available on crate features dep_jiff and alloc only.

A parser for Temporal datetimes.

This parser converts a machine (but also human) readable format of a datetime to the various types found in Jiff: Zoned, Timestamp, civil::DateTime, civil::Date or civil::Time. Note that all of those types provide FromStr implementations that utilize the default configuration of this parser. However, this parser can be configured to behave differently and can also parse directly from a &[u8].

See the fmt::temporal module documentation for more information on the specific format used.

Example

This example shows how to parse a Zoned datetime from a byte string. (That is, &[u8] and not a &str.)

use jiff::{civil::date, fmt::temporal::DateTimeParser, tz};

// A parser can be created in a const context.
static PARSER: DateTimeParser = DateTimeParser::new();

let zdt = PARSER.parse_zoned(b"2024-06-15T07-04[America/New_York]")?;
assert_eq!(zdt.datetime(), date(2024, 6, 15).at(7, 0, 0, 0));
assert_eq!(zdt.time_zone(), &tz::db().get("America/New_York")?);

Note that an ASCII space instead of the T separator is automatically supported too:

use jiff::{civil::date, fmt::temporal::DateTimeParser, tz};

// A parser can be created in a const context.
static PARSER: DateTimeParser = DateTimeParser::new();

let zdt = PARSER.parse_zoned(b"2024-06-15 07-04[America/New_York]")?;
assert_eq!(zdt.datetime(), date(2024, 6, 15).at(7, 0, 0, 0));
assert_eq!(zdt.time_zone(), &tz::db().get("America/New_York")?);

Implementations

impl DateTimeParser

pub const fn new() -> DateTimeParser

Create a new Temporal datetime parser with the default configuration.

pub const fn offset_conflict(self, strategy: OffsetConflict) -> DateTimeParser

Set the conflict resolution strategy for when an offset in a datetime string is inconsistent with the time zone.

See the documentation on OffsetConflict for more details about the different strategies one can choose.

This only applies when parsing Zoned values.

The default is OffsetConflict::Reject, which results in an error whenever parsing a datetime with an offset that is inconsistent with the time zone.

Example

use jiff::{civil::date, fmt::temporal::DateTimeParser, tz};

static PARSER: DateTimeParser = DateTimeParser::new()
    .offset_conflict(tz::OffsetConflict::AlwaysOffset);

let zdt = PARSER.parse_zoned("2024-06-09T07:00-05[America/New_York]")?;
// Notice that the time *and* offset have been corrected. The offset
// given was invalid for `America/New_York` at the given time, so
// it cannot be kept, but the instant returned is equivalent to
// `2024-06-09T07:00-05`. It is just adjusted automatically to be
// correct in the `America/New_York` time zone.
assert_eq!(zdt.datetime(), date(2024, 6, 9).at(8, 0, 0, 0));
assert_eq!(zdt.offset(), tz::offset(-4));

pub const fn disambiguation(self, strategy: Disambiguation) -> DateTimeParser

Set the disambiguation strategy for when a datetime falls into a time zone transition “fold” or “gap.”

The most common manifestation of such time zone transitions is daylight saving time. In most cases, the transition into daylight saving time moves the civil time (“the time you see on the clock”) ahead one hour. This is called a “gap” because an hour on the clock is skipped. While the transition out of daylight saving time moves the civil time back one hour. This is called a “fold” because an hour on the clock is repeated.

In the case of a gap, an ambiguous datetime manifests as a time that never appears on a clock. (For example, 02:30 on 2024-03-10 in New York.) In the case of a fold, an ambiguous datetime manifests as a time that repeats itself. (For example, 01:30 on 2024-11-03 in New York.) So when a fold occurs, you don’t know whether it’s the “first” occurrence of that time or the “second.”

Time zone transitions are not just limited to daylight saving time, although those are the most common. In other cases, a transition occurs because of a change in the offset of the time zone itself. (See the examples below.)

Example

This example shows how to set the disambiguation configuration while parsing a Zoned datetime. In this example, we always prefer the earlier time.

use jiff::{civil::date, fmt::temporal::DateTimeParser, tz};

static PARSER: DateTimeParser = DateTimeParser::new()
    .disambiguation(tz::Disambiguation::Earlier);

let zdt = PARSER.parse_zoned("2024-03-10T02:05[America/New_York]")?;
assert_eq!(zdt.datetime(), date(2024, 3, 10).at(1, 5, 0, 0));
assert_eq!(zdt.offset(), tz::offset(-5));

Example: time zone offset change

In this example, we explore a time zone offset change in Hawaii that occurred on 1947-06-08. Namely, Hawaii went from a -10:30 offset to a -10:00 offset at 02:00. This results in a 30 minute gap in civil time.

use jiff::{civil::date, fmt::temporal::DateTimeParser, tz, ToSpan};

static PARSER: DateTimeParser = DateTimeParser::new()
    .disambiguation(tz::Disambiguation::Later);

// 02:05 didn't exist on clocks on 1947-06-08.
let zdt = PARSER.parse_zoned(
    "1947-06-08T02:05[Pacific/Honolulu]",
)?;
// Our parser is configured to select the later time, so we jump to
// 02:35. But if we used `Disambiguation::Earlier`, then we'd get
// 01:35.
assert_eq!(zdt.datetime(), date(1947, 6, 8).at(2, 35, 0, 0));
assert_eq!(zdt.offset(), tz::offset(-10));

// If we subtract 10 minutes from 02:35, notice that we (correctly)
// jump to 01:55 *and* our offset is corrected to -10:30.
let zdt = zdt.checked_sub(10.minutes())?;
assert_eq!(zdt.datetime(), date(1947, 6, 8).at(1, 55, 0, 0));
assert_eq!(zdt.offset(), tz::offset(-10).saturating_sub(30.minutes()));

pub fn parse_zoned<I>(&self, input: I) -> Result<Zoned, Error>

where I: AsRef<[u8]>,

Parse a datetime string with a time zone annotation into a Zoned value using the system time zone database.

Errors

This returns an error if the datetime string given is invalid or if it is valid but doesn’t fit in the datetime range supported by Jiff.

The DateTimeParser::offset_conflict and DateTimeParser::disambiguation settings can also influence whether an error occurs or not. Namely, if OffsetConflict::Reject is used (which is the default), then an error occurs when there is an inconsistency between the offset and the time zone. And if Disambiguation::Reject is used, then an error occurs when the civil time in the string is ambiguous.

Example: parsing without an IANA time zone

Note that when parsing a Zoned value, it is required for the datetime string to contain a time zone annotation in brackets. For example, this fails to parse even though it refers to a precise instant in time:

use jiff::fmt::temporal::DateTimeParser;

static PARSER: DateTimeParser = DateTimeParser::new();

assert!(PARSER.parse_zoned("2024-06-08T07:00-04").is_err());

While it is better to include a time zone name, if the only thing that’s available is an offset, the offset can be repeated as a time zone annotation:

use jiff::{civil::date, fmt::temporal::DateTimeParser, tz};

static PARSER: DateTimeParser = DateTimeParser::new();

let zdt = PARSER.parse_zoned("2024-06-08T07:00-04[-04]")?;
assert_eq!(zdt.datetime(), date(2024, 6, 8).at(7, 0, 0, 0));
assert_eq!(zdt.offset(), tz::offset(-4));

Otherwise, if you need to be able to parse something like 2024-06-08T07:00-04 as-is, you should parse it into an Timestamp:

use jiff::{civil::date, fmt::temporal::DateTimeParser, tz};

static PARSER: DateTimeParser = DateTimeParser::new();

let timestamp = PARSER.parse_timestamp("2024-06-08T07:00-04")?;
let zdt = timestamp.to_zoned(tz::TimeZone::UTC);
assert_eq!(zdt.datetime(), date(2024, 6, 8).at(11, 0, 0, 0));
assert_eq!(zdt.offset(), tz::offset(0));

pub fn parse_zoned_with<I>( &self, db: &TimeZoneDatabase, input: I, ) -> Result<Zoned, Error>

where I: AsRef<[u8]>,

Parse a datetime string with a time zone annotation into a Zoned value using the time zone database given.

Errors

This returns an error if the datetime string given is invalid or if it is valid but doesn’t fit in the datetime range supported by Jiff.

The DateTimeParser::offset_conflict and DateTimeParser::disambiguation settings can also influence whether an error occurs or not. Namely, if OffsetConflict::Reject is used (which is the default), then an error occurs when there is an inconsistency between the offset and the time zone. And if Disambiguation::Reject is used, then an error occurs when the civil time in the string is ambiguous.

Example

This example demonstrates the utility of this routine by parsing a datetime using an older copy of the IANA Time Zone Database. This example leverages the fact that the 2018 copy of tzdb preceded Brazil’s announcement that daylight saving time would be abolished. This meant that datetimes in the future, when parsed with the older copy of tzdb, would still follow the old daylight saving time rules. But a mere update of tzdb would otherwise change the meaning of the datetime.

This scenario can come up if one stores datetimes in the future. This is also why the default offset conflict resolution strategy is OffsetConflict::Reject, which prevents one from silently re-interpreting datetimes to a different timestamp.

use jiff::{fmt::temporal::DateTimeParser, tz::{self, TimeZoneDatabase}};

static PARSER: DateTimeParser = DateTimeParser::new();

// Open a version of tzdb from before Brazil announced its abolition
// of daylight saving time.
let tzdb2018 = TimeZoneDatabase::from_dir("path/to/tzdb-2018b")?;
// Open the system tzdb.
let tzdb = tz::db();

// Parse the same datetime string with the same parser, but using two
// different versions of tzdb.
let dt = "2020-01-15T12:00[America/Sao_Paulo]";
let zdt2018 = PARSER.parse_zoned_with(&tzdb2018, dt)?;
let zdt = PARSER.parse_zoned_with(tzdb, dt)?;

// Before DST was abolished, 2020-01-15 was in DST, which corresponded
// to UTC offset -02. Since DST rules applied to datetimes in the
// future, the 2018 version of tzdb would lead one to interpret
// 2020-01-15 as being in DST.
assert_eq!(zdt2018.offset(), tz::offset(-2));
// But DST was abolished in 2019, which means that 2020-01-15 was no
// no longer in DST. So after a tzdb update, the same datetime as above
// now has a different offset.
assert_eq!(zdt.offset(), tz::offset(-3));

// So if you try to parse a datetime serialized from an older copy of
// tzdb, you'll get an error under the default configuration because
// of `OffsetConflict::Reject`. This would succeed if you parsed it
// using tzdb2018!
assert!(PARSER.parse_zoned_with(tzdb, zdt2018.to_string()).is_err());

pub fn parse_timestamp<I>(&self, input: I) -> Result<Timestamp, Error>

where I: AsRef<[u8]>,

Parse a datetime string into a Timestamp.

The datetime string must correspond to a specific instant in time. This requires an offset in the datetime string.

Errors

This returns an error if the datetime string given is invalid or if it is valid but doesn’t fit in the datetime range supported by Jiff.

Example

This shows a basic example of parsing an Timestamp.

use jiff::fmt::temporal::DateTimeParser;

static PARSER: DateTimeParser = DateTimeParser::new();

let timestamp = PARSER.parse_timestamp("2024-03-10T02:05-04")?;
assert_eq!(timestamp.to_string(), "2024-03-10T06:05:00Z");

Example: parsing a timestamp from a datetime with a time zone

A timestamp can also be parsed fron a time zone aware datetime string. The time zone is ignored and the offset is always used.

use jiff::fmt::temporal::DateTimeParser;

static PARSER: DateTimeParser = DateTimeParser::new();

let timestamp = PARSER.parse_timestamp(
    "2024-03-10T02:05-04[America/New_York]",
)?;
assert_eq!(timestamp.to_string(), "2024-03-10T06:05:00Z");

pub fn parse_datetime<I>(&self, input: I) -> Result<DateTime, Error>

where I: AsRef<[u8]>,

Parse a civil datetime string into a civil::DateTime.

A civil datetime can be parsed from anything that contains a datetime. For example, a time zone aware string.

Errors

This returns an error if the datetime string given is invalid or if it is valid but doesn’t fit in the datetime range supported by Jiff.

This also returns an error if a Z (Zulu) offset is found, since interpreting such strings as civil time is usually a bug.

Example

This shows a basic example of parsing a civil::DateTime.

use jiff::{civil::date, fmt::temporal::DateTimeParser};

static PARSER: DateTimeParser = DateTimeParser::new();

let datetime = PARSER.parse_datetime("2024-03-10T02:05")?;
assert_eq!(datetime, date(2024, 3, 10).at(2, 5, 0, 0));

Example: parsing fails if a Z (Zulu) offset is encountered

Because parsing a datetime with a Z offset and interpreting it as a civil time is usually a bug, it is forbidden:

use jiff::{civil::date, fmt::temporal::DateTimeParser};

static PARSER: DateTimeParser = DateTimeParser::new();

assert!(PARSER.parse_datetime("2024-03-10T02:05Z").is_err());

// Note though that -00 and +00 offsets parse successfully.
let datetime = PARSER.parse_datetime("2024-03-10T02:05+00")?;
assert_eq!(datetime, date(2024, 3, 10).at(2, 5, 0, 0));
let datetime = PARSER.parse_datetime("2024-03-10T02:05-00")?;
assert_eq!(datetime, date(2024, 3, 10).at(2, 5, 0, 0));

pub fn parse_date<I>(&self, input: I) -> Result<Date, Error>

where I: AsRef<[u8]>,

Parse a civil date string into a civil::Date.

A civil date can be parsed from anything that contains a date. For example, a time zone aware string.

Errors

This returns an error if the date string given is invalid or if it is valid but doesn’t fit in the date range supported by Jiff.

This also returns an error if a Z (Zulu) offset is found, since interpreting such strings as civil date or time is usually a bug.

Example

This shows a basic example of parsing a civil::Date.

use jiff::{civil::date, fmt::temporal::DateTimeParser};

static PARSER: DateTimeParser = DateTimeParser::new();

let d = PARSER.parse_date("2024-03-10")?;
assert_eq!(d, date(2024, 3, 10));

Example: parsing fails if a Z (Zulu) offset is encountered

Because parsing a date with a Z offset and interpreting it as a civil date or time is usually a bug, it is forbidden:

use jiff::{civil::date, fmt::temporal::DateTimeParser};

static PARSER: DateTimeParser = DateTimeParser::new();

assert!(PARSER.parse_date("2024-03-10T00:00:00Z").is_err());

// Note though that -00 and +00 offsets parse successfully.
let d = PARSER.parse_date("2024-03-10T00:00:00+00")?;
assert_eq!(d, date(2024, 3, 10));
let d = PARSER.parse_date("2024-03-10T00:00:00-00")?;
assert_eq!(d, date(2024, 3, 10));

pub fn parse_time<I>(&self, input: I) -> Result<Time, Error>

where I: AsRef<[u8]>,

Parse a civil time string into a civil::Time.

A civil time can be parsed from anything that contains a time. For example, a time zone aware string.

Errors

This returns an error if the time string given is invalid or if it is valid but doesn’t fit in the time range supported by Jiff.

This also returns an error if a Z (Zulu) offset is found, since interpreting such strings as civil time is usually a bug.

Example

This shows a basic example of parsing a civil::Time.

use jiff::{civil::time, fmt::temporal::DateTimeParser};

static PARSER: DateTimeParser = DateTimeParser::new();

let t = PARSER.parse_time("02:05")?;
assert_eq!(t, time(2, 5, 0, 0));

Example: parsing fails if a Z (Zulu) offset is encountered

Because parsing a time with a Z offset and interpreting it as a civil time is usually a bug, it is forbidden:

use jiff::{civil::time, fmt::temporal::DateTimeParser};

static PARSER: DateTimeParser = DateTimeParser::new();

assert!(PARSER.parse_time("02:05Z").is_err());

// Note though that -00 and +00 offsets parse successfully.
let t = PARSER.parse_time("02:05+00")?;
assert_eq!(t, time(2, 5, 0, 0));
let t = PARSER.parse_time("02:05-00")?;
assert_eq!(t, time(2, 5, 0, 0));

pub fn parse_pieces<'i, I>(&self, input: &'i I) -> Result<Pieces<'i>, Error>

where I: AsRef<[u8]> + 'i + ?Sized,

Parse a Temporal datetime string into Pieces.

This is a lower level routine meant to give callers raw access to the individual “pieces” of a parsed Temporal ISO 8601 datetime string. Note that this only includes strings that have a date component.

The benefit of this routine is that it only checks that the datetime is itself valid. It doesn’t do any automatic diambiguation, offset conflict resolution or attempt to prevent you from shooting yourself in the foot. For example, this routine will let you parse a fixed offset datetime into a Zoned without a time zone abbreviation.

Note that when using this routine, the DateTimeParser::offset_conflict and DateTimeParser::disambiguation configuration knobs are completely ignored. This is because with the lower level Pieces, callers must handle offset conflict resolution (if they want it) themselves. See the Pieces documentation for a case study on how to do this if you need it.

Errors

This returns an error if the datetime string given is invalid or if it is valid but doesn’t fit in the date range supported by Jiff.

Example

This shows how to parse a fixed offset timestamp into a Zoned.

use jiff::{fmt::temporal::DateTimeParser, tz::TimeZone};

static PARSER: DateTimeParser = DateTimeParser::new();

let timestamp = "2025-01-02T15:13-05";

// Normally this operation will fail.
assert_eq!(
    PARSER.parse_zoned(timestamp).unwrap_err().to_string(),
    "failed to find time zone in square brackets in \
     \"2025-01-02T15:13-05\", which is required for \
     parsing a zoned instant",
);

// But you can work-around this with `Pieces`, which gives you direct
// access to the components parsed from the string.
let pieces = PARSER.parse_pieces(timestamp)?;
let time = pieces.time().unwrap_or_else(jiff::civil::Time::midnight);
let dt = pieces.date().to_datetime(time);
let tz = match pieces.to_time_zone()? {
    Some(tz) => tz,
    None => {
        let Some(offset) = pieces.to_numeric_offset() else {
            let msg = format!(
                "timestamp `{timestamp}` has no time zone \
                 or offset, and thus cannot be parsed into \
                 an instant",
            );
            return Err(msg.into());
        };
        TimeZone::fixed(offset)
    }
};
// We don't bother with offset conflict resolution. And note that
// this uses automatic "compatible" disambiguation in the case of
// discontinuities. Of course, this is all moot if `TimeZone` is
// fixed. The above code handles the case where it isn't!
let zdt = tz.to_zoned(dt)?;
assert_eq!(zdt.to_string(), "2025-01-02T15:13:00-05:00[-05:00]");

Example: work around errors when a Z (Zulu) offset is encountered

Because parsing a date with a Z offset and interpreting it as a civil date or time is usually a bug, it is forbidden:

use jiff::{civil::date, fmt::temporal::DateTimeParser};

static PARSER: DateTimeParser = DateTimeParser::new();

assert_eq!(
    PARSER.parse_date("2024-03-10T00:00:00Z").unwrap_err().to_string(),
    "cannot parse civil date from string with a Zulu offset, \
     parse as a `Timestamp` and convert to a civil date instead",
);

But this sort of error checking doesn’t happen when you parse into a Pieces. You just get what was parsed, which lets you extract a date even if the higher level APIs forbid it:

use jiff::{civil, fmt::temporal::DateTimeParser, tz::Offset};

static PARSER: DateTimeParser = DateTimeParser::new();

let pieces = PARSER.parse_pieces("2024-03-10T00:00:00Z")?;
assert_eq!(pieces.date(), civil::date(2024, 3, 10));
assert_eq!(pieces.time(), Some(civil::time(0, 0, 0, 0)));
assert_eq!(pieces.to_numeric_offset(), Some(Offset::UTC));
assert_eq!(pieces.to_time_zone()?, None);

This is usually not the right thing to do. It isn’t even suggested in the error message above. But if you know it’s the right thing, then Pieces will let you do it.

Trait Implementations

impl Debug for DateTimeParser

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.