# Class Period

**Since**1.0.x

**Availability**net45, netstandard1.3

##### Inherited Members

**Namespace**: NodaTime

**Assembly**: NodaTime.dll

##### Syntax

```
[Serializable]
public sealed class Period : IEquatable<Period>, ISerializable
```

**Remarks**

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

**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

#### HasDateComponent

**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. |

##### Remarks

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.)

#### HasTimeComponent

**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. |

##### Remarks

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.)

#### Hours

**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

#### Milliseconds

**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

#### Minutes

**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

#### Months

**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

#### Nanoseconds

**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

#### NormalizingEqualityComparer

**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. |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### Seconds

**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

#### Ticks

**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

#### Weeks

**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

#### Years

**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

#### Zero

**Since**1.0.x

**Availability**net45, netstandard1.3

##### Declaration

`public static Period Zero { get; }`

##### Property Value

Type | Description |
---|---|

Period |

##### Remarks

Period equality is implemented by comparing each property's values individually.

### Methods

#### Between(LocalDate, LocalDate)

**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

`end`

is before `start`

, each property in the returned period
will be negative.
#### Between(LocalDate, LocalDate, PeriodUnits)

**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

`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)

**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

`end`

is before `start`

, each property in the returned period
will be negative.
#### Between(LocalDateTime, LocalDateTime, PeriodUnits)

**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

`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)

**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

`end`

is before `start`

, each property in the returned period
will be negative.
#### Between(LocalTime, LocalTime, PeriodUnits)

**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

`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)

**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

`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)

**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

#### Equals(Object)

**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

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### FromDays(Int32)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### FromHours(Int64)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### FromMilliseconds(Int64)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### FromMinutes(Int64)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### FromMonths(Int32)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### FromNanoseconds(Int64)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### FromSeconds(Int64)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### FromTicks(Int64)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### FromWeeks(Int32)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### FromYears(Int32)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### GetHashCode()

**Since**1.0.x

**Availability**net45, netstandard1.3

##### Declaration

`public override int GetHashCode()`

##### Returns

Type | Description |
---|---|

Int32 | The hash code for this period. |

##### Overrides

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### Normalize()

**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

##### Exceptions

Type | Condition |
---|---|

OverflowException | The period doesn't have years or months, but it contains more than 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()

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

#### ToDuration()

**Since**1.0.x

**Availability**net45, netstandard1.3

##### Declaration

`public Duration ToDuration()`

##### Returns

Type | Description |
---|---|

Duration | The duration of the period. |

##### Remarks

Period equality is implemented by comparing each property's values individually.

##### Exceptions

Type | Condition |
---|---|

InvalidOperationException | The month or year property in the period is non-zero. |

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

**Since**1.0.x

**Availability**net45, netstandard1.3

##### Declaration

`public override string ToString()`

##### Returns

Type | Description |
---|---|

String | A formatted representation of this period. |

##### Overrides

##### Remarks

Period equality is implemented by comparing each property's values individually.

### Operators

#### Addition(Period, Period)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

##### Exceptions

Type | Condition |
---|---|

ArgumentNullException | left or right is null |

#### Subtraction(Period, Period)

**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.) |

##### Remarks

Period equality is implemented by comparing each property's values individually.

##### Exceptions

Type | Condition |
---|---|

ArgumentNullException | minuend or subtrahend is null |

### Explicit Interface Implementations

#### ISerializable.GetObjectData(SerializationInfo, StreamingContext)

**Since**1.2.x

**Availability**net45

##### Declaration

```
[SecurityCritical]
void ISerializable.GetObjectData(SerializationInfo info, StreamingContext context)
```

##### Parameters

Type | Name | Description |
---|---|---|

SerializationInfo | info | The SerializationInfo to populate with data. |

StreamingContext | context | The destination for this serialization. |

##### Remarks

Period equality is implemented by comparing each property's values individually.