impl PiecesNumericOffset

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(),
);

# Ok::<(), Box<dyn std::error::Error>>(())

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

# Ok::<(), Box<dyn std::error::Error>>(())

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