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

Implements

IMessage Timestamp, IEquatable Timestamp, IDeepCloneable Timestamp, IBufferMessage, ICustomDiagnosticMessage, IMessage, IComparable Timestamp

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

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

object.Equals(object)

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

object.GetHashCode()

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

object.ToString()

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.