Struct Timestamp 

pub struct Timestamp { /* private fields */ }

An instant in time represented as the number of nanoseconds since the Unix epoch.

A timestamp is always in the Unix timescale with a UTC offset of zero.

Implementations

impl Timestamp

pub const MIN: Timestamp

The minimum allow Unix timestamp.

pub const MAX: Timestamp

The maximum allow Unix timestamp.

pub const UNIX_EPOCH: Timestamp

The Unix epoch represented as a timestamp.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub const fn as_nanosecond(self) -> i128

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

pub 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.

pub 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.

pub 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.

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

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

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

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

pub 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.

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

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

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

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

Subtracts the given number of seconds from this timestamp.

Trait Implementations

impl Add<(i64, i32)> for Timestamp

Adds a number of seconds and nanoseconds to a Timestamp.

Panics

When adding would result in a value outside the boundaries of a Timestamp.

Example

use jiff_core::Timestamp;

let ts = Timestamp::new(123, 999_999_999).unwrap();;
assert_eq!(ts + (400, 1), Timestamp::new(524, 0).unwrap());

type Output = Timestamp

The resulting type after applying the + operator.

fn add(self, (seconds, nanoseconds): (i64, i32)) -> Timestamp

Performs the + operation.

impl Add<i64> for Timestamp

Adds a number of seconds to a Timestamp.

Panics

When adding would result in a value outside the boundaries of a Timestamp.

Example

use jiff_core::Timestamp;

let ts = Timestamp::new(123, 999_999_999).unwrap();;
assert_eq!(ts + 400, Timestamp::new(523, 999_999_999).unwrap());

type Output = Timestamp

The resulting type after applying the + operator.

fn add(self, seconds: i64) -> Timestamp

Performs the + operation.

impl AddAssign<(i64, i32)> for Timestamp

Adds a number of seconds and nanoseconds to a Timestamp.

Panics

When adding would result in a value outside the boundaries of a Timestamp.

fn add_assign(&mut self, rhs: (i64, i32))

Performs the += operation.

impl AddAssign<i64> for Timestamp

Adds a number of seconds to a Timestamp.

Panics

When adding would result in a value outside the boundaries of a Timestamp.

fn add_assign(&mut self, rhs: i64)

Performs the += operation.

impl Clone for Timestamp

fn clone(&self) -> Timestamp

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Timestamp

impl Debug for Timestamp

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

Formats the value using the given formatter.

impl Default for Timestamp

fn default() -> Timestamp

Returns the “default value” for a type.

impl Eq for Timestamp

impl Format for Timestamp

fn format(&self, f: Formatter<'_>)

Writes the defmt representation of self to fmt.

impl Hash for Timestamp

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 Ord for Timestamp

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

fn eq(&self, other: &Timestamp) -> bool

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for Timestamp

fn partial_cmp(&self, other: &Timestamp) -> 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 StructuralPartialEq for Timestamp

impl Sub<(i64, i32)> for Timestamp

Subtracts a number of seconds and nanoseconds from a Timestamp.

Panics

When adding would result in a value outside the boundaries of a Timestamp.

Example

use jiff_core::Timestamp;

let ts = Timestamp::new(523, 999_999_999).unwrap();;
assert_eq!(ts - (400, 1), Timestamp::new(123, 999_999_998).unwrap());

type Output = Timestamp

The resulting type after applying the - operator.

fn sub(self, (seconds, nanoseconds): (i64, i32)) -> Timestamp

Performs the - operation.

impl Sub<i64> for Timestamp

Subtracts a number of seconds from a Timestamp.

Panics

When adding would result in a value outside the boundaries of a Timestamp.

Example

use jiff_core::Timestamp;

let ts = Timestamp::new(523, 999_999_999).unwrap();;
assert_eq!(ts - 400, Timestamp::new(123, 999_999_999).unwrap());

type Output = Timestamp

The resulting type after applying the - operator.

fn sub(self, seconds: i64) -> Timestamp

Performs the - operation.

impl SubAssign<(i64, i32)> for Timestamp

Subtracts a number of seconds and nanoseconds from a Timestamp.

Panics

When subtracting would result in a value outside the boundaries of a Timestamp.

fn sub_assign(&mut self, rhs: (i64, i32))

Performs the -= operation.

impl SubAssign<i64> for Timestamp

Subtracts a number of seconds from a Timestamp.

Panics

When subtracting would result in a value outside the boundaries of a Timestamp.

fn sub_assign(&mut self, rhs: i64)

Performs the -= operation.