Class Timestamp (3.23.0) 

public sealed class Timestamp : IMessage<Timestamp>, IEquatable<Timestamp>, IDeepCloneable<Timestamp>, IBufferMessage, ICustomDiagnosticMessage, IMessage, IComparable<Timestamp>

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.

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() to obtain a formatter capable of generating timestamps in this format.

Inheritance

object > Timestamp

Namespace

Google.Protobuf.WellKnownTypes

Assembly

Google.Protobuf.dll

Constructors

Timestamp()

public Timestamp()

Timestamp(Timestamp)

public Timestamp(Timestamp other)
Parameter
Name Description
other Timestamp

Fields

NanosFieldNumber

public const int NanosFieldNumber = 2

Field number for the "nanos" field.

Field Value
Type Description
int

SecondsFieldNumber

public const int SecondsFieldNumber = 1

Field number for the "seconds" field.

Field Value
Type Description
int

Properties

Descriptor

public static MessageDescriptor Descriptor { get; }
Property Value
Type Description
MessageDescriptor

Nanos

public int Nanos { get; set; }

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.

Property Value
Type Description
int

Parser

public static MessageParser<Timestamp> Parser { get; }
Property Value
Type Description
MessageParserTimestamp

Seconds

public long Seconds { get; set; }

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.

Property Value
Type Description
long

Methods

CalculateSize()

public int CalculateSize()

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

Returns
Type Description
int

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

Clone()

public Timestamp Clone()

Creates a deep clone of this object.

Returns
Type Description
Timestamp

A deep clone of this object.

CompareTo(Timestamp)

public int CompareTo(Timestamp other)

Given another timestamp, returns 0 if the timestamps are equivalent, -1 if this timestamp precedes the other, and 1 otherwise

Parameter
Name Description
other Timestamp

Timestamp to compare
Returns
Type Description
int

an integer indicating whether this timestamp precedes or follows the other
Remarks

Make sure the timestamps are normalized. Comparing non-normalized timestamps is not specified and may give unexpected results.

Equals(Timestamp)

public bool Equals(Timestamp other)
Parameter
Name Description
other Timestamp
Returns
Type Description
bool

Equals(object)

public override bool Equals(object other)
Parameter
Name Description
other object
Returns
Type Description
bool
Overrides

FromDateTime(DateTime)

public static Timestamp FromDateTime(DateTime dateTime)

Converts the specified DateTime to a Timestamp.

Parameter
Name Description
dateTime DateTime
Returns
Type Description
Timestamp

The converted timestamp.
Exceptions
Type Description
ArgumentException

The Kind of dateTime is not DateTimeKind.Utc.

FromDateTimeOffset(DateTimeOffset)

public static Timestamp FromDateTimeOffset(DateTimeOffset dateTimeOffset)

Converts the given DateTimeOffset to a Timestamp

Parameter
Name Description
dateTimeOffset DateTimeOffset

The date and time (with UTC offset) to convert to a timestamp.
Returns
Type Description
Timestamp

The converted timestamp.
Remarks

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.

GetHashCode()

public override int GetHashCode()
Returns
Type Description
int
Overrides

MergeFrom(CodedInputStream)

public void MergeFrom(CodedInputStream input)

Merges the data from the specified coded input stream with the current message.

Parameter
Name Description
input CodedInputStream
Remarks

See the user guide for precise merge semantics.

MergeFrom(Timestamp)

public void MergeFrom(Timestamp other)

Merges the given message into this one.

Parameter
Name Description
other Timestamp
Remarks

See the user guide for precise merge semantics.

ToDateTime()

public DateTime ToDateTime()

Converts this timestamp into a DateTime.

Returns
Type Description
DateTime

This timestamp as a DateTime.
Remarks

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.

Exceptions
Type Description
InvalidOperationException

The timestamp contains invalid values; either it is incorrectly normalized or is outside the valid range.

ToDateTimeOffset()

public DateTimeOffset ToDateTimeOffset()

Converts this timestamp into a DateTimeOffset.

Returns
Type Description
DateTimeOffset

This timestamp as a DateTimeOffset.
Remarks

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.

