Class Period

Represents a period of time expressed in human chronological terms: hours, days, weeks, months and so on.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Inheritance
object
Period
Implements
Inherited Members
Namespace: NodaTime
Assembly: NodaTime.dll
Syntax
[TypeConverter(typeof(PeriodTypeConverter))]
public sealed class Period : IEquatable<Period?>, IAdditionOperators<Period, Period, Period>, ISubtractionOperators<Period, Period, Period>, IUnaryNegationOperators<Period, Period>, IUnaryPlusOperators<Period, Period>, IAdditiveIdentity<Period, Period>, IMinMaxValue<Period>
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, without any normalization. (For example, a period of "24 hours" is not considered equal to a period of "1 day".) The static NormalizingEqualityComparer comparer provides an equality comparer which performs normalization before comparisons.

There is no natural ordering for periods, but CreateComparer(LocalDateTime) can be used to create a comparer which orders periods according to a reference date, by adding each period to that date and comparing the results.

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

The complexity of each method in this type is hard to document precisely, and often depends on the calendar system involved in performing the actual calculations. Operations do not depend on the magnitude of the units in the period, other than for optimizations for values of zero or occasionally for particularly small values. For example, adding 10,000 days to a date does not require greater algorithmic complexity than adding 1,000 days to the same date.

Properties

AdditiveIdentity

Gets the additive identity.
Since 3.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period AdditiveIdentity { get; }
Property Value
Type Description
Period

Days

Gets the number of days within this period.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public int Days { get; }
Property Value
Type Description
int 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 net6.0, net8.0, netstandard2.0
Declaration
public bool HasDateComponent { get; }
Property Value
Type Description
bool 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 net6.0, net8.0, netstandard2.0
Declaration
public bool HasTimeComponent { get; }
Property Value
Type Description
bool 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 net6.0, net8.0, netstandard2.0
Declaration
public long Hours { get; }
Property Value
Type Description
long 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.

MaxValue

A period containing the maximum value for all properties.
Since 3.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period MaxValue { get; }
Property Value
Type Description
Period A period containing the maximum value for all properties.

Milliseconds

Gets the number of milliseconds within this period.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public long Milliseconds { get; }
Property Value
Type Description
long 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.

MinValue

A period containing the minimum value for all properties.
Since 3.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period MinValue { get; }
Property Value
Type Description
Period A period containing the minimum value for all properties.

Minutes

Gets the number of minutes within this period.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public long Minutes { get; }
Property Value
Type Description
long 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 net6.0, net8.0, netstandard2.0
Declaration
public int Months { get; }
Property Value
Type Description
int 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 net6.0, net8.0, netstandard2.0
Declaration
public long Nanoseconds { get; }
Property Value
Type Description
long 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 net6.0, net8.0, netstandard2.0
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 net6.0, net8.0, netstandard2.0
Declaration
public long Seconds { get; }
Property Value
Type Description
long 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 net6.0, net8.0, netstandard2.0
Declaration
public long Ticks { get; }
Property Value
Type Description
long 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 net6.0, net8.0, netstandard2.0
Declaration
public int Weeks { get; }
Property Value
Type Description
int 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 net6.0, net8.0, netstandard2.0
Declaration
public int Years { get; }
Property Value
Type Description
int 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 net6.0, net8.0, netstandard2.0
Declaration
public static Period Zero { get; }
Property Value
Type Description
Period A period containing only zero-valued properties.

Methods

Add(Period, Period)

