Struct DateTimeParser

pub struct DateTimeParser { /* private fields */ }

Available on crate features dep_jiff and alloc only.

A parser for RFC 2822 datetimes.

Warning

The RFC 2822 format only supports writing a precise instant in time expressed via a time zone offset. It does not support serializing the time zone itself. This means that if you format a zoned datetime in a time zone like America/New_York and then deserialize it, the zoned datetime you get back will be a “fixed offset” zoned datetime. This in turn means it will not perform daylight saving time safe arithmetic.

Basically, you should use the RFC 2822 format if it’s required (for example, when dealing with email). But you should not choose it as a general interchange format for new applications.

Example

This example shows how serializing a zoned datetime to RFC 2822 format and then deserializing will drop information:

use jiff::{civil::date, fmt::rfc2822};

let zdt = date(2024, 7, 13)
    .at(15, 9, 59, 789_000_000)
    .intz("America/New_York")?;
// The default format (i.e., Temporal) guarantees lossless
// serialization.
assert_eq!(zdt.to_string(), "2024-07-13T15:09:59.789-04:00[America/New_York]");

let rfc2822 = rfc2822::to_string(&zdt)?;
// Notice that the time zone name and fractional seconds have been dropped!
assert_eq!(rfc2822, "Sat, 13 Jul 2024 15:09:59 -0400");
// And of course, if we parse it back, all that info is still lost.
// Which means this `zdt` cannot do DST safe arithmetic!
let zdt = rfc2822::parse(&rfc2822)?;
assert_eq!(zdt.to_string(), "2024-07-13T15:09:59-04:00[-04:00]");

Implementations

impl DateTimeParser

pub const fn new() -> DateTimeParser

Create a new RFC 2822 datetime parser with the default configuration.

pub const fn relaxed_weekday(self, yes: bool) -> DateTimeParser

When enabled, parsing will permit the weekday to be inconsistent with the date. When enabled, the weekday is still parsed and can result in an error if it isn’t a valid weekday. Only the error checking for whether it is the correct weekday for the parsed date is disabled.

This is sometimes useful for interaction with systems that don’t do strict error checking.

This is disabled by default. And note that RFC 2822 compliance requires that the weekday is consistent with the date.

Example

use jiff::{civil::date, fmt::rfc2822};

let string = "Sun, 13 Jul 2024 15:09:59 -0400";
// The above normally results in an error, since 2024-07-13 is a
// Saturday:
assert!(rfc2822::parse(string).is_err());
// But we can relax the error checking:
static P: rfc2822::DateTimeParser = rfc2822::DateTimeParser::new()
    .relaxed_weekday(true);
assert_eq!(
    P.parse_zoned(string)?,
    date(2024, 7, 13).at(15, 9, 59, 0).intz("America/New_York")?,
);
// But note that something that isn't recognized as a valid weekday
// will still result in an error:
assert!(P.parse_zoned("Wat, 13 Jul 2024 15:09:59 -0400").is_err());

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

where I: AsRef<[u8]>,

Parse a datetime string into a Zoned value.

Note that RFC 2822 does not support time zone annotations. The zoned datetime returned will therefore always have a fixed offset time zone.

Warning

The RFC 2822 format only supports writing a precise instant in time expressed via a time zone offset. It does not support serializing the time zone itself. This means that if you format a zoned datetime in a time zone like America/New_York and then deserialize it, the zoned datetime you get back will be a “fixed offset” zoned datetime. This in turn means it will not perform daylight saving time safe arithmetic.

Basically, you should use the RFC 2822 format if it’s required (for example, when dealing with email). But you should not choose it as a general interchange format for new applications.

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. For example, RFC 2822 supports offsets up to 99 hours and 59 minutes, but Jiff’s maximum offset is 25 hours, 59 minutes and 59 seconds.

Example

This shows a basic example of parsing a Timestamp from an RFC 2822 datetime string.

use jiff::fmt::rfc2822::DateTimeParser;

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

let zdt = PARSER.parse_zoned("Thu, 29 Feb 2024 05:34 -0500")?;
assert_eq!(zdt.to_string(), "2024-02-29T05:34:00-05:00[-05:00]");

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

where I: AsRef<[u8]>,

Parse an RFC 2822 datetime string into a Timestamp.

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. For example, RFC 2822 supports offsets up to 99 hours and 59 minutes, but Jiff’s maximum offset is 25 hours, 59 minutes and 59 seconds.

Example

This shows a basic example of parsing a Timestamp from an RFC 2822 datetime string.

use jiff::fmt::rfc2822::DateTimeParser;

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

let timestamp = PARSER.parse_timestamp("Thu, 29 Feb 2024 05:34 -0500")?;
assert_eq!(timestamp.to_string(), "2024-02-29T10:34:00Z");

Trait Implementations

impl Debug for DateTimeParser

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

Formats the value using the given formatter.