Struct Offset

pub struct Offset { /* private fields */ }

Available on crate features dep_jiff and alloc only.

Represents a fixed time zone offset.

Negative offsets correspond to time zones west of the prime meridian, while positive offsets correspond to time zones east of the prime meridian. Equivalently, in all cases, civil-time - offset = UTC.

Display format

This type implements the std::fmt::Display trait. It will convert the offset to a string format in the form {sign}{hours}[:{minutes}[:{seconds}]], where minutes and seconds are only present when non-zero. For example:

use jiff::tz;

let o = tz::offset(-5);
assert_eq!(o.to_string(), "-05");
let o = tz::Offset::from_seconds(-18_000).unwrap();
assert_eq!(o.to_string(), "-05");
let o = tz::Offset::from_seconds(-18_060).unwrap();
assert_eq!(o.to_string(), "-05:01");
let o = tz::Offset::from_seconds(-18_062).unwrap();
assert_eq!(o.to_string(), "-05:01:02");

// The min value.
let o = tz::Offset::from_seconds(-93_599).unwrap();
assert_eq!(o.to_string(), "-25:59:59");
// The max value.
let o = tz::Offset::from_seconds(93_599).unwrap();
assert_eq!(o.to_string(), "+25:59:59");
// No offset.
let o = tz::offset(0);
assert_eq!(o.to_string(), "+00");

Example

This shows how to create a zoned datetime with a time zone using a fixed offset:

use jiff::{civil::date, tz, Zoned};

let offset = tz::offset(-4).to_time_zone();
let zdt = date(2024, 7, 8).at(15, 20, 0, 0).to_zoned(offset)?;
assert_eq!(zdt.to_string(), "2024-07-08T15:20:00-04:00[-04:00]");

Notice that the zoned datetime still includes a time zone annotation. But since there is no time zone identifier, the offset instead is repeated as an additional assertion that a fixed offset datetime was intended.

Implementations

impl Offset

pub const MIN: Offset

The minimum possible time zone offset.

This corresponds to the offset -25:59:59.

pub const MAX: Offset

The maximum possible time zone offset.

This corresponds to the offset 25:59:59.

pub const UTC: Offset = Offset::ZERO

The offset corresponding to UTC. That is, no offset at all.

This is defined to always be equivalent to Offset::ZERO, but it is semantically distinct. This ought to be used when UTC is desired specifically, while Offset::ZERO ought to be used when one wants to express “no offset.” For example, when adding offsets, Offset::ZERO corresponds to the identity.

pub const ZERO: Offset

The offset corresponding to no offset at all.

This is defined to always be equivalent to Offset::UTC, but it is semantically distinct. This ought to be used when a zero offset is desired specifically, while Offset::UTC ought to be used when one wants to express UTC. For example, when adding offsets, Offset::ZERO corresponds to the identity.

pub const fn constant(hours: i8) -> Offset

Creates a new time zone offset in a const context from a given number of hours.

Negative offsets correspond to time zones west of the prime meridian, while positive offsets correspond to time zones east of the prime meridian. Equivalently, in all cases, civil-time - offset = UTC.

The fallible non-const version of this constructor is Offset::from_hours.

Panics

This routine panics when the given number of hours is out of range. Namely, hours must be in the range -25..=25.

Example

use jiff::tz::Offset;

let o = Offset::constant(-5);
assert_eq!(o.seconds(), -18_000);
let o = Offset::constant(5);
assert_eq!(o.seconds(), 18_000);

Alternatively, one can use the terser jiff::tz::offset free function:

use jiff::tz;

let o = tz::offset(-5);
assert_eq!(o.seconds(), -18_000);
let o = tz::offset(5);
assert_eq!(o.seconds(), 18_000);

pub fn from_hours(hours: i8) -> Result<Offset, Error>

Creates a new time zone offset from a given number of hours.

