Class Duration (3.27.1)

public sealed class Duration : IMessage<Duration>, IEquatable<Duration>, IDeepCloneable<Duration>, IBufferMessage, ICustomDiagnosticMessage, IMessage, IComparable<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

object > Duration

Namespace

Google.Protobuf.WellKnownTypes

Assembly

Google.Protobuf.dll

Constructors

Duration()

public Duration()

Duration(Duration)

public Duration(Duration other)
Parameter
Name Description
other Duration

Fields

MaxSeconds

public const long MaxSeconds = 315576000000

The maximum permitted number of seconds.

Field Value
Type Description
long

MinSeconds

public const long MinSeconds = -315576000000

The minimum permitted number of seconds.

Field Value
Type Description
long

NanosFieldNumber

public const int NanosFieldNumber = 2

Field number for the "nanos" field.

Field Value
Type Description
int

NanosecondsPerSecond

public const int NanosecondsPerSecond = 1000000000

The number of nanoseconds in a second.

Field Value
Type Description
int

NanosecondsPerTick

public const int NanosecondsPerTick = 100

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

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; }

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.

Property Value
Type Description
int

Parser

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

Seconds

public long Seconds { get; set; }

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

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

Creates a deep clone of this object.

Returns
Type Description
Duration

A deep clone of this object.

CompareTo(Duration)

public int CompareTo(Duration other)

Given another duration, returns 0 if the durations are equivalent, -1 if this duration is shorter than the other, and 1 otherwise.

Parameter
Name Description
other Duration

The duration to compare with this object.
Returns
Type Description
int

An integer indicating whether this duration is shorter or longer than other.
Remarks

This method expects that both durations are normalized; that is, that the values of Seconds and Nanos are within the documented bounds. If either value is not normalized, the results of this method are unspecified.

Equals(Duration)

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

Equals(object)

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

FromTimeSpan(TimeSpan)

public static Duration FromTimeSpan(TimeSpan timeSpan)

Converts the given TimeSpan to a Duration.

Parameter
Name Description
timeSpan TimeSpan

The TimeSpan to convert.
Returns
Type Description
Duration

The value of the given TimeSpan, as a Duration.

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

public void MergeFrom(Duration other)

Merges the given message into this one.

Parameter
Name Description
other Duration
Remarks

See the user guide for precise merge semantics.

ToDiagnosticString()

public string ToDiagnosticString()

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

ToTimeSpan()

public TimeSpan ToTimeSpan()

Converts this Duration to a TimeSpan.

Returns
Type Description
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 Description
InvalidOperationException

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

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

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

Adds the two specified Duration values together.

Parameters
Name Description
lhs Duration

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

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

operator -(Duration, Duration)

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

Subtracts one Duration from another.

Parameters
Name Description
lhs Duration

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

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

The difference between the two specified durations.

operator -(Duration)

public static Duration operator -(Duration value)

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

Parameter
Name Description
value Duration

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

The negated value of this duration.

Extension Methods