Class Period
Represents a period of time expressed in human chronological terms: hours, days,
weeks, months and so on.
Since 1.0.x
Availability net45, netstandard1.3
Inheritance
Object
Period
Inherited Members
Object.Equals(Object, Object)
Object.ReferenceEquals(Object, Object)
Object.GetType()
Object.MemberwiseClone()
Namespace: NodaTime
Assembly: NodaTime.dll
Syntax
[Serializable]
public sealed class Period : IEquatable<Period>, ISerializableRemarks
A Period contains a set of properties such as Years, Months, and so on that return the number of each unit contained within this period. Note that these properties are not normalized in any way by default, and so a Period may contain values such as "2 hours and 90 minutes". The Normalize() method will convert equivalent periods into a standard representation.
Periods can contain negative units as well as positive units ("+2 hours, -43 minutes, +10 seconds"), but do not differentiate between properties that are zero and those that are absent (i.e. a period created as "10 years" and one created as "10 years, zero months" are equal periods; the Months property returns zero in both cases).
Period equality is implemented by comparing each property's values individually.
Periods operate on calendar-related types such as LocalDateTime whereas Duration operates on instants on the time line. (Note that although ZonedDateTime includes both concepts, it only supports duration-based arithmetic.)
Properties
Days
Gets the number of days within this period.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int Days { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The number of days within this period. |
Remarks
This property returns zero both when the property has been explicitly set to zero and when the period does not
contain this property.
HasDateComponent
Returns whether or not this period contains any non-zero date-based properties (days or higher).
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public bool HasDateComponent { get; }Property Value
| Type | Description |
|---|---|
| Boolean | true if this period contains any non-zero date-based properties (days or higher); false otherwise. |
HasTimeComponent
Returns whether or not this period contains any non-zero-valued time-based properties (hours or lower).
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public bool HasTimeComponent { get; }Property Value
| Type | Description |
|---|---|
| Boolean | true if the period contains any non-zero-valued time-based properties (hours or lower); false otherwise. |
Hours
Gets the number of hours within this period.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public long Hours { get; }Property Value
| Type | Description |
|---|---|
| Int64 | The number of hours within this period. |
Remarks
This property returns zero both when the property has been explicitly set to zero and when the period does not
contain this property.
Milliseconds
Gets the number of milliseconds within this period.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public long Milliseconds { get; }Property Value
| Type | Description |
|---|---|
| Int64 | The number of milliseconds within this period. |
Remarks
This property returns zero both when the property has been explicitly set to zero and when the period does not
contain this property.
Minutes
Gets the number of minutes within this period.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public long Minutes { get; }Property Value
| Type | Description |
|---|---|
| Int64 | The number of minutes within this period. |
Remarks
This property returns zero both when the property has been explicitly set to zero and when the period does not
contain this property.
Months
Gets the number of months within this period.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int Months { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The number of months within this period. |
Remarks
This property returns zero both when the property has been explicitly set to zero and when the period does not
contain this property.
Nanoseconds
Gets the number of nanoseconds within this period.
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public long Nanoseconds { get; }Property Value
| Type | Description |
|---|---|
| Int64 | The number of nanoseconds within this period. |
Remarks
This property returns zero both when the property has been explicitly set to zero and when the period does not
contain this property.
NormalizingEqualityComparer
Returns an equality comparer which compares periods by first normalizing them - so 24 hours is deemed equal to 1 day, and so on.
Note that as per the Normalize() method, years and months are unchanged by normalization - so 12 months does not
equal 1 year.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static IEqualityComparer<Period> NormalizingEqualityComparer { get; }Property Value
| Type | Description |
|---|---|
| IEqualityComparer<Period> | An equality comparer which compares periods by first normalizing them. (The value returned is never null.) |
Seconds
Gets the number of seconds within this period.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public long Seconds { get; }Property Value
| Type | Description |
|---|---|
| Int64 | The number of seconds within this period. |
Remarks
This property returns zero both when the property has been explicitly set to zero and when the period does not
contain this property.
Ticks
Gets the number of ticks within this period.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public long Ticks { get; }Property Value
| Type | Description |
|---|---|
| Int64 | The number of ticks within this period. |
Remarks
This property returns zero both when the property has been explicitly set to zero and when the period does not
contain this property.
Weeks
Gets the number of weeks within this period.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int Weeks { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The number of weeks within this period. |
Remarks
This property returns zero both when the property has been explicitly set to zero and when the period does not
contain this property.
Years
Gets the number of years within this period.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int Years { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The number of years within this period. |
Remarks
This property returns zero both when the property has been explicitly set to zero and when the period does not
contain this property.
Zero
A period containing only zero-valued properties.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period Zero { get; }Property Value
| Type | Description |
|---|---|
| Period | A period containing only zero-valued properties. (The value returned is never null.) |
Methods
Between(LocalDate, LocalDate)
Returns the exact difference between two dates.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period Between(LocalDate start, LocalDate end)Parameters
| Type | Name | Description |
|---|---|---|
| LocalDate | start | Start date |
| LocalDate | end | End date |
Returns
| Type | Description |
|---|---|
| Period | The period between the two dates, using year, month and day units. (The value returned is never null.) |
Remarks
If
end is before start, each property in the returned period
will be negative.
Between(LocalDate, LocalDate, PeriodUnits)
Returns the period between a start and an end date, using only the given units.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period Between(LocalDate start, LocalDate end, PeriodUnits units)Parameters
| Type | Name | Description |
|---|---|---|
| LocalDate | start | Start date |
| LocalDate | end | End date |
| PeriodUnits | units | Units to use for calculations |
Returns
| Type | Description |
|---|---|
| Period | The period between the given dates, using the given units. (The value returned is never null.) |
Remarks
If
end is before start, each property in the returned period
will be negative. If the given set of units cannot exactly reach the end point (e.g. finding
the difference between 12th February and 15th March in months) the result will be such that adding it to start
will give a value between start and end. In other words,
any rounding is "towards start"; this is true whether the resulting period is negative or positive.
Exceptions
| Type | Condition |
|---|---|
| ArgumentException | units contains time units, is empty or contains unknown values. |
| ArgumentException | start and end use different calendars. |
Between(LocalDateTime, LocalDateTime)
Returns the exact difference between two date/times.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period Between(LocalDateTime start, LocalDateTime end)Parameters
| Type | Name | Description |
|---|---|---|
| LocalDateTime | start | Start date/time |
| LocalDateTime | end | End date/time |
Returns
| Type | Description |
|---|---|
| Period | The period between the two date and time values, using all units. (The value returned is never null.) |
Remarks
If
end is before start, each property in the returned period
will be negative.
Between(LocalDateTime, LocalDateTime, PeriodUnits)
Returns the period between a start and an end date/time, using only the given units.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period Between(LocalDateTime start, LocalDateTime end, PeriodUnits units)Parameters
| Type | Name | Description |
|---|---|---|
| LocalDateTime | start | Start date/time |
| LocalDateTime | end | End date/time |
| PeriodUnits | units | Units to use for calculations |
Returns
| Type | Description |
|---|---|
| Period | The period between the given date/times, using the given units. (The value returned is never null.) |
Remarks
If
end is before start, each property in the returned period
will be negative. If the given set of units cannot exactly reach the end point (e.g. finding
the difference between 1am and 3:15am in hours) the result will be such that adding it to start
will give a value between start and end. In other words,
any rounding is "towards start"; this is true whether the resulting period is negative or positive.
Exceptions
| Type | Condition |
|---|---|
| ArgumentException | units is empty or contained unknown values. |
| ArgumentException | start and end use different calendars. |
Between(LocalTime, LocalTime)
Returns the exact difference between two times.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period Between(LocalTime start, LocalTime end)Parameters
| Type | Name | Description |
|---|---|---|
| LocalTime | start | Start time |
| LocalTime | end | End time |
Returns
| Type | Description |
|---|---|
| Period | The period between the two times, using the time period units. (The value returned is never null.) |
Remarks
If
end is before start, each property in the returned period
will be negative.
Between(LocalTime, LocalTime, PeriodUnits)
Returns the period between a start and an end time, using only the given units.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period Between(LocalTime start, LocalTime end, PeriodUnits units)Parameters
| Type | Name | Description |
|---|---|---|
| LocalTime | start | Start time |
| LocalTime | end | End time |
| PeriodUnits | units | Units to use for calculations |
Returns
| Type | Description |
|---|---|
| Period | The period between the given times, using the given units. (The value returned is never null.) |
Remarks
If
end is before start, each property in the returned period
will be negative. If the given set of units cannot exactly reach the end point (e.g. finding
the difference between 3am and 4.30am in hours) the result will be such that adding it to start
will give a value between start and end. In other words,
any rounding is "towards start"; this is true whether the resulting period is negative or positive.
Exceptions
| Type | Condition |
|---|---|
| ArgumentException | units contains date units, is empty or contains unknown values. |
| ArgumentException | start and end use different calendars. |
CreateComparer(LocalDateTime)
Creates an System.Collections.Generic.IComparer<T> for periods, using the given "base" local date/time.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static IComparer<Period> CreateComparer(LocalDateTime baseDateTime)Parameters
| Type | Name | Description |
|---|---|---|
| LocalDateTime | baseDateTime | The base local date/time to use for comparisons. |
Returns
| Type | Description |
|---|---|
| IComparer<Period> | The new comparer. (The value returned is never null.) |
Remarks
Certain periods can't naturally be compared without more context - how "one month" compares to
"30 days" depends on where you start. In order to compare two periods, the returned comparer
effectively adds both periods to the "base" specified by
baseDateTime and compares
the results. In some cases this arithmetic isn't actually required - when two periods can be
converted to durations, the comparer uses that conversion for efficiency.
Equals(Period)
Compares the given period for equality with this one.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public bool Equals(Period other)Parameters
| Type | Name | Description |
|---|---|---|
| Period | other | The period to compare this one with. |
Returns
| Type | Description |
|---|---|
| Boolean | True if this period has the same values for the same properties as the one specified. |
Remarks
Periods are equal if they contain the same values for the same properties.
However, no normalization takes place, so "one hour" is not equal to "sixty minutes".
Equals(Object)
Compares the given object for equality with this one, as per Equals(Period).
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public override bool Equals(object other)Parameters
| Type | Name | Description |
|---|---|---|
| Object | other | The value to compare this one with. |
Returns
| Type | Description |
|---|---|
| Boolean | true if the other object is a period equal to this one, consistent with Equals(Period) |
Overrides
System.Object.Equals(System.Object)
FromDays(Int32)
Creates a period representing the specified number of days.
Since 1.4.x
Availability net45, netstandard1.3
Declaration
public static Period FromDays(int days)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | days | The number of days in the new period |
Returns
| Type | Description |
|---|---|
| Period | A period consisting of the given number of days. (The value returned is never null.) |
FromHours(Int64)
Creates a period representing the specified number of hours.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period FromHours(long hours)Parameters
| Type | Name | Description |
|---|---|---|
| Int64 | hours | The number of hours in the new period |
Returns
| Type | Description |
|---|---|
| Period | A period consisting of the given number of hours. (The value returned is never null.) |
FromMilliseconds(Int64)
Creates a period representing the specified number of milliseconds.
Since 1.1.x
Availability net45, netstandard1.3
Declaration
public static Period FromMilliseconds(long milliseconds)Parameters
| Type | Name | Description |
|---|---|---|
| Int64 | milliseconds | The number of milliseconds in the new period |
Returns
| Type | Description |
|---|---|
| Period | A period consisting of the given number of milliseconds. (The value returned is never null.) |
FromMinutes(Int64)
Creates a period representing the specified number of minutes.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period FromMinutes(long minutes)Parameters
| Type | Name | Description |
|---|---|---|
| Int64 | minutes | The number of minutes in the new period |
Returns
| Type | Description |
|---|---|
| Period | A period consisting of the given number of minutes. (The value returned is never null.) |
FromMonths(Int32)
Creates a period representing the specified number of months.
Since 1.4.x
Availability net45, netstandard1.3
Declaration
public static Period FromMonths(int months)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | months | The number of months in the new period |
Returns
| Type | Description |
|---|---|
| Period | A period consisting of the given number of months. (The value returned is never null.) |
FromNanoseconds(Int64)
Creates a period representing the specified number of nanooseconds.
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public static Period FromNanoseconds(long nanoseconds)Parameters
| Type | Name | Description |
|---|---|---|
| Int64 | nanoseconds | The number of nanoseconds in the new period |
Returns
| Type | Description |
|---|---|
| Period | A period consisting of the given number of nanoseconds. (The value returned is never null.) |
FromSeconds(Int64)
Creates a period representing the specified number of seconds.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period FromSeconds(long seconds)Parameters
| Type | Name | Description |
|---|---|---|
| Int64 | seconds | The number of seconds in the new period |
Returns
| Type | Description |
|---|---|
| Period | A period consisting of the given number of seconds. (The value returned is never null.) |
FromTicks(Int64)
Creates a period representing the specified number of ticks.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period FromTicks(long ticks)Parameters
| Type | Name | Description |
|---|---|---|
| Int64 | ticks | The number of ticks in the new period |
Returns
| Type | Description |
|---|---|
| Period | A period consisting of the given number of ticks. (The value returned is never null.) |
FromWeeks(Int32)
Creates a period representing the specified number of weeks.
Since 1.4.x
Availability net45, netstandard1.3
Declaration
public static Period FromWeeks(int weeks)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | weeks | The number of weeks in the new period |
Returns
| Type | Description |
|---|---|
| Period | A period consisting of the given number of weeks. (The value returned is never null.) |
FromYears(Int32)
Creates a period representing the specified number of years.
Since 1.4.x
Availability net45, netstandard1.3
Declaration
public static Period FromYears(int years)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | years | The number of years in the new period |
Returns
| Type | Description |
|---|---|
| Period | A period consisting of the given number of years. (The value returned is never null.) |
GetHashCode()
Returns the hash code for this period, consistent with Equals(Period).
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public override int GetHashCode()Returns
| Type | Description |
|---|---|
| Int32 | The hash code for this period. |
Overrides
System.Object.GetHashCode()
Normalize()
Returns a normalized version of this period, such that equivalent (but potentially non-equal) periods are
changed to the same representation.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public Period Normalize()Returns
| Type | Description |
|---|---|
| Period | The normalized period. (The value returned is never null.) |
Remarks
Months and years are unchanged
(as they can vary in length), but weeks are multiplied by 7 and added to the
Days property, and all time properties are normalized to their natural range.
Subsecond values are normalized to millisecond and "nanosecond within millisecond" values.
So for example, a period of 25 hours becomes a period of 1 day
and 1 hour. A period of 1,500,750,000 nanoseconds becomes 1 second, 500 milliseconds and
750,000 nanoseconds. Aside from months and years, either all the properties
end up positive, or they all end up negative. "Week" and "tick" units in the returned period are always 0.
Exceptions
| Type | Condition |
|---|---|
| System.OverflowException | The period doesn't have years or months, but it contains more than System.Int64.MaxValue nanoseconds when the combined weeks/days/time portions are considered. This is over 292 years, so unlikely to be a problem in normal usage. In some cases this may occur even though the theoretical result would be valid due to balancing positive and negative values, but for simplicity there is no attempt to work around this. |
See Also
ToBuilder()
Creates a PeriodBuilder from this instance. The new builder
is populated with the values from this period, but is then detached from it:
changes made to the builder are not reflected in this period.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public PeriodBuilder ToBuilder()Returns
| Type | Description |
|---|---|
| PeriodBuilder | A builder with the same values and units as this period. (The value returned is never null.) |
ToDuration()
For periods that do not contain a non-zero number of years or months, returns a duration for this period
assuming a standard 7-day week, 24-hour day, 60-minute hour etc.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public Duration ToDuration()Returns
| Type | Description |
|---|---|
| Duration | The duration of the period. |
Exceptions
| Type | Condition |
|---|---|
| System.InvalidOperationException | The month or year property in the period is non-zero. |
| System.OverflowException | The period doesn't have years or months, but the calculation overflows the bounds of Duration. In some cases this may occur even though the theoretical result would be valid due to balancing positive and negative values, but for simplicity there is no attempt to work around this - in realistic periods, it shouldn't be a problem. |
ToString()
Returns this string formatted according to the Roundtrip.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public override string ToString()Returns
| Type | Description |
|---|---|
| String | A formatted representation of this period. |
Overrides
System.Object.ToString()
Operators
Addition(Period, Period)
Adds two periods together, by simply adding the values for each property.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period operator +(Period left, Period right)Parameters
| Type | Name | Description |
|---|---|---|
| Period | left | The first period to add |
| Period | right | The second period to add |
Returns
| Type | Description |
|---|---|
| Period | The sum of the two periods. The units of the result will be the union of those in both periods. (The value returned is never null.) |
Exceptions
| Type | Condition |
|---|---|
| ArgumentNullException | left or right is null |
Subtraction(Period, Period)
Subtracts one period from another, by simply subtracting each property value.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public static Period operator -(Period minuend, Period subtrahend)Parameters
| Type | Name | Description |
|---|---|---|
| Period | minuend | The period to subtract the second operand from |
| Period | subtrahend | The period to subtract the first operand from |
Returns
| Type | Description |
|---|---|
| Period | The result of subtracting all the values in the second operand from the values in the first. The units of the result will be the union of both periods, even if the subtraction caused some properties to become zero (so "2 weeks, 1 days" minus "2 weeks" is "zero weeks, 1 days", not "1 days"). (The value returned is never null.) |
Exceptions
| Type | Condition |
|---|---|
| ArgumentNullException | minuend or subtrahend is null |
Explicit Interface Implementations
ISerializable.GetObjectData(SerializationInfo, StreamingContext)
Implementation of System.Runtime.Serialization.ISerializable.GetObjectData(System.Runtime.Serialization.SerializationInfo, System.Runtime.Serialization.StreamingContext).
Since 1.2.x
Availability net45
Declaration
[SecurityCritical]
void ISerializable.GetObjectData(SerializationInfo info, StreamingContext context)Parameters
| Type | Name | Description |
|---|---|---|
| SerializationInfo | info | The System.Runtime.Serialization.SerializationInfo to populate with data. |
| StreamingContext | context | The destination for this serialization. |
Implements
System.IEquatable<T>
System.Runtime.Serialization.ISerializable