Struct UTCDate 

#[non_exhaustive]
pub struct UTCDate(/* private fields */);

RFC 3339 UTC timestamp string (RFC 8620 §1.4).

Format: YYYY-MM-DDTHH:MM:SSZ — time-offset MUST be Z, letters uppercase, fractional seconds omitted if zero. Example: "2014-10-30T06:12:00Z".

Deserialization is NOT validated

UTCDate is #[serde(transparent)] over String. Any string that deserializes into a String deserializes into a UTCDate — including "not-a-date", "2024-01-19T18:00:00" (no Z suffix), or any other shape that violates RFC 8620 §1.4. The newtype carries the type-level intent of “RFC 8620 UTC timestamp” but does NOT enforce it at the wire boundary.

Use UTCDate::new_validated when constructing from untrusted input, or call UTCDate::to_epoch_seconds when consuming a deserialized value: the latter re-validates structural format AND semantic ranges (month, day, hour, minute, second) and returns ValidationError on any deviation. Treat any field of type Option<UTCDate> arriving from a peer as “RFC 8620 timestamp by convention, not by contract”.

Implementations

impl UTCDate

pub fn into_inner(self) -> String

Consumes the value and returns the inner String.

impl UTCDate

pub fn new_validated(s: impl Into<String>) -> Result<Self, ValidationError>

Construct a UTCDate with RFC 8620 §1.4 validation.

Validation has two layers:

1. Shape: exactly 20 characters in the YYYY-MM-DDTHH:MM:SSZ layout with Z suffix and ASCII digits in every numeric position.
2. Values: month 1..=12; day 1..=days_in_month(year, month) with proleptic Gregorian leap-year rules so e.g. 2024-02-29 is accepted but 2023-02-29 and 2024-02-30 are rejected; hour 0..=23; minute 0..=59; second 0..=59 (RFC 8620 §1.4 does not permit leap seconds even though RFC 3339 §5.6 does).

Errors

Returns ValidationError when the input does not satisfy RFC 8620 §1.4. The error description contains a substring that callers can match on if they need finer-grained handling:

• "exactly 20 characters" — wrong length;
• "wrong structure" — separators or Z suffix missing / misplaced;
• "is not a digit" — non-digit at a numeric position;
• "month must be" — month outside 1..=12;
• "day must be" — day outside 1..=days_in_month(year, month) (catches both out-of-range day numbers like 32 and non-existent dates like Feb 30 or Feb 29 in a non-leap year);
• "hour must be", "minute must be", "second must be" — the corresponding time component is out of range.

Use UTCDate::from when the value is known to be valid.

pub fn to_epoch_seconds(&self) -> Result<i64, ValidationError>

Convert this UTCDate to seconds since the Unix epoch (1970-01-01T00:00:00Z).

Re-validates the structural RFC 8620 §1.4 format (the value may have been constructed via UTCDate::from without validation) and also validates semantic ranges: month 1..=12, day 1..=days_in_month, hour 0..=23, minute 0..=59, second 0..=59 (no leap seconds). Returns ValidationError on any validation failure.

Negative values are returned for dates before 1970-01-01T00:00:00Z.

Uses the proleptic Gregorian calendar via Hinnant’s days_from_civil algorithm, which is exact-integer and handles leap years and century rules correctly. No external dependencies.

Examples

use jmap_types::UTCDate;
let d = UTCDate::new_validated("1970-01-01T00:00:00Z").unwrap();
assert_eq!(d.to_epoch_seconds().unwrap(), 0);
let rfc = UTCDate::new_validated("2014-10-30T06:12:00Z").unwrap();
assert_eq!(rfc.to_epoch_seconds().unwrap(), 1_414_649_520);

Trait Implementations

impl AsRef<str> for UTCDate

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<str> for UTCDate

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl Clone for UTCDate

fn clone(&self) -> UTCDate

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for UTCDate

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for UTCDate

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for UTCDate

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

Formats the value using the given formatter.

impl Eq for UTCDate

impl From<&str> for UTCDate

fn from(s: &str) -> Self

Converts to this type from the input type.

impl From<String> for UTCDate

fn from(s: String) -> Self

Converts to this type from the input type.

impl Hash for UTCDate

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

Feeds this value into the given Hasher.

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 PartialEq for UTCDate

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

Tests for self and other values to be equal, and is used by ==.

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 PartialEq<&str> for UTCDate

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

Tests for self and other values to be equal, and is used by ==.

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 PartialEq<str> for UTCDate

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

Tests for self and other values to be equal, and is used by ==.

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 Serialize for UTCDate

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for UTCDate