Struct DateTimeParser

struct DateTimeParser { ... }

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")?);

# Ok::<(), Box<dyn std::error::Error>>(())

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")?);

# Ok::<(), Box<dyn std::error::Error>>(())

Implementations

impl DateTimeParser

const fn new() -> DateTimeParser

Create a new Temporal datetime parser with the default configuration.

const fn offset_conflict(self: 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: respecting offsets even when they're invalid

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));

# Ok::<(), Box<dyn std::error::Error>>(())

Example: all offsets are invalid for gaps in civil time by default

When parsing a datetime with an offset for a gap in civil time, the offset is treated as invalid. This results in parsing failing. For example, some parts of Indiana in the US didn't start using daylight saving time until 2006. If a datetime for 2006 were serialized before the updated daylight saving time rules were known, then this parse error will prevent you from silently changing the originally intended time:

use jiff::{fmt::temporal::DateTimeParser};

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

// DST in Indiana/Vevay began at 2006-04-02T02:00 local time.
// The last time Indiana/Vevay observed DST was in 1972.
let result = PARSER.parse_zoned(
    "2006-04-02T02:30-05[America/Indiana/Vevay]",
);
assert_eq!(
    result.unwrap_err().to_string(),
    "parsing \"2006-04-02T02:30-05[America/Indiana/Vevay]\" failed: \
     datetime 2006-04-02T02:30:00 could not resolve to timestamp \
     since 'reject' conflict resolution was chosen, and because \
     datetime has offset -05, but the time zone America/Indiana/Vevay \
     for the given datetime falls in a gap \
     (between offsets -05 and -04), \
     and all offsets for a gap are regarded as invalid",
);

If one doesn't want an error here, then you can either prioritize the instant in time by respecting the offset:

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

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

let zdt = PARSER.parse_zoned(
    "2006-04-02T02:30-05[America/Indiana/Vevay]",
)?;
assert_eq!(
    zdt.to_string(),
    "2006-04-02T03:30:00-04:00[America/Indiana/Vevay]",
);

# Ok::<(), Box<dyn std::error::Error>>(())

or you can force your own disambiguation rules, e.g., by taking the earlier time:

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

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

let zdt = PARSER.parse_zoned(
    "2006-04-02T02:30-05[America/Indiana/Vevay]",
)?;
assert_eq!(
    zdt.to_string(),
    "2006-04-02T01:30:00-05:00[America/Indiana/Vevay]",
);

# Ok::<(), Box<dyn std::error::Error>>(())

Example: a Z never results in an offset conflict

RFC 9557 specifies that Z indicates that the offset from UTC to get local time is unknown. Since it doesn't prescribe a particular offset, when a Z is parsed with a time zone annotation, the OffsetConflict::ALwaysOffset strategy is used regardless of what is set here. For example:

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

// NOTE: The default is reject.
static PARSER: DateTimeParser = DateTimeParser::new();

let zdt = PARSER.parse_zoned(
    "2025-06-20T17:30Z[America/New_York]",
)?;
assert_eq!(
    zdt.to_string(),
    "2025-06-20T13:30:00-04:00[America/New_York]",
);

# Ok::<(), Box<dyn std::error::Error>>(())

Conversely, if the +00:00 offset was used, then an error would occur because of the offset conflict:

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

// NOTE: The default is reject.
static PARSER: DateTimeParser = DateTimeParser::new();

let result = PARSER.parse_zoned(
    "2025-06-20T17:30+00[America/New_York]",
);
assert_eq!(
    result.unwrap_err().to_string(),
    "parsing \"2025-06-20T17:30+00[America/New_York]\" failed: \
     datetime 2025-06-20T17:30:00 could not resolve to a timestamp \
     since 'reject' conflict resolution was chosen, and because \
     datetime has offset +00, but the time zone America/New_York \
     for the given datetime unambiguously has offset -04",
);

const fn disambiguation(self: 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));

# Ok::<(), Box<dyn std::error::Error>>(())

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()));

# Ok::<(), Box<dyn std::error::Error>>(())

fn parse_zoned<I: AsRef<[u8]>>(self: &Self, input: I) -> Result<Zoned, Error>

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));

# Ok::<(), Box<dyn std::error::Error>>(())

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));

# Ok::<(), Box<dyn std::error::Error>>(())

If you really need to parse something like 2024-06-08T07:00-04 into a Zoned with a fixed offset of -04:00 as its TimeZone, then you'll need to use lower level parsing routines. See the documentation on Pieces for a case study of how to achieve this.

fn parse_zoned_with<I: AsRef<[u8]>>(self: &Self, db: &TimeZoneDatabase, input: I) -> Result<Zoned, Error>

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());

