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

The result is a u32; the protobuf specification requires all messages to fit within 2 GiB (2,147,483,647 bytes), so a compliant message will never overflow this type.

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

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 BufMut)

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

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

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

fn encoded_len(&self) -> u32

Compute the encoded byte size of this message.

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

Encode this message as a length-delimited byte sequence.

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

Encode this message to a new Vec<u8>.

fn encode_to_bytes(&self) -> Bytes

Encode this message to a new bytes::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

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