Exceptions
Type Description
InvalidOperationException

The timestamp contains invalid values; either it is incorrectly normalized or is outside the valid range.

ToDiagnosticString()

public string ToDiagnosticString()

Returns a string representation of this Timestamp for diagnostic purposes.

Returns
Type Description
string

A string representation of this value.
Remarks

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.

ToString()

public override string ToString()
Returns
Type Description
string
Overrides

WriteTo(CodedOutputStream)

public void WriteTo(CodedOutputStream output)

Writes the data to the given coded output stream.

Parameter
Name Description
output CodedOutputStream

Coded output stream to write the data to. Must not be null.

Operators

operator +(Timestamp, Duration)

public static Timestamp operator +(Timestamp lhs, Duration rhs)

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

Parameters
Name Description
lhs Timestamp

The timestamp to add the duration to. Must not be null.
rhs Duration

The duration to add. Must not be null.
Returns
Type Description
Timestamp

The result of adding the duration to the timestamp.

operator ==(Timestamp, Timestamp)

public static bool operator ==(Timestamp a, Timestamp b)

Returns whether two timestamps are equivalent

Parameters
Name Description
a Timestamp
b Timestamp
Returns
Type Description
bool

true if the two timestamps refer to the same nanosecond
Remarks

Make sure the timestamps are normalized. Comparing non-normalized timestamps is not specified and may give unexpected results.

operator >(Timestamp, Timestamp)

public static bool operator >(Timestamp a, Timestamp b)

Compares two timestamps and returns whether the first is greater than (chronologically follows) the second

Parameters
Name Description
a Timestamp
b Timestamp
Returns
Type Description
bool

true if a follows b
Remarks

Make sure the timestamps are normalized. Comparing non-normalized timestamps is not specified and may give unexpected results.

operator >=(Timestamp, Timestamp)

public static bool operator >=(Timestamp a, Timestamp b)

Compares two timestamps and returns whether the first is greater than (chronologically follows) the second

Parameters
Name Description
a Timestamp
b Timestamp
Returns
Type Description
bool

true if a follows b
Remarks

Make sure the timestamps are normalized. Comparing non-normalized timestamps is not specified and may give unexpected results.

operator !=(Timestamp, Timestamp)

public static bool operator !=(Timestamp a, Timestamp b)

Returns whether two timestamps differ

Parameters
Name Description
a Timestamp
b Timestamp
Returns
Type Description
bool

true if the two timestamps differ
Remarks

Make sure the timestamps are normalized. Comparing non-normalized timestamps is not specified and may give unexpected results.

operator <(Timestamp, Timestamp)

public static bool operator <(Timestamp a, Timestamp b)

Compares two timestamps and returns whether the first is less than (chronologically precedes) the second

Parameters
Name Description
a Timestamp
b Timestamp
Returns
Type Description
bool

true if a precedes b
Remarks

Make sure the timestamps are normalized. Comparing non-normalized timestamps is not specified and may give unexpected results.

operator <=(Timestamp, Timestamp)

public static bool operator <=(Timestamp a, Timestamp b)

Compares two timestamps and returns whether the first is less than (chronologically precedes) the second

Parameters
Name Description
a Timestamp
b Timestamp
Returns
Type Description
bool

true if a precedes b
Remarks

Make sure the timestamps are normalized. Comparing non-normalized timestamps is not specified and may give unexpected results.

operator -(Timestamp, Duration)

public static Timestamp operator -(Timestamp lhs, Duration rhs)

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

Parameters
Name Description
lhs Timestamp

The timestamp to subtract the duration from. Must not be null.
rhs Duration

The duration to subtract.
Returns
Type Description
Timestamp

The result of subtracting the duration from the timestamp.

operator -(Timestamp, Timestamp)

public static Duration operator -(Timestamp lhs, Timestamp rhs)

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

Parameters
Name Description
lhs Timestamp

The timestamp to subtract from. Must not be null.
rhs Timestamp

The timestamp to subtract. Must not be null.
Returns
Type Description
Duration

The difference between the two specified timestamps.

Extension Methods