Struct DateTimePrinter

struct DateTimePrinter { ... }

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).in_tz("Australia/Tasmania")?;

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

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

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

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

Implementations

impl DateTimePrinter

const fn new() -> DateTimePrinter

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

fn zoned_to_string(self: &Self, zdt: &Zoned) -> Result<alloc::string::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).in_tz("America/New_York")?;
assert_eq!(
    PRINTER.zoned_to_string(&zdt)?,
    "Sat, 15 Jun 2024 07:00:00 -0400",
);

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

fn timestamp_to_string(self: &Self, timestamp: &Timestamp) -> Result<alloc::string::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",
);

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

fn timestamp_to_rfc9110_string(self: &Self, timestamp: &Timestamp) -> Result<alloc::string::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",
);

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

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

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).in_tz("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");

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

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

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

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

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

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

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

impl Debug for DateTimePrinter

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

impl Freeze for DateTimePrinter

impl RefUnwindSafe for DateTimePrinter

impl Send for DateTimePrinter

impl Sync for DateTimePrinter

impl Unpin for DateTimePrinter

impl UnwindSafe for DateTimePrinter

impl<T> Any for DateTimePrinter

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for DateTimePrinter

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

impl<T> BorrowMut for DateTimePrinter

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

impl<T> From for DateTimePrinter

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for DateTimePrinter

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 DateTimePrinter

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

impl<T, U> TryInto for DateTimePrinter

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