# Ok::<(), Box<dyn std::error::Error>>(())

fn parse_timestamp<I: AsRef<[u8]>>(self: &Self, input: I) -> Result<Timestamp, Error>

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");

# Ok::<(), Box<dyn std::error::Error>>(())

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");

# Ok::<(), Box<dyn std::error::Error>>(())

fn parse_datetime<I: AsRef<[u8]>>(self: &Self, input: I) -> Result<civil::DateTime, Error>

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));

# Ok::<(), Box<dyn std::error::Error>>(())

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));

# Ok::<(), Box<dyn std::error::Error>>(())

fn parse_date<I: AsRef<[u8]>>(self: &Self, input: I) -> Result<civil::Date, Error>

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));

# Ok::<(), Box<dyn std::error::Error>>(())

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));

# Ok::<(), Box<dyn std::error::Error>>(())

fn parse_time<I: AsRef<[u8]>>(self: &Self, input: I) -> Result<civil::Time, Error>

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));

# Ok::<(), Box<dyn std::error::Error>>(())

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));

# Ok::<(), Box<dyn std::error::Error>>(())

fn parse_time_zone<'i, I: AsRef<[u8]>>(self: &Self, input: I) -> Result<TimeZone, Error>

Parses a string representing a time zone into a TimeZone.

This will parse one of three different categories of strings:

  1. An IANA Time Zone Database identifier. For example, America/New_York or UTC.
  2. A fixed offset. For example, -05:00 or -00:44:30.
  3. A POSIX time zone string. For example, EST5EDT,M3.2.0,M11.1.0.

Example

This shows a few examples of parsing different kinds of time zones:

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

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

assert_eq!(
    PARSER.parse_time_zone("-05:00")?,
    TimeZone::fixed(tz::offset(-5)),
);
assert_eq!(
    PARSER.parse_time_zone("+05:00:01")?,
    TimeZone::fixed(tz::Offset::from_seconds(5 * 60 * 60 + 1).unwrap()),
);
assert_eq!(
    PARSER.parse_time_zone("America/New_York")?,
    TimeZone::get("America/New_York")?,
);
assert_eq!(
    PARSER.parse_time_zone("Israel")?,
    TimeZone::get("Israel")?,
);
assert_eq!(
    PARSER.parse_time_zone("EST5EDT,M3.2.0,M11.1.0")?,
    TimeZone::posix("EST5EDT,M3.2.0,M11.1.0")?,
);

// Some error cases!
assert!(PARSER.parse_time_zone("Z").is_err());
assert!(PARSER.parse_time_zone("05:00").is_err());
assert!(PARSER.parse_time_zone("+05:00:01.5").is_err());
assert!(PARSER.parse_time_zone("Does/Not/Exist").is_err());

# Ok::<(), Box<dyn std::error::Error>>(())

fn parse_time_zone_with<'i, I: AsRef<[u8]>>(self: &Self, db: &TimeZoneDatabase, input: I) -> Result<TimeZone, Error>

Parses a string representing a time zone into a TimeZone and performs any time zone database lookups using the TimeZoneDatabase given.

This is like DateTimeParser::parse_time_zone, but uses the time zone database given instead of the implicit global time zone database.

This will parse one of three different categories of strings:

  1. An IANA Time Zone Database identifier. For example, America/New_York or UTC.
  2. A fixed offset. For example, -05:00 or -00:44:30.
  3. A POSIX time zone string. For example, EST5EDT,M3.2.0,M11.1.0.

Example

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

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

let db = jiff::tz::db();
assert_eq!(
    PARSER.parse_time_zone_with(db, "America/New_York")?,
    TimeZone::get("America/New_York")?,
);

# Ok::<(), Box<dyn std::error::Error>>(())

See also the example for DateTimeParser::parse_zoned_with for a more interesting example using a time zone database other than the default.

fn parse_pieces<'i, I: ?Sized + AsRef<[u8]> + 'i>(self: &Self, input: &'i I) -> Result<Pieces<'i>, Error>

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]");

# Ok::<(), Box<dyn std::error::Error>>(())

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",
);

# Ok::<(), Box<dyn std::error::Error>>(())

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);

# Ok::<(), Box<dyn std::error::Error>>(())

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.

impl Debug for DateTimeParser

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

impl Freeze for DateTimeParser

impl RefUnwindSafe for DateTimeParser

impl Send for DateTimeParser

impl Sync for DateTimeParser

impl Unpin for DateTimeParser

impl UnwindSafe for DateTimeParser

impl<T> Any for DateTimeParser

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for DateTimeParser

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for DateTimeParser

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> From for DateTimeParser

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for DateTimeParser

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for DateTimeParser

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for DateTimeParser

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>