Class Duration

A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years.

Examples

Example 1: Compute Duration from two Timestamps in pseudo code.

Timestamp start = ...; Timestamp end = ...; Duration duration = ...;

duration.seconds = end.seconds - start.seconds; duration.nanos = end.nanos - start.nanos;

if (duration.seconds < 0 && duration.nanos > 0) { duration.seconds += 1; duration.nanos -= 1000000000; } else if (duration.seconds > 0 && duration.nanos < 0) { duration.seconds -= 1; duration.nanos += 1000000000; }

Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.

Timestamp start = ...; Duration duration = ...; Timestamp end = ...;

end.seconds = start.seconds + duration.seconds; end.nanos = start.nanos + duration.nanos;

if (end.nanos < 0) { end.seconds -= 1; end.nanos += 1000000000; } else if (end.nanos >= 1000000000) { end.seconds += 1; end.nanos -= 1000000000; }

Example 3: Compute Duration from datetime.timedelta in Python.

td = datetime.timedelta(days=3, minutes=10) duration = Duration() duration.FromTimedelta(td)

JSON Mapping

In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s".

Inheritance
System.Object
Duration
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 Duration : IMessage<Duration>, IEquatable<Duration>, IDeepCloneable<Duration>, ICustomDiagnosticMessage, IMessage

Constructors

Duration()

Declaration
public Duration()

Duration(Duration)

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

Fields

MaxSeconds

The maximum permitted number of seconds.

Declaration
public const long MaxSeconds = 315576000000L
Field Value
Type Description
System.Int64

MinSeconds

The minimum permitted number of seconds.

Declaration
public const long MinSeconds = -315576000000L
Field Value
Type Description
System.Int64

NanosecondsPerSecond

The number of nanoseconds in a second.

Declaration
public const int NanosecondsPerSecond = 1000000000
Field Value
Type Description
System.Int32

NanosecondsPerTick

The number of nanoseconds in a BCL tick (as used by System.TimeSpan and System.DateTime).

Declaration
public const int NanosecondsPerTick = 100
Field Value
Type Description
System.Int32

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

Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 seconds field and a positive or negative nanos field. For durations of one second or more, a non-zero value for the nanos field must be of the same sign as the seconds field. Must be from -999,999,999 to +999,999,999 inclusive.

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

Parser

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

Seconds

Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

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 Duration Clone()
Returns
Type Description
Duration
Implements

Equals(Duration)

Declaration
public bool Equals(Duration other)
Parameters
Type Name Description
Duration 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)

FromTimeSpan(TimeSpan)

Converts the given System.TimeSpan to a Duration.

Declaration
public static Duration FromTimeSpan(TimeSpan timeSpan)
Parameters
Type Name Description
System.TimeSpan timeSpan

The TimeSpan to convert.
Returns
Type Description
Duration

The value of the given TimeSpan, as a Duration.

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(Duration)

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

ToDiagnosticString()

Returns a string representation of this Duration 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()

ToTimeSpan()

Converts this Duration to a System.TimeSpan.

Declaration
public TimeSpan ToTimeSpan()
Returns
Type Description
System.TimeSpan

The value of this duration, as a TimeSpan.
Remarks

If the duration is not a precise number of ticks, it is truncated towards 0.

Exceptions
Type Condition
System.InvalidOperationException

This value isn't a valid normalized duration, as described in the documentation.

WriteTo(CodedOutputStream)

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

Operators

Addition(Duration, Duration)

Adds the two specified Duration values together.

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

The first value to add. Must not be null.
Duration rhs

The second value to add. Must not be null.
Returns
Type Description
Duration

Subtraction(Duration, Duration)

Subtracts one Duration from another.

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

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

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

The difference between the two specified durations.

UnaryNegation(Duration)

Returns the result of negating the duration. For example, the negation of 5 minutes is -5 minutes.

Declaration
public static Duration operator -(Duration value)
Parameters
Type Name Description
Duration value

The duration to negate. Must not be null.
Returns
Type Description
Duration

The negated value of this duration.

Explicit Interface Implementations

IMessage.Descriptor

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

Extension Methods