Early Preview

This is currently very much a preview. Please feel free to try things out, but don't be upset if anything is not yet working. Feedback is welcome over on our GitHub Dicussions page.

class NodaTime.​Period

Assembly: NodaTime

Inheritance: object → Period

Implemented Interfaces

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

Remarks

<para> A <see cref="T:NodaTime.Period" /> contains a set of properties such as <see cref="P:NodaTime.Period.Years" />, <see cref="P:NodaTime.Period.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 <see cref="T:NodaTime.Period" /> may contain values such as "2 hours and 90 minutes". The <see cref="M:NodaTime.Period.Normalize" /> method will convert equivalent periods into a standard representation. </para> <para> 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 <see cref="P:NodaTime.Period.Months" /> property returns zero in both cases). </para> <para> <see cref="T:NodaTime.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 <see cref="P:NodaTime.Period.NormalizingEqualityComparer" /> comparer provides an equality comparer which performs normalization before comparisons. </para> <para> There is no natural ordering for periods, but <see cref="M:NodaTime.Period.CreateComparer(NodaTime.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. </para> <para> Periods operate on calendar-related types such as <see cref="T:NodaTime.LocalDateTime" /> whereas <see cref="T:NodaTime.Duration" /> operates on instants on the time line. (Note that although <see cref="T:NodaTime.ZonedDateTime" /> includes both concepts, it only supports duration-based arithmetic.) </para> <para> 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. </para>

Properties

public static Period
Zero
A period containing only zero-valued properties.
public static Period
MaxValue
A period containing the maximum value for all properties.
public static Period
MinValue
A period containing the minimum value for all properties.
public static Period
AdditiveIdentity
Gets the additive identity.
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 <see cref="M:NodaTime.Period.Normalize" /> method, years and months are unchanged by normalization - so 12 months does not equal 1 year.
public long
Nanoseconds
Gets 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.
public long
Ticks
Gets 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.
public long
Milliseconds
Gets 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.
public long
Seconds
Gets 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.
public long
Minutes
Gets 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.
public long
Hours
Gets 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.
public int
Days
Gets 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.
public int
Weeks
Gets 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.
public int
Months
Gets 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.
public int
Years
Gets 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.
public bool
HasTimeComponent
Returns whether or not this period contains any non-zero-valued time-based properties (hours or lower).
public bool
HasDateComponent
Returns whether or not this period contains any non-zero date-based properties (days or higher).

Methods

public static Period
FromYears​(int years)
Creates a period representing the specified number of years.
Returns A period consisting of the given number of years.
years The number of years in the new period
public static Period
FromMonths​(int months)
Creates a period representing the specified number of months.
Returns A period consisting of the given number of months.
months The number of months in the new period
public static Period
FromWeeks​(int weeks)
Creates a period representing the specified number of weeks.
Returns A period consisting of the given number of weeks.
weeks The number of weeks in the new period
public static Period
FromDays​(int days)
Creates a period representing the specified number of days.
Returns A period consisting of the given number of days.
days The number of days in the new period
public static Period
FromHours​(long hours)
Creates a period representing the specified number of hours.
Returns A period consisting of the given number of hours.
hours The number of hours in the new period
public static Period
FromMinutes​(long minutes)
Creates a period representing the specified number of minutes.
Returns A period consisting of the given number of minutes.
minutes The number of minutes in the new period
public static Period
FromSeconds​(long seconds)
Creates a period representing the specified number of seconds.
Returns A period consisting of the given number of seconds.
seconds The number of seconds in the new period
public static Period
FromMilliseconds​(long milliseconds)
Creates a period representing the specified number of milliseconds.
Returns A period consisting of the given number of milliseconds.
milliseconds The number of milliseconds in the new period
public static Period
FromTicks​(long ticks)
Creates a period representing the specified number of ticks.
Returns A period consisting of the given number of ticks.
ticks The number of ticks in the new period
public static Period
FromNanoseconds​(long nanoseconds)
Creates a period representing the specified number of nanoseconds.
Returns A period consisting of the given number of nanoseconds.
nanoseconds The number of nanoseconds in the new period
public static Period
Add​(Period left, Period right)
Adds two periods together, by simply adding the values for each property.
Returns The sum of the two periods. The units of the result will be the union of those in both periods.
left The first period to add
right The second period to add
CreateComparer​(LocalDateTime baseDateTime)
Creates an <see cref="T:System.Collections.Generic.IComparer`1" /> for periods, using the given "base" local date/time.
Returns The new comparer.
baseDateTime The base local date/time to use for comparisons.
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 <paramref name="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.
public static Period
Subtract​(Period minuend, Period subtrahend)
Subtracts one period from another, by simply subtracting each property value.
Returns 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").
minuend The period to subtract the second operand from
subtrahend The period to subtract the first operand from
public static int
DaysBetween​(LocalDate start, LocalDate end)
Returns the number of days between two <see cref="T:NodaTime.LocalDate" /> values.
Returns The number of days between the given dates.
start Start date
end End date
public static long
NanosecondsBetween​(LocalTime start, LocalTime end)
Returns the number of nanoseconds between two <see cref="T:NodaTime.LocalTime" /> values.
Returns The number of nanoseconds between the given times.
start Start time
end End time
Remarks If <paramref name="end" /> is before <paramref name="start" /> , the returned value will be negative.
public static Period
Between​(LocalDateTime start, LocalDateTime end, PeriodUnits units)
Returns the period between a start and an end date/time, using only the given units.
Returns The period between the given date/times, using the given units.
start Start date/time
end End date/time
units Units to use for calculations
Remarks If <paramref name="end" /> is before <paramref name="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 <paramref name="start" /> will give a value between <paramref name="start" /> and <paramref name="end" /> . In other words, any rounding is "towards start"; this is true whether the resulting period is negative or positive.
public static Period
Between​(LocalDateTime start, LocalDateTime end)
Returns the exact difference between two date/times.
Returns The period between the two date and time values, using all units.
start Start date/time
end End date/time
Remarks If <paramref name="end" /> is before <paramref name="start" /> , each property in the returned period will be negative.
public static Period
Between​(LocalDate start, LocalDate end, PeriodUnits units)
Returns the period between a start and an end date, using only the given units.
Returns The period between the given dates, using the given units.
start Start date
end End date
units Units to use for calculations
Remarks If <paramref name="end" /> is before <paramref name="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 <paramref name="start" /> will give a value between <paramref name="start" /> and <paramref name="end" /> . In other words, any rounding is "towards start"; this is true whether the resulting period is negative or positive.
public static Period
Between​(LocalDate start, LocalDate end)
Returns the exact difference between two dates.
Returns The period between the two dates, using year, month and day units.
start Start date
end End date
Remarks If <paramref name="end" /> is before <paramref name="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.
public static Period
Between​(LocalTime start, LocalTime end, PeriodUnits units)
Returns the period between a start and an end time, using only the given units.
Returns The period between the given times, using the given units.
start Start time
end End time
units Units to use for calculations
Remarks If <paramref name="end" /> is before <paramref name="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 <paramref name="start" /> will give a value between <paramref name="start" /> and <paramref name="end" /> . In other words, any rounding is "towards start"; this is true whether the resulting period is negative or positive.
public static Period
Between​(LocalTime start, LocalTime end)
Returns the exact difference between two times.
Returns The period between the two times, using the time period units.
start Start time
end End time
Remarks If <paramref name="end" /> is before <paramref name="start" /> , each property in the returned period will be negative.
public static Period
Between​(YearMonth start, YearMonth end, PeriodUnits units)
Returns the period between a start and an end <see cref="T:NodaTime.YearMonth" /> , using only the given units.
Returns The period between the given YearMonths, using the given units.
start Start year and month
end End year and month
units Units to use for calculations
Remarks If <paramref name="end" /> is before <paramref name="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 <paramref name="start" /> will give a value between <paramref name="start" /> and <paramref name="end" /> . In other words, any rounding is "towards start"; this is true whether the resulting period is negative or positive.
public static Period
Between​(YearMonth start, YearMonth end)
Returns the exact difference between two <see cref="T:NodaTime.YearMonth" /> .
Returns The period between the two YearMonths, using year and month units.
start Start year and month
end End year and month
Remarks If <paramref name="end" /> is before <paramref name="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.
public Duration
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.
Returns The duration of the period.
public PeriodBuilder
ToBuilder​()
Creates a <see cref="T:NodaTime.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.
Returns A builder with the same values and units as this period.
public Period
Normalize​()
Returns a normalized version of this period, such that equivalent (but potentially non-equal) periods are changed to the same representation.
Returns 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.
public string
ToString​()
Returns this string formatted according to the <see cref="P:NodaTime.Text.PeriodPattern.Roundtrip" /> .
Returns A formatted representation of this period.
public bool
Equals​(object other)
Compares the given object for equality with this one, as per <see cref="M:NodaTime.Period.Equals(NodaTime.Period)" /> . See the type documentation for a description of equality semantics.
Returns true if the other object is a period equal to this one, consistent with <see cref="M:NodaTime.Period.Equals(NodaTime.Period)" />
other The value to compare this one with.
public int
GetHashCode​()
Returns the hash code for this period, consistent with <see cref="M:NodaTime.Period.Equals(NodaTime.Period)" /> . See the type documentation for a description of equality semantics.
Returns The hash code for this period.
public bool
Equals​(Period other)
Compares the given period for equality with this one. See the type documentation for a description of equality semantics.
Returns True if this period has the same values for the same properties as the one specified.
other The period to compare this one with.
protected void
Finalize​()
Inherited from object
GetType​()
Inherited from object
protected object
MemberwiseClone​()
Inherited from object