Negative offsets correspond to time zones west of the prime meridian, while positive offsets correspond to time zones east of the prime meridian. Equivalently, in all cases, civil-time - offset = UTC.

Errors

This routine returns an error when the given number of hours is out of range. Namely, hours must be in the range -25..=25.

Example

use jiff::tz::Offset;

let o = Offset::from_hours(-5)?;
assert_eq!(o.seconds(), -18_000);
let o = Offset::from_hours(5)?;
assert_eq!(o.seconds(), 18_000);

pub fn from_seconds(seconds: i32) -> Result<Offset, Error>

Creates a new time zone offset in a const context from a given number of seconds.

Negative offsets correspond to time zones west of the prime meridian, while positive offsets correspond to time zones east of the prime meridian. Equivalently, in all cases, civil-time - offset = UTC.

Errors

This routine returns an error when the given number of seconds is out of range. The range corresponds to the offsets -25:59:59..=25:59:59. In units of seconds, that corresponds to -93,599..=93,599.

Example

use jiff::tz::Offset;

let o = Offset::from_seconds(-18_000)?;
assert_eq!(o.seconds(), -18_000);
let o = Offset::from_seconds(18_000)?;
assert_eq!(o.seconds(), 18_000);

pub fn seconds(self) -> i32

Returns the total number of seconds in this offset.

The value returned is guaranteed to represent an offset in the range -25:59:59..=25:59:59. Or more precisely, the value will be in units of seconds in the range -93,599..=93,599.

Negative offsets correspond to time zones west of the prime meridian, while positive offsets correspond to time zones east of the prime meridian. Equivalently, in all cases, civil-time - offset = UTC.

Example

use jiff::tz;

let o = tz::offset(-5);
assert_eq!(o.seconds(), -18_000);
let o = tz::offset(5);
assert_eq!(o.seconds(), 18_000);

pub fn negate(self) -> Offset

Returns the negation of this offset.

A negative offset will become positive and vice versa. This is a no-op if the offset is zero.

This never panics.

Example

use jiff::tz;

assert_eq!(tz::offset(-5).negate(), tz::offset(5));
// It's also available via the `-` operator:
assert_eq!(-tz::offset(-5), tz::offset(5));

pub fn signum(self) -> i8

Returns the “sign number” or “signum” of this offset.

The number returned is -1 when this offset is negative, 0 when this offset is zero and 1 when this span is positive.

Example

use jiff::tz;

assert_eq!(tz::offset(5).signum(), 1);
assert_eq!(tz::offset(0).signum(), 0);
assert_eq!(tz::offset(-5).signum(), -1);

pub fn is_positive(self) -> bool

Returns true if and only if this offset is positive.

This returns false when the offset is zero or negative.

Example

use jiff::tz;

assert!(tz::offset(5).is_positive());
assert!(!tz::offset(0).is_positive());
assert!(!tz::offset(-5).is_positive());

pub fn is_negative(self) -> bool

Returns true if and only if this offset is less than zero.

Example

use jiff::tz;

assert!(!tz::offset(5).is_negative());
assert!(!tz::offset(0).is_negative());
assert!(tz::offset(-5).is_negative());

pub fn is_zero(self) -> bool

Returns true if and only if this offset is zero.

Or equivalently, when this offset corresponds to Offset::UTC.

Example

use jiff::tz;

assert!(!tz::offset(5).is_zero());
assert!(tz::offset(0).is_zero());
assert!(!tz::offset(-5).is_zero());

pub fn to_time_zone(self) -> TimeZone

Converts this offset into a TimeZone.

This is a convenience function for calling TimeZone::fixed with this offset.

Example

use jiff::tz::offset;

let tz = offset(-4).to_time_zone();
assert_eq!(
    tz.to_datetime(jiff::Timestamp::UNIX_EPOCH).to_string(),
    "1969-12-31T20:00:00",
);

pub fn to_datetime(self, timestamp: Timestamp) -> DateTime

