Enum PiecesOffset

#[non_exhaustive]
pub enum PiecesOffset {
    Zulu,
    Numeric(PiecesNumericOffset),
}

An offset parsed from a Temporal ISO 8601 datetime string, for use with Pieces.

One can almost think of this as effectively equivalent to an Offset. And indeed, all PiecesOffset values can be convert to an Offset. However, some offsets in a datetime string have a different connotation that can’t be captured by an Offset.

For example, the offsets Z, -00:00 and +00:00 all map to Offset::UTC after parsing. However, Z and -00:00 generally indicate that the offset from local time is unknown, where as +00:00 indicates that the offset from local is known and is zero. This type permits callers to inspect what offset was actually written.

Example

This example shows how one can create Temporal ISO 8601 datetime strings with +00:00, -00:00 or Z offsets.

use jiff::{
    fmt::temporal::{Pieces, PiecesNumericOffset},
    tz::Offset,
    Timestamp,
};

// If you create a `Pieces` from a `Timestamp` with a UTC offset,
// then this is interpreted as "the offset from UTC is known and is
// zero."
let pieces = Pieces::from((Timestamp::UNIX_EPOCH, Offset::UTC));
assert_eq!(pieces.to_string(), "1970-01-01T00:00:00+00:00");

// Otherwise, if you create a `Pieces` from just a `Timestamp` with
// no offset, then it is interpreted as "the offset from UTC is not
// known." Typically, this is rendered with `Z` for "Zulu":
let pieces = Pieces::from(Timestamp::UNIX_EPOCH);
assert_eq!(pieces.to_string(), "1970-01-01T00:00:00Z");

// But it might be the case that you want to use `-00:00` instead,
// perhaps to conform to some existing convention or legacy
// applications that require it:
let pieces = Pieces::from(Timestamp::UNIX_EPOCH)
    .with_offset(
        PiecesNumericOffset::from(Offset::UTC).with_negative_zero(),
    );
assert_eq!(pieces.to_string(), "1970-01-01T00:00:00-00:00");

Without Pieces, it’s not otherwise possible to emit a -00:00 offset. For example, DateTimePrinter::print_timestamp will always emit Z, which is consider semantically identical to -00:00 by RFC 9557. There’s no specific use case where it’s expected that you should need to write -00:00 instead of Z, but it’s conceivable legacy or otherwise inflexible applications might want it. Or perhaps, in some systems, there is a distinction to draw between Z and -00:00.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Zulu

The “Zulu” offset, corresponding to UTC in a context where the offset for civil time is unknown or unavailable.

RFC 9557 defines this as equivalent in semantic meaning to -00:00:

If the time in UTC is known, but the offset to local time is unknown, this can be represented with an offset of Z. (The original version of this specification provided -00:00 for this purpose, which is not allowed by ISO-8601:2000 and therefore is less interoperable; Section 3.3 of RFC 5322 describes a related convention for email, which does not have this problem). This differs semantically from an offset of +00:00, which implies that UTC is the preferred reference point for the specified time.

Numeric(PiecesNumericOffset)

A specific numeric offset, including whether the parsed sign is negative.

The sign is usually redundant, since an Offset is itself signed. But it can be used to distinguish between +00:00 (+00 is the preferred offset) and -00:00 (+00 is what should be used, but only because the offset to local time is not known). Generally speaking, one should regard -00:00 as equivalent to Z, per RFC 9557.

Implementations

impl PiecesOffset

pub fn to_numeric_offset(&self) -> Offset

Converts this offset to a concrete numeric offset in all cases.

If this was a Z or a -00:00 offset, then Offset::UTC is returned. In all other cases, the underlying numeric offset is returned as-is.

Example

use jiff::{
    fmt::temporal::{Pieces, PiecesNumericOffset, PiecesOffset},
    tz::Offset,
};

let pieces = Pieces::parse("1970-01-01T00:00:00Z")?;
let off = pieces.offset().unwrap();
// Parsed as Zulu.
assert_eq!(off, PiecesOffset::Zulu);
// Gets converted from Zulu to UTC, i.e., just zero.
assert_eq!(off.to_numeric_offset(), Offset::UTC);

let pieces = Pieces::parse("1970-01-01T00:00:00-00:00")?;
let off = pieces.offset().unwrap();
// Parsed as a negative zero.
assert_eq!(off, PiecesOffset::from(
    PiecesNumericOffset::from(Offset::UTC).with_negative_zero(),
));
// Gets converted from -00:00 to UTC, i.e., just zero.
assert_eq!(off.to_numeric_offset(), Offset::UTC);

let pieces = Pieces::parse("1970-01-01T00:00:00+00:00")?;
let off = pieces.offset().unwrap();
// Parsed as a positive zero.
assert_eq!(off, PiecesOffset::from(
    PiecesNumericOffset::from(Offset::UTC),
));
// Gets converted from -00:00 to UTC, i.e., just zero.
assert_eq!(off.to_numeric_offset(), Offset::UTC);

Trait Implementations

impl Clone for PiecesOffset

fn clone(&self) -> PiecesOffset

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for PiecesOffset

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

Formats the value using the given formatter.

impl From<Offset> for PiecesOffset

fn from(offset: Offset) -> PiecesOffset

Converts to this type from the input type.

impl From<PiecesNumericOffset> for PiecesOffset

fn from(offset: PiecesNumericOffset) -> PiecesOffset

Converts to this type from the input type.

impl Hash for PiecesOffset

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

where __H: Hasher,

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 PiecesOffset

fn eq(&self, other: &PiecesOffset) -> 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 Copy for PiecesOffset

impl Eq for PiecesOffset

impl StructuralPartialEq for PiecesOffset