Struct Timestamp 

pub struct Timestamp {
    pub seconds: i64,
    pub nanos: i32,
    /* private fields */
}

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](https://developers.google.com/time/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](https://www.ietf.org/rfc/rfc3339.txt) date strings.

Examples

Example 1: Compute Timestamp from POSIX time().

Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);

Example 2: Compute Timestamp from POSIX gettimeofday().

struct timeval tv;
gettimeofday(&tv, NULL);

Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);

Example 3: Compute Timestamp from Win32 GetSystemTimeAsFileTime().

FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;

// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));

Example 4: Compute Timestamp from Java System.currentTimeMillis().

long millis = System.currentTimeMillis();

Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
    .setNanos((int) ((millis % 1000) * 1000000)).build();

Example 5: Compute Timestamp from Java Instant.now().

Instant now = Instant.now();

Timestamp timestamp =
    Timestamp.newBuilder().setSeconds(now.getEpochSecond())
        .setNanos(now.getNano()).build();

Example 6: Compute Timestamp from current time in Python.

timestamp = Timestamp()
timestamp.GetCurrentTime()

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. A proto3 JSON serializer should always use UTC (as indicated by “Z”) when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset).

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

In JavaScript, one can convert a Date object to this format using the standard toISOString() method. In Python, a standard datetime.datetime object can be converted to this format using strftime with the time format spec ‘%Y-%m-%dT%H:%M:%S.%fZ’. Likewise, in Java, one can use the Joda Time’s [ISODateTimeFormat.dateTime()]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() ) to obtain a formatter capable of generating timestamps in this format.

Fields

seconds: 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.

Field 1: seconds

nanos: i32

Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.

Field 2: nanos

Implementations

impl Timestamp

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

Create a Timestamp from a Unix epoch offset.

seconds is the number of seconds since (or before, if negative) the Unix epoch. nanos must be in [0, 999_999_999].

Panics

Panics in debug mode if nanos is outside [0, 999_999_999]. In release mode the value is stored as-is, producing an invalid timestamp. Use Timestamp::from_unix_checked for a checked variant that returns None on invalid input.

pub fn from_unix_secs(seconds: i64) -> Self

Create a Timestamp from a whole number of Unix seconds (nanoseconds = 0).

This is a convenience shorthand for Timestamp::from_unix(seconds, 0).

pub fn from_unix_checked(seconds: i64, nanos: i32) -> Option<Self>

Create a Timestamp from a Unix epoch offset, returning None if nanos is outside [0, 999_999_999].

pub fn now() -> Self

Available on crate feature std only.

Return the current wall-clock time as a Timestamp.

Requires the std feature.

impl Timestamp

pub const TYPE_URL: &'static str = "type.googleapis.com/google.protobuf.Timestamp"

Protobuf type URL for this message, for use with Any::pack and Any::unpack_if.

Format: type.googleapis.com/<fully.qualified.TypeName>

Trait Implementations

impl<'arbitrary> Arbitrary<'arbitrary> for Timestamp

fn arbitrary(u: &mut Unstructured<'arbitrary>) -> Result<Self>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'arbitrary>) -> Result<Self>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

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

fn default_instance() -> &'static Self

Return a reference to the single default instance of this type.

impl<'de> Deserialize<'de> for Timestamp

Available on crate feature json only.

fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error>

Deserializes from an RFC 3339 string.

impl ExtensionSet for Timestamp

const PROTO_FQN: &'static str = "google.protobuf.Timestamp"

Fully-qualified proto type name of this message (no leading dot), e.g. "google.protobuf.FieldOptions".

fn unknown_fields(&self) -> &UnknownFields

Immutable access to the extendee’s unknown-field storage.

fn unknown_fields_mut(&mut self) -> &mut UnknownFields

Mutable access to the extendee’s unknown-field storage.

fn extension<C>(&self, ext: &Extension<C>) -> <C as ExtensionCodec>::Output

where C: ExtensionCodec,

Read an extension value.

fn set_extension<C>( &mut self, ext: &Extension<C>, value: <C as ExtensionCodec>::Value, )

where C: ExtensionCodec,

Write an extension value, replacing any prior occurrences.

fn try_set_extension<C>( &mut self, ext: &Extension<C>, value: <C as ExtensionCodec>::Value, ) -> Result<(), EncodeError>

where C: ExtensionCodec,

Write an extension value, replacing any prior occurrences — returning an error instead of panicking if a message-typed value’s encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn has_extension<C>(&self, ext: &Extension<C>) -> bool