Adds two periods together, by simply adding the values for each property.
Since 3.1.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period Add(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.

Between(LocalDate, LocalDate)

Returns the exact difference between two dates.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
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.
Remarks
If end is before start, each property in the returned period will be negative. The calendar systems of the two dates must be the same; an exception will be thrown otherwise.
Sample snippet
using NodaTime;
using System;

Period period = Period.Between(
    new LocalDate(1990, 6, 26),
    new LocalDate(2017, 11, 15));

Console.WriteLine(period.Years);
Console.WriteLine(period.Months);
Console.WriteLine(period.Days);
Console.WriteLine(period.ToString());

Output:

27
4
20
P27Y4M20D
Exceptions
Type Condition
ArgumentException start and end are not in the same calendar system.

Between(LocalDate, LocalDate, PeriodUnits)

Returns the period between a start and an end date, using only the given units.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
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.
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.
Sample snippet
using NodaTime;
using System;

Period period = Period.Between(
    new LocalDate(2016, 11, 14),
    new LocalDate(2017, 11, 21),
    PeriodUnits.Years | PeriodUnits.Days);

Console.WriteLine(period.Years);
Console.WriteLine(period.Days);
Console.WriteLine(period.ToString());

Output:

1
7
P1Y7D
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 net6.0, net8.0, netstandard2.0
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.
Remarks
If end is before start, each property in the returned period will be negative.
Sample snippet
using NodaTime;
using System;

Period period = Period.Between(
    new LocalDateTime(2015, 1, 23, 21, 30, 15),
    new LocalDateTime(2017, 10, 15, 21, 02, 17));

Console.WriteLine(period.Years);
Console.WriteLine(period.Months);
Console.WriteLine(period.Days);
Console.WriteLine(period.Hours);
Console.WriteLine(period.Minutes);
Console.WriteLine(period.Seconds);
Console.WriteLine(period.ToString());

Output:

2
8
21
23
32
2
P2Y8M21DT23H32M2S

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 net6.0, net8.0, netstandard2.0
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.
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.
Sample snippet
using NodaTime;
using System;

Period period = Period.Between(
    new LocalDateTime(2015, 1, 23, 21, 30, 15),
    new LocalDateTime(2017, 10, 15, 21, 02, 17),
    PeriodUnits.Years | PeriodUnits.Days | PeriodUnits.Hours);

Console.WriteLine(period.Years);
Console.WriteLine(period.Days);
Console.WriteLine(period.Hours);
Console.WriteLine(period.ToString());

Output:

2
264
23
P2Y264DT23H
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 net6.0, net8.0, netstandard2.0
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.
Remarks
If end is before start, each property in the returned period will be negative.
Sample snippet
using NodaTime;
using System;

Period period = Period.Between(new LocalTime(10, 10), new LocalTime(13, 15));

Console.WriteLine(period.Hours);
Console.WriteLine(period.Minutes);
Console.WriteLine(period.ToString());

Output:

3
5
PT3H5M

Between(LocalTime, LocalTime, PeriodUnits)

Returns the period between a start and an end time, using only the given units.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
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.
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.
Sample snippet
using NodaTime;
using System;

Period period = Period.Between(
    new LocalTime(10, 10, 2),
    new LocalTime(13, 15, 49),
    PeriodUnits.Hours | PeriodUnits.Seconds);

Console.WriteLine(period.Hours);
Console.WriteLine(period.Seconds);
Console.WriteLine(period.ToString());

Output:

3
347
PT3H347S
Exceptions
Type Condition
ArgumentException units contains date units, is empty or contains unknown values.
ArgumentException start and end use different calendars.

Between(YearMonth, YearMonth)

Returns the exact difference between two YearMonth.
Since 3.1.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period Between(YearMonth start, YearMonth end)
Parameters
Type Name Description
YearMonth start Start year and month
YearMonth end End year and month
Returns
Type Description
Period The period between the two YearMonths, using year and month units.
Remarks
If end is before start, each property in the returned period will be negative. The calendar systems of the two dates must be the same; an exception will be thrown otherwise.
Exceptions
Type Condition
ArgumentException start and end are not in the same calendar system.

Between(YearMonth, YearMonth, PeriodUnits)

Returns the period between a start and an end YearMonth, using only the given units.
Since 3.1.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period Between(YearMonth start, YearMonth end, PeriodUnits units)
Parameters
Type Name Description
YearMonth start Start year and month
YearMonth end End year and month
PeriodUnits units Units to use for calculations
Returns
Type Description
Period The period between the given YearMonths, using the given units.
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 February 2010 and March 2012 in years) 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 contains anything other than than PeriodUnits.Years and/or PeriodUnits.Months.
ArgumentException start and end use different calendars.

CreateComparer(LocalDateTime)

Creates an IComparer<T> for periods, using the given "base" local date/time.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
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.
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.

DaysBetween(LocalDate, LocalDate)

Returns the number of days between two LocalDate values.
Since 3.1.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static int DaysBetween(LocalDate start, LocalDate end)
Parameters
Type Name Description
LocalDate start Start date
LocalDate end End date
Returns
Type Description
int The number of days between the given dates.
Exceptions
Type Condition
ArgumentException start and end use different calendars.

Equals(Period?)

Compares the given period for equality with this one. See the type documentation for a description of equality semantics.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public bool Equals(Period? other)
Parameters
Type Name Description
Period other The period to compare this one with.
Returns
Type Description
bool True if this period has the same values for the same properties as the one specified.

Equals(object?)

Compares the given object for equality with this one, as per Equals(Period?). See the type documentation for a description of equality semantics.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public override bool Equals(object? other)
Parameters
Type Name Description
object other The value to compare this one with.
Returns
Type Description
bool true if the other object is a period equal to this one, consistent with Equals(Period?)
Overrides

FromDays(int)

Creates a period representing the specified number of days.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period FromDays(int days)
Parameters
Type Name Description
int days The number of days in the new period
Returns
Type Description
Period A period consisting of the given number of days.
Sample snippet
using NodaTime;
using System;

Period period = Period.FromDays(3);
Console.WriteLine(period.Days);
Console.WriteLine(period.ToString());

Output:

3
P3D

FromHours(long)

Creates a period representing the specified number of hours.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period FromHours(long hours)
Parameters
Type Name Description
long hours The number of hours in the new period
Returns
Type Description
Period A period consisting of the given number of hours.
Sample snippet
using NodaTime;
using System;

Period period = Period.FromHours(5);
Console.WriteLine(period.Hours);
Console.WriteLine(period.ToString());

Output:

5
PT5H

FromMilliseconds(long)

Creates a period representing the specified number of milliseconds.
Since 1.1.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period FromMilliseconds(long milliseconds)
Parameters
Type Name Description
long milliseconds The number of milliseconds in the new period
Returns
Type Description
Period A period consisting of the given number of milliseconds.
Sample snippet
using NodaTime;
using System;

Period period = Period.FromMilliseconds(1500);
Console.WriteLine(period.Milliseconds);
Console.WriteLine(period.ToString());

Output:

1500
PT1500s

FromMinutes(long)

Creates a period representing the specified number of minutes.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period FromMinutes(long minutes)
Parameters
Type Name Description
long minutes The number of minutes in the new period
Returns
Type Description
Period A period consisting of the given number of minutes.
Sample snippet
using NodaTime;
using System;

Period period = Period.FromMinutes(15);
Console.WriteLine(period.Minutes);
Console.WriteLine(period.ToString());

Output:

15
PT15M

FromMonths(int)

Creates a period representing the specified number of months.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period FromMonths(int months)
Parameters
Type Name Description
int months The number of months in the new period
Returns
Type Description
Period A period consisting of the given number of months.
Sample snippet
using NodaTime;
using System;

Period period = Period.FromMonths(10);
Console.WriteLine(period.Months);
Console.WriteLine(period.ToString());

Output:

10
P10M

FromNanoseconds(long)

Creates a period representing the specified number of nanoseconds.
Since 2.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period FromNanoseconds(long nanoseconds)
Parameters
Type Name Description
long nanoseconds The number of nanoseconds in the new period
Returns
Type Description
Period A period consisting of the given number of nanoseconds.
Sample snippet
using NodaTime;
using System;

Period period = Period.FromNanoseconds(42);
Console.WriteLine(period.Nanoseconds);
Console.WriteLine(period.ToString());

Output:

42
PT42n

FromSeconds(long)

Creates a period representing the specified number of seconds.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period FromSeconds(long seconds)
Parameters
Type Name Description
long seconds The number of seconds in the new period
Returns
Type Description
Period A period consisting of the given number of seconds.
Sample snippet
using NodaTime;
using System;

Period period = Period.FromSeconds(70);
Console.WriteLine(period.Seconds);
Console.WriteLine(period.ToString());

Output:

70
PT70S

FromTicks(long)

Creates a period representing the specified number of ticks.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period FromTicks(long ticks)
Parameters
Type Name Description
long ticks The number of ticks in the new period
Returns
Type Description
Period A period consisting of the given number of ticks.
Sample snippet
using NodaTime;
using System;

Period period = Period.FromTicks(42);
Console.WriteLine(period.Ticks);
Console.WriteLine(period.ToString());

Output:

42
PT42t

FromWeeks(int)

Creates a period representing the specified number of weeks.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period FromWeeks(int weeks)
Parameters
Type Name Description
int weeks The number of weeks in the new period
Returns
Type Description
Period A period consisting of the given number of weeks.
Sample snippet
using NodaTime;
using System;

Period period = Period.FromWeeks(1);
Console.WriteLine(period.Weeks);
Console.WriteLine(period.ToString());

Output:

1
P1W

FromYears(int)

Creates a period representing the specified number of years.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period FromYears(int years)
Parameters
Type Name Description
int years The number of years in the new period
Returns
Type Description
Period A period consisting of the given number of years.
Sample snippet
using NodaTime;
using System;

Period period = Period.FromYears(27);
Console.WriteLine(period.Years);
Console.WriteLine(period.ToString());

Output:

27
P27Y

GetHashCode()

Returns the hash code for this period, consistent with Equals(Period?). See the type documentation for a description of equality semantics.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public override int GetHashCode()
Returns
Type Description
int The hash code for this period.
Overrides

NanosecondsBetween(LocalTime, LocalTime)

Returns the number of nanoseconds between two LocalTime values.
Since unstable
Availability net6.0, net8.0, netstandard2.0
Declaration
public static long NanosecondsBetween(LocalTime start, LocalTime end)
Parameters
Type Name Description
LocalTime start Start time
LocalTime end End time
Returns
Type Description
long The number of nanoseconds between the given times.
Remarks
If end is before start, the returned value will be negative.

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 net6.0, net8.0, netstandard2.0
Declaration
public Period Normalize()
Returns
Type Description
Period The normalized period.
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.
Sample snippet
using NodaTime;
using System;

var original = new PeriodBuilder { Weeks = 2, Days = 5 }.Build();
var actual = original.Normalize();
Console.WriteLine(actual);

Output:

P19D
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

Subtract(Period, Period)

Subtracts one period from another, by simply subtracting each property value.
Since 3.1.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period Subtract(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").

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 net6.0, net8.0, netstandard2.0
Declaration
public PeriodBuilder ToBuilder()
Returns
Type Description
PeriodBuilder A builder with the same values and units as this period.

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 net6.0, net8.0, netstandard2.0
Declaration
public Duration ToDuration()
Returns
Type Description
Duration The duration of the period.
Sample snippet
using NodaTime;
using System;

Period oneDayAsPeriod = Period.FromDays(1);
var actual = oneDayAsPeriod.ToDuration();
Console.WriteLine(oneDayAsPeriod.HasTimeComponent);
Console.WriteLine(actual);

Output:

False
1:00:00:00
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()

Returns this string formatted according to the Roundtrip.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public override string ToString()
Returns
Type Description
string A formatted representation of this period.
Overrides

Operators

operator +(Period, Period)

Adds two periods together, by simply adding the values for each property.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
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.

operator ==(Period?, Period?)

Implements the operator == (equality). See the type documentation for a description of equality semantics.
Since 3.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static bool operator ==(Period? left, Period? right)
Parameters
Type Name Description
Period left The left hand side of the operator.
Period right The right hand side of the operator.
Returns
Type Description
bool true if values are equal to each other, otherwise false.

operator !=(Period?, Period?)

Implements the operator != (inequality). See the type documentation for a description of equality semantics.
Since 3.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static bool operator !=(Period? left, Period? right)
Parameters
Type Name Description
Period left The left hand side of the operator.
Period right The right hand side of the operator.
Returns
Type Description
bool true if values are not equal to each other, otherwise false.

operator -(Period, Period)

Subtracts one period from another, by simply subtracting each property value.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
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").

operator -(Period)

Implements the unary negation operator.
Since 3.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period operator -(Period period)
Parameters
Type Name Description
Period period Period to negate
Returns
Type Description
Period The negative value of this period

operator +(Period)

Implements the operator + (unary).
Since 3.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Period operator +(Period period)
Parameters
Type Name Description
Period period The period.
Returns
Type Description
Period The same period Period as provided.

Implements