Struct DateTimePrinter

pub struct DateTimePrinter { /* private fields */ }

Available on crate features dep_jiff and alloc only.

A printer for RFC 2822 datetimes.

This printer converts an in memory representation of a precise instant in time to an RFC 2822 formatted string. That is, Zoned or Timestamp, since all other datetime types in Jiff are inexact.

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 to convert a zoned datetime to the RFC 2822 format:

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

const PRINTER: DateTimePrinter = DateTimePrinter::new();

let zdt = date(2024, 6, 15).at(7, 0, 0, 0).intz("Australia/Tasmania")?;

let mut buf = String::new();
PRINTER.print_zoned(&zdt, &mut buf)?;
assert_eq!(buf, "Sat, 15 Jun 2024 07:00:00 +1000");

Example: using adapters with std::io::Write and std::fmt::Write

By using the StdIoWrite and StdFmtWrite adapters, one can print datetimes directly to implementations of std::io::Write and std::fmt::Write, respectively. The example below demonstrates writing to anything that implements std::io::Write. Similar code can be written for std::fmt::Write.

use std::{fs::File, io::{BufWriter, Write}, path::Path};

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

let zdt = date(2024, 6, 15).at(7, 0, 0, 0).intz("Asia/Kolkata")?;

let path = Path::new("/tmp/output");
let mut file = BufWriter::new(File::create(path)?);
DateTimePrinter::new().print_zoned(&zdt, StdIoWrite(&mut file)).unwrap();
file.flush()?;
assert_eq!(
    std::fs::read_to_string(path)?,
    "Sat, 15 Jun 2024 07:00:00 +0530",
);

Implementations

impl DateTimePrinter

pub const fn new() -> DateTimePrinter

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

pub fn zoned_to_string(&self, zdt: &Zoned) -> Result<String, Error>

Format a Zoned datetime into a string.

This never emits -0000 as the offset in the RFC 2822 format. If you desire a -0000 offset, use DateTimePrinter::print_timestamp via Zoned::timestamp.

Moreover, since RFC 2822 does not support fractional seconds, this routine prints the zoned datetime as if truncating any fractional seconds.

This is a convenience routine for DateTimePrinter::print_zoned with a String.

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 can return an error if the year corresponding to this timestamp cannot be represented in the RFC 2822 format. For example, a negative year.

Example

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

const PRINTER: DateTimePrinter = DateTimePrinter::new();

let zdt = date(2024, 6, 15).at(7, 0, 0, 0).intz("America/New_York")?;
assert_eq!(
    PRINTER.zoned_to_string(&zdt)?,
    "Sat, 15 Jun 2024 07:00:00 -0400",
);

pub fn timestamp_to_string( &self, timestamp: &Timestamp, ) -> Result<String, Error>

Format a Timestamp datetime into a string.

This always emits -0000 as the offset in the RFC 2822 format. If you desire a +0000 offset, use DateTimePrinter::print_zoned with a zoned datetime with TimeZone::UTC.

Moreover, since RFC 2822 does not support fractional seconds, this routine prints the timestamp as if truncating any fractional seconds.

This is a convenience routine for DateTimePrinter::print_timestamp with a String.

Errors

This returns an error if the year corresponding to this timestamp cannot be represented in the RFC 2822 format. For example, a negative year.

Example

use jiff::{fmt::rfc2822::DateTimePrinter, Timestamp};

let timestamp = Timestamp::from_second(1)
    .expect("one second after Unix epoch is always valid");
assert_eq!(
    DateTimePrinter::new().timestamp_to_string(&timestamp)?,
    "Thu, 1 Jan 1970 00:00:01 -0000",
);

pub fn timestamp_to_rfc9110_string( &self, timestamp: &Timestamp, ) -> Result<String, Error>

Format a Timestamp datetime into a string in a way that is explicitly compatible with RFC 9110. This is typically useful in contexts where strict compatibility with HTTP is desired.

This always emits GMT as the offset and always uses two digits for the day. This results in a fixed length format that always uses 29 characters.

Since neither RFC 2822 nor RFC 9110 supports fractional seconds, this routine prints the timestamp as if truncating any fractional seconds.