Converts the given timestamp to a civil datetime using this offset.

Example

use jiff::{civil::date, tz, Timestamp};

assert_eq!(
    tz::offset(-8).to_datetime(Timestamp::UNIX_EPOCH),
    date(1969, 12, 31).at(16, 0, 0, 0),
);

pub fn to_timestamp(self, dt: DateTime) -> Result<Timestamp, Error>

Converts the given civil datetime to a timestamp using this offset.

Errors

This returns an error if this would have returned a timestamp outside of its minimum and maximum values.

Example

This example shows how to find the timestamp corresponding to 1969-12-31T16:00:00-08.

use jiff::{civil::date, tz, Timestamp};

assert_eq!(
    tz::offset(-8).to_timestamp(date(1969, 12, 31).at(16, 0, 0, 0))?,
    Timestamp::UNIX_EPOCH,
);

This example shows some maximum boundary conditions where this routine will fail:

use jiff::{civil::date, tz, Timestamp, ToSpan};

let dt = date(9999, 12, 31).at(23, 0, 0, 0);
assert!(tz::offset(-8).to_timestamp(dt).is_err());

// If the offset is big enough, then converting it to a UTC
// timestamp will fit, even when using the maximum civil datetime.
let dt = date(9999, 12, 31).at(23, 59, 59, 999_999_999);
assert_eq!(tz::Offset::MAX.to_timestamp(dt).unwrap(), Timestamp::MAX);
// But adjust the offset down 1 second is enough to go out-of-bounds.
assert!((tz::Offset::MAX - 1.seconds()).to_timestamp(dt).is_err());

Same as above, but for minimum values:

use jiff::{civil::date, tz, Timestamp, ToSpan};

let dt = date(-9999, 1, 1).at(1, 0, 0, 0);
assert!(tz::offset(8).to_timestamp(dt).is_err());

// If the offset is small enough, then converting it to a UTC
// timestamp will fit, even when using the minimum civil datetime.
let dt = date(-9999, 1, 1).at(0, 0, 0, 0);
assert_eq!(tz::Offset::MIN.to_timestamp(dt).unwrap(), Timestamp::MIN);
// But adjust the offset up 1 second is enough to go out-of-bounds.
assert!((tz::Offset::MIN + 1.seconds()).to_timestamp(dt).is_err());

pub fn checked_add<A>(self, duration: A) -> Result<Offset, Error>

where A: Into<OffsetArithmetic>,

Adds the given span of time to this offset.

Since time zone offsets have second resolution, any fractional seconds in the duration given are ignored.

This operation accepts three different duration types: Span, SignedDuration or std::time::Duration. This is achieved via From trait implementations for the OffsetArithmetic type.

Errors

This returns an error if the result of adding the given span would exceed the minimum or maximum allowed Offset value.

This also returns an error if the span given contains any non-zero units bigger than hours.

Example

This example shows how to add one hour to an offset (if the offset corresponds to standard time, then adding an hour will usually give you DST time):

use jiff::{tz, ToSpan};

let off = tz::offset(-5);
assert_eq!(off.checked_add(1.hours()).unwrap(), tz::offset(-4));

And note that while fractional seconds are ignored, units less than seconds aren’t ignored if they sum up to a duration at least as big as one second:

use jiff::{tz, ToSpan};

let off = tz::offset(5);
let span = 900.milliseconds()
    .microseconds(50_000)
    .nanoseconds(50_000_000);
assert_eq!(
    off.checked_add(span).unwrap(),
    tz::Offset::from_seconds((5 * 60 * 60) + 1).unwrap(),
);
// Any leftover fractional part is ignored.
let span = 901.milliseconds()
    .microseconds(50_001)
    .nanoseconds(50_000_001);
assert_eq!(
    off.checked_add(span).unwrap(),
    tz::Offset::from_seconds((5 * 60 * 60) + 1).unwrap(),
);

