Class Timestamp

public sealed class Timestamp : object, 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
TypeNameDescription
Timestampother

Fields

NanosFieldNumber

public const int NanosFieldNumber = null

Field number for the "nanos" field.

Field Value
TypeDescription
Int32

SecondsFieldNumber

public const int SecondsFieldNumber = null

Field number for the "seconds" field.

Field Value
TypeDescription
Int32

Properties

Descriptor

public static MessageDescriptor Descriptor { get; }
Property Value
TypeDescription
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
TypeDescription
Int32

Parser

public static MessageParser<Timestamp> Parser { get; }
Property Value
TypeDescription
MessageParser<Timestamp>

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
TypeDescription
Int64

Methods

CalculateSize()

public int CalculateSize()
Returns
TypeDescription
Int32

Clone()

public Timestamp Clone()
Returns
TypeDescription
Timestamp

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
TypeNameDescription
Timestampother

Timestamp to compare

Returns
TypeDescription
Int32

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
TypeNameDescription
Timestampother
Returns
TypeDescription
Boolean

Equals(Object)

public override bool Equals(object other)
Parameter
TypeNameDescription
Objectother
Returns
TypeDescription
Boolean

FromDateTime(DateTime)

public static Timestamp FromDateTime(DateTime dateTime)

Converts the specified to a Timestamp.

Parameter
TypeNameDescription
DateTimedateTime
Returns
TypeDescription
Timestamp

The converted timestamp.

FromDateTimeOffset(DateTimeOffset)

public static Timestamp FromDateTimeOffset(DateTimeOffset dateTimeOffset)

Converts the given to a Timestamp

Parameter
TypeNameDescription
DateTimeOffsetdateTimeOffset

The date and time (with UTC offset) to convert to a timestamp.

Returns
TypeDescription
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
TypeDescription
Int32

MergeFrom(CodedInputStream)

public void MergeFrom(CodedInputStream input)
Parameter
TypeNameDescription
CodedInputStreaminput

MergeFrom(Timestamp)

public void MergeFrom(Timestamp other)
Parameter
TypeNameDescription
Timestampother

ToDateTime()

public DateTime ToDateTime()

Converts this timestamp into a .

Returns
TypeDescription
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 value precisely on a second.

ToDateTimeOffset()

public DateTimeOffset ToDateTimeOffset()

Converts this timestamp into a .

Returns
TypeDescription
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 value precisely on a second.

ToDiagnosticString()

public string ToDiagnosticString()

Returns a string representation of this Timestamp for diagnostic purposes.

Returns
TypeDescription
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
TypeDescription
String

WriteTo(CodedOutputStream)

public void WriteTo(CodedOutputStream output)
Parameter
TypeNameDescription
CodedOutputStreamoutput

Operators

Addition(Timestamp, Duration)

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

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

Parameters
TypeNameDescription
Timestamplhs

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

Durationrhs

The duration to add. Must not be null.

Returns
TypeDescription
Timestamp

The result of adding the duration to the timestamp.

Equality(Timestamp, Timestamp)

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

Returns whether two timestamps are equivalent

Parameters
TypeNameDescription
Timestampa
Timestampb
Returns
TypeDescription
Boolean

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.

GreaterThan(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
TypeNameDescription
Timestampa
Timestampb
Returns
TypeDescription
Boolean

true if a follows b

Remarks

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

GreaterThanOrEqual(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
TypeNameDescription
Timestampa
Timestampb
Returns
TypeDescription
Boolean

true if a follows b

Remarks

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

Inequality(Timestamp, Timestamp)

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

Returns whether two timestamps differ

Parameters
TypeNameDescription
Timestampa
Timestampb
Returns
TypeDescription
Boolean

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.

LessThan(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
TypeNameDescription
Timestampa
Timestampb
Returns
TypeDescription
Boolean

true if a precedes b

Remarks

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

LessThanOrEqual(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
TypeNameDescription
Timestampa
Timestampb
Returns
TypeDescription
Boolean

true if a precedes b

Remarks

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

Subtraction(Timestamp, Duration)

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

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

Parameters
TypeNameDescription
Timestamplhs

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

Durationrhs

The duration to subtract.

Returns
TypeDescription
Timestamp

The result of subtracting the duration from the timestamp.

Subtraction(Timestamp, Timestamp)

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

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

Parameters
TypeNameDescription
Timestamplhs

The timestamp to subtract from. Must not be null.

Timestamprhs

The timestamp to subtract. Must not be null.

Returns
TypeDescription
Duration

The difference between the two specified timestamps.

Explicit Interface Implementations

IBufferMessage.InternalMergeFrom(ref ParseContext)

void IBufferMessage.InternalMergeFrom(ref ParseContext input)
Parameter
TypeNameDescription
ParseContextinput

IBufferMessage.InternalWriteTo(ref WriteContext)

void IBufferMessage.InternalWriteTo(ref WriteContext output)
Parameter
TypeNameDescription
WriteContextoutput

IMessage.Descriptor

MessageDescriptor IMessage.Descriptor { get; }
Returns
TypeDescription
MessageDescriptor

Implements

IEquatable<>
IComparable<>