Class 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 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
System.Object
Timestamp
Implements
System.IEquatable<Timestamp>
System.IComparable<Timestamp>
Inherited Members
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Google.Protobuf.WellKnownTypes
Assembly: Google.Protobuf.dll
Syntax
public sealed class Timestamp : IMessage<Timestamp>, IEquatable<Timestamp>, IDeepCloneable<Timestamp>, ICustomDiagnosticMessage, IMessage, IComparable<Timestamp>

Constructors

Timestamp()

Declaration
public Timestamp()

Timestamp(Timestamp)

Declaration
public Timestamp(Timestamp other)
Parameters
Type Name Description
Timestamp other

Fields

NanosFieldNumber

Field number for the "nanos" field.

Declaration
public const int NanosFieldNumber = 2
Field Value
Type Description
System.Int32

SecondsFieldNumber

Field number for the "seconds" field.

Declaration
public const int SecondsFieldNumber = 1
Field Value
Type Description
System.Int32

Properties

Descriptor

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

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.

Declaration
public int Nanos { get; set; }
Property Value
Type Description
System.Int32

Parser

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

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.

Declaration
public long Seconds { get; set; }
Property Value
Type Description
System.Int64

Methods

CalculateSize()

Declaration
public int CalculateSize()
Returns
Type Description
System.Int32
Implements

Clone()

Declaration
public Timestamp Clone()
Returns
Type Description
Timestamp
Implements

CompareTo(Timestamp)

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

Declaration
public int CompareTo(Timestamp other)
Parameters
Type Name Description
Timestamp other

Timestamp to compare
Returns
Type Description
System.Int32

an integer indicating whether this timestamp precedes or follows the other
Implements
System.IComparable<T>.CompareTo(T)
Remarks

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

Equals(Timestamp)

Declaration
public bool Equals(Timestamp other)
Parameters
Type Name Description
Timestamp other
Returns
Type Description
System.Boolean
Implements
System.IEquatable<T>.Equals(T)

Equals(Object)

Declaration
public override bool Equals(object other)
Parameters
Type Name Description
System.Object other
Returns
Type Description
System.Boolean
Overrides
System.Object.Equals(System.Object)

FromDateTime(DateTime)

Converts the specified System.DateTime to a Timestamp.

Declaration
public static Timestamp FromDateTime(DateTime dateTime)
Parameters
Type Name Description
System.DateTime dateTime
Returns
Type Description
Timestamp

The converted timestamp.
Exceptions
Type Condition
System.ArgumentException

The Kind of dateTime is not DateTimeKind.Utc.

FromDateTimeOffset(DateTimeOffset)

Converts the given System.DateTimeOffset to a Timestamp

Declaration
public static Timestamp FromDateTimeOffset(DateTimeOffset dateTimeOffset)
Parameters
Type Name Description
System.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()

Declaration
public override int GetHashCode()
Returns
Type Description
System.Int32
Overrides
System.Object.GetHashCode()

MergeFrom(CodedInputStream)

Declaration
public void MergeFrom(CodedInputStream input)
Parameters
Type Name Description
CodedInputStream input
Implements

MergeFrom(Timestamp)

Declaration
public void MergeFrom(Timestamp other)
Parameters
Type Name Description
Timestamp other
Implements

ToDateTime()

Converts this timestamp into a System.DateTime.

Declaration
public DateTime ToDateTime()
Returns
Type Description
System.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 System.DateTime value precisely on a second.

Exceptions
Type Condition
System.InvalidOperationException

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

ToDateTimeOffset()

Converts this timestamp into a System.DateTimeOffset.

Declaration
public DateTimeOffset ToDateTimeOffset()
Returns
Type Description
System.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 System.DateTimeOffset value precisely on a second.

Exceptions
Type Condition
System.InvalidOperationException

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

ToDiagnosticString()

Returns a string representation of this Timestamp for diagnostic purposes.

Declaration
public string ToDiagnosticString()
Returns
Type Description
System.String

A string representation of this value.
Implements
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()

Declaration
public override string ToString()
Returns
Type Description
System.String
Overrides
System.Object.ToString()

WriteTo(CodedOutputStream)

Declaration
public void WriteTo(CodedOutputStream output)
Parameters
Type Name Description
CodedOutputStream output
Implements

Operators

Addition(Timestamp, Duration)

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

Declaration
public static Timestamp operator +(Timestamp lhs, Duration rhs)
Parameters
Type Name Description
Timestamp lhs

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

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

The result of adding the duration to the timestamp.

Equality(Timestamp, Timestamp)

Returns whether two timestamps are equivalent

Declaration
public static bool operator ==(Timestamp a, Timestamp b)
Parameters
Type Name Description
Timestamp a
Timestamp b
Returns
Type Description
System.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)

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

Declaration
public static bool operator>(Timestamp a, Timestamp b)
Parameters
Type Name Description
Timestamp a
Timestamp b
Returns
Type Description
System.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)

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

Declaration
public static bool operator >=(Timestamp a, Timestamp b)
Parameters
Type Name Description
Timestamp a
Timestamp b
Returns
Type Description
System.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)

Returns whether two timestamps differ

Declaration
public static bool operator !=(Timestamp a, Timestamp b)
Parameters
Type Name Description
Timestamp a
Timestamp b
Returns
Type Description
System.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)

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

Declaration
public static bool operator <(Timestamp a, Timestamp b)
Parameters
Type Name Description
Timestamp a
Timestamp b
Returns
Type Description
System.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)

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

Declaration
public static bool operator <=(Timestamp a, Timestamp b)
Parameters
Type Name Description
Timestamp a
Timestamp b
Returns
Type Description
System.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)

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

Declaration
public static Timestamp operator -(Timestamp lhs, Duration rhs)
Parameters
Type Name Description
Timestamp lhs

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

The duration to subtract.
Returns
Type Description
Timestamp

The result of subtracting the duration from the timestamp.

Subtraction(Timestamp, Timestamp)

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

Declaration
public static Duration operator -(Timestamp lhs, Timestamp rhs)
Parameters
Type Name Description
Timestamp lhs

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

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

The difference between the two specified timestamps.

Explicit Interface Implementations

IMessage.Descriptor

Declaration
MessageDescriptor IMessage.Descriptor { get; }
Returns
Type Description
MessageDescriptor
Implements

Extension Methods