Function parse

pub fn parse(string: &str) -> Result<Zoned, Error> 

Available on crate features dep_jiff and alloc only.

Parse an RFC 2822 datetime string into a Zoned.

This is a convenience function for using DateTimeParser. In particular, this takes a &str while the DateTimeParser accepts a &[u8]. Moreover, if any configuration options are added to RFC 2822 parsing (none currently exist at time of writing), then it will be necessary to use a DateTimeParser to toggle them. Additionally, a DateTimeParser is needed for parsing into a Timestamp.

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