Class Period

Represents a period of time expressed in human chronological terms: hours, days, weeks, months and so on.

Since 1.0.x

Availability net35-Client, PCL

Inheritance

Object

Period

Implements

IEquatable<Period>

ISerializable

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

Fields

Zero

A period containing only zero-valued properties.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public static readonly Period Zero

Field Value

Type	Description
Period

Properties

Days

Gets the number of days within this period.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public long Days { get; }

Property Value

Type	Description
Int64

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 net35-Client, PCL

Declaration

public bool HasDateComponent { get; }

Property Value

Type	Description
Boolean

HasTimeComponent

Returns whether or not this period contains any non-zero-valued time-based properties (hours or lower).

Since 1.0.x

Availability net35-Client, PCL

Declaration

public bool HasTimeComponent { get; }

Property Value

Type	Description
Boolean

Hours

Gets the number of hours within this period.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public long Hours { get; }

Property Value

Type	Description
Int64

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 net35-Client, PCL

Declaration

public long Milliseconds { get; }

Property Value

Type	Description
Int64

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 net35-Client, PCL

Declaration

public long Minutes { get; }

Property Value

Type	Description
Int64

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 net35-Client, PCL

Declaration

public long Months { get; }

Property Value

Type	Description
Int64

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 net35-Client, PCL

Declaration

public static IEqualityComparer<Period> NormalizingEqualityComparer { get; }

Property Value

Type	Description
IEqualityComparer<Period>

Seconds

Gets the number of seconds within this period.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public long Seconds { get; }

Property Value

Type	Description
Int64

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 net35-Client, PCL

Declaration

public long Ticks { get; }

Property Value

Type	Description
Int64

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 net35-Client, PCL

Declaration

public long Weeks { get; }

Property Value

Type	Description
Int64

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 net35-Client, PCL

Declaration

public long Years { get; }

Property Value

Type	Description
Int64

Remarks

This property returns zero both when the property has been explicitly set to zero and when the period does not contain this property.

Methods

Between(LocalDate, LocalDate)

Returns the exact difference between two dates.

Since 1.0.x

Availability net35-Client, PCL

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.

Between(LocalDate, LocalDate, PeriodUnits)

Returns the period between a start and an end date, using only the given units.

Since 1.0.x

Availability net35-Client, PCL

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.

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 net35-Client, PCL

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.

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 net35-Client, PCL

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.

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 net35-Client, PCL

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.

Between(LocalTime, LocalTime, PeriodUnits)

Returns the period between a start and an end time, using only the given units.

Since 1.0.x

Availability net35-Client, PCL

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.

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 net35-Client, PCL

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.

Equals(Period)

Compares the given period for equality with this one.

Since 1.0.x

Availability net35-Client, PCL

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 net35-Client, PCL

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

Creates a period representing the specified number of days.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public static Period FromDays(long days)

Parameters

Type	Name	Description
Int64	days	The number of days in the new period

Returns

Type	Description
Period	A period consisting of the given number of days.

FromHours(Int64)

Creates a period representing the specified number of hours.

Since 1.0.x

Availability net35-Client, PCL

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.

FromMilliseconds(Int64)

Creates a period representing the specified number of milliseconds.

Since 1.1.x

Availability net35-Client, PCL

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.

FromMillseconds(Int64)

Creates a period representing the specified number of milliseconds.

Since 1.0.x

Availability net35-Client

Declaration

[Obsolete("Use FromMilliseconds instead. This method's name was a typo, and it will be removed in a future release.")]
public static Period FromMillseconds(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.

Remarks

This method is not available in the PCL version, as it was made obsolete in Noda Time 1.1.

FromMinutes(Int64)

Creates a period representing the specified number of minutes.

Since 1.0.x

Availability net35-Client, PCL

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.

FromMonths(Int64)

Creates a period representing the specified number of months.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public static Period FromMonths(long months)

Parameters

Type	Name	Description
Int64	months	The number of months in the new period

Returns

Type	Description
Period	A period consisting of the given number of months.

FromSeconds(Int64)

Creates a period representing the specified number of seconds.

Since 1.0.x

Availability net35-Client, PCL

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.

FromTicks(Int64)

Creates a period representing the specified number of ticks.

Since 1.0.x

Availability net35-Client, PCL

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.

FromWeeks(Int64)

Creates a period representing the specified number of weeks.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public static Period FromWeeks(long weeks)

Parameters

Type	Name	Description
Int64	weeks	The number of weeks in the new period

Returns

Type	Description
Period	A period consisting of the given number of weeks.

FromYears(Int64)

Creates a period representing the specified number of years.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public static Period FromYears(long years)

Parameters

Type	Name	Description
Int64	years	The number of years in the new period

Returns

Type	Description
Period	A period consisting of the given number of years.

GetHashCode()

Returns the hash code for this period, consistent with Equals(Period).

Since 1.0.x

Availability net35-Client, PCL

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 net35-Client, PCL

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 (where ticks are "within a millisecond"), adding to the larger property where necessary. So for example, a period of 25 hours becomes a period of 1 day and 1 hour. Aside from months and years, either all the properties end up positive, or they all end up negative.

Exceptions

Type

Condition

System.OverflowException

The period doesn't have years or months, but it contains more than System.Int64.MaxValue ticks when the combined weeks/days/time portions are considered. Such a period could never be useful anyway, however. 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.

See Also

NormalizingEqualityComparer

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 net35-Client, PCL

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 net35-Client, PCL

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

Since 1.0.x

Availability net35-Client, PCL

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 net35-Client, PCL

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.

Subtraction(Period, Period)

Subtracts one period from another, by simply subtracting each property value.

Since 1.0.x

Availability net35-Client, PCL

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

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 net35-Client

Declaration

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