This is a convenience routine for DateTimePrinter::print_timestamp_rfc9110 with a String.

Errors

This returns an error if the year corresponding to this timestamp cannot be represented in the RFC 2822 or RFC 9110 format. For example, a negative year.

Example

use jiff::{fmt::rfc2822::DateTimePrinter, Timestamp};

let timestamp = Timestamp::from_second(1)
    .expect("one second after Unix epoch is always valid");
assert_eq!(
    DateTimePrinter::new().timestamp_to_rfc9110_string(&timestamp)?,
    "Thu, 01 Jan 1970 00:00:01 GMT",
);

pub fn print_zoned<W>(&self, zdt: &Zoned, wtr: W) -> Result<(), Error>

where W: Write,

Print a Zoned datetime to the given writer.

This never emits -0000 as the offset in the RFC 2822 format. If you desire a -0000 offset, use DateTimePrinter::print_timestamp via Zoned::timestamp.

Moreover, since RFC 2822 does not support fractional seconds, this routine prints the zoned datetime as if truncating any fractional seconds.

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 when writing to the given Write implementation would fail. Some such implementations, like for String and Vec<u8>, never fail (unless memory allocation fails).

This can also return an error if the year corresponding to this timestamp cannot be represented in the RFC 2822 format. For example, a negative year.

Example

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

const PRINTER: DateTimePrinter = DateTimePrinter::new();

let zdt = date(2024, 6, 15).at(7, 0, 0, 0).intz("America/New_York")?;

let mut buf = String::new();
PRINTER.print_zoned(&zdt, &mut buf)?;
assert_eq!(buf, "Sat, 15 Jun 2024 07:00:00 -0400");

pub fn print_timestamp<W>( &self, timestamp: &Timestamp, wtr: W, ) -> Result<(), Error>

where W: Write,

Print a Timestamp datetime to the given writer.

This always emits -0000 as the offset in the RFC 2822 format. If you desire a +0000 offset, use DateTimePrinter::print_zoned with a zoned datetime with TimeZone::UTC.

Moreover, since RFC 2822 does not support fractional seconds, this routine prints the timestamp as if truncating any fractional seconds.

Errors

This returns an error when writing to the given Write implementation would fail. Some such implementations, like for String and Vec<u8>, never fail (unless memory allocation fails).

This can also return an error if the year corresponding to this timestamp cannot be represented in the RFC 2822 format. For example, a negative year.

Example

use jiff::{fmt::rfc2822::DateTimePrinter, Timestamp};

let timestamp = Timestamp::from_second(1)
    .expect("one second after Unix epoch is always valid");

let mut buf = String::new();
DateTimePrinter::new().print_timestamp(&timestamp, &mut buf)?;
assert_eq!(buf, "Thu, 1 Jan 1970 00:00:01 -0000");

pub fn print_timestamp_rfc9110<W>( &self, timestamp: &Timestamp, wtr: W, ) -> Result<(), Error>

where W: Write,

Print a Timestamp datetime to the given writer in a way that is explicitly compatible with RFC 9110. This is typically useful in contexts where strict compatibility with HTTP is desired.

This always emits GMT as the offset and always uses two digits for the day. This results in a fixed length format that always uses 29 characters.

Since neither RFC 2822 nor RFC 9110 supports fractional seconds, this routine prints the timestamp as if truncating any fractional seconds.

Errors

This returns an error when writing to the given Write implementation would fail. Some such implementations, like for String and Vec<u8>, never fail (unless memory allocation fails).

This can also return an error if the year corresponding to this timestamp cannot be represented in the RFC 2822 or RFC 9110 format. For example, a negative year.

Example

use jiff::{fmt::rfc2822::DateTimePrinter, Timestamp};

let timestamp = Timestamp::from_second(1)
    .expect("one second after Unix epoch is always valid");

let mut buf = String::new();
DateTimePrinter::new().print_timestamp_rfc9110(&timestamp, &mut buf)?;
assert_eq!(buf, "Thu, 01 Jan 1970 00:00:01 GMT");

Trait Implementations

impl Debug for DateTimePrinter

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

Formats the value using the given formatter.