Struct DateTime 

#[non_exhaustive]
pub struct DateTime { /* private fields */ }

Date-time with timezone offset preserved.

Equality and Ordering

PartialEq, Eq, Hash, PartialOrd, and Ord are implemented manually rather than derived. All comparisons normalize to UTC first, so two values representing the same instant with different timezone offsets are considered equal (e.g., 2025-01-01T00:00:00+0000 == 2024-12-31T19:00:00-0500).

References

• RFC 5322 Section 3.3 (date-time specification)

Implementations

impl DateTime

pub fn new( year: u16, month: u8, day: u8, hour: u8, minute: u8, second: u8, tz_offset_minutes: i16, ) -> Self

Creates a new DateTime from individual components.

Fields are stored as-is; clamping to valid ranges happens at formatting / comparison time (see Self::to_rfc5322_string, Self::to_unix_timestamp).

References

• RFC 5322 Section 3.3 (date-time specification)

pub fn year(&self) -> u16

Returns the year (e.g., 2025).

pub fn month(&self) -> u8

Returns the month, clamped to 1–12 (RFC 5322 Section 3.3).

pub fn day(&self) -> u8

Returns the day of month, clamped to a valid range for the current month and year (RFC 5322 Section 3.3).

pub fn hour(&self) -> u8

Returns the hour, clamped to 0–23 (RFC 5322 Section 3.3).

pub fn minute(&self) -> u8

Returns the minute, clamped to 0–59 (RFC 5322 Section 3.3).

pub fn second(&self) -> u8

Returns the second, clamped to 0–60 (60 is valid for leap seconds per RFC 5322 Section 3.3).

pub fn tz_offset_minutes(&self) -> i16

Returns the timezone offset from UTC in minutes (e.g., +0530 → 330, −0800 → −480), clamped to ±1439 (RFC 5322 Section 3.3).

pub fn to_unix_timestamp(&self) -> i64

Converts this date-time to a Unix timestamp (seconds since 1970-01-01T00:00:00Z).

The timezone offset is applied so the result is always UTC-based. Uses the same civil-to-days algorithm as the builder.

References

• RFC 5322 Section 3.3

pub fn from_unix_timestamp(timestamp: i64, tz_offset_minutes: i16) -> Self

Creates a DateTime from a Unix timestamp (seconds since epoch) and a timezone offset in minutes.

References

• RFC 5322 Section 3.3

pub fn now() -> Self

Returns the current UTC time as a DateTime.

References

• RFC 5322 Section 3.3

pub fn weekday(&self) -> u8

Returns the day of week for this date.

Returns 0 for Sunday, 1 for Monday, …, 6 for Saturday. Uses clamped month/day values for consistency with to_rfc5322_string() (RFC 5322 Section 3.3).

References

• RFC 5322 Section 3.3

pub fn to_rfc5322_string(&self) -> String

Formats this date-time as an RFC 5322 date-time string.

Produces the format: day-of-week, DD Mon YYYY HH:MM:SS ±HHMM (e.g., "Thu, 13 Feb 2025 15:47:33 +0000").

All fields are clamped to their valid ranges per RFC 5322 Section 3.3 to ensure well-formed output (Postel’s law: be conservative in what you send).

References

• RFC 5322 Section 3.3

pub fn to_iso8601_string(&self) -> String

Formats this date-time as an ISO 8601 / RFC 3339 string.

Produces the format: YYYY-MM-DDTHH:MM:SS±HH:MM (e.g., "2025-02-13T15:47:33+00:00").

All fields are clamped to their valid ranges for consistency with to_rfc5322_string().

This format is widely used in JSON APIs and structured data exchange.

References

• ISO 8601 (date-time representation)
• RFC 3339 (date-time on the Internet)

pub fn parse_rfc5322(input: &str) -> Option<Self>

Parses an RFC 5322 date-time string into a DateTime.

Accepts: [day-of-week ","] day month year hour ":" minute [":" second] zone

Strips CFWS (comments and folding white space) before parsing, as allowed by the obsolete date syntax (RFC 5322 Section 4.3).

Returns None if the input is not a valid RFC 5322 date-time.

References

• RFC 5322 Section 3.3
• RFC 5322 Section 4.3 (obsolete syntax)

Trait Implementations

impl Clone for DateTime

fn clone(&self) -> DateTime

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DateTime

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

Formats the value using the given formatter.

impl Display for DateTime

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

Formats this date-time for human-readable display.

All fields are clamped to their valid ranges, consistent with to_rfc5322_string() and to_iso8601_string() (RFC 5322 §3.3).

impl FromStr for DateTime

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses an RFC 5322 date-time string into a DateTime.

Accepts: [day-of-week ","] day month year hour ":" minute [":" second] zone

This enables the ergonomic "Thu, 13 Feb 2025 15:47:33 +0000".parse::<DateTime>() pattern via the standard FromStr trait.

References

• RFC 5322 Section 3.3
• RFC 5322 Section 4.3 (obsolete syntax)

type Err = Error

The associated error which can be returned from parsing.

impl Hash for DateTime

fn hash<H: Hasher>(&self, state: &mut H)

Hashes by UTC-normalized timestamp, consistent with Eq and Ord.

Two DateTime values representing the same UTC instant (but with different timezone offsets) will produce the same hash, matching the Eq behavior.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for DateTime

fn cmp(&self, other: &Self) -> Ordering

Compares two DateTime values by their UTC-normalized timestamps.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for DateTime

fn eq(&self, other: &Self) -> bool

Compares two DateTime values by their UTC-normalized timestamps, consistent with the Ord implementation.

References

• RFC 5322 Section 3.3 (date-time specification)

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for DateTime

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for DateTime