This example shows some cases where checked addition will fail.

use jiff::{tz::Offset, ToSpan};

// Adding units above 'hour' always results in an error.
assert!(Offset::UTC.checked_add(1.day()).is_err());
assert!(Offset::UTC.checked_add(1.week()).is_err());
assert!(Offset::UTC.checked_add(1.month()).is_err());
assert!(Offset::UTC.checked_add(1.year()).is_err());

// Adding even 1 second to the max, or subtracting 1 from the min,
// will result in overflow and thus an error will be returned.
assert!(Offset::MIN.checked_add(-1.seconds()).is_err());
assert!(Offset::MAX.checked_add(1.seconds()).is_err());

Example: adding absolute durations

This shows how to add signed and unsigned absolute durations to an Offset. Like with Spans, any fractional seconds are ignored.

use std::time::Duration;

use jiff::{tz::offset, SignedDuration};

let off = offset(-10);

let dur = SignedDuration::from_hours(11);
assert_eq!(off.checked_add(dur)?, offset(1));
assert_eq!(off.checked_add(-dur)?, offset(-21));

// Any leftover time is truncated. That is, only
// whole seconds from the duration are considered.
let dur = Duration::new(3 * 60 * 60, 999_999_999);
assert_eq!(off.checked_add(dur)?, offset(-7));

pub fn checked_sub<A>(self, duration: A) -> Result<Offset, Error>

where A: Into<OffsetArithmetic>,

This routine is identical to Offset::checked_add with the duration negated.

Errors

This has the same error conditions as Offset::checked_add.

Example

use std::time::Duration;

use jiff::{tz, SignedDuration, ToSpan};

let off = tz::offset(-4);
assert_eq!(
    off.checked_sub(1.hours())?,
    tz::offset(-5),
);
assert_eq!(
    off.checked_sub(SignedDuration::from_hours(1))?,
    tz::offset(-5),
);
assert_eq!(
    off.checked_sub(Duration::from_secs(60 * 60))?,
    tz::offset(-5),
);

pub fn saturating_add<A>(self, duration: A) -> Offset

where A: Into<OffsetArithmetic>,

This routine is identical to Offset::checked_add, except the result saturates on overflow. That is, instead of overflow, either Offset::MIN or Offset::MAX is returned.

Example

This example shows some cases where saturation will occur.

use jiff::{tz::Offset, SignedDuration, ToSpan};

// Adding units above 'day' always results in saturation.
assert_eq!(Offset::UTC.saturating_add(1.weeks()), Offset::MAX);
assert_eq!(Offset::UTC.saturating_add(1.months()), Offset::MAX);
assert_eq!(Offset::UTC.saturating_add(1.years()), Offset::MAX);

// Adding even 1 second to the max, or subtracting 1 from the min,
// will result in saturationg.
assert_eq!(Offset::MIN.saturating_add(-1.seconds()), Offset::MIN);
assert_eq!(Offset::MAX.saturating_add(1.seconds()), Offset::MAX);

// Adding absolute durations also saturates as expected.
assert_eq!(Offset::UTC.saturating_add(SignedDuration::MAX), Offset::MAX);
assert_eq!(Offset::UTC.saturating_add(SignedDuration::MIN), Offset::MIN);
assert_eq!(Offset::UTC.saturating_add(std::time::Duration::MAX), Offset::MAX);

pub fn saturating_sub<A>(self, duration: A) -> Offset

where A: Into<OffsetArithmetic>,

This routine is identical to Offset::saturating_add with the span parameter negated.

Example

This example shows some cases where saturation will occur.

use jiff::{tz::Offset, SignedDuration, ToSpan};

// Adding units above 'day' always results in saturation.
assert_eq!(Offset::UTC.saturating_sub(1.weeks()), Offset::MIN);
assert_eq!(Offset::UTC.saturating_sub(1.months()), Offset::MIN);
assert_eq!(Offset::UTC.saturating_sub(1.years()), Offset::MIN);

