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

Struct PiecesNumericOffset

pub struct PiecesNumericOffset { /* private fields */ }

Available on crate features dep_jiff and alloc only.

Expand description

A specific numeric offset, including the sign of the offset, for use with Pieces.

§Signedness

The sign attached to this type is usually redundant, since the underlying 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 PiecesNumericOffset

pub fn offset(&self) -> Offset

Returns the numeric offset.

§Example

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

let pieces = Pieces::parse("1970-01-01T00:00:00-05:30")?;
let off = match pieces.offset().unwrap() {
    PiecesOffset::Numeric(off) => off,
    _ => unreachable!(),
};
// This is really only useful if you care that an actual
// numeric offset was written and not, e.g., `Z`. Otherwise,
// you could just use `PiecesOffset::to_numeric_offset`.
assert_eq!(
    off.offset(),
    Offset::from_seconds(-5 * 60 * 60 - 30 * 60).unwrap(),
);

pub fn is_negative(&self) -> bool

Returns whether the sign of the offset is negative or not.

When formatting a Pieces to a string, this is only used to determine the rendered sign when the Offset is itself zero. In all other cases, the sign rendered matches the sign of the Offset.

Since Offset does not keep track of a sign when its value is zero, when using the From<Offset> trait implementation for this type, is_negative is always set to false when the offset is zero.

§Example

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

let pieces = Pieces::parse("1970-01-01T00:00:00-00:00")?;
let off = match pieces.offset().unwrap() {
    PiecesOffset::Numeric(off) => off,
    _ => unreachable!(),
};
// The numeric offset component in this case is
// indistiguisable from `Offset::UTC`. This is
// because an `Offset` does not use different
// representations for negative and positive zero.
assert_eq!(off.offset(), Offset::UTC);
// This is where `is_negative` comes in handy:
assert_eq!(off.is_negative(), true);

pub fn with_negative_zero(self) -> PiecesNumericOffset

Sets this numeric offset to use -00:00 if and only if the offset is zero.

§Example

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