Struct Timestamp 

#[non_exhaustive]
pub struct Timestamp { /* private fields */ }

Well-known point in time representation for Google APIs.

Examples

let ts = Timestamp::try_from("2025-05-16T09:46:12.500Z")?;
assert_eq!(ts.seconds(), 1747388772);
assert_eq!(ts.nanos(), 500_000_000);

assert_eq!(ts, Timestamp::new(1747388772, 500_000_000)?);
assert_eq!(ts, Timestamp::clamp(1747388772, 500_000_000));

A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one.

All minutes are 60 seconds long. Leap seconds are “smeared” so that no leap second table is needed for interpretation, using a 24-hour linear smear.

The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from RFC 3339 date strings.

JSON Mapping

In JSON format, the Timestamp type is encoded as a string in the RFC 3339 format. That is, the format is “{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z” where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The “Z” suffix indicates the timezone (“UTC”); the timezone is required.

For example, “2017-01-15T01:30:15.01Z” encodes 15.01 seconds past 01:30 UTC on January 15, 2017.

Implementations

impl Timestamp

pub const MIN_SECONDS: i64 = -62_135_596_800i64

The minimum value for the seconds component. Corresponds to ‘0001-01-01T00:00:00Z’.

pub const MAX_SECONDS: i64 = 253_402_300_799i64

The maximum value for the seconds component. Corresponds to ‘9999-12-31T23:59:59Z’.

pub const MIN_NANOS: i32 = 0i32

The minimum value for the nanos component.

pub const MAX_NANOS: i32 = 999_999_999i32

The maximum value for the nanos component.

pub fn new(seconds: i64, nanos: i32) -> Result<Self, TimestampError>

Creates a new Timestamp from the seconds and nanoseconds.

If either value is out of range it returns an error.

Examples

let ts = Timestamp::new(1747388772, 0)?;
assert_eq!(String::from(ts), "2025-05-16T09:46:12Z");

let ts = Timestamp::new(1747388772, 2_000_000_000);
assert!(matches!(ts, Err(TimestampError::OutOfRange)));

Parameters

• seconds - the seconds on the timestamp.
• nanos - the nanoseconds on the timestamp.

pub fn clamp(seconds: i64, nanos: i32) -> Self

Create a normalized, clamped Timestamp.

Examples

let ts = Timestamp::clamp(1747388772, 0);
assert_eq!(String::from(ts), "2025-05-16T09:46:12Z");

let ts = Timestamp::clamp(1747388772, 2_000_000_000);
// extra nanoseconds are carried as seconds
assert_eq!(String::from(ts), "2025-05-16T09:46:14Z");

Timestamps must be between 0001-01-01T00:00:00Z and 9999-12-31T23:59:59.999999999Z, and the nanoseconds component must always be in the range [0, 999_999_999]. This function creates a new Timestamp instance clamped to those ranges.

The function effectively adds the nanoseconds part (with carry) to the seconds part, with saturation.

Parameters

• seconds - the seconds on the timestamp.
• nanos - the nanoseconds added to the seconds.

pub fn seconds(&self) -> i64

Represents seconds of UTC time since Unix epoch (1970-01-01T00:00:00Z).

Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.

Examples

let ts = Timestamp::new(120, 500_000_000)?;
assert_eq!(ts.seconds(), 120);

pub fn nanos(&self) -> i32

Non-negative fractions of a second at nanosecond resolution.

Negative second values (before the Unix epoch) with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.

Examples

let ts = Timestamp::new(120, 500_000_000)?;
assert_eq!(ts.nanos(), 500_000_000);

Trait Implementations

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 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 From<Timestamp> for String

Converts a Timestamp to its String representation.

Example

let ts = Timestamp::new(1747388772, 0)?;
assert_eq!(String::from(ts), "2025-05-16T09:46:12Z");

fn from(timestamp: Timestamp) -> Self

Converts to this type from the input type.

impl Message for Timestamp

fn typename() -> &'static str

The typename of this message.

impl PartialEq for Timestamp

fn eq(&self, other: &Timestamp) -> 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 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 TryFrom<&String> for Timestamp

Converts the string representation of a timestamp to Timestamp.

Example

let s = "2025-05-16T09:46:12.500Z".to_string();
let ts = Timestamp::try_from(&s)?;
assert_eq!(ts.seconds(), 1747388772);
assert_eq!(ts.nanos(), 500_000_000);

type Error = TimestampError

The type returned in the event of a conversion error.

fn try_from(value: &String) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&str> for Timestamp

Converts the string representation of a timestamp to Timestamp.

Example

let ts = Timestamp::try_from("2025-05-16T09:46:12.500Z")?;
assert_eq!(ts.seconds(), 1747388772);
assert_eq!(ts.nanos(), 500_000_000);

type Error = TimestampError

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<DateTime<Utc>> for Timestamp

Available on crate feature chrono only.

Converts from chrono::DateTime to Timestamp.

This conversion may fail if the chrono::DateTime value is out of range.

Example

use chrono::{DateTime, TimeZone, Utc};
let date : DateTime<Utc> = Utc.with_ymd_and_hms(2025, 5, 16, 10, 15, 00).unwrap();
let ts = Timestamp::try_from(date)?;
assert_eq!(String::from(ts), "2025-05-16T10:15:00Z");

type Error = TimestampError

The type returned in the event of a conversion error.

fn try_from(value: DateTime<Utc>) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<OffsetDateTime> for Timestamp

Available on crate feature time only.

Convert from time::OffsetDateTime to Timestamp.

This conversion may fail if the time::OffsetDateTime value is out of range.

Examples

use time::{macros::datetime, OffsetDateTime};
let dt = datetime!(2025-05-16 09:46:12 UTC);
let ts = Timestamp::try_from(dt)?;
assert_eq!(String::from(ts), "2025-05-16T09:46:12Z");

type Error = TimestampError

The type returned in the event of a conversion error.

fn try_from(value: OffsetDateTime) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<SystemTime> for Timestamp

Converts from std::time::SystemTime to Timestamp.

This conversion may fail if the std::time::SystemTime value is out of range.

Example

let ts = Timestamp::try_from(SystemTime::now())?;
println!("now={ts:?}");

type Error = TimestampError

The type returned in the event of a conversion error.

fn try_from(value: SystemTime) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Timestamp> for DateTime<Utc>

Available on crate feature chrono only.

Converts from Timestamp to chrono::DateTime.

Example

use chrono::{DateTime, TimeZone, Utc};
let ts = Timestamp::try_from("2025-05-16T10:15:00Z")?;
let date = DateTime::try_from(ts)?;

type Error = TimestampError

The type returned in the event of a conversion error.

fn try_from(value: Timestamp) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Timestamp> for OffsetDateTime

Available on crate feature time only.

Convert from Timestamp to OffsetDateTime

This conversion may fail if the Timestamp value is out of range.

Examples

use time::{macros::datetime, OffsetDateTime};
let ts = Timestamp::try_from("2025-05-16T09:46:12Z")?;
let dt = OffsetDateTime::try_from(ts)?;
assert_eq!(dt, datetime!(2025-05-16 09:46:12 UTC));

type Error = ComponentRange

The type returned in the event of a conversion error.

fn try_from(value: Timestamp) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Timestamp> for SystemTime

Converts from Timestamp to std::time::SystemTime.

This conversion may fail if the std::time::SystemTime value is out of range.

Example

let ts = Timestamp::new(0, 0)?;
let epoch = SystemTime::try_from(ts)?;
assert_eq!(epoch, SystemTime::UNIX_EPOCH);

type Error = TimestampError

The type returned in the event of a conversion error.

fn try_from(value: Timestamp) -> Result<SystemTime, Self::Error>

Performs the conversion.

impl Copy for Timestamp

impl StructuralPartialEq for Timestamp