Early Preview
This is currently very much a preview. Please feel free to try things out,
but don't be upset if anything is not yet working. Feedback is welcome over on our
GitHub Dicussions page.
struct NodaTime.Duration
Assembly: NodaTime
Implemented Interfaces
- System.IEquatable`1
- System.IComparable`1
- System.IComparable
- System.Xml.Serialization.IXmlSerializable
- System.IFormattable
- System.Numerics.IAdditionOperators`3
- System.Numerics.ISubtractionOperators`3
- System.Numerics.IUnaryNegationOperators`2
- System.Numerics.IUnaryPlusOperators`2
- System.Numerics.IComparisonOperators`3 (Inherits: IEqualityOperators<NodaTime.Duration, NodaTime.Duration, bool>)
- System.Numerics.IMinMaxValue`1
- System.Numerics.IAdditiveIdentity`2
Represents a fixed (and calendar-independent) length of time.
Remarks
<para>
A duration is a length of time defined by an integral number of nanoseconds.
Although durations are usually used with a positive number of nanoseconds, negative durations are valid, and may occur
naturally when e.g. subtracting a later <see cref="T:NodaTime.Instant" /> from an earlier one.
</para> <para>Equality and ordering are defined in the natural way, simply comparing the number of nanoseconds contained.</para> <para>
A duration represents a fixed length of elapsed time along the time line that occupies the same amount of
time regardless of when it is applied. In contrast, <see cref="T:NodaTime.Period" /> represents a period of time in
calendrical terms (years, months, days, and so on) that may vary in elapsed time when applied.
</para> <para>
In general, use <see cref="T:NodaTime.Duration" /> to represent durations applied to global types like <see cref="T:NodaTime.Instant" />
and <see cref="T:NodaTime.ZonedDateTime" />; use <c>Period</c> to represent a period applied to local types like
<see cref="T:NodaTime.LocalDateTime" />.
</para> <para>
The range of valid values of a <c>Duration</c> is greater than the span of time supported by Noda Time - so for
example, subtracting one <see cref="T:NodaTime.Instant" /> from another will always give a valid <c>Duration</c>. The range
is also greater than that of <see cref="T:System.TimeSpan" /> (<see cref="F:System.Int64.MinValue" /> ticks to <see cref="F:System.Int64.MaxValue" /> ticks).
See the user guide for more details of the exact range, but it is not expected that this will ever be exceeded in normal code.
</para> <para>
Various operations accept or return a <see cref="T:System.Double" />, in-keeping with durations often being natural lengths
of time which are imprecisely measured anyway. The implementation of these operations should never result in a not-a-number
or infinite value, nor do any operations accept not-a-number or infinite values. Additionally, operations involving
<c>Double</c> have initially been implemented fairly naively; it's possible that future releases will improve the accuracy
or performance (or both) of various operations.
</para> <para>The default value of this type is <see cref="P:NodaTime.Duration.Zero" />.</para>
Properties
public static
Duration
Zero
Gets a zero <see cref="T:NodaTime.Duration" /> of 0 nanoseconds.
public static
Duration
AdditiveIdentity
Gets the additive identity.
public static
Duration
Epsilon
Gets a <see cref="T:NodaTime.Duration" /> value equal to 1 nanosecond; the smallest amount by which an instant can vary.
public static
Duration
MaxValue
Gets the maximum value supported by <see cref="T:NodaTime.Duration" /> .
public static
Duration
MinValue
Gets the minimum (largest negative) value supported by <see cref="T:NodaTime.Duration" /> .
public
int
Days
Gets the whole number of standard (24 hour) days within this duration. This is truncated towards zero;
for example, "-1.75 days" and "1.75 days" would have results of -1 and 1 respectively.
public
long
NanosecondOfDay
Gets the number of nanoseconds within the day of this duration. For negative durations, this
will be negative (or zero).
public
int
Hours
The hour component of this duration, in the range [-23, 23], truncated towards zero.
public
int
Minutes
The minute component of this duration, in the range [-59, 59], truncated towards zero.
public
int
Seconds
Gets the second component of this duration, in the range [-59, 59], truncated towards zero.
public
int
Milliseconds
Gets the subsecond component of this duration, expressed in milliseconds, in the range [-999, 999] and truncated towards zero.
public
int
SubsecondTicks
Gets the subsecond component of this duration, expressed in ticks, in the range [-9999999, 9999999] and truncated towards zero.
public
int
SubsecondNanoseconds
Gets the subsecond component of this duration, expressed in nanoseconds, in the range [-999999999, 999999999].
public
long
BclCompatibleTicks
Gets the total number of ticks in the duration as a 64-bit integer, truncating towards zero where necessary.
Remarks <para>
Within the constraints specified below, this property is intended to be equivalent to
<see cref="P:System.TimeSpan.Ticks" />.
</para> <para>
If the number of nanoseconds in a duration is not a whole number of ticks, it is truncated towards zero.
For example, durations in the range [-99ns, 99ns] would all count as 0 ticks.
</para> <para>Although this method can overflow, it will only do so in very exceptional cases, with durations
with a magnitude of more than 29000 Gregorian years or so.</para>
public
double
TotalDays
Gets the total number of days in this duration, as a <see cref="T:System.Double" /> .
Remarks This property is the <c>Duration</c> equivalent of <see cref="P:System.TimeSpan.TotalDays" /> .
It represents the complete duration in days, rather than only the whole number of
days. For example, for a duration of 36 hours, this property would return 1.5.
public
double
TotalHours
Gets the total number of hours in this duration, as a <see cref="T:System.Double" /> .
Remarks This property is the <c>Duration</c> equivalent of <see cref="P:System.TimeSpan.TotalHours" /> .
Unlike <see cref="P:NodaTime.Duration.Hours" /> , it represents the complete duration in hours rather than the
whole number of hours as part of the day. So for a duration
of 1 day, 2 hours and 30 minutes, the <c>Hours</c> property will return 2, but <c>TotalHours</c>
will return 26.5.
public
double
TotalMinutes
Gets the total number of minutes in this duration, as a <see cref="T:System.Double" /> .
Remarks This property is the <c>Duration</c> equivalent of <see cref="P:System.TimeSpan.TotalMinutes" /> .
Unlike <see cref="P:NodaTime.Duration.Minutes" /> , it represents the complete duration in minutes rather than
the whole number of minutes within the hour. So for a duration
of 2 hours, 30 minutes and 45 seconds, the <c>Minutes</c> property will return 30, but <c>TotalMinutes</c>
will return 150.75.
public
double
TotalSeconds
Gets the total number of seconds in this duration, as a <see cref="T:System.Double" /> .
Remarks This property is the <c>Duration</c> equivalent of <see cref="P:System.TimeSpan.TotalSeconds" /> .
Unlike <see cref="P:NodaTime.Duration.Seconds" /> , it represents the complete duration in seconds rather than
the whole number of seconds within the minute. So for a duration
of 10 minutes, 20 seconds and 250 milliseconds, the <c>Seconds</c> property will return 20, but <c>TotalSeconds</c>
will return 620.25.
public
double
TotalMilliseconds
Gets the total number of milliseconds in this duration, as a <see cref="T:System.Double" /> .
Remarks This property is the <c>Duration</c> equivalent of <see cref="P:System.TimeSpan.TotalMilliseconds" /> .
Unlike <see cref="P:NodaTime.Duration.Milliseconds" /> , it represents the complete duration in milliseconds rather than
the whole number of milliseconds within the second. So for a duration
of 10 minutes, 20 seconds and 250 milliseconds, the <c>Milliseconds</c> property will return 250, but <c>TotalMilliseconds</c>
will return 620250.
public
double
TotalTicks
Gets the total number of ticks in this duration, as a <see cref="T:System.Double" /> .
Remarks This property is the <c>Duration</c> equivalent of <see cref="P:System.TimeSpan.Ticks" /> ,
except represented as double-precision floating point number instead of a 64-bit integer. This
is because <see cref="T:NodaTime.Duration" /> has a precision of nanoseconds, and also because the range
of 64-bit integers doesn't cover the number of possible ticks in a <see cref="T:NodaTime.Duration" /> . (The
latter is only an issue in durations outside the range of <see cref="T:System.TimeSpan" /> - in other words,
with magnitudes of over 29,000 years.)
public
double
TotalNanoseconds
Gets the total number of nanoseconds in this duration, as a <see cref="T:System.Double" /> .
Remarks The result is always an integer, but may not be precise due to the limitations
of the <c>Double</c> type. In other works, <c>Duration.FromNanoseconds(duration.TotalNanoseconds)</c>
is not guaranteed to round-trip. To guarantee precision and round-tripping,
use <see cref="M:NodaTime.Duration.ToBigIntegerNanoseconds" /> and <see cref="M:NodaTime.Duration.FromNanoseconds(System.Numerics.BigInteger)" />
(or the <c>Int128</c> equivalents where available).
Methods
public
bool
Equals(object obj)
Determines whether the specified <see cref="T:System.Object" /> is equal to this instance.
See the type documentation for a description of equality semantics.
Returns <c>true</c> if the specified <see cref="T:System.Object" /> is equal to this instance;
otherwise, <c>false</c> .
obj
The <see cref="T:System.Object" /> to compare with this instance.
public
int
GetHashCode()
Returns a hash code for this instance.
See the type documentation for a description of equality semantics.
Returns A hash code for this instance, suitable for use in hashing algorithms and data
structures like a hash table.
public
string
ToString()
Returns a <see cref="T:System.String" /> that represents this instance.
Returns The value of the current instance in the default format pattern ("o"), using the current thread's
culture to obtain a format provider.
public
string
ToString(string patternText,
System.IFormatProvider formatProvider)
Formats the value of the current instance using the specified pattern.
Returns A <see cref="T:System.String" /> containing the value of the current instance in the specified format.
patternText
The <see cref="T:System.String" /> specifying the pattern to use,
or null to use the default format pattern ("o").
formatProvider
The <see cref="T:System.IFormatProvider" /> to use when formatting the value,
or null to use the current thread's culture to obtain a format provider.
public static
Duration
Add(Duration left,
Duration right)
Adds one duration to another. Friendly alternative to <c>operator+()</c> .
Returns A new <see cref="T:NodaTime.Duration" /> representing the sum of the given values.
left
The left hand side of the operator.
right
The right hand side of the operator.
public
Duration
Plus(Duration other)
Returns the result of adding another duration to this one, for a fluent alternative to <c>operator+()</c> .
Returns A new <see cref="T:NodaTime.Duration" /> representing the result of the addition.
other
The duration to add
public static
Duration
Subtract(Duration left,
Duration right)
Subtracts one duration from another. Friendly alternative to <c>operator-()</c> .
Returns A new <see cref="T:NodaTime.Duration" /> representing the difference of the given values.
left
The left hand side of the operator.
right
The right hand side of the operator.
public
Duration
Minus(Duration other)
Returns the result of subtracting another duration from this one, for a fluent alternative to <c>operator-()</c> .
Returns A new <see cref="T:NodaTime.Duration" /> representing the result of the subtraction.
other
The duration to subtract
public static
Duration
Divide(Duration left,
long right)
Divides a duration by an <see cref="T:System.Int64" /> . Friendly alternative to <c>operator/()</c> .
Returns A new <see cref="T:NodaTime.Duration" /> representing the result of dividing <paramref name="left" /> by
<paramref name="right" /> .
left
The left hand side of the operator.
right
The right hand side of the operator.
public static
Duration
Divide(Duration left,
double right)
Divides a duration by a <see cref="T:System.Double" /> . Friendly alternative to <c>operator/()</c> .
Returns A new <see cref="T:NodaTime.Duration" /> representing the result of dividing <paramref name="left" /> by
<paramref name="right" /> .
left
The left hand side of the operator.
right
The right hand side of the operator.
public static
double
Divide(Duration left,
Duration right)
Divides one duration by another. Friendly alternative to <c>operator/()</c> .
Returns The <see cref="T:System.Double" /> representing the result of dividing <paramref name="left" /> by
<paramref name="right" /> .
left
The left hand side of the operator.
right
The right hand side of the operator.
public static
Duration
Multiply(Duration left,
long right)
Multiplies a duration by a number. Friendly alternative to <c>operator*()</c> .
Returns A new <see cref="T:NodaTime.Duration" /> representing the product of the given values.
left
The left hand side of the operator.
right
The right hand side of the operator.
public static
Duration
Multiply(Duration left,
double right)
Multiplies a duration by a number. Friendly alternative to <c>operator*()</c> .
Returns A new <see cref="T:NodaTime.Duration" /> representing the product of the given values.
left
The left hand side of the operator.
right
The right hand side of the operator.
public static
Duration
Multiply(long left,
Duration right)
Multiplies a duration by a number. Friendly alternative to <c>operator*()</c> .
Returns A new <see cref="T:NodaTime.Duration" /> representing the product of the given values.
left
The left hand side of the operator.
right
The right hand side of the operator.
public static
Duration
Multiply(double left,
Duration right)
Multiplies a duration by a number. Friendly alternative to <c>operator*()</c> .
Returns A new <see cref="T:NodaTime.Duration" /> representing the product of the given values.
left
The left hand side of the operator.
right
The right hand side of the operator.
public static
Duration
Negate(Duration duration)
Implements a friendly alternative to the unary negation operator.
Returns The negative value of this duration
duration
Duration to negate
public
int
CompareTo(Duration other)
Implementation of <see cref="M:System.IComparable`1.CompareTo(`0)" /> to compare two durations.
See the type documentation for a description of ordering semantics.
Returns A 32-bit signed integer that indicates the relative order of the objects being compared.
The return value has the following meanings:
<list type="table">
<listheader>
<term>Value</term>
<description>Meaning</description>
</listheader>
<item>
<term>< 0</term>
<description>This object is less than the <paramref name="other" /> parameter.</description>
</item>
<item>
<term>0</term>
<description>This object is equal to <paramref name="other" />.</description>
</item>
<item>
<term>> 0</term>
<description>This object is greater than <paramref name="other" />.</description>
</item>
</list>
other
An object to compare with this object.
public
bool
Equals(Duration other)
Indicates whether the current object is equal to another object of the same type.
See the type documentation for a description of equality semantics.
Returns true if the current object is equal to the <paramref name="other" /> parameter;
otherwise, false.
other
An object to compare with this object.
public static
Duration
FromDays(int days)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of days, assuming a 'standard' 24-hour
day.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of days.
days
The number of days.
public static
Duration
FromDays(double days)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of days, assuming a 'standard' 24-hour
day.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of days.
days
The number of days.
public static
Duration
FromHours(int hours)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of hours.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of hours.
hours
The number of hours.
public static
Duration
FromHours(double hours)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of hours.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of hours.
hours
The number of hours.
public static
Duration
FromMinutes(long minutes)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of minutes.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of minutes.
minutes
The number of minutes.
public static
Duration
FromMinutes(double minutes)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of minutes.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of minutes.
minutes
The number of minutes.
public static
Duration
FromSeconds(long seconds)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of seconds.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of seconds.
seconds
The number of seconds.
public static
Duration
FromSeconds(double seconds)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of seconds.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of seconds.
seconds
The number of seconds.
public static
Duration
FromMilliseconds(long milliseconds)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of milliseconds.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of milliseconds.
milliseconds
The number of milliseconds.
public static
Duration
FromMilliseconds(double milliseconds)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of milliseconds.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of milliseconds.
milliseconds
The number of milliseconds.
public static
Duration
FromTicks(long ticks)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of ticks.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of ticks.
ticks
The number of ticks.
public static
Duration
FromTicks(double ticks)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of ticks.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of ticks.
ticks
The number of ticks.
public static
Duration
FromNanoseconds(long nanoseconds)
Returns a <see cref="T:NodaTime.Duration" /> that represents the given number of nanoseconds.
Returns A <see cref="T:NodaTime.Duration" /> representing the given number of nanoseconds.
nanoseconds
The number of nanoseconds.
public static
Duration
FromNanoseconds(double nanoseconds)
Converts a number of nanoseconds expressed as a <see cref="T:System.Double" /> into a duration. Any fractional
parts of the value are truncated towards zero.
Returns A duration with the given number of nanoseconds.
nanoseconds
The number of nanoseconds to represent.
public static
Duration
FromNanoseconds(System.Numerics.BigInteger nanoseconds)
Converts a number of nanoseconds expressed as a <see cref="T:System.Numerics.BigInteger" /> into a duration.
Returns A duration with the given number of nanoseconds.
nanoseconds
The number of nanoseconds to represent.
public static
Duration
FromNanoseconds(System.Int128 nanoseconds)
Converts a number of nanoseconds expressed as an <see cref="T:System.Int128" /> into a duration.
Returns A duration with the given number of nanoseconds.
nanoseconds
The number of nanoseconds to represent.
public static
Duration
FromTimeSpan(System.TimeSpan timeSpan)
Returns a <see cref="T:NodaTime.Duration" /> that represents the same number of ticks as the
given <see cref="T:System.TimeSpan" /> .
Returns A new Duration with the same number of ticks as the given TimeSpan.
timeSpan
The TimeSpan value to convert
public
System.TimeSpan
ToTimeSpan()
Returns a <see cref="T:System.TimeSpan" /> that represents the same number of ticks as this
<see cref="T:NodaTime.Duration" /> .
Returns A new TimeSpan with the same number of ticks as this Duration.
Remarks
If the number of nanoseconds in a duration is not a whole number of ticks, it is truncated towards zero.
For example, durations in the range [-99ns, 99ns] would all count as 0 ticks.
public static
System.Xml.XmlQualifiedName
AddSchema(System.Xml.Schema.XmlSchemaSet xmlSchemaSet)
Adds the XML schema type describing the structure of the <see cref="T:NodaTime.Duration" /> XML serialization to the given <paramref name="xmlSchemaSet" /> .
Returns The qualified name of the schema type that was added to the <paramref name="xmlSchemaSet" /> .
xmlSchemaSet
The XML schema set provided by <see cref="T:System.Xml.Serialization.XmlSchemaExporter" /> .
public
long
ToInt64Nanoseconds()
Conversion to an <see cref="T:System.Int64" /> number of nanoseconds. This will fail if the number of nanoseconds is
out of the range of <c>Int64</c> , which is approximately 292 years (positive or negative).
Returns This duration as a number of nanoseconds, represented as an <c>Int64</c> .
public
System.Numerics.BigInteger
ToBigIntegerNanoseconds()
Conversion to a <see cref="T:System.Numerics.BigInteger" /> number of nanoseconds, as a convenient built-in numeric
type which can always represent values in the range we need.
Returns This duration as a number of nanoseconds, represented as a <c>BigInteger</c> .
public
System.Int128
ToInt128Nanoseconds()
Conversion to a <see cref="T:System.Int128" /> number of nanoseconds, as a convenient built-in numeric
type which can always represent values in the range we need.
Returns This duration as a number of nanoseconds, represented as a <c>BigInteger</c> .
Returns The larger duration of <paramref name="x" /> or <paramref name="y" /> .
x
The first duration to compare.
y
The second duration to compare.
Remarks
A "larger" duration is one that advances time by more than a "smaller" one. This means
that a positive duration is always larger than a negative one, for example. (This is the same
comparison used by the binary comparison operators.)
Returns The smaller duration of <paramref name="x" /> or <paramref name="y" /> .
x
The first duration to compare.
y
The second duration to compare.
Remarks
A "larger" duration is one that advances time by more than a "smaller" one. This means
that a positive duration is always larger than a negative one, for example. (This is the same
comparison used by the binary comparison operators.)
protected
void
Finalize()
Inherited from object
protected
object
MemberwiseClone()
Inherited from object