// Adding even 1 second to the max, or subtracting 1 from the min,
// will result in saturationg.
assert_eq!(Offset::MIN.saturating_sub(1.seconds()), Offset::MIN);
assert_eq!(Offset::MAX.saturating_sub(-1.seconds()), Offset::MAX);

// Adding absolute durations also saturates as expected.
assert_eq!(Offset::UTC.saturating_sub(SignedDuration::MAX), Offset::MIN);
assert_eq!(Offset::UTC.saturating_sub(SignedDuration::MIN), Offset::MAX);
assert_eq!(Offset::UTC.saturating_sub(std::time::Duration::MAX), Offset::MIN);

pub fn until(self, other: Offset) -> Span

Returns the span of time from this offset until the other given.

When the other offset is more west (i.e., more negative) of the prime meridian than this offset, then the span returned will be negative.

Properties

Adding the span returned to this offset will always equal the other offset given.

Examples

use jiff::{tz, ToSpan};

assert_eq!(
    tz::offset(-5).until(tz::Offset::UTC),
    (5 * 60 * 60).seconds(),
);
// Flipping the operands in this case results in a negative span.
assert_eq!(
    tz::Offset::UTC.until(tz::offset(-5)),
    -(5 * 60 * 60).seconds(),
);

pub fn since(self, other: Offset) -> Span

Returns the span of time since the other offset given from this offset.

When the other is more east (i.e., more positive) of the prime meridian than this offset, then the span returned will be negative.

Properties

Adding the span returned to the other offset will always equal this offset.

Examples

use jiff::{tz, ToSpan};

assert_eq!(
    tz::Offset::UTC.since(tz::offset(-5)),
    (5 * 60 * 60).seconds(),
);
// Flipping the operands in this case results in a negative span.
assert_eq!(
    tz::offset(-5).since(tz::Offset::UTC),
    -(5 * 60 * 60).seconds(),
);

pub fn duration_until(self, other: Offset) -> SignedDuration

Returns an absolute duration representing the difference in time from this offset until the given other offset.

When the other offset is more west (i.e., more negative) of the prime meridian than this offset, then the duration returned will be negative.

Unlike Offset::until, this returns a duration corresponding to a 96-bit integer of nanoseconds between two offsets.

When should I use this versus Offset::until?

See the type documentation for SignedDuration for the section on when one should use Span and when one should use SignedDuration. In short, use Span (and therefore Offset::until) unless you have a specific reason to do otherwise.

Examples

use jiff::{tz, SignedDuration};

assert_eq!(
    tz::offset(-5).duration_until(tz::Offset::UTC),
    SignedDuration::from_hours(5),
);
// Flipping the operands in this case results in a negative span.
assert_eq!(
    tz::Offset::UTC.duration_until(tz::offset(-5)),
    SignedDuration::from_hours(-5),
);

pub fn duration_since(self, other: Offset) -> SignedDuration

This routine is identical to Offset::duration_until, but the order of the parameters is flipped.

Examples

use jiff::{tz, SignedDuration};

assert_eq!(
    tz::Offset::UTC.duration_since(tz::offset(-5)),
    SignedDuration::from_hours(5),
);
assert_eq!(
    tz::offset(-5).duration_since(tz::Offset::UTC),
    SignedDuration::from_hours(-5),
);

Trait Implementations

impl Add<Duration> for Offset

Adds an unsigned duration of time to an offset. This panics on overflow.

For checked arithmetic, see Offset::checked_add.

type Output = Offset

The resulting type after applying the + operator.

fn add(self, rhs: Duration) -> Offset

Performs the + operation.

impl Add<SignedDuration> for Offset

Adds a signed duration of time to an offset. This panics on overflow.

For checked arithmetic, see Offset::checked_add.

type Output = Offset

The resulting type after applying the + operator.

