Struct PiecesNumericOffset

pub struct PiecesNumericOffset { /* private fields */ }

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

Trait Implementations

impl Clone for PiecesNumericOffset

fn clone(&self) -> PiecesNumericOffset

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PiecesNumericOffset

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

Formats the value using the given formatter.

impl From<Offset> for PiecesNumericOffset

fn from(offset: Offset) -> PiecesNumericOffset

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 PiecesNumericOffset

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 PiecesNumericOffset

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

impl Eq for PiecesNumericOffset

impl StructuralPartialEq for PiecesNumericOffset