Google.Protobuf.WellKnownTypes.Timestamp

A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.

Summary

It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. 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. See https://www.ietf.org/rfc/rfc3339.txt.

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 current time in Python.

timestamp = Timestamp()
timestamp.GetCurrentTime()

Inheritance

Inherits from: Google.Protobuf.ICustomDiagnosticMessage, pb::IMessage< Timestamp >

Constructors and Destructors

Timestamp()
Timestamp(Timestamp other)

Properties

Descriptor
pbr::MessageDescriptor
Descriptor
pbr::MessageDescriptor pb::IMessage.
Nanos
int
Non-negative fractions of a second at nanosecond resolution.
Parser
pb::MessageParser< Timestamp >
Seconds
long
Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z.

Public attributes

NanosFieldNumber = 2
const int
Field number for the "nanos" field.
SecondsFieldNumber = 1
const int
Field number for the "seconds" field.

Public functions

CalculateSize()
int
Calculates the size of this message in Protocol Buffer wire format, in bytes.
Clone()
Equals(object other)
override bool
Equals(Timestamp other)
bool
GetHashCode()
override int
MergeFrom(Timestamp other)
void
MergeFrom(pb::CodedInputStream input)
void
ToDateTime()
DateTime
Converts this timestamp into a DateTime.
ToDateTimeOffset()
DateTimeOffset
Converts this timestamp into a DateTimeOffset.
ToDiagnosticString()
string
Returns a string representation of this Timestamp for diagnostic purposes.
ToString()
override string
WriteTo(pb::CodedOutputStream output)
void

Public static functions

FromDateTime(DateTime dateTime)
Converts the specified DateTime to a Timestamp.
FromDateTimeOffset(DateTimeOffset dateTimeOffset)
Converts the given DateTimeOffset to a Timestamp
operator+(Timestamp lhs, Duration rhs)
Adds a Duration to a Timestamp, to obtain another Timestamp.
operator-(Timestamp lhs, Timestamp rhs)
Returns the difference between one Timestamp and another, as a Duration.
operator-(Timestamp lhs, Duration rhs)
Subtracts a Duration from a Timestamp, to obtain another Timestamp.

Properties

Descriptor

pbr::MessageDescriptor Descriptor

Descriptor

pbr::MessageDescriptor pb::IMessage. Descriptor

Nanos

int Nanos

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.

Parser

pb::MessageParser< Timestamp > Parser

Seconds

long Seconds

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.

Public attributes

NanosFieldNumber

const int NanosFieldNumber = 2

Field number for the "nanos" field.

SecondsFieldNumber

const int SecondsFieldNumber = 1

Field number for the "seconds" field.

Public functions

CalculateSize

int CalculateSize()

Calculates the size of this message in Protocol Buffer wire format, in bytes.

Details
Returns
The number of bytes required to write this message to a coded output stream.

Clone

Timestamp Clone()

Equals

override bool Equals(
  object other
)

Equals

bool Equals(
  Timestamp other
)

GetHashCode

override int GetHashCode()

MergeFrom

void MergeFrom(
  Timestamp other
)

MergeFrom

void MergeFrom(
  pb::CodedInputStream input
)

Timestamp

 Timestamp()

Timestamp

 Timestamp(
  Timestamp other
)

ToDateTime

DateTime ToDateTime()

Converts this timestamp into a DateTime.

The resulting DateTime will always have a Kind of Utc. If the timestamp is not a precise number of ticks, it will be truncated towards the start of time. For example, a timestamp with a Nanos value of 99 will result in a DateTime value precisely on a second.

Details
Exceptions
InvalidOperationException
The timestamp contains invalid values; either it is incorrectly normalized or is outside the valid range.
Returns
This timestamp as a DateTime.

ToDateTimeOffset

DateTimeOffset ToDateTimeOffset()

Converts this timestamp into a DateTimeOffset.

The resulting DateTimeOffset will always have an Offset of zero. If the timestamp is not a precise number of ticks, it will be truncated towards the start of time. For example, a timestamp with a Nanos value of 99 will result in a DateTimeOffset value precisely on a second.

Details
Exceptions
InvalidOperationException
The timestamp contains invalid values; either it is incorrectly normalized or is outside the valid range.
Returns
This timestamp as a DateTimeOffset.

ToDiagnosticString

string ToDiagnosticString()

Returns a string representation of this Timestamp for diagnostic purposes.

Normally the returned value will be a JSON string value (including leading and trailing quotes) but when the value is non-normalized or out of range, a JSON object representation will be returned instead, including a warning. This is to avoid exceptions being thrown when trying to diagnose problems - the regular JSON formatter will still throw an exception for non-normalized values.

Details
Returns
A string representation of this value.

ToString

override string ToString()

WriteTo

void WriteTo(
  pb::CodedOutputStream output
)

Public static functions

FromDateTime

Timestamp FromDateTime(
  DateTime dateTime
)

Converts the specified DateTime to a Timestamp.

Details
Parameters
dateTime
Exceptions
ArgumentException
The Kind of dateTime is not DateTimeKind.Utc.
Returns
The converted timestamp.

FromDateTimeOffset

Timestamp FromDateTimeOffset(
  DateTimeOffset dateTimeOffset
)

Converts the given DateTimeOffset to a Timestamp

The offset is taken into consideration when converting the value (so the same instant in time is represented) but is not a separate part of the resulting value. In other words, there is no roundtrip operation to retrieve the original DateTimeOffset.

Details
Parameters
dateTimeOffset
The date and time (with UTC offset) to convert to a timestamp.
Returns
The converted timestamp.

operator+

Timestamp operator+(
  Timestamp lhs,
  Duration rhs
)

Adds a Duration to a Timestamp, to obtain another Timestamp.

Details
Parameters
lhs
The timestamp to add the duration to. Must not be null.
rhs
The duration to add. Must not be null.
Returns
The result of adding the duration to the timestamp.

operator-

Duration operator-(
  Timestamp lhs,
  Timestamp rhs
)

Returns the difference between one Timestamp and another, as a Duration.

Details
Parameters
lhs
The timestamp to subtract from. Must not be null.
rhs
The timestamp to subtract. Must not be null.
Returns
The difference between the two specified timestamps.

operator-

Timestamp operator-(
  Timestamp lhs,
  Duration rhs
)

Subtracts a Duration from a Timestamp, to obtain another Timestamp.

Details
Parameters
lhs
The timestamp to subtract the duration from. Must not be null.
rhs
The duration to subtract.
Returns
The result of subtracting the duration from the timestamp.