fn add(self, rhs: SignedDuration) -> Offset

Performs the + operation.

impl Add<Span> for Offset

Adds a span of time to an offset. This panics on overflow.

For checked arithmetic, see Offset::checked_add.

type Output = Offset

The resulting type after applying the + operator.

fn add(self, rhs: Span) -> Offset

Performs the + operation.

impl AddAssign<Duration> for Offset

Adds an unsigned duration of time to an offset in place. This panics on overflow.

For checked arithmetic, see Offset::checked_add.

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

impl AddAssign<SignedDuration> for Offset

Adds a signed duration of time to an offset in place. This panics on overflow.

For checked arithmetic, see Offset::checked_add.

fn add_assign(&mut self, rhs: SignedDuration)

Performs the += operation.

impl AddAssign<Span> for Offset

Adds a span of time to an offset in place. This panics on overflow.

For checked arithmetic, see Offset::checked_add.

fn add_assign(&mut self, rhs: Span)

Performs the += operation.

impl Clone for Offset

fn clone(&self) -> Offset

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Offset

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

Formats the value using the given formatter.

impl Display for Offset

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

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<Offset> for PiecesOffset

fn from(offset: Offset) -> PiecesOffset

Converts to this type from the input type.

impl From<Offset> for TimeZoneAnnotation<'static>

fn from(offset: Offset) -> TimeZoneAnnotation<'static>

Converts to this type from the input type.

impl From<Offset> for TimeZoneAnnotationKind<'static>

fn from(offset: Offset) -> TimeZoneAnnotationKind<'static>

Converts to this type from the input type.

impl Hash for Offset

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 Neg for Offset

Negate this offset.

A positive offset becomes negative and vice versa. This is a no-op for the zero offset.

This never panics.

type Output = Offset

The resulting type after applying the - operator.

fn neg(self) -> Offset

Performs the unary - operation.

impl Ord for Offset

fn cmp(&self, other: &Offset) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Offset

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

fn partial_cmp(&self, other: &Offset) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Sub<Duration> for Offset

Subtracts an unsigned duration of time from an offset. This panics on overflow.

For checked arithmetic, see Offset::checked_sub.

type Output = Offset

The resulting type after applying the - operator.

fn sub(self, rhs: Duration) -> Offset

Performs the - operation.

impl Sub<SignedDuration> for Offset

Subtracts a signed duration of time from an offset. This panics on overflow.

For checked arithmetic, see Offset::checked_sub.

type Output = Offset

The resulting type after applying the - operator.

fn sub(self, rhs: SignedDuration) -> Offset

Performs the - operation.

impl Sub<Span> for Offset

Subtracts a span of time from an offset. This panics on overflow.

For checked arithmetic, see Offset::checked_sub.

type Output = Offset

The resulting type after applying the - operator.

fn sub(self, rhs: Span) -> Offset

Performs the - operation.

impl Sub for Offset

Computes the span of time between two offsets.

This will return a negative span when the offset being subtracted is greater (i.e., more east with respect to the prime meridian).

type Output = Span

The resulting type after applying the - operator.

fn sub(self, rhs: Offset) -> Span

Performs the - operation.

impl SubAssign<Duration> for Offset

Subtracts an unsigned duration of time from an offset in place. This panics on overflow.

For checked arithmetic, see Offset::checked_sub.

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation.

impl SubAssign<SignedDuration> for Offset

Subtracts a signed duration of time from an offset in place. This panics on overflow.

For checked arithmetic, see Offset::checked_sub.

fn sub_assign(&mut self, rhs: SignedDuration)

Performs the -= operation.

impl SubAssign<Span> for Offset

Subtracts a span of time from an offset in place. This panics on overflow.

For checked arithmetic, see Offset::checked_sub.

fn sub_assign(&mut self, rhs: Span)

Performs the -= operation.

impl Copy for Offset

impl Eq for Offset

impl StructuralPartialEq for Offset