impl Timestamp

const MIN: Timestamp = _;

The minimum allow Unix timestamp.

const MAX: Timestamp = _;

The maximum allow Unix timestamp.

const UNIX_EPOCH: Timestamp = _;

The Unix epoch represented as a timestamp.

const fn new(secs: i64, nanos: i32) -> Result<Timestamp, RangeError>

Create a new timestamp from the given number of seconds and its sub-second component.

This returns an error if nanos is not in the range specified by SignedSubsecNanosecond. An error is also returned when secs is not in the range specified by UnixEpochSeconds.

const fn constant(second: i64, nanosecond: i32) -> Timestamp

Creates a new Timestamp value in a const context.

This is identical to Timestamp::new, except that it panics when Timestamp::new would return an error. This can be more convenient in a const context where unwrapping a Result is not ergonomic.

const fn from_second(second: i64) -> Result<Timestamp, RangeError>

Constructs a timestamp from seconds since the Unix epoch.

This is preferred to Timestamp::new when it is known that the sub-second component is always 0. In particular, this generates less code and is likely to be faster.

An error is returned when second is not in the range specified by UnixEpochSeconds.

const fn from_millisecond(millisecond: i64) -> Result<Timestamp, RangeError>

Constructs a timestamp from milliseconds since the Unix epoch.

An error is returned when millisecond is not in the range specified by UnixEpochMilliseconds.

const fn from_microsecond(microsecond: i64) -> Result<Timestamp, RangeError>

Constructs a timestamp from microseconds since the Unix epoch.

An error is returned when microsecond is not in the range specified by UnixEpochMicroseconds.

const fn from_nanosecond(nanosecond: i128) -> Result<Timestamp, RangeError>

Constructs a timestamp from nanoseconds since the Unix epoch.

An error is returned when nanosecond refers to a timestamp outside of the range Timestamp::MIN to Timestamp::MAX.

const fn as_second(self) -> i64

Returns this timestamp as a number of seconds since the Unix epoch.

This only returns the number of whole seconds. That is, if there are any fractional seconds in this timestamp, then they are truncated.

const fn as_millisecond(self) -> i64

Returns this timestamp as a number of milliseconds since the Unix epoch.

This only returns the number of whole milliseconds. That is, if there are any fractional milliseconds in this timestamp, then they are truncated.

const fn as_microsecond(self) -> i64

Returns this timestamp as a number of microseconds since the Unix epoch.

This only returns the number of whole microseconds. That is, if there are any fractional microseconds in this timestamp, then they are truncated.

const fn as_nanosecond(self) -> i128

Returns this timestamp as a number of nanoseconds since the Unix epoch.

const fn subsec_millisecond(&self) -> i32

Returns the fractional second component of this timestamp in units of microseconds.

The value returned is negative when the timestamp is negative. It is guaranteed that the range of the value returned is in the inclusive range -999_999..=999_999.

const fn subsec_microsecond(&self) -> i32

Returns the fractional second component of this timestamp in units of milliseconds.

The value returned is negative when the timestamp is negative. It is guaranteed that the range of the value returned is in the inclusive range -999..=999.

const fn subsec_nanosecond(&self) -> i32

Returns the fractional second component of this timestamp in units of nanoseconds.

The value returned is negative when the timestamp is negative. It is guaranteed that the range of the value returned is in the inclusive range -999,999,999..=999,999,999.

const fn signum(self) -> i8

Returns a number that represents the sign of this timestamp.

• When Timestamp::is_zero is true, this returns 0.
• When Timestamp::is_positive is true, this returns 1.
• When Timestamp::is_negative is true, this returns -1.

The above cases are mutually exclusive.

Example

use jiff_core::Timestamp;

assert_eq!(0, Timestamp::UNIX_EPOCH.signum());

let ts = Timestamp::new(5, -999_999_999).unwrap();
assert_eq!(ts.signum(), 1);
// The mixed signs were normalized away!
assert_eq!(ts.as_second(), 4);
assert_eq!(ts.subsec_nanosecond(), 1);

// The same applies for negative timestamps.
let ts = Timestamp::new(-5, 999_999_999).unwrap();
assert_eq!(ts.signum(), -1);
assert_eq!(ts.as_second(), -4);
assert_eq!(ts.subsec_nanosecond(), -1);

const fn is_zero(self) -> bool

Returns true if and only if this timestamp corresponds to the instant in time known as the Unix epoch.

Example

use jiff_core::Timestamp;

assert!(Timestamp::UNIX_EPOCH.is_zero());

const fn is_positive(&self) -> bool

Returns true when this timestamp is positive. That is, after the Unix epoch.

Example

use jiff_core::Timestamp;

let ts = Timestamp::new(0, 1).unwrap();
assert!(ts.is_positive());

const fn is_negative(&self) -> bool

Returns true when this timestamp is negative. That is, before the Unix epoch.

Example

use jiff_core::Timestamp;

let ts = Timestamp::new(0, -1).unwrap();
assert!(ts.is_negative());

const fn to_datetime(&self, offset: Offset) -> DateTime

Converts a Unix timestamp with an offset to a Gregorian datetime.

The offset should correspond to the number of seconds required to add to this timestamp to get the local time.

const fn checked_add(self, seconds: i64, nanos: i32) -> Result<Timestamp, RangeError>

Add the given number of seconds and nanoseconds to this timestamp.

If this would result in a timestamp outside of its boundaries, then this returns an error.

Examples

use jiff_core::Timestamp;

let mkts = |sec, nano| Timestamp::new(sec, nano).unwrap();
let ts = mkts(123, 0);

assert_eq!(ts.checked_add(1, 0), Ok(mkts(124, 0)));
assert_eq!(ts.checked_add(1, 1), Ok(mkts(124, 1)));
assert_eq!(ts.checked_add(1, -1), Ok(mkts(123, 999_999_999)));
assert_eq!(ts.checked_add(0, 1), Ok(mkts(123, 1)));
assert_eq!(ts.checked_add(0, -1), Ok(mkts(122, 999_999_999)));
assert_eq!(ts.checked_add(-1, 0), Ok(mkts(122, 0)));
assert_eq!(ts.checked_add(-1, 1), Ok(mkts(122, 1)));
assert_eq!(ts.checked_add(-1, -1), Ok(mkts(121, 999_999_999)));

assert_eq!(ts.checked_add(0, i32::MIN), Ok(mkts(121, -147_483_648)));
assert_eq!(ts.checked_add(1, i32::MIN), Ok(mkts(122, -147_483_648)));
assert_eq!(ts.checked_add(-1, i32::MIN), Ok(mkts(120, -147_483_648)));
assert_eq!(ts.checked_add(0, i32::MAX), Ok(mkts(125, 147_483_647)));
assert_eq!(ts.checked_add(1, i32::MAX), Ok(mkts(126, 147_483_647)));
assert_eq!(ts.checked_add(-1, i32::MAX), Ok(mkts(124, 147_483_647)));

assert!(ts.checked_add(i64::MAX, 0).is_err());
assert!(ts.checked_add(i64::MIN, 0).is_err());

let ts = Timestamp::UNIX_EPOCH;
let max = Timestamp::MAX.as_second();
assert!(ts.checked_add(max, 0).is_ok());
assert!(ts.checked_add(max + 1, 0).is_err());
assert!(ts.checked_add(max, 999_999_999).is_ok());
assert!(ts.checked_add(max, 1_000_000_000).is_err());

const fn checked_sub(self, seconds: i64, nanos: i32) -> Result<Timestamp, RangeError>

Subtracts the given number of seconds and nanoseconds from this timestamp.

Examples

use jiff_core::Timestamp;

let mkts = |sec, nano| Timestamp::new(sec, nano).unwrap();
let ts = mkts(123, 0);

assert_eq!(ts.checked_sub(1, 0), Ok(mkts(122, 0)));
assert_eq!(ts.checked_sub(1, 1), Ok(mkts(121, 999_999_999)));
assert_eq!(ts.checked_sub(1, -1), Ok(mkts(122, 1)));
assert_eq!(ts.checked_sub(0, 1), Ok(mkts(122, 999_999_999)));
assert_eq!(ts.checked_sub(0, -1), Ok(mkts(123, 1)));
assert_eq!(ts.checked_sub(-1, 0), Ok(mkts(124, 0)));
assert_eq!(ts.checked_sub(-1, 1), Ok(mkts(123, 999_999_999)));
assert_eq!(ts.checked_sub(-1, -1), Ok(mkts(124, 1)));

assert_eq!(ts.checked_sub(0, i32::MIN), Ok(mkts(125, 147_483_648)));
assert_eq!(ts.checked_sub(1, i32::MIN), Ok(mkts(124, 147_483_648)));
assert_eq!(ts.checked_sub(-1, i32::MIN), Ok(mkts(126, 147_483_648)));
assert_eq!(ts.checked_sub(0, i32::MAX), Ok(mkts(121, -147_483_647)));
assert_eq!(ts.checked_sub(1, i32::MAX), Ok(mkts(120, -147_483_647)));
assert_eq!(ts.checked_sub(-1, i32::MAX), Ok(mkts(122, -147_483_647)));

assert!(ts.checked_sub(i64::MAX, 0).is_err());
assert!(ts.checked_sub(i64::MIN, 0).is_err());

let ts = Timestamp::UNIX_EPOCH;
let min = Timestamp::MIN.as_second();
assert!(ts.checked_sub(-min, 0).is_ok());
assert!(ts.checked_sub(-(min - 1), 0).is_err());
assert!(ts.checked_sub(-min, 999_999_999).is_ok());
assert!(ts.checked_sub(-min, 1_000_000_000).is_err());

const fn checked_add_seconds(self, seconds: i64) -> Result<Timestamp, RangeError>

Add the given number of seconds to this timestamp.

If this would result in a timestamp outside of its boundaries, then this returns an error.

The nanosecond component of the timestamp returned is guaranteed to match the nanosecond component of self.

Examples

use jiff_core::Timestamp;

let mkts = |sec, nano| Timestamp::new(sec, nano).unwrap();

let ts = mkts(123, 0);
assert_eq!(ts.checked_add_seconds(0), Ok(mkts(123, 0)));
assert_eq!(ts.checked_add_seconds(1), Ok(mkts(124, 0)));
assert_eq!(ts.checked_add_seconds(-1), Ok(mkts(122, 0)));

let ts = mkts(123, 999_999_999);
assert_eq!(ts.checked_add_seconds(0), Ok(mkts(123, 999_999_999)));
assert_eq!(ts.checked_add_seconds(1), Ok(mkts(124, 999_999_999)));
assert_eq!(ts.checked_add_seconds(-1), Ok(mkts(122, 999_999_999)));

assert!(ts.checked_add_seconds(i64::MIN).is_err());
assert!(ts.checked_add_seconds(i64::MAX).is_err());

const fn checked_sub_seconds(self, seconds: i64) -> Result<Timestamp, RangeError>

Subtracts the given number of seconds from this timestamp.