devela::_dep::jiff::fmt::temporal

Enum PiecesOffset

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

Available on crate features dep_jiff and alloc only.

Expand description

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)§

This enum is marked as 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);