where C: ExtensionCodec,

Returns true if any record at the extension’s field number is present.

fn clear_extension<C>(&mut self, ext: &Extension<C>)

where C: ExtensionCodec,

Remove all records at the extension’s field number.

fn extension_or_default<C>( &self, ext: &Extension<C>, ) -> <C as ExtensionCodec>::Value

where C: ExtensionCodec<Output = Option<<C as ExtensionCodec>::Value>>, <C as ExtensionCodec>::Value: Default,

Read a singular extension value, returning the proto2 [default = ...] value if absent, or the type’s Default if no proto default was declared.

impl<Tz: TimeZone> From<DateTime<Tz>> for Timestamp

Available on crate feature chrono only.

fn from(dt: DateTime<Tz>) -> Self

Convert a chrono::DateTime in any time zone to a protobuf Timestamp.

Infallible. The instant is preserved — proto Timestamp is always UTC, so the offset is folded in (a DateTime<FixedOffset> of 2023-11-15T03:13:20+05:00 and a DateTime<Utc> of 2023-11-14T22:13:20Z produce the same Timestamp).

Examples

use buffa_types::Timestamp;
use chrono::{DateTime, Utc};

let dt = DateTime::<Utc>::from_timestamp(1_700_000_000, 123_456_789).unwrap();
let ts: Timestamp = dt.into();
assert_eq!(ts.seconds, 1_700_000_000);
assert_eq!(ts.nanos, 123_456_789);

Warning: proto JSON spec range

chrono::DateTime supports years up to ~262143, while the proto JSON spec restricts Timestamp to years 0001–9999. A DateTime outside that range converts without error here, but the resulting Timestamp will fail JSON serialization (json feature).

Leap seconds

A leap-second DateTime (constructed via NaiveTime::from_hms_nano_opt(_, _, 59, 1_000_000_000)) reports timestamp_subsec_nanos() of 1_000_000_000, which exceeds the proto Timestamp.nanos upper bound of 999_999_999. The conversion clamps the nanos field to 999_999_999 — the leap second collapses to the final representable nanosecond of the same POSIX second (23:59:59.999999999).

impl From<SystemTime> for Timestamp

Available on crate feature std only.

fn from(t: SystemTime) -> Self

Convert a std::time::SystemTime to a protobuf Timestamp.

Pre-epoch times (where t < UNIX_EPOCH) are represented with a negative seconds field and a non-negative nanos field, following the protobuf convention that nanos is always in [0, 999_999_999].

Saturation

Times more than ~292 billion years from the epoch (beyond i64::MAX seconds) are saturated to i64::MAX seconds rather than wrapping, which would produce a semantically incorrect negative timestamp.

impl From<Timestamp> for Timestamp

Available on crate feature jiff only.

fn from(ts: Timestamp) -> Self

Convert a jiff::Timestamp to a protobuf Timestamp.

Infallible: every jiff::Timestamp fits the binary proto Timestamp range (proto allows any i64 second; jiff spans ≈ years -9999 through 9999, a strict subset).

Warning: proto JSON spec range

jiff::Timestamp reaches back to ≈ year -9999, but the proto JSON spec restricts Timestamp to years 0001–9999. A pre-year-1 instant converts without error here and round-trips through binary encoding, but the resulting Timestamp will fail JSON serialization (json feature), which enforces the spec range.

Sign normalization

jiff::Timestamp reports its sub-second component with the same sign as the overall instant — a pre-epoch instant has a negative subsec_nanosecond — whereas proto Timestamp.nanos is always in [0, 999_999_999]. The conversion re-normalizes by borrowing a second for negative sub-second components, so -1.5s becomes { seconds: -2, nanos: 500_000_000 }.

Examples

use buffa_types::Timestamp;

let jt = jiff::Timestamp::new(1_700_000_000, 123_456_789).unwrap();
let ts: Timestamp = jt.into();
assert_eq!(ts.seconds, 1_700_000_000);
assert_eq!(ts.nanos, 123_456_789);

impl HasMessageView for Timestamp

type View<'a> = TimestampView<'a>

The zero-copy view of Self, borrowing from a buffer with lifetime 'a.

type ViewHandle = TimestampOwnedView

The generated 'static owned-view handle for Self (FooOwnedView).

fn decode_view(buf: &[u8]) -> Result<Self::View<'_>, DecodeError>

Decode a borrowed View from a byte slice.

fn decode_view_with_options<'a>( buf: &'a [u8], opts: &DecodeOptions, ) -> Result<Self::View<'a>, DecodeError>

Decode a borrowed View under custom DecodeOptions (recursion limit, max message size, unknown-field limit).

fn decode_view_handle(bytes: Bytes) -> Result<Self::ViewHandle, DecodeError>

Decode a ViewHandle from a Bytes buffer.

fn decode_view_handle_with_options( bytes: Bytes, opts: &DecodeOptions, ) -> Result<Self::ViewHandle, DecodeError>

Decode a ViewHandle with custom DecodeOptions (recursion limit, max message size).

impl Message for Timestamp

fn compute_size(&self, _cache: &mut SizeCache) -> u32

Returns the total encoded size in bytes.

Accumulates in u64 (which cannot overflow for in-memory data) and saturates to u32 at return, so a message whose encoded size exceeds the 2 GiB protobuf limit yields a value above ::buffa::MAX_MESSAGE_BYTES that the encode entry points reject, never a silently wrapped size.

fn write_to(&self, _cache: &mut SizeCache, buf: &mut impl EncodeSink)

Write this message’s encoded bytes to a buffer, consuming nested-message sizes from cache (populated by a prior compute_size call on the same cache).

fn merge_field( &mut self, tag: Tag, buf: &mut impl Buf, ctx: DecodeContext<'_>, ) -> Result<(), DecodeError>

Processes a single already-decoded tag and its associated field data from buf.

fn clear(&mut self)

Clear all fields to their default values.

fn encode(&self, buf: &mut impl EncodeSink)

Compute size, then write. This is the primary encoding API.

fn try_encode(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError>

Encode, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn encode_with_cache(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink)

Encode using a caller-supplied SizeCache, for reuse across many encodes in a hot loop. Clears the cache first.

fn try_encode_with_cache( &self, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError>

Encode with a caller-supplied SizeCache, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES). Clears the cache first.

fn try_encode_bounded( &self, max_bytes: u32, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError>

Encode this message into buf only if its encoded size fits within max_bytes, using a single size pass that is then reused for the write.

fn try_encode_bounded_with_cache( &self, max_bytes: u32, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError>

Like try_encode_bounded but reuses an existing SizeCache, clearing it first.

fn encoded_len(&self) -> u32

Compute the encoded byte size of this message.

fn try_encoded_len(&self) -> Result<u32, EncodeError>

Compute the encoded byte size, returning an error instead of panicking if it exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn encode_length_delimited(&self, buf: &mut impl EncodeSink)

Encode this message as a length-delimited byte sequence.

fn try_encode_length_delimited( &self, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError>

Encode as a length-delimited byte sequence, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn encode_to_vec(&self) -> Vec<u8>

Encode this message to a new Vec<u8>.

fn try_encode_to_vec(&self) -> Result<Vec<u8>, EncodeError>

Encode to a new Vec<u8>, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn encode_to_bytes(&self) -> Bytes

Encode this message to a new bytes::Bytes.

fn try_encode_to_bytes(&self) -> Result<Bytes, EncodeError>

Encode to a new bytes::Bytes, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn decode(buf: &mut impl Buf) -> Result<Self, DecodeError>

where Self: Sized,

Decode a message from a buffer.

fn decode_from_slice(data: &[u8]) -> Result<Self, DecodeError>

where Self: Sized,

Decode a message from a byte slice.

fn decode_length_delimited(buf: &mut impl Buf) -> Result<Self, DecodeError>

where Self: Sized,

Decode a length-delimited message from a buffer.

fn merge_to_limit( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, limit: usize, ) -> Result<(), DecodeError>

Merge fields from a buffer until buf.remaining() reaches limit.

fn merge_group( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, field_number: u32, ) -> Result<(), DecodeError>

Merges a group-encoded message from buf, reading fields until an EndGroup tag with the given field_number is encountered.

fn merge( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, ) -> Result<(), DecodeError>

Merge fields from a buffer into this message.

fn merge_from_slice(&mut self, data: &[u8]) -> Result<(), DecodeError>

Merge fields from a byte slice into this message.

fn merge_length_delimited( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, ) -> Result<(), DecodeError>

Merge fields from a length-delimited sub-message payload into this message.

impl MessageName for Timestamp

const PACKAGE: &'static str = "google.protobuf"

The protobuf package the message is declared in.

const NAME: &'static str = "Timestamp"

The unqualified message name, with . between nesting levels.

const FULL_NAME: &'static str = "google.protobuf.Timestamp"

The fully-qualified protobuf type name with no leading dot.

const TYPE_URL: &'static str = "type.googleapis.com/google.protobuf.Timestamp"

The google.protobuf.Any.type_url form for this message.

impl PartialEq for Timestamp

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

Equality operator ==.

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

Inequality operator !=.

impl ReflectElement for Timestamp

Available on crate feature reflect only.

fn as_value_ref(&self) -> ValueRef<'_>

Borrow this element as a ValueRef.

impl ReflectMessage for Timestamp

Available on crate feature reflect only.

fn message_descriptor(&self) -> &MessageDescriptor

The descriptor for this message type.

fn pool(&self) -> &Arc<DescriptorPool>

The pool the descriptor lives in. Use this to dereference MessageIndex / EnumIndex from FieldKind, or Arc::clone it to construct sibling DynamicMessages while navigating nested fields.

fn unknown_fields(&self) -> &UnknownFields

The fields preserved from decode that the message’s descriptor does not recognize.

fn get(&self, field: &FieldDescriptor) -> ValueRef<'_>

Get a field’s value.

fn has(&self, field: &FieldDescriptor) -> bool

Whether a field is present.

fn for_each_set(&self, f: &mut dyn FnMut(&FieldDescriptor, ValueRef<'_>))

Visit every set field.

fn to_dynamic(&self) -> DynamicMessage

Snapshot this message as an owned DynamicMessage.

fn which_oneof(&self, oneof: &OneofDescriptor) -> Option<&FieldDescriptor>

Which member of oneof is set, if any.

impl Reflectable for Timestamp

Available on crate feature reflect only.

fn reflect(&self) -> ReflectCow<'_>

Vtable-mode reflective handle: borrows self directly. No encode/decode round-trip and no allocation — the reflective accessors read this message’s fields in place.

impl Serialize for Timestamp

Available on crate feature json only.

fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error>

Serializes as an RFC 3339 string (e.g. "2021-01-01T00:00:00Z").

Errors

Returns a serialization error if nanos is outside [0, 999_999_999] or if seconds is outside the proto spec range (years 0001–9999).

impl StructuralPartialEq for Timestamp

impl TextFormat for Timestamp

fn encode_text(&self, enc: &mut TextEncoder<'_>) -> Result

Write this message’s fields to enc.

fn merge_text(&mut self, dec: &mut TextDecoder<'_>) -> Result<(), ParseError>

Merge fields from dec into this message.

impl TryFrom<Timestamp> for SystemTime

Available on crate feature std only.

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

Convert a protobuf Timestamp to a std::time::SystemTime.

Errors

Returns TimestampError::InvalidNanos if nanos is outside [0, 999_999_999], or TimestampError::Overflow if the result does not fit in a std::time::SystemTime.

type Error = TimestampError

The type returned in the event of a conversion error.

impl TryFrom<Timestamp> for DateTime<Utc>

Available on crate feature chrono only.

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

Convert a protobuf Timestamp to a chrono::DateTime<Utc>.

Examples

use buffa_types::Timestamp;
use chrono::{DateTime, Utc};

let ts = Timestamp {
    seconds: 1_700_000_000,
    nanos: 0,
    ..Default::default()
};
let dt: DateTime<Utc> = ts.try_into().unwrap();
assert_eq!(dt.timestamp(), 1_700_000_000);

Errors

Returns TimestampError::InvalidNanos if nanos is outside [0, 999_999_999], or TimestampError::Overflow if the value is outside the range chrono::DateTime<Utc> can represent.

type Error = TimestampError

The type returned in the event of a conversion error.

impl TryFrom<Timestamp> for Timestamp

Available on crate feature jiff only.

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

Convert a protobuf Timestamp to a jiff::Timestamp.

Examples

use buffa_types::Timestamp;

let ts = Timestamp {
    seconds: 1_700_000_000,
    nanos: 0,
    ..Default::default()
};
let jt: jiff::Timestamp = ts.try_into().unwrap();
assert_eq!(jt.as_second(), 1_700_000_000);

Errors

Returns TimestampError::InvalidNanos if nanos is outside [0, 999_999_999], or TimestampError::Overflow if the instant is outside jiff::Timestamp’s representable range (≈ years -9999 through 9999 — proto permits a far wider second range).

type Error = TimestampError

The type returned in the event of a conversion error.