Struct LocalDate

LocalDate is an immutable struct representing a date within the calendar, with no reference to a particular time zone or time of day.
Since 1.0.x
Availability net35-Client, PCL
Implements
IEquatable<LocalDate>
IComparable<LocalDate>
IComparable
IFormattable
Inherited Members
Object.Equals(Object, Object)
Object.ReferenceEquals(Object, Object)
Object.GetType()
Namespace: NodaTime
Assembly: NodaTime.dll
Syntax
public struct LocalDate : IEquatable<LocalDate>, IComparable<LocalDate>, IComparable, IFormattable
Remarks

Comparisons of dates can be handled in a way which is either calendar-sensitive or calendar-insensitive. Noda Time implements all the operators (and the Equals(LocalDate) method) such that all operators other than Inequality(LocalDate, LocalDate) will return false if asked to compare two values in different calendar systems.

However, the CompareTo(LocalDate) method (implementing System.IComparable<T>) is calendar-insensitive; it compares the two dates historically in terms of when they actually occurred, as if they're both converted to some "neutral" calendar system first.

It's unclear at the time of this writing whether this is the most appropriate approach, and it may change in future versions. In general, it would be a good idea for users to avoid comparing dates in different calendar systems, and indeed most users are unlikely to ever explicitly consider which calendar system they're working in anyway.

Constructors

LocalDate(Era, Int32, Int32, Int32)

Constructs an instance for the given era, year of era, month and day in the ISO calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate(Era era, int yearOfEra, int month, int day)
Parameters
Type Name Description
Era era The era within which to create a date. Must be a valid era within the ISO calendar.
Int32 yearOfEra The year of era.
Int32 month The month of year.
Int32 day The day of month.
Exceptions
Type Condition
ArgumentOutOfRangeException The parameters do not form a valid date.

LocalDate(Era, Int32, Int32, Int32, CalendarSystem)

Constructs an instance for the given era, year of era, month and day in the specified calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate(Era era, int yearOfEra, int month, int day, CalendarSystem calendar)
Parameters
Type Name Description
Era era The era within which to create a date. Must be a valid era within the specified calendar.
Int32 yearOfEra The year of era.
Int32 month The month of year.
Int32 day The day of month.
CalendarSystem calendar Calendar system in which to create the date.
Exceptions
Type Condition
ArgumentOutOfRangeException The parameters do not form a valid date.
System.ArgumentNullException calendar is null.

LocalDate(Int32, Int32, Int32)

Constructs an instance for the given year, month and day in the ISO calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate(int year, int month, int day)
Parameters
Type Name Description
Int32 year The year. This is the "absolute year", so a value of 0 means 1 BC, for example.
Int32 month The month of year.
Int32 day The day of month.
Exceptions
Type Condition
ArgumentOutOfRangeException The parameters do not form a valid date.

LocalDate(Int32, Int32, Int32, CalendarSystem)

Constructs an instance for the given year, month and day in the specified calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate(int year, int month, int day, CalendarSystem calendar)
Parameters
Type Name Description
Int32 year The year. This is the "absolute year", so, for the ISO calendar, a value of 0 means 1 BC, for example.
Int32 month The month of year.
Int32 day The day of month.
CalendarSystem calendar Calendar system in which to create the date.
Exceptions
Type Condition
ArgumentOutOfRangeException The parameters do not form a valid date.
System.ArgumentNullException calendar is null.

Properties

Calendar

Gets the calendar system associated with this local date.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public CalendarSystem Calendar { get; }
Property Value
Type Description
CalendarSystem

Day

Gets the day of this local date within the month.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int Day { get; }
Property Value
Type Description
Int32

DayOfWeek

Gets the week day of this local date as a number.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int DayOfWeek { get; }
Property Value
Type Description
Int32
Remarks
For calendars using ISO week days, this gives 1 for Monday to 7 for Sunday.
See Also

DayOfYear

Gets the day of this local date within the year.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int DayOfYear { get; }
Property Value
Type Description
Int32

Era

Gets the era of this local date.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public Era Era { get; }
Property Value
Type Description
Era

IsoDayOfWeek

Gets the week day of this local date expressed as an IsoDayOfWeek value, for calendars which use ISO days of the week.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public IsoDayOfWeek IsoDayOfWeek { get; }
Property Value
Type Description
IsoDayOfWeek
Exceptions
Type Condition
System.InvalidOperationException The underlying calendar doesn't use ISO days of the week.
See Also

Month

Gets the month of this local date within the year.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int Month { get; }
Property Value
Type Description
Int32

WeekOfWeekYear

Gets the week within the WeekYear. See WeekYear for more details.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int WeekOfWeekYear { get; }
Property Value
Type Description
Int32

WeekYear

Gets the "week year" of this local date.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int WeekYear { get; }
Property Value
Type Description
Int32
Remarks

The WeekYear is the year that matches with the WeekOfWeekYear field. In the standard ISO8601 week algorithm, the first week of the year is that in which at least 4 days are in the year. As a result of this definition, day 1 of the first week may be in the previous year. The WeekYear allows you to query the effective year for that day.

For example, January 1st 2011 was a Saturday, so only two days of that week (Saturday and Sunday) were in 2011. Therefore January 1st is part of week 52 of WeekYear 2010. Conversely, December 31st 2012 is a Monday, so is part of week 1 of WeekYear 2013.

Year

Gets the year of this local date.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int Year { get; }
Property Value
Type Description
Int32
Remarks
This returns the "absolute year", so, for the ISO calendar, a value of 0 means 1 BC, for example.

YearOfCentury

Gets the year of this local date within the century.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int YearOfCentury { get; }
Property Value
Type Description
Int32
Remarks
This always returns a value in the range 0 to 99 inclusive.

YearOfEra

Gets the year of this local date within the era.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int YearOfEra { get; }
Property Value
Type Description
Int32

Methods

Add(LocalDate, Period)

Adds the specified period to the date. Friendly alternative to operator+().
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static LocalDate Add(LocalDate date, Period period)
Parameters
Type Name Description
LocalDate date The date to add the period to
Period period The period to add. Must not contain any (non-zero) time units.
Returns
Type Description
LocalDate The sum of the given date and period

AtMidnight()

Gets a LocalDateTime at midnight on the date represented by this local date.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDateTime AtMidnight()
Returns
Type Description
LocalDateTime The LocalDateTime representing midnight on tthis local date, in the same calendar system.

CompareTo(LocalDate)

Indicates whether this date is earlier, later or the same as another one.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int CompareTo(LocalDate other)
Parameters
Type Name Description
LocalDate other The other date to compare this one with
Returns
Type Description
Int32 A value less than zero if this date is earlier than other; zero if this date is the same as other; a value greater than zero if this date is later than other.
Remarks
The comparison is performed in terms of a calendar-independent notion of date; the calendar systems of both LocalDate values are ignored. When both values use the same calendar, this is absolutely natural. However, when comparing a value in one calendar with a value in another, this can lead to surprising results. For example, 1945 in the ISO calendar corresponds to around 1364 in the Islamic calendar, so an Islamic date in year 1400 is "after" a date in 1945 in the ISO calendar.

Equals(LocalDate)

Compares two LocalDate values for equality. This requires that the dates be the same, within the same calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public bool Equals(LocalDate other)
Parameters
Type Name Description
LocalDate other The value to compare this date with.
Returns
Type Description
Boolean True if the given value is another local date equal to this one; false otherwise.

Equals(Object)

Compares two LocalDate values for equality. This requires that the dates be the same, within the same calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
Object obj The object to compare this date with.
Returns
Type Description
Boolean True if the given value is another local date equal to this one; false otherwise.
Overrides
System.ValueType.Equals(System.Object)

FromWeekYearWeekAndDay(Int32, Int32, IsoDayOfWeek)

Returns the local date corresponding to the given "week year", "week of week year", and "day of week" in the ISO calendar system.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static LocalDate FromWeekYearWeekAndDay(int weekYear, int weekOfWeekYear, IsoDayOfWeek dayOfWeek)
Parameters
Type Name Description
Int32 weekYear ISO-8601 week year of value to return
Int32 weekOfWeekYear ISO-8601 week of week year of value to return
IsoDayOfWeek dayOfWeek ISO-8601 day of week to return
Returns
Type Description
LocalDate The date corresponding to the given week year / week of week year / day of week.

GetHashCode()

Returns a hash code for this local date.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public override int GetHashCode()
Returns
Type Description
Int32 A hash code for this local date.
Overrides
System.ValueType.GetHashCode()

Minus(Period)

Subtracts the specified period from this date. Fluent alternative to operator-().
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate Minus(Period period)
Parameters
Type Name Description
Period period The period to subtract. Must not contain any (non-zero) time units.
Returns
Type Description
LocalDate The result of subtracting the given period from this date.

Next(IsoDayOfWeek)

Returns the next LocalDate falling on the specified IsoDayOfWeek. This is a strict "next" - if this date on already falls on the target day of the week, the returned value will be a week later.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate Next(IsoDayOfWeek targetDayOfWeek)
Parameters
Type Name Description
IsoDayOfWeek targetDayOfWeek The ISO day of the week to return the next date of.
Returns
Type Description
LocalDate The next LocalDate falling on the specified day of the week.
Exceptions
Type Condition
System.InvalidOperationException The underlying calendar doesn't use ISO days of the week.
ArgumentOutOfRangeException targetDayOfWeek is not a valid day of the week (Monday to Sunday).

Plus(Period)

Adds the specified period to this date. Fluent alternative to operator+().
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate Plus(Period period)
Parameters
Type Name Description
Period period The period to add. Must not contain any (non-zero) time units.
Returns
Type Description
LocalDate The sum of this date and the given period

PlusDays(Int32)

Returns a new LocalDate representing the current value with the given number of days added.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate PlusDays(int days)
Parameters
Type Name Description
Int32 days The number of days to add
Returns
Type Description
LocalDate The current value plus the given number of days.
Remarks

This method does not try to maintain the month or year of the current value, so adding 3 days to a value of January 30th will result in a value of February 2nd.

PlusMonths(Int32)

Returns a new LocalDate representing the current value with the given number of months added.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate PlusMonths(int months)
Parameters
Type Name Description
Int32 months The number of months to add
Returns
Type Description
LocalDate The current date plus the given number of months
Remarks

This method does not try to maintain the year of the current value, so adding four months to a value in October will result in a value in the following February.

If the resulting date is invalid, the day of month is reduced to find a valid value. For example, adding one month to January 30th 2011 will return February 28th 2011; subtracting one month from March 30th 2011 will return February 28th 2011.

PlusWeeks(Int32)

Returns a new LocalDate representing the current value with the given number of weeks added.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate PlusWeeks(int weeks)
Parameters
Type Name Description
Int32 weeks The number of weeks to add
Returns
Type Description
LocalDate The current value plus the given number of weeks.

PlusYears(Int32)

Returns a new LocalDate representing the current value with the given number of years added.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate PlusYears(int years)
Parameters
Type Name Description
Int32 years The number of years to add
Returns
Type Description
LocalDate The current value plus the given number of years.
Remarks
If the resulting date is invalid, lower fields (typically the day of month) are reduced to find a valid value. For example, adding one year to February 29th 2012 will return February 28th 2013; subtracting one year from February 29th 2012 will return February 28th 2011.

Previous(IsoDayOfWeek)

Returns the previous LocalDate falling on the specified IsoDayOfWeek. This is a strict "previous" - if this date on already falls on the target day of the week, the returned value will be a week earlier.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate Previous(IsoDayOfWeek targetDayOfWeek)
Parameters
Type Name Description
IsoDayOfWeek targetDayOfWeek The ISO day of the week to return the previous date of.
Returns
Type Description
LocalDate The previous LocalDate falling on the specified day of the week.
Exceptions
Type Condition
System.InvalidOperationException The underlying calendar doesn't use ISO days of the week.
ArgumentOutOfRangeException targetDayOfWeek is not a valid day of the week (Monday to Sunday).

Subtract(LocalDate, Period)

Subtracts the specified period from the date. Friendly alternative to operator-().
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static LocalDate Subtract(LocalDate date, Period period)
Parameters
Type Name Description
LocalDate date The date to subtract the period from
Period period The period to subtract. Must not contain any (non-zero) time units.
Returns
Type Description
LocalDate The result of subtracting the given period from the date.

ToString()

Returns a System.String that represents this instance.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public override string ToString()
Returns
Type Description
String The value of the current instance in the standard format pattern, using the current thread's culture to obtain a format provider.
Overrides
System.ValueType.ToString()

ToString(String, IFormatProvider)

Formats the value of the current instance using the specified pattern.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public string ToString(string patternText, IFormatProvider formatProvider)
Parameters
Type Name Description
String patternText The System.String specifying the pattern to use, or null to use the default format pattern.
IFormatProvider formatProvider The System.IFormatProvider to use when formatting the value, or null to use the current thread's culture to obtain a format provider.
Returns
Type Description
String A System.String containing the value of the current instance in the specified format.

WithCalendar(CalendarSystem)

Creates a new LocalDate representing the same physical date, but in a different calendar. The returned LocalDate is likely to have different field values to this one. For example, January 1st 1970 in the Gregorian calendar was December 19th 1969 in the Julian calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDate WithCalendar(CalendarSystem calendarSystem)
Parameters
Type Name Description
CalendarSystem calendarSystem The calendar system to convert this local date to.
Returns
Type Description
LocalDate The converted LocalDate
Exceptions
Type Condition
System.ArgumentNullException calendarSystem is null.

Operators

Addition(LocalDate, LocalTime)

Combines the given LocalDate and LocalTime components into a single LocalDateTime.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static LocalDateTime operator +(LocalDate date, LocalTime time)
Parameters
Type Name Description
LocalDate date The date to add the time to
LocalTime time The time to add
Returns
Type Description
LocalDateTime The sum of the given date and time

Addition(LocalDate, Period)

Adds the specified period to the date.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static LocalDate operator +(LocalDate date, Period period)
Parameters
Type Name Description
LocalDate date The date to add the period to
Period period The period to add. Must not contain any (non-zero) time units.
Returns
Type Description
LocalDate The sum of the given date and period

Equality(LocalDate, LocalDate)

Compares two LocalDate values for equality. This requires that the dates be the same, within the same calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator ==(LocalDate lhs, LocalDate rhs)
Parameters
Type Name Description
LocalDate lhs The first value to compare
LocalDate rhs The second value to compare
Returns
Type Description
Boolean True if the two dates are the same and in the same calendar; false otherwise

GreaterThan(LocalDate, LocalDate)

Compares two LocalDate values to see if the left one is strictly later than the right one.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator>(LocalDate lhs, LocalDate rhs)
Parameters
Type Name Description
LocalDate lhs First operand of the comparison
LocalDate rhs Second operand of the comparison
Returns
Type Description
Boolean true if the lhs is strictly later than rhs, false otherwise.
Remarks
This operator always returns false if the two operands have different calendars. See the top-level type documentation for more information about comparisons.

GreaterThanOrEqual(LocalDate, LocalDate)

Compares two LocalDate values to see if the left one is later than or equal to the right one.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator >=(LocalDate lhs, LocalDate rhs)
Parameters
Type Name Description
LocalDate lhs First operand of the comparison
LocalDate rhs Second operand of the comparison
Returns
Type Description
Boolean true if the lhs is later than or equal to rhs, false otherwise.
Remarks
This operator always returns false if the two operands have different calendars. See the top-level type documentation for more information about comparisons.

Inequality(LocalDate, LocalDate)

Compares two LocalDate values for inequality.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator !=(LocalDate lhs, LocalDate rhs)
Parameters
Type Name Description
LocalDate lhs The first value to compare
LocalDate rhs The second value to compare
Returns
Type Description
Boolean False if the two dates are the same and in the same calendar; true otherwise

LessThan(LocalDate, LocalDate)

Compares two LocalDate values to see if the left one is strictly earlier than the right one.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator <(LocalDate lhs, LocalDate rhs)
Parameters
Type Name Description
LocalDate lhs First operand of the comparison
LocalDate rhs Second operand of the comparison
Returns
Type Description
Boolean true if the lhs is strictly earlier than rhs, false otherwise.
Remarks
This operator always returns false if the two operands have different calendars. See the top-level type documentation for more information about comparisons.

LessThanOrEqual(LocalDate, LocalDate)

Compares two LocalDate values to see if the left one is earlier than or equal to the right one.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator <=(LocalDate lhs, LocalDate rhs)
Parameters
Type Name Description
LocalDate lhs First operand of the comparison
LocalDate rhs Second operand of the comparison
Returns
Type Description
Boolean true if the lhs is earlier than or equal to rhs, false otherwise.
Remarks
This operator always returns false if the two operands have different calendars. See the top-level type documentation for more information about comparisons.

Subtraction(LocalDate, Period)

Subtracts the specified period from the date.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static LocalDate operator -(LocalDate date, Period period)
Parameters
Type Name Description
LocalDate date The date to subtract the period from
Period period The period to subtract. Must not contain any (non-zero) time units.
Returns
Type Description
LocalDate The result of subtracting the given period from the date

Explicit Interface Implementations

IComparable.CompareTo(Object)

Implementation of System.IComparable.CompareTo(System.Object) to compare two LocalDates.
Since 1.1.x
Availability net35-Client, PCL
Declaration
int IComparable.CompareTo(object obj)
Parameters
Type Name Description
Object obj The object to compare this value with.
Returns
Type Description
Int32 The result of comparing this LocalDate with another one; see CompareTo(LocalDate) for general details. If obj is null, this method returns a value greater than 0.
Remarks
This uses explicit interface implementation to avoid it being called accidentally. The generic implementation should usually be preferred.
Exceptions
Type Condition
ArgumentException obj is non-null but does not refer to an instance of LocalDate.

Implements

System.IEquatable<T>
System.IComparable<T>
System.IComparable
System.IFormattable