DateOnlyExtensions Class

Definition

Namespace: Bodu.Extensions

Assembly: Bodu.Core.dll

Package: Bodu.Core 1.0.1

Source: DateOnlyExtensions.Add.cs

Provides calendar-arithmetic operations over DateOnly - age, period anchors, weekday navigation, week and quarter numbering, and culture-aware formatting helpers - that complement the small surface shipped with DateOnly itself.

public static class DateOnlyExtensions

Inheritance: object

DateOnlyExtensions

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

DateOnly intentionally exposes very little behavior beyond a numeric day count, leaving callers to build calendar logic by hand or to fall back to DateTime. This class supplies the period and weekday arithmetic that most scheduling, reporting, and fiscal-calendar code needs, expressed directly on DateOnly so the time component cannot leak in by accident.

The API surface clusters into four groups: relative period anchors (FirstDateOfMonth, FirstDateOfQuarter, FirstDateOfYear and their LastDateOf… counterparts), weekday navigation ( NextDateOfWeek, PreviousDateOfWeek, NearestDateOfWeek, NthDateOfWeekInMonth), period predicates and counters (IsLeapYear, IsWeekend, IsInRange, WeekOfMonth, WeekOfYear, Quarter), and culture-aware formatting (DayName, MonthName).

Methods that emit text or read Calendar data accept an optional culture or calendar argument; when omitted they fall back to CurrentCulture, so the same call produces different text on different threads. Methods that perform pure date arithmetic (period anchors, weekday navigation) are culture-neutral, allocation-free, and deterministic. ArgumentOutOfRangeException is thrown when an arithmetic operation would leave the supported DateOnly range.

When compiled with a tool-chain that supports C# 14 extension members, the parameterless predicate and scalar-accessor helpers are exposed as extension properties (for example date.IsFirstDateOfMonth); otherwise they compile as classic extension methods (for example date.IsFirstDateOfMonth()).

var date = new DateOnly(2025, 4, 30);

// Anchor to the first Monday in this month.
DateOnly firstMonday = date.FirstDateOfWeekInMonth(DayOfWeek.Monday); // => 2025-04-07

// Walk to the previous Friday, even if today is already a Friday.
DateOnly priorFriday = date.PreviousDateOfWeek(DayOfWeek.Friday); // => 2025-04-25

// Compute the calendar week within the month using ISO rules.
int weekOfMonth = date.WeekOfMonth(CalendarWeekRule.FirstFourDayWeek, DayOfWeek.Monday); // => 5

Methods

Add(DateOnly, int, int, int)

Returns a new DateOnly obtained by adding the specified number of years, months, and days to the supplied date.

public static DateOnly Add(this DateOnly date, int years, int months, int days)

Parameters

date DateOnly: The date value to which the offsets are applied.
years int: The number of calendar years to add. A negative value subtracts years.
months int: The number of calendar months to add. A negative value subtracts months.
days int: The number of days to add. A negative value subtracts days.

Returns

DateOnly: A DateOnly value adjusted by the specified number of years, months, and days.

Remarks

Adjustments are applied in the order years, then months, then days. When the resulting day does not exist in the target month (e.g. February 30), the date is clamped to the last valid day of that month, accounting for leap years and varying month lengths.

Examples:

var d1 = new DateOnly(2023, 1, 31);
var result1 = d1.Add(0, 1, 0); // → 2023-02-28 (non-leap year)

var d2 = new DateOnly(2020, 1, 31);
var result2 = d2.Add(0, 1, 0); // → 2020-02-29 (leap year)

var d3 = new DateOnly(2024, 2, 29);
var result3 = d3.Add(1, 0, 0); // → 2025-02-28 (2025 is not a leap year)

Exceptions

ArgumentOutOfRangeException: Thrown if the resulting date is earlier than MinValue or later than MaxValue.

AddFiscalYears(DateOnly, int, IQuarterDefinitionProvider)

Returns a new DateOnly obtained by advancing or retreating date by the signed number of fiscal years specified in count.

public static DateOnly AddFiscalYears(this DateOnly date, int count, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The starting date.
count int: The signed number of fiscal years to apply.
provider IQuarterDefinitionProvider: The provider that defines the fiscal year boundaries.

Returns

DateOnly: A DateOnly whose value is offset by count fiscal years, preserving the day-index within the fiscal year of date. The result is clamped to the last day of the target fiscal year when the source day-index does not fit (e.g. a Q4 53rd-week date mapped onto a 52-week year).

Exceptions

ArgumentNullException: Thrown when provider is null.

Age(DateOnly)

Returns the age in full calendar years between the specified date and today's date.

public static int Age(this DateOnly date)

Parameters

date DateOnly: The earlier date to calculate from, typically representing a birth date or other reference point.

Returns

int: The number of full calendar years that have elapsed between date and today. Returns 0 if date occurs after today.

Remarks

This overload determines the number of full years that have passed by comparing the year, month, and day components. If the month and day of date have not yet occurred in the current year, the result is decremented by one.

If date is February 29 in a leap year and today is not a leap year, the comparison is performed as if the date were February 28.

The result is clamped to 0 to avoid returning negative values when date is in the future.

Age(DateOnly, DateOnly)

Returns the age in full calendar years between the specified date and a supplied reference date.

public static int Age(this DateOnly date, DateOnly asAtDate)

Parameters

date DateOnly: The earlier date to calculate from, typically representing a birth date or other reference point.
asAtDate DateOnly: The later date to calculate to, representing the point in time at which the age is evaluated.

Returns

int: The number of full calendar years that have elapsed between date and asAtDate. Returns 0 if asAtDate occurs before date.

Remarks

This overload determines the number of full years that have passed by comparing the year, month, and day components. If the month and day of date have not yet occurred in the year of asAtDate, the result is decremented by one.

If date is February 29 in a leap year and asAtDate is in a non-leap year, the comparison is performed as if the date were February 28.

The result is clamped to 0 to avoid returning negative values when date is after asAtDate.

DayName(DateOnly)

Returns the full name of the day of the week for the specified DateOnly, using the formatting rules of CurrentCulture.

public static string DayName(this DateOnly date)

Parameters

date DateOnly: The date value whose DayOfWeek is used to determine the name.

Returns

string: A string containing the localized full day name, formatted using CurrentCulture.

Remarks

This overload uses the GetDayName(DayOfWeek) method of the current culture to retrieve the day name. For culture-specific results, use the DayName(DateOnly, CultureInfo?) overload.

DayName(DateOnly, CultureInfo?)

Returns the full name of the day of the week for the specified DateOnly, using the formatting rules of the supplied or current culture.

public static string DayName(this DateOnly date, CultureInfo? culture)

Parameters

date DateOnly: The date value whose DayOfWeek is used to determine the name.
culture CultureInfo: An optional CultureInfo used to format the result. If null, CurrentCulture is used.

Returns

string: A string containing the localized full day name for date, formatted using the supplied or current culture.

Remarks

This overload uses the GetDayName(DayOfWeek) method of the supplied or current culture to retrieve the day name.

DaysInMonth(DateOnly)

Returns the number of days in the calendar month of the specified DateOnly, using the proleptic Gregorian calendar.

public static int DaysInMonth(this DateOnly date)

Parameters

date DateOnly: The date value whose year and month are used to determine the result.

Returns

int: The total number of days in the specified month and year of date, based on the GregorianCalendar.

Remarks

This overload always evaluates the result using the proleptic Gregorian calendar, regardless of the current culture or calendar settings. For culture-specific results, use the DaysInMonth(DateOnly, CultureInfo?) or DaysInMonth(DateOnly, Calendar?) overload.

DaysInMonth(DateOnly, Calendar?)

Returns the number of days in the calendar month of the specified DateOnly, using the supplied or current culture's calendar.

public static int DaysInMonth(this DateOnly date, Calendar? calendar)

Parameters

date DateOnly: The date value whose year and month are used to determine the result.
calendar Calendar: An optional Calendar instance used to evaluate the result. If null, the Calendar of CurrentCulture is used.

Returns

int: The total number of days in the specified month and year of date, based on the rules of the supplied or current calendar.

Remarks

This overload supports calendar-aware computations for systems such as HebrewCalendar, HijriCalendar, JapaneseCalendar, and others supported by .NET. date is first projected into the target calendar, so the result is equivalent to calendar.GetDaysInMonth(calendar.GetYear(dateTime), calendar.GetMonth(dateTime)) for the DateTime at midnight of date - the length of the calendar's own month containing the date, not the Gregorian month. If calendar is null, the Calendar of CurrentCulture is used.

This method does not account for leap months. For calendars that support leap months or multiple eras, consider using GetDaysInMonth(year, month, era) instead.

DaysInMonth(DateOnly, CultureInfo?)

Returns the number of days in the calendar month of the specified DateOnly, using the calendar associated with the supplied culture.

public static int DaysInMonth(this DateOnly date, CultureInfo? culture)

Parameters

date DateOnly: The date value whose year and month are used to determine the result.
culture CultureInfo: An optional CultureInfo that supplies the calendar. If null, CurrentCulture is used.

Returns

int: The total number of days in the specified month and year of date, based on the calendar of culture.

Remarks

This overload retrieves the Calendar from the culture's Calendar property and returns the number of days in the month of that calendar's own year/month reckoning that contains date.

This is useful when working with cultures that use non-Gregorian calendars such as HebrewCalendar or HijriCalendar. If the calendar supports leap months or eras, this method does not account for them explicitly. For precise control, use the overload that accepts a Calendar directly.

DaysInYear(DateOnly)

Returns the number of days in the calendar year of the specified DateOnly, using the calendar of CurrentCulture.

public static int DaysInYear(this DateOnly date)

Parameters

date DateOnly: The date value whose year is used to determine the result.

Returns

int: The total number of days in the year of date, as defined by the calendar of CurrentCulture.

Remarks

This overload uses the calendar the current culture is set to use: the Calendar of CurrentCulture, which is not necessarily the culture's default Calendar. The result may vary depending on the calendar system (e.g. Gregorian, Hebrew, Hijri).

DaysInYear(DateOnly, Calendar?)

Returns the number of days in the calendar year of the specified DateOnly, using the supplied or current calendar.

public static int DaysInYear(this DateOnly date, Calendar? calendar)

Parameters

date DateOnly: The date value whose year is used to determine the result.
calendar Calendar: An optional Calendar used to evaluate the result. If null, the Calendar of CurrentCulture is used.

Returns

int: The number of days in the year of date, based on the supplied or fallback calendar.

Remarks

Use this overload when you want to explicitly calculate based on a specific calendar system (e.g. GregorianCalendar, HebrewCalendar). If calendar is null, the Calendar of CurrentCulture is used.

date is first projected into the target calendar, so the result is equivalent to calendar.GetDaysInYear(calendar.GetYear(dateTime)) for the DateTime at midnight of date - the length of the calendar's own year containing the date, not the Gregorian year.

FirstDateOfFiscalYear(int, IQuarterDefinitionProvider)

Returns the first calendar day of the supplied fiscal year under the supplied IQuarterDefinitionProvider.

public static DateOnly FirstDateOfFiscalYear(int fiscalYear, IQuarterDefinitionProvider provider)

Parameters

fiscalYear int: The fiscal year whose start date is requested.
provider IQuarterDefinitionProvider: The provider that defines the fiscal year boundaries.

Returns

DateOnly: A DateOnly representing the first day of the fiscal year.

Exceptions

ArgumentNullException: Thrown when provider is null.

FirstDateOfMonth(DateOnly)

Returns a new DateOnly representing the first day of the same calendar month and year as the specified date.

public static DateOnly FirstDateOfMonth(this DateOnly date)

Parameters

date DateOnly: The date value whose year and month are used to determine the result.

Returns

DateOnly: A DateOnly value set to the first day of the same calendar month and year as date.

Remarks

This method calculates the first day of the month using Gregorian calendar rules.

Example:

var date = new DateOnly(2025, 7, 15);
var result = date.FirstDateOfMonth(); // → 2025-07-01

FirstDateOfQuarter(DateOnly)

Returns a new DateOnly representing the first day of the calendar quarter that contains the specified date, using the standard calendar quarter definition.

public static DateOnly FirstDateOfQuarter(this DateOnly date)

Parameters

date DateOnly: The date value used to determine the containing quarter.

Returns

DateOnly: A DateOnly value set to the first day of the quarter that contains date.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember:

Q1January - March
Q2April - June
Q3July - September
Q4October - December

FirstDateOfQuarter(DateOnly, CalendarQuarterDefinition)

Returns a new DateOnly representing the first day of the quarter that contains the specified date, using the specified calendar quarter definition.

public static DateOnly FirstDateOfQuarter(this DateOnly date, CalendarQuarterDefinition definition)

Parameters

date DateOnly: The date value used to determine the containing quarter.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how quarter boundaries are aligned.

Returns

DateOnly: A DateOnly value set to the first day of the corresponding quarter.

Remarks

The definition controls whether quarters are aligned to the first day of a month (e.g. January - March) or anchored to a custom day-of-month boundary.

For provider-driven (e.g. 4-4-5 fiscal) quarters, use the FirstDateOfQuarter(DateOnly, IQuarterDefinitionProvider) overload instead.

Exceptions

ArgumentOutOfRangeException: Thrown if definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use the provider-based overload instead.

FirstDateOfQuarter(DateOnly, IQuarterDefinitionProvider)

Returns a new DateOnly representing the first day of the quarter that contains the specified date, using a custom IQuarterDefinitionProvider.

public static DateOnly FirstDateOfQuarter(this DateOnly date, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The date value used to determine the containing quarter.
provider IQuarterDefinitionProvider: The IQuarterDefinitionProvider that defines custom quarter boundaries. Must not be null.

Returns

DateOnly: A DateOnly value set to the first day of the quarter containing date.

Remarks

This overload supports advanced or domain-specific quarter systems by delegating boundary logic to the supplied provider - for example, 4-4-5 retail calendars or regional fiscal quarters.

Exceptions

ArgumentNullException: Thrown if provider is null.
ArgumentOutOfRangeException: Thrown if the provider returns a date outside the range of MinValue and MaxValue.

FirstDateOfWeek(DateOnly)

Returns a new DateOnly representing the first day of the week that contains the specified date, using the first day of the week defined by CurrentCulture.

public static DateOnly FirstDateOfWeek(this DateOnly date)

Parameters

date DateOnly: The date value used to determine the containing week.

Returns

DateOnly: A DateOnly value set to the culturally defined first day of the week containing date.

Remarks

This overload uses CurrentCulture to determine the first day of the week, based on FirstDayOfWeek.

FirstDateOfWeek(DateOnly, WorkingDaysOfWeek)

Returns a new DateOnly representing the first day of the week that contains the specified date, using a start-of-week inferred from the specified WorkingDaysOfWeek.

public static DateOnly FirstDateOfWeek(this DateOnly date, WorkingDaysOfWeek workingWeek)

Parameters

date DateOnly: The date value used to determine the containing week.
workingWeek WorkingDaysOfWeek: A WorkingDaysOfWeek used to infer the first day of the week. For example, MondayToFriday implies a Monday start.

Returns

DateOnly: A DateOnly value set to the first day of the week containing date.

Remarks

The method infers the start of the week based on the specified workingWeek value. If AllDays is supplied, the method defaults to using Monday.

Exceptions

ArgumentOutOfRangeException: Thrown if workingWeek is not a defined WorkingDaysOfWeek value, -or- the resulting date is earlier than MinValue.

FirstDateOfWeek(DateOnly, CultureInfo?)

Returns a new DateOnly representing the first day of the week that contains the specified date, using the first day of the week defined by the supplied or current culture.

public static DateOnly FirstDateOfWeek(this DateOnly date, CultureInfo? culture)

Parameters

date DateOnly: The date value used to determine the containing week.
culture CultureInfo: An optional CultureInfo that defines the first day of the week via FirstDayOfWeek. If null, CurrentCulture is used.

Returns

DateOnly: A DateOnly value set to the culturally defined first day of the week containing date.

Remarks

This method computes the day offset between date and the culture-specific first day of the week, and subtracts that offset.

Exceptions

ArgumentOutOfRangeException: Thrown if the resulting date is earlier than MinValue.

FirstDateOfWeekInMonth(DateOnly, DayOfWeek)

Returns a new DateOnly representing the first occurrence of the specified DayOfWeek within the same calendar month and year as the specified date.

public static DateOnly FirstDateOfWeekInMonth(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The date value whose month and year are used to determine the result.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the month. For example, Monday returns the first Monday.

Returns

DateOnly: A DateOnly value set to the first occurrence of dayOfWeek within the same calendar month and year as date.

Remarks

The search begins on the first day of the month and proceeds forward to locate the first matching weekday.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

FirstDateOfWeekInQuarter(DateOnly, DayOfWeek)

Returns a new DateOnly representing the first occurrence of the specified DayOfWeek within the calendar quarter that contains the specified date, using the standard calendar quarter definition.

public static DateOnly FirstDateOfWeekInQuarter(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The date value used to determine the containing quarter.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the quarter. For example, Monday returns the first Monday.

Returns

DateOnly: A DateOnly value set to the first occurrence of dayOfWeek within the quarter that contains date.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember. The search begins on the first day of the quarter and proceeds forward to locate the first matching weekday.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

FirstDateOfWeekInQuarter(DateOnly, DayOfWeek, CalendarQuarterDefinition)

Returns a new DateOnly representing the first occurrence of the specified DayOfWeek within the quarter that contains the specified date, using the supplied calendar quarter definition.

public static DateOnly FirstDateOfWeekInQuarter(this DateOnly date, DayOfWeek dayOfWeek, CalendarQuarterDefinition definition)

Parameters

date DateOnly: The date value used to determine the containing quarter.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the quarter. For example, Monday returns the first Monday.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how quarter boundaries are aligned.

Returns

DateOnly: A DateOnly value set to the first occurrence of dayOfWeek within the quarter that contains date.

Remarks

The start of the quarter is computed using definition, and the search proceeds forward to the first date that matches the specified dayOfWeek.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration, -or- definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use the provider-based overload instead.

FirstDateOfWeekInQuarter(DateOnly, DayOfWeek, IQuarterDefinitionProvider)

Returns a new DateOnly representing the first occurrence of the specified DayOfWeek within the quarter that contains the specified date, using a custom IQuarterDefinitionProvider.

public static DateOnly FirstDateOfWeekInQuarter(this DateOnly date, DayOfWeek dayOfWeek, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The date value used to determine the containing quarter.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the quarter. For example, Monday returns the first Monday.
provider IQuarterDefinitionProvider: The IQuarterDefinitionProvider that defines custom quarter boundaries. Must not be null.

Returns

DateOnly: A DateOnly value set to the first occurrence of dayOfWeek within the quarter that contains date.

Remarks

The start of the quarter is determined by the supplied provider, and the search proceeds forward to the first date that matches the specified dayOfWeek.

Exceptions

ArgumentNullException: Thrown if provider is null.
ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

FirstDateOfWeekInYear(DateOnly, DayOfWeek)

Returns a new DateOnly representing the first occurrence of the specified DayOfWeek within the same calendar year as the specified date.

public static DateOnly FirstDateOfWeekInYear(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The date value whose year is used to determine the result.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the year. For example, Monday returns the first Monday.

Returns

DateOnly: A DateOnly value set to the first occurrence of dayOfWeek within the same calendar year as date.

Remarks

The search begins on January 1 of the year and proceeds forward to locate the first matching weekday.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

FirstDateOfYear(DateOnly)

Returns a new DateOnly representing the first day of the same calendar year as the specified date.

public static DateOnly FirstDateOfYear(this DateOnly date)

Parameters

date DateOnly: The date value whose year is used to determine the result.

Returns

DateOnly: A DateOnly value set to January 1 of the same calendar year as date.

Remarks

This method calculates the first day of the year using Gregorian calendar rules.

Example:

var date = new DateOnly(2025, 7, 15);
var result = date.FirstDateOfYear(); // → 2025-01-01

FiscalYear(DateOnly, IQuarterDefinitionProvider)

Returns the fiscal year that contains the supplied DateOnly under the supplied IQuarterDefinitionProvider.

public static int FiscalYear(this DateOnly date, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The date to identify.
provider IQuarterDefinitionProvider: The provider that defines the fiscal year boundaries.

Returns

int: The fiscal year number under the provider's conventions.

Exceptions

ArgumentNullException: Thrown when provider is null.

FromDayOfYear(int, int)

Returns a new DateOnly representing the dayOfYear-th day of the specified year.

public static DateOnly FromDayOfYear(int year, int dayOfYear)

Parameters

year int: The calendar year to evaluate.
dayOfYear int: The one-based ordinal day within the year.

Returns

DateOnly: A DateOnly value set to the date that is the dayOfYear-th day of year.

Remarks

This method is the inverse of the DayOfYear property. Day numbering is one-based, so day 1 is January 1 and the final day (365 in a common year, 366 in a leap year) is December 31.

The mapping depends on whether year is a leap year: day 60 resolves to February 29 in a leap year but to March 1 in a common year.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than 1 or greater than 9999, -or- dayOfYear is less than 1 or greater than the number of days in year (365 in a common year, 366 in a leap year).

FromUnixTimeMilliseconds(long)

Returns a new DateOnly representing the calendar date corresponding to the specified Unix timestamp, expressed in milliseconds since 1970-01-01T00:00:00Z.

public static DateOnly FromUnixTimeMilliseconds(long timestamp)

Parameters

timestamp long: The number of milliseconds that have elapsed since the Unix epoch.

Returns

DateOnly: A DateOnly value representing the calendar date in UTC corresponding to timestamp.

Remarks

Use ToUnixTimeMilliseconds(DateOnly) to perform the inverse conversion.

Exceptions

ArgumentOutOfRangeException: Thrown if timestamp is outside the range supported for conversion to DateOnly .

See Also: ToUnixTimeMilliseconds(DateOnly)

FromUnixTimeSeconds(long)

Returns a new DateOnly representing the calendar date corresponding to the specified Unix timestamp, expressed in seconds since 1970-01-01T00:00:00Z.

public static DateOnly FromUnixTimeSeconds(long timestamp)

Parameters

timestamp long: The number of seconds that have elapsed since the Unix epoch.

Returns

DateOnly: A DateOnly value representing the calendar date in UTC corresponding to timestamp.

Remarks

Use ToUnixTimeSeconds(DateOnly) to perform the inverse conversion.

Exceptions

ArgumentOutOfRangeException: Thrown if timestamp is outside the range supported for conversion to DateOnly .

See Also: ToUnixTimeSeconds(DateOnly)

GetFirstDateOfIsoWeek(int, int)

Returns a new DateOnly representing the first day (Monday) of the specified ISO 8601 week and year.

public static DateOnly GetFirstDateOfIsoWeek(int isoYear, int isoWeek)

Parameters

isoYear int: The ISO 8601 year, defined as the year containing the Thursday of the first ISO week. Must be between the Year property values of MinValue and MaxValue, inclusive.
isoWeek int: The ISO 8601 week number to evaluate, ranging from 1 to the number of ISO weeks in the supplied year.

Returns

DateOnly: A DateOnly value set to the Monday that begins the specified ISO 8601 week.

Remarks

This method computes the first day of a given ISO 8601 week by anchoring on January 4 (which always falls in ISO week 1), then backtracking to the preceding Monday and advancing by the supplied number of weeks.

The ISO 8601 calendar follows these rules:

weeks begin on Monday;
week 1 is the first week containing at least four days of the new year;
years contain either 52 or 53 weeks.

This member delegates to GetFirstDateOfIsoWeek(int, int) - the twins share one implementation, so both surfaces always agree.

Exceptions

ArgumentOutOfRangeException: Thrown if isoYear is less than the Year of MinValue or greater than that of MaxValue, -or- isoWeek is less than 1 or greater than the number of ISO weeks in isoYear.

GetFirstDateOfMonth(int, int)

Returns a new DateOnly representing the first day of the specified calendar month and year.

public static DateOnly GetFirstDateOfMonth(int year, int month)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
month int: The calendar month of the result. Must be between 1 and 12, inclusive, where 1 represents January and 12 represents December.

Returns

DateOnly: A DateOnly value set to the first day of the specified month and year.

Remarks

This method uses Gregorian calendar rules to determine the resulting date.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue, -or- month is less than 1 or greater than 12.

GetFirstDateOfQuarter(int, int)

Returns a new DateOnly representing the first day of the specified calendar quarter in the given year, using the standard calendar quarter definition.

public static DateOnly GetFirstDateOfQuarter(int year, int quarter)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
quarter int: The quarter number, from 1 (Jan - Mar) through 4 (Oct - Dec).

Returns

DateOnly: A DateOnly value set to the first day of the specified quarter and year.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember.

Exceptions

ArgumentOutOfRangeException: Thrown if quarter is less than 1 or greater than 4.

GetFirstDateOfQuarter(int, int, CalendarQuarterDefinition)

Returns a new DateOnly representing the first day of the specified quarter and year, using the supplied calendar quarter definition.

public static DateOnly GetFirstDateOfQuarter(int year, int quarter, CalendarQuarterDefinition definition)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive. If the quarter begins in the next calendar year (based on the definition's anchor), the year will be incremented accordingly.
quarter int: The quarter number, from 1 through 4.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how quarters are aligned.

Returns

DateOnly: A DateOnly value set to the first day of the specified quarter.

Remarks

The definition controls whether quarters are aligned to the first day of a month or anchored to a custom day-of-month boundary.

Exceptions

ArgumentOutOfRangeException: Thrown if quarter is less than 1 or greater than 4, -or- definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use a provider-based overload instead.

GetFirstDateOfWeekInMonth(int, int, DayOfWeek)

Returns a new DateOnly representing the first occurrence of the specified DayOfWeek in the given month and year.

public static DateOnly GetFirstDateOfWeekInMonth(int year, int month, DayOfWeek dayOfWeek)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
month int: The calendar month of the result, from 1 through 12.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the month. For example, Monday returns the first Monday.

Returns

DateOnly: A DateOnly value set to the first occurrence of dayOfWeek within the specified month and year.

Remarks

The search begins on the first day of the month and proceeds forward to locate the first matching weekday.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue, -or- month is less than 1 or greater than 12, -or- dayOfWeek is not a defined value of the DayOfWeek enumeration.

GetFirstDateOfWeekInQuarter(int, int, DayOfWeek)

Returns a new DateOnly representing the first occurrence of the specified DayOfWeek within the specified calendar quarter and year, using the standard calendar quarter definition.

public static DateOnly GetFirstDateOfWeekInQuarter(int year, int quarter, DayOfWeek dayOfWeek)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
quarter int: The quarter number, from 1 (Jan - Mar) through 4 (Oct - Dec).
dayOfWeek DayOfWeek: The DayOfWeek to locate within the quarter. For example, Monday returns the first Monday.

Returns

DateOnly: A DateOnly value set to the first occurrence of dayOfWeek within the specified quarter and year.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue, -or- quarter is less than 1 or greater than 4, -or- dayOfWeek is not a defined value of the DayOfWeek enumeration.

GetFirstDateOfWeekInQuarter(int, int, DayOfWeek, CalendarQuarterDefinition)

Returns a new DateOnly representing the first occurrence of the specified DayOfWeek within the specified quarter and year, using the supplied calendar quarter definition.

public static DateOnly GetFirstDateOfWeekInQuarter(int year, int quarter, DayOfWeek dayOfWeek, CalendarQuarterDefinition definition)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
quarter int: The quarter number, from 1 through 4.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the quarter. For example, Monday returns the first Monday.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how quarter boundaries are aligned.

Returns

DateOnly: A DateOnly value set to the first occurrence of dayOfWeek within the specified quarter and year.

Remarks

The start of the quarter is computed using definition, and the search proceeds forward to the first date that matches the specified dayOfWeek.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue, -or- quarter is less than 1 or greater than 4, -or- dayOfWeek is not a defined value of the DayOfWeek enumeration, -or- definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use the provider-based overload instead.

GetIsoWeeksInYear(int)

Returns the number of ISO 8601 weeks in the specified year.

public static int GetIsoWeeksInYear(int year)

Parameters

year int: The ISO 8601 year to evaluate. Must be between the Year property values of MinValue and MaxValue, inclusive.

Returns

int: The number of ISO 8601 weeks in the supplied year - either 52 or 53.

Remarks

According to ISO 8601, a year contains 53 weeks if either of the following is true:

January 1 of the supplied year falls on a Thursday;
December 31 of the supplied year falls on a Thursday (equivalent to January 1 of the following year falling on a Friday).

All other years contain exactly 52 weeks. This member delegates to GetIsoWeeksInYear(int) - the twins share one implementation, so both surfaces always agree.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue.

GetLastDateOfIsoWeek(int, int)

Returns a new DateOnly representing the last day (Sunday) of the specified ISO 8601 week and year.

public static DateOnly GetLastDateOfIsoWeek(int isoYear, int isoWeek)

Parameters

isoYear int: The ISO 8601 year, defined as the year containing the Thursday of the first ISO week. Must be between the Year property values of MinValue and MaxValue, inclusive.
isoWeek int: The ISO 8601 week number to evaluate, ranging from 1 to the number of ISO weeks in the supplied year.

Returns

DateOnly: A DateOnly value set to the Sunday that ends the specified ISO 8601 week.

Remarks

This method computes the last day of a given ISO 8601 week by anchoring on January 4 (which always falls in ISO week 1), backtracking to the preceding Monday, advancing by the supplied number of weeks, and adding six days to reach the Sunday of that week.

The ISO 8601 calendar follows these rules:

weeks begin on Monday and end on Sunday;
week 1 is the first week containing at least four days of the new year;
years contain either 52 or 53 weeks.

For the corresponding start of the week, use GetFirstDateOfIsoWeek(int, int). This member delegates to GetLastDateOfIsoWeek(int, int) - the twins share one implementation, so both surfaces always agree.

Exceptions

ArgumentOutOfRangeException: Thrown if isoYear is less than the Year of MinValue or greater than that of MaxValue, -or- isoWeek is less than 1 or greater than the number of ISO weeks in isoYear.

GetLastDateOfMonth(int, int)

Returns a new DateOnly representing the last day of the specified calendar month and year.

public static DateOnly GetLastDateOfMonth(int year, int month)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
month int: The calendar month of the result. Must be between 1 and 12, inclusive, where 1 represents January and 12 represents December.

Returns

DateOnly: A DateOnly value set to the last day of the specified month and year.

Remarks

This method uses Gregorian calendar rules to determine the number of days in the specified month, including leap-year adjustments for February.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue, -or- month is less than 1 or greater than 12.

GetLastDateOfQuarter(int, int)

Returns a new DateOnly representing the last day of the specified calendar quarter in the given year, using the standard calendar quarter definition.

public static DateOnly GetLastDateOfQuarter(int year, int quarter)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
quarter int: The quarter number, from 1 (Jan - Mar) through 4 (Oct - Dec).

Returns

DateOnly: A DateOnly value set to the last day of the specified quarter and year.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember.

Exceptions

ArgumentOutOfRangeException: Thrown if quarter is less than 1 or greater than 4.

GetLastDateOfQuarter(int, int, CalendarQuarterDefinition)

Returns a new DateOnly representing the last day of the specified quarter and year, using the supplied calendar quarter definition.

public static DateOnly GetLastDateOfQuarter(int year, int quarter, CalendarQuarterDefinition definition)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive. If the quarter ends in the next calendar year (based on the definition's anchor), the year will be incremented accordingly.
quarter int: The quarter number, from 1 through 4.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how quarters are aligned.

Returns

DateOnly: A DateOnly value set to the last day of the specified quarter.

Remarks

The definition controls whether quarters are aligned to the first day of a month or anchored to a custom day-of-month boundary.

Exceptions

ArgumentOutOfRangeException: Thrown if quarter is less than 1 or greater than 4, -or- definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use a provider-based overload instead.

GetLastDateOfWeekInMonth(int, int, DayOfWeek)

Returns a new DateOnly representing the last occurrence of the specified DayOfWeek in the given month and year.

public static DateOnly GetLastDateOfWeekInMonth(int year, int month, DayOfWeek dayOfWeek)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
month int: The calendar month of the result, from 1 through 12.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the month. For example, Monday returns the last Monday.

Returns

DateOnly: A DateOnly value set to the last occurrence of dayOfWeek within the specified month and year.

Remarks

The search begins on the last day of the month and proceeds backward to locate the last matching weekday.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue, -or- month is less than 1 or greater than 12, -or- dayOfWeek is not a defined value of the DayOfWeek enumeration.

GetLastDateOfWeekInQuarter(int, int, DayOfWeek)

Returns a new DateOnly representing the last occurrence of the specified DayOfWeek within the specified calendar quarter and year, using the standard calendar quarter definition.

public static DateOnly GetLastDateOfWeekInQuarter(int year, int quarter, DayOfWeek dayOfWeek)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
quarter int: The quarter number, from 1 (Jan - Mar) through 4 (Oct - Dec).
dayOfWeek DayOfWeek: The DayOfWeek to locate within the quarter. For example, Monday returns the last Monday.

Returns

DateOnly: A DateOnly value set to the last occurrence of dayOfWeek within the specified quarter and year.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue, -or- quarter is less than 1 or greater than 4, -or- dayOfWeek is not a defined value of the DayOfWeek enumeration.

GetLastDateOfWeekInQuarter(int, int, DayOfWeek, CalendarQuarterDefinition)

Returns a new DateOnly representing the last occurrence of the specified DayOfWeek within the specified quarter and year, using the supplied calendar quarter definition.

public static DateOnly GetLastDateOfWeekInQuarter(int year, int quarter, DayOfWeek dayOfWeek, CalendarQuarterDefinition definition)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
quarter int: The quarter number, from 1 through 4.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the quarter. For example, Monday returns the last Monday.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how quarter boundaries are aligned.

Returns

DateOnly: A DateOnly value set to the last occurrence of dayOfWeek within the specified quarter and year.

Remarks

The end of the quarter is computed using definition, and the search proceeds backward to the last date that matches the specified dayOfWeek.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue, -or- quarter is less than 1 or greater than 4, -or- dayOfWeek is not a defined value of the DayOfWeek enumeration, -or- definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use the provider-based overload instead.

GetNearestDateOfWeek(int, int, int, DayOfWeek)

Returns a new DateOnly representing the nearest date (before or after) to the specified calendar year, month, and day that falls on the given DayOfWeek.

public static DateOnly GetNearestDateOfWeek(int year, int month, int day, DayOfWeek dayOfWeek)

Parameters

year int: The calendar year of the reference date. Must be between the Year property values of MinValue and MaxValue, inclusive.
month int: The calendar month of the reference date. Must be between 1 and 12, inclusive, where 1 represents January and 12 represents December.
day int: The day component of the reference date. Must be valid for the specified year and month, including leap-year considerations for February.
dayOfWeek DayOfWeek: The target DayOfWeek to locate.

Returns

DateOnly: A DateOnly value set to the closest date (either before or after) to the specified reference date that falls on the given dayOfWeek. If two dates are equally close, the earlier one is returned.

Remarks

The result is computed by evaluating the day-distance between the specified reference date and the nearest occurrence of dayOfWeek in either direction.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

GetNthDateOfWeekInMonth(int, int, DayOfWeek, WeekOrdinal)

Returns a new DateOnly representing the specified ordinal occurrence of a DayOfWeek within the given calendar month and year.

public static DateOnly GetNthDateOfWeekInMonth(int year, int month, DayOfWeek dayOfWeek, WeekOrdinal ordinal)

Parameters

year int: The calendar year of the result. Must be between the Year property values of MinValue and MaxValue, inclusive.
month int: The calendar month of the result. Must be between 1 and 12, inclusive, where 1 represents January and 12 represents December.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the month. For example, Tuesday returns the nth Tuesday.
ordinal WeekOrdinal: The ordinal occurrence to return. Valid values are First, Second, Third, Fourth, Fifth, and Last. Fifth is valid only in months where five matching weekdays occur.

Returns

DateOnly: A DateOnly value set to the requested occurrence of dayOfWeek within the specified year and month.

Remarks

For Last, the method returns the final matching dayOfWeek in the month. For other ordinal values, the method locates the first matching weekday and offsets by a multiple of seven days to reach the desired ordinal.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue, -or- month is less than 1 or greater than 12, -or- dayOfWeek is not a defined value of the DayOfWeek enumeration, -or- ordinal is not a defined value of the WeekOrdinal enumeration, -or- the requested ordinal does not occur within the month (for example, a fifth Thursday in February).

GetStartDateOfWeek(int, int, CultureInfo?)

Returns a new DateOnly representing the first day of the specified culture-defined week number in the given calendar year.

public static DateOnly GetStartDateOfWeek(int year, int week, CultureInfo? culture = null)

Parameters

year int: The calendar year to evaluate. Must be between the Year property values of MinValue and MaxValue, inclusive.
week int: The culture-defined week number to evaluate, starting at 1. The maximum valid value depends on the CalendarWeekRule and DayOfWeek used by the supplied culture.
culture CultureInfo: An optional CultureInfo used to determine the CalendarWeekRule and starting DayOfWeek. If null, CurrentCulture is used.

Returns

DateOnly: A DateOnly value set to the first date of the specified week in the specified year.

Remarks

This method uses the culture-defined week numbering system. The start of week 1 depends on the culture's CalendarWeekRule: under FirstDay the (possibly partial) first week begins on January 1 itself; under FirstFullWeek it begins at the first occurrence of the culture's FirstDayOfWeek on or after January 1; and under FirstFourDayWeek it begins at the week boundary of the week containing January 1 when at least four days of that week fall in the new year (which may place the start in the previous December), otherwise one week later. Subsequent weeks advance in 7-day intervals from the week-boundary alignment.

The result is validated by recalculating the week number for the computed date and comparing it to week. Dates that fall in the previous calendar year (such as the start of ISO week 1 in late December) are handled correctly. This member delegates to GetStartDateOfWeek(int, int, CultureInfo?) - the twins share one implementation, so both surfaces always agree.

Exceptions

ArgumentOutOfRangeException: Thrown if year is less than the Year of MinValue or greater than that of MaxValue, -or- week does not correspond to a valid week number for year under the rules of the supplied or current culture.

IsFirstDateOfFiscalYear(DateOnly, IQuarterDefinitionProvider)

Returns true when date is the first day of its fiscal year under the supplied IQuarterDefinitionProvider.

public static bool IsFirstDateOfFiscalYear(this DateOnly date, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The date to test.
provider IQuarterDefinitionProvider: The provider that defines the fiscal year boundaries.

Returns

bool: true if date equals the first day of its fiscal year; otherwise false.

Exceptions

ArgumentNullException: Thrown when provider is null.

IsFirstDateOfMonth(DateOnly)

Determines whether the specified DateOnly falls on the first day of its calendar month.

public static bool IsFirstDateOfMonth(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

bool: true if date represents the first day of its month; otherwise, false.

Remarks

This method evaluates whether the Day component is equal to 1.

IsFirstDateOfQuarter(DateOnly)

Determines whether the specified DateOnly falls on the first day of its calendar quarter, using the standard calendar quarter definition.

public static bool IsFirstDateOfQuarter(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

bool: true if date represents the first day of its quarter; otherwise, false.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember: Q1 = Jan - Mar, Q2 = Apr - Jun, Q3 = Jul - Sep, Q4 = Oct - Dec.

IsFirstDateOfQuarter(DateOnly, CalendarQuarterDefinition)

Determines whether the specified DateOnly falls on the first day of its calendar quarter, using the supplied calendar quarter definition.

public static bool IsFirstDateOfQuarter(this DateOnly date, CalendarQuarterDefinition definition)

Parameters

date DateOnly: The date value to evaluate.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how quarter boundaries are aligned.

Returns

bool: true if date represents the first day of its quarter under definition; otherwise, false.

Exceptions

ArgumentOutOfRangeException: Thrown if definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use the provider-based overload instead.

IsFirstDateOfQuarter(DateOnly, IQuarterDefinitionProvider)

Determines whether the specified DateOnly falls on the first day of its calendar quarter, using a custom IQuarterDefinitionProvider.

public static bool IsFirstDateOfQuarter(this DateOnly date, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The date value to evaluate.
provider IQuarterDefinitionProvider: The IQuarterDefinitionProvider that defines custom quarter boundaries. Must not be null.

Returns

bool: true if date represents the first day of its quarter as defined by provider; otherwise, false.

Exceptions

ArgumentNullException: Thrown if provider is null.

IsInRange(DateOnly, DateOnly, DateOnly)

Determines whether the specified DateOnly falls within the inclusive range defined by start and end.

public static bool IsInRange(this DateOnly date, DateOnly start, DateOnly end)

Parameters

date DateOnly: The date value to evaluate.
start DateOnly: The inclusive lower bound of the range.
end DateOnly: The inclusive upper bound of the range.

Returns

bool: true if date is greater than or equal to start and less than or equal to end; otherwise, false.

Remarks

The range check is inclusive: the result is true if date equals either start or end.

If end is earlier than start, the method returns false for all values of date.

IsInRange(DateOnly?, DateOnly, DateOnly)

Determines whether the specified nullable DateOnly falls within the inclusive range defined by start and end.

public static bool IsInRange(this DateOnly? date, DateOnly start, DateOnly end)

Parameters

date DateOnly?: The nullable date value to evaluate.
start DateOnly: The inclusive lower bound of the range.
end DateOnly: The inclusive upper bound of the range.

Returns

bool: true if date has a value that is greater than or equal to start and less than or equal to end; otherwise, false .

Remarks

If date is null, the result is false.

The range check is inclusive: the result is true if the value equals either boundary.

If end is earlier than start, the method returns false for all values of date.

IsInWorkingWeek(DateOnly, WeekPattern)

Determines whether the specified DateOnly falls on a day that is selected in the supplied WeekPattern working week.

public static bool IsInWorkingWeek(this DateOnly date, WeekPattern workingWeek)

Parameters

date DateOnly: The date to evaluate.
workingWeek WeekPattern: The working-week pattern.

Returns

bool: true if date's DayOfWeek is selected in workingWeek; otherwise, false.

Remarks

This predicate considers only the day-of-week dimension. It does not consult any holiday catalogue. Combine it with a notable-date service when both working-week and holiday awareness are required.

IsInWorkingWeek(DateOnly, WorkingDaysOfWeek)

Determines whether the specified DateOnly falls on a day that is selected in the supplied WorkingDaysOfWeek working week.

public static bool IsInWorkingWeek(this DateOnly date, WorkingDaysOfWeek workingWeek)

Parameters

date DateOnly: The date to evaluate.
workingWeek WorkingDaysOfWeek: The named working-week pattern.

Returns

bool: true if date's DayOfWeek is in the working week; otherwise, false.

Exceptions

ArgumentOutOfRangeException: Thrown when workingWeek is not a defined value of the WorkingDaysOfWeek enumeration.
ArgumentException: Thrown when workingWeek is Custom, which has no canonical pattern.

IsLastDateOfFiscalYear(DateOnly, IQuarterDefinitionProvider)

Returns true when date is the last day of its fiscal year under the supplied IQuarterDefinitionProvider.

public static bool IsLastDateOfFiscalYear(this DateOnly date, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The date to test.
provider IQuarterDefinitionProvider: The provider that defines the fiscal year boundaries.

Returns

bool: true if date equals the last day of its fiscal year; otherwise false.

Exceptions

ArgumentNullException: Thrown when provider is null.

IsLastDateOfMonth(DateOnly)

Determines whether the specified DateOnly falls on the last day of its calendar month.

public static bool IsLastDateOfMonth(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

bool: true if date represents the last day of its month; otherwise, false.

Remarks

This method compares the Day component to the total number of days in the same month and year, accounting for leap-year adjustments to February.

Equivalent to checking whether date.Day == DateTime.DaysInMonth(date.Year, date.Month).

IsLastDateOfQuarter(DateOnly)

Determines whether the specified DateOnly falls on the last day of its calendar quarter, using the standard calendar quarter definition.

public static bool IsLastDateOfQuarter(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

bool: true if date represents the last day of its quarter; otherwise, false.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember: Q1 = Jan - Mar, Q2 = Apr - Jun, Q3 = Jul - Sep, Q4 = Oct - Dec.

IsLastDateOfQuarter(DateOnly, CalendarQuarterDefinition)

Determines whether the specified DateOnly falls on the last day of its calendar quarter, using the supplied calendar quarter definition.

public static bool IsLastDateOfQuarter(this DateOnly date, CalendarQuarterDefinition definition)

Parameters

date DateOnly: The date value to evaluate.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how quarter boundaries are aligned.

Returns

bool: true if date represents the last day of its quarter under definition; otherwise, false.

Exceptions

ArgumentOutOfRangeException: Thrown if definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use the provider-based overload instead.

IsLastDateOfQuarter(DateOnly, IQuarterDefinitionProvider)

Determines whether the specified DateOnly falls on the last day of its calendar quarter, using a custom IQuarterDefinitionProvider.

public static bool IsLastDateOfQuarter(this DateOnly date, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The date value to evaluate.
provider IQuarterDefinitionProvider: The IQuarterDefinitionProvider that defines custom quarter boundaries. Must not be null.

Returns

bool: true if date represents the last day of its quarter as defined by provider; otherwise, false.

Exceptions

ArgumentNullException: Thrown if provider is null.

IsLeapYear(DateOnly)

Determines whether the year of the specified DateOnly is a leap year, according to the proleptic Gregorian calendar.

public static bool IsLeapYear(this DateOnly date)

Parameters

date DateOnly: The date value whose Year is evaluated.

Returns

bool: true if the year contains February 29; otherwise, false.

Remarks

This method applies the Gregorian leap-year rules:

Years divisible by 4 are leap years,
except years divisible by 100,
unless also divisible by 400.

For example, the years 2000 and 2024 are leap years, while 1900 and 2100 are not.

This method does not consider culture-specific calendars; it always evaluates leap years using the Gregorian calendar.

IsRestDay(DateOnly, WeekPattern)

Determines whether the specified DateOnly falls on a day that is not selected in the supplied WeekPattern working week.

public static bool IsRestDay(this DateOnly date, WeekPattern workingWeek)

Parameters

date DateOnly: The date to evaluate.
workingWeek WeekPattern: The working-week pattern.

Returns

bool: true if date's DayOfWeek is not selected in workingWeek; otherwise, false.

Remarks

This predicate is the complement of IsInWorkingWeek(DateOnly, WeekPattern) and considers only the day-of-week dimension. It does not consult any holiday catalogue.

IsRestDay(DateOnly, WorkingDaysOfWeek)

Determines whether the specified DateOnly falls on a day that is not selected in the supplied WorkingDaysOfWeek working week.

public static bool IsRestDay(this DateOnly date, WorkingDaysOfWeek workingWeek)

Parameters

date DateOnly: The date to evaluate.
workingWeek WorkingDaysOfWeek: The named working-week pattern.

Returns

bool: true if date's DayOfWeek is not in the working week; otherwise, false.

Exceptions

ArgumentOutOfRangeException: Thrown when workingWeek is not a defined value of the WorkingDaysOfWeek enumeration.
ArgumentException: Thrown when workingWeek is Custom, which has no canonical pattern.

IsWeekday(DateOnly)

Determines whether the specified DateOnly falls on a weekday, using the default MondayToFriday rule.

public static bool IsWeekday(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

bool: true if date does not fall on Saturday or Sunday; otherwise, false.

Remarks

A weekday is any day selected by the working-week pattern. This overload uses MondayToFriday and no custom provider.

IsWeekday(DateOnly, WorkingDaysOfWeek, IWeekendDefinitionProvider?)

Determines whether the specified DateOnly falls on a weekday, using the supplied WorkingDaysOfWeek and an optional custom provider.

public static bool IsWeekday(this DateOnly date, WorkingDaysOfWeek workingWeek, IWeekendDefinitionProvider? provider = null)

Parameters

date DateOnly: The date value to evaluate.
workingWeek WorkingDaysOfWeek: The WorkingDaysOfWeek that determines which days are treated as working days.
provider IWeekendDefinitionProvider: An optional IWeekendDefinitionProvider that supplies custom weekend logic when workingWeek is Custom.

Returns

bool: true if date is not a weekend under the supplied rule or provider; otherwise, false.

Remarks

The method evaluates whether the DayOfWeek of date is included in the working-week pattern supplied by workingWeek and optionally refined by provider.

Exceptions

ArgumentOutOfRangeException: Thrown if workingWeek is not a defined value of the WorkingDaysOfWeek enumeration, -or- workingWeek is Custom and provider is null.

IsWeekend(DateOnly)

Determines whether the specified DateOnly falls on a weekend, using the default MondayToFriday rule.

public static bool IsWeekend(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

bool: true if date falls on Saturday or Sunday; otherwise, false.

Remarks

This overload uses the standard working-week pattern (Monday through Friday), so Saturday and Sunday are treated as weekend days.

IsWeekend(DateOnly, WorkingDaysOfWeek, IWeekendDefinitionProvider?)

Determines whether the specified DateOnly falls on a weekend, using the supplied WorkingDaysOfWeek and an optional custom provider.

public static bool IsWeekend(this DateOnly date, WorkingDaysOfWeek workingWeek, IWeekendDefinitionProvider? provider = null)

Parameters

date DateOnly: The date value to evaluate.
workingWeek WorkingDaysOfWeek: The WorkingDaysOfWeek that determines which days are treated as working days. Any day not selected is treated as a weekend day.
provider IWeekendDefinitionProvider: An optional IWeekendDefinitionProvider that supplies custom weekend logic when workingWeek is Custom.

Returns

bool: true if date falls on a weekend day as defined by the supplied working-week or provider; otherwise, false.

Remarks

This method supports alternative working-week patterns used in different cultures and regions, such as Sunday-to-Thursday or Saturday-to-Wednesday.

Exceptions

ArgumentOutOfRangeException: Thrown if workingWeek is not a defined value of the WorkingDaysOfWeek enumeration, -or- workingWeek is Custom and provider is null.

IsoWeekOfYear(DateOnly)

Returns the ISO 8601 week number for the specified date.

public static int IsoWeekOfYear(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

int: An integer in the range 1 - 53 representing the ISO 8601 week number that contains date.

Remarks

This method follows the ISO 8601 standard for week numbering, where:

weeks begin on Monday;
week 1 is the first week containing at least four days of the new year.

The result is computed using FirstFourDayWeek and Monday, and is identical to the value produced by the DateTime twin for the same calendar date.

IsoYear(DateOnly)

Returns the ISO 8601 year associated with the specified date.

public static int IsoYear(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

int: The ISO 8601 calendar year that contains the ISO week of date.

Remarks

The ISO 8601 year may differ from the calendar year of date. A date near the start or end of a calendar year may belong to the ISO year of the adjacent calendar year, depending on which ISO week it falls into. For example, January 1 may belong to the last week of the previous ISO year, and December 31 may belong to week 1 of the following ISO year.

LastDateOfFiscalYear(int, IQuarterDefinitionProvider)

Returns the last calendar day of the supplied fiscal year under the supplied IQuarterDefinitionProvider.

public static DateOnly LastDateOfFiscalYear(int fiscalYear, IQuarterDefinitionProvider provider)

Parameters

fiscalYear int: The fiscal year whose end date is requested.
provider IQuarterDefinitionProvider: The provider that defines the fiscal year boundaries.

Returns

DateOnly: A DateOnly representing the last day of the fiscal year.

Exceptions

ArgumentNullException: Thrown when provider is null.

LastDateOfMonth(DateOnly)

Returns a new DateOnly representing the last day of the same calendar month and year as the specified date.

public static DateOnly LastDateOfMonth(this DateOnly date)

Parameters

date DateOnly: The date value whose year and month are used to determine the result.

Returns

DateOnly: A DateOnly value set to the last day of the same calendar month and year as date.

Remarks

This method calculates the last day of the month using Gregorian calendar rules. Leap years are correctly accounted for when determining the length of February.

Example:

var date = new DateOnly(2024, 2, 15);
var result = date.LastDateOfMonth(); // → 2024-02-29

LastDateOfQuarter(DateOnly)

Returns a new DateOnly representing the last day of the calendar quarter that contains the specified date, using the standard calendar quarter definition.

public static DateOnly LastDateOfQuarter(this DateOnly date)

Parameters

date DateOnly: The date value used to determine the containing quarter.

Returns

DateOnly: A DateOnly value set to the last day of the quarter that contains date.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember:

Q1January - March
Q2April - June
Q3July - September
Q4October - December

LastDateOfQuarter(DateOnly, CalendarQuarterDefinition)

Returns a new DateOnly representing the last day of the quarter that contains the specified date, using the specified calendar quarter definition.

public static DateOnly LastDateOfQuarter(this DateOnly date, CalendarQuarterDefinition definition)

Parameters

date DateOnly: The date value used to determine the containing quarter.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how quarter boundaries are aligned.

Returns

DateOnly: A DateOnly value set to the last day of the corresponding quarter.

Remarks

The definition controls whether quarters are aligned to the first day of a month (e.g. January - March) or anchored to a custom day-of-month boundary.

For provider-driven (e.g. 4-4-5 fiscal) quarters, use the LastDateOfQuarter(DateOnly, IQuarterDefinitionProvider) overload instead.

Exceptions

ArgumentOutOfRangeException: Thrown if definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use the provider-based overload instead.

LastDateOfQuarter(DateOnly, IQuarterDefinitionProvider)

Returns a new DateOnly representing the last day of the quarter that contains the specified date, using a custom IQuarterDefinitionProvider.

public static DateOnly LastDateOfQuarter(this DateOnly date, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The date value used to determine the containing quarter.
provider IQuarterDefinitionProvider: The IQuarterDefinitionProvider that defines custom quarter boundaries. Must not be null.

Returns

DateOnly: A DateOnly value set to the last day of the quarter containing date.

Remarks

This overload supports advanced or domain-specific quarter systems by delegating boundary logic to the supplied provider - for example, 4-4-5 retail calendars or regional fiscal quarters.

Exceptions

ArgumentNullException: Thrown if provider is null.
ArgumentOutOfRangeException: Thrown if the provider returns a date outside the range of MinValue and MaxValue.

LastDateOfWeek(DateOnly)

Returns a new DateOnly representing the last day of the week that contains the specified date, using the last day of the week defined by CurrentCulture.

public static DateOnly LastDateOfWeek(this DateOnly date)

Parameters

date DateOnly: The date value used to determine the containing week.

Returns

DateOnly: A DateOnly value set to the culturally defined last day of the week containing date.

Remarks

This overload uses CurrentCulture to determine the last day of the week, inferred from FirstDayOfWeek.

LastDateOfWeek(DateOnly, WorkingDaysOfWeek)

Returns a new DateOnly representing the last day of the week that contains the specified date, using a start-of-week inferred from the specified WorkingDaysOfWeek.

public static DateOnly LastDateOfWeek(this DateOnly date, WorkingDaysOfWeek workingWeek)

Parameters

date DateOnly: The date value used to determine the containing week.
workingWeek WorkingDaysOfWeek: A WorkingDaysOfWeek used to infer the last day of the week. For example, MondayToFriday implies a Monday start (and therefore a Sunday end).

Returns

DateOnly: A DateOnly value set to the last day of the week containing date.

Remarks

The method infers the start of the week based on the specified workingWeek value, then calculates the last day as six days after the inferred start. If AllDays is supplied, the method defaults to using Monday.

Exceptions

ArgumentOutOfRangeException: Thrown if workingWeek is not a defined WorkingDaysOfWeek value, -or- the resulting date is later than MaxValue.

LastDateOfWeek(DateOnly, CultureInfo?)

Returns a new DateOnly representing the last day of the week that contains the specified date, using the last day of the week defined by the supplied or current culture.

public static DateOnly LastDateOfWeek(this DateOnly date, CultureInfo? culture)

Parameters

date DateOnly: The date value used to determine the containing week.
culture CultureInfo: An optional CultureInfo that defines the first day of the week via FirstDayOfWeek. If null, CurrentCulture is used.

Returns

DateOnly: A DateOnly value set to the culturally defined last day of the week containing date.

Remarks

This method computes the day offset between date and the culture-specific last day of the week, and adds that offset.

Exceptions

ArgumentOutOfRangeException: Thrown if the resulting date is later than MaxValue.

LastDateOfWeekInMonth(DateOnly, DayOfWeek)

Returns a new DateOnly representing the last occurrence of the specified DayOfWeek within the same calendar month and year as the specified date.

public static DateOnly LastDateOfWeekInMonth(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The date value whose month and year are used to determine the result.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the month. For example, Monday returns the last Monday.

Returns

DateOnly: A DateOnly value set to the last occurrence of dayOfWeek within the same calendar month and year as date.

Remarks

The search begins on the last day of the month and proceeds backward to locate the last matching weekday.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

LastDateOfWeekInQuarter(DateOnly, DayOfWeek)

Returns a new DateOnly representing the last occurrence of the specified DayOfWeek within the calendar quarter that contains the specified date, using the standard calendar quarter definition.

public static DateOnly LastDateOfWeekInQuarter(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The date value used to determine the containing quarter.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the quarter. For example, Monday returns the last Monday.

Returns

DateOnly: A DateOnly value set to the last occurrence of dayOfWeek within the quarter that contains date.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember. The search begins on the last day of the quarter and proceeds backward to locate the last matching weekday.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

LastDateOfWeekInQuarter(DateOnly, DayOfWeek, CalendarQuarterDefinition)

Returns a new DateOnly representing the last occurrence of the specified DayOfWeek within the quarter that contains the specified date, using the supplied calendar quarter definition.

public static DateOnly LastDateOfWeekInQuarter(this DateOnly date, DayOfWeek dayOfWeek, CalendarQuarterDefinition definition)

Parameters

date DateOnly: The date value used to determine the containing quarter.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the quarter. For example, Monday returns the last Monday.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how quarter boundaries are aligned.

Returns

DateOnly: A DateOnly value set to the last occurrence of dayOfWeek within the quarter that contains date.

Remarks

The end of the quarter is computed using definition, and the search proceeds backward to the last date that matches the specified dayOfWeek.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration, -or- definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use the provider-based overload instead.

LastDateOfWeekInQuarter(DateOnly, DayOfWeek, IQuarterDefinitionProvider)

Returns a new DateOnly representing the last occurrence of the specified DayOfWeek within the quarter that contains the specified date, using a custom IQuarterDefinitionProvider.

public static DateOnly LastDateOfWeekInQuarter(this DateOnly date, DayOfWeek dayOfWeek, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The date value used to determine the containing quarter.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the quarter. For example, Monday returns the last Monday.
provider IQuarterDefinitionProvider: The IQuarterDefinitionProvider that defines custom quarter boundaries. Must not be null.

Returns

DateOnly: A DateOnly value set to the last occurrence of dayOfWeek within the quarter that contains date.

Remarks

The end of the quarter is determined by the supplied provider, and the search proceeds backward to the last date that matches the specified dayOfWeek.

Exceptions

ArgumentNullException: Thrown if provider is null.
ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

LastDateOfWeekInYear(DateOnly, DayOfWeek)

Returns a new DateOnly representing the last occurrence of the specified DayOfWeek within the same calendar year as the specified date.

public static DateOnly LastDateOfWeekInYear(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The date value whose year is used to determine the result.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the year. For example, Monday returns the last Monday.

Returns

DateOnly: A DateOnly value set to the last occurrence of dayOfWeek within the same calendar year as date.

Remarks

The search begins on December 31 of the year and proceeds backward to locate the last matching weekday.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

LastDateOfYear(DateOnly)

Returns a new DateOnly representing the last day of the same calendar year as the specified date.

public static DateOnly LastDateOfYear(this DateOnly date)

Parameters

date DateOnly: The date value whose year is used to determine the result.

Returns

DateOnly: A DateOnly value set to December 31 of the same calendar year as date.

Remarks

This method calculates the last day of the year using Gregorian calendar rules.

Example:

var date = new DateOnly(2025, 7, 15);
var result = date.LastDateOfYear(); // → 2025-12-31

Max(DateOnly, DateOnly)

Returns the later of two specified DateOnly values.

public static DateOnly Max(DateOnly first, DateOnly second)

Parameters

first DateOnly: The first DateOnly value to compare.
second DateOnly: The second DateOnly value to compare.

Returns

DateOnly: The later of the two DateOnly values. If both values are equal, first is returned.

Remarks

This method compares the two values using the greater-than-or-equal-to (>=) operator, which is equivalent to CompareTo(DateOnly).

Max(DateOnly?, DateOnly?)

Returns the later of two specified nullable DateOnly values.

public static DateOnly? Max(DateOnly? first, DateOnly? second)

Parameters

first DateOnly?: The first nullable DateOnly value to compare.
second DateOnly?: The second nullable DateOnly value to compare.

Returns

DateOnly?: The later non-null DateOnly value, or null if both values are null.

Remarks

If both values are non-null, they are compared using the greater-than-or-equal-to (>=) operator. If only one value is non-null, that value is returned. If both are null, the result is null.

Min(DateOnly, DateOnly)

Returns the earlier of two specified DateOnly values.

public static DateOnly Min(DateOnly first, DateOnly second)

Parameters

first DateOnly: The first DateOnly value to compare.
second DateOnly: The second DateOnly value to compare.

Returns

DateOnly: The earlier of the two DateOnly values. If both values are equal, first is returned.

Remarks

This method compares the two values using the less-than-or-equal-to (<=) operator, which is equivalent to CompareTo(DateOnly).

Min(DateOnly?, DateOnly?)

Returns the earlier of two specified nullable DateOnly values.

public static DateOnly? Min(DateOnly? first, DateOnly? second)

Parameters

first DateOnly?: The first nullable DateOnly value to compare.
second DateOnly?: The second nullable DateOnly value to compare.

Returns

DateOnly?: The earlier non-null DateOnly value, or null if both values are null.

Remarks

If both values are non-null, they are compared using the less-than-or-equal-to (<=) operator. If only one value is non-null, that value is returned. If both are null, the result is null.

MonthName(DateOnly)

Returns the full name of the month for the specified DateOnly, using the formatting rules of CurrentCulture.

public static string MonthName(this DateOnly date)

Parameters

date DateOnly: The date value whose month component is used to determine the name.

Returns

string: A string containing the localized full month name, formatted using CurrentCulture.

Remarks

This overload uses the GetMonthName(int) method of the current culture to retrieve the month name. For culture-specific results, use the MonthName(DateOnly, CultureInfo?) overload.

MonthName(DateOnly, CultureInfo?)

Returns the full name of the month for the specified DateOnly, using the formatting rules of the supplied or current culture.

public static string MonthName(this DateOnly date, CultureInfo? culture)

Parameters

date DateOnly: The date value whose month component is used to determine the name.
culture CultureInfo: An optional CultureInfo used to format the result. If null, CurrentCulture is used.

Returns

string: A string containing the localized full month name for date, formatted using the supplied or current culture.

Remarks

This overload uses the GetMonthName(int) method of the supplied or current culture to retrieve the month name.

NearestDateOfWeek(DateOnly, DayOfWeek)

Returns a new DateOnly representing the nearest date (before or after) to the specified date that falls on the given DayOfWeek.

public static DateOnly NearestDateOfWeek(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The reference date value.
dayOfWeek DayOfWeek: The target DayOfWeek to locate.

Returns

DateOnly: A DateOnly value set to the closest date (either before or after) to date that falls on the specified dayOfWeek. If two dates are equally close, the earlier one is returned.

Remarks

The result is computed by evaluating the day-distance between date and the nearest occurrence of dayOfWeek in either direction.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

NextDateOfWeek(DateOnly, DayOfWeek)

Returns a new DateOnly representing the next calendar occurrence of the specified DayOfWeek after the given date.

public static DateOnly NextDateOfWeek(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The starting date value from which to search forward.
dayOfWeek DayOfWeek: The DayOfWeek to locate. For example, Monday returns the next Monday.

Returns

DateOnly: A DateOnly value set to the next occurrence of dayOfWeek following date.

Remarks

If date already falls on the specified dayOfWeek, the result is exactly seven days later. The method advances forward in time and never returns the original date.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

NextOccurrence(DateOnly, int, DateOnly)

Returns a new DateOnly representing the next occurrence of a recurring event that starts at start and repeats every intervalDays days, occurring on or after the specified after date.

public static DateOnly NextOccurrence(this DateOnly start, int intervalDays, DateOnly after)

Parameters

start DateOnly: The date value representing the initial reference point of the recurring event.
intervalDays int: The fixed number of days between successive occurrences. Must be greater than zero.
after DateOnly: The date after which the next occurrence must fall.

Returns

DateOnly: A DateOnly value representing the next occurrence of the event aligned with start and recurring every intervalDays days, on or after after.

Remarks

If after is earlier than start, the method returns start. Otherwise, it computes the smallest multiple of intervalDays added to start that occurs after after.

Example:

var start = new DateOnly(2024, 1, 1);
var after = new DateOnly(2024, 1, 12);
var next = start.NextOccurrence(intervalDays: 5, after); // → 2024-01-16

Exceptions

ArgumentOutOfRangeException: Thrown if intervalDays is less than or equal to zero.

NextOrSameDateOfWeek(DateOnly, DayOfWeek)

Returns a new DateOnly representing the next calendar occurrence of the specified DayOfWeek at or after the given date.

public static DateOnly NextOrSameDateOfWeek(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The starting date value from which to search forward.
dayOfWeek DayOfWeek: The DayOfWeek to locate. For example, Monday returns the next Monday on or after date.

Returns

DateOnly: A DateOnly value set to the next occurrence of dayOfWeek at or after date.

Remarks

If date already falls on the specified dayOfWeek, the result is date itself. This is the on-or-after counterpart of NextDateOfWeek(DateOnly, DayOfWeek), which always advances by at least one day.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

NextWeekday(DateOnly, WeekPattern)

Returns a new DateOnly representing the next day after date whose DayOfWeek is selected in the supplied workingWeek.

public static DateOnly NextWeekday(this DateOnly date, WeekPattern workingWeek)

Parameters

date DateOnly: The starting date value from which to search forward.
workingWeek WeekPattern: The working-week pattern that determines which days are considered working days.

Returns

DateOnly: The first calendar day strictly after date whose day-of-week is selected in workingWeek.

Exceptions

ArgumentOutOfRangeException: Thrown when workingWeek is Empty.

NextWeekday(DateOnly, WorkingDaysOfWeek)

Returns a new DateOnly representing the next calendar weekday after the specified date, based on the supplied workingWeek pattern.

public static DateOnly NextWeekday(this DateOnly date, WorkingDaysOfWeek workingWeek)

Parameters

date DateOnly: The starting date value from which to search forward.
workingWeek WorkingDaysOfWeek: The WorkingDaysOfWeek that determines which days are treated as working days.

Returns

DateOnly: A DateOnly value set to the first calendar day after date that is a working day under the specified workingWeek rule.

Remarks

The method evaluates each successive day until it finds one that is selected as a working day by the specified rule. The original date is never returned, even if it already falls on a working day.

Exceptions

ArgumentOutOfRangeException: Thrown if workingWeek is not a defined value of the WorkingDaysOfWeek enumeration.

NextWeekday(DateOnly, WorkingDaysOfWeek, IWeekendDefinitionProvider?)

Returns a new DateOnly representing the next calendar weekday after the specified date, using the supplied workingWeek pattern and an optional custom provider.

public static DateOnly NextWeekday(this DateOnly date, WorkingDaysOfWeek workingWeek, IWeekendDefinitionProvider? provider)

Parameters

date DateOnly: The starting date value from which to search forward.
workingWeek WorkingDaysOfWeek: The WorkingDaysOfWeek that determines which days are treated as working days.
provider IWeekendDefinitionProvider: An optional IWeekendDefinitionProvider that supplies custom weekend logic when workingWeek is Custom. If null, the default behavior for the supplied workingWeek applies.

Returns

DateOnly: A DateOnly value set to the first calendar day after date that is a working day under the specified workingWeek rule and the logic of provider.

Remarks

The method evaluates each successive day following date until it finds one that is a working day, either by the supplied workingWeek pattern or by the custom logic of provider.

Exceptions

ArgumentOutOfRangeException: Thrown if workingWeek is not a defined value of the WorkingDaysOfWeek enumeration.

NthDateOfWeekInMonth(DateOnly, DayOfWeek, WeekOrdinal)

Returns a new DateOnly representing the specified ordinal occurrence of a DayOfWeek within the same calendar month and year as the specified date.

public static DateOnly NthDateOfWeekInMonth(this DateOnly date, DayOfWeek dayOfWeek, WeekOrdinal ordinal)

Parameters

date DateOnly: The date value whose month and year are used to determine the result. The day component is ignored.
dayOfWeek DayOfWeek: The DayOfWeek to locate within the month. For example, Monday returns the nth Monday.
ordinal WeekOrdinal: The ordinal occurrence to return. Valid values are First, Second, Third, Fourth, Fifth, and Last. Fifth is valid only in months where five matching weekdays occur.

Returns

DateOnly: A DateOnly value set to the requested occurrence of dayOfWeek within the same calendar month and year as date.

Remarks

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration, -or- ordinal is not a defined value of the WeekOrdinal enumeration, -or- the requested ordinal does not occur within the month (for example, a fifth Thursday in February).

PreviousDateOfWeek(DateOnly, DayOfWeek)

Returns a new DateOnly representing the previous calendar occurrence of the specified DayOfWeek before the given date.

public static DateOnly PreviousDateOfWeek(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The starting date value from which to search backward.
dayOfWeek DayOfWeek: The DayOfWeek to locate. For example, Monday returns the previous Monday.

Returns

DateOnly: A DateOnly value set to the previous occurrence of dayOfWeek preceding date.

Remarks

If date already falls on the specified dayOfWeek, the result is exactly seven days earlier. The method moves backward in time and never returns the original date.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

PreviousOccurrence(DateOnly, int, DateOnly)

Returns a new DateOnly representing the previous occurrence of a recurring event that starts at start and repeats every intervalDays days, occurring strictly before the specified before date.

public static DateOnly PreviousOccurrence(this DateOnly start, int intervalDays, DateOnly before)

Parameters

start DateOnly: The date value representing the initial reference point of the recurring event.
intervalDays int: The fixed number of days between successive occurrences. Must be greater than zero.
before DateOnly: The date before which the previous occurrence must fall.

Returns

DateOnly: A DateOnly value representing the last occurrence of the event that falls strictly before before, based on the supplied start and recurring intervalDays.

Remarks

If before is earlier than or equal to start, the method returns the occurrence immediately prior to start. Otherwise, it computes the largest multiple of intervalDays added to start that remains strictly earlier than before. When before falls exactly on an occurrence boundary, the occurrence at that boundary is excluded and the preceding one is returned.

Example:

var start = new DateOnly(2024, 1, 1);

// before is between two occurrences - returns the occurrence at 2024-01-11
var prev1 = start.PreviousOccurrence(intervalDays: 5, new DateOnly(2024, 1, 13)); // → 2024-01-11

// before falls exactly on an occurrence - returns the one before it
var prev2 = start.PreviousOccurrence(intervalDays: 5, new DateOnly(2024, 1, 11)); // → 2024-01-06

Exceptions

ArgumentOutOfRangeException: Thrown if intervalDays is less than or equal to zero.

PreviousOrSameDateOfWeek(DateOnly, DayOfWeek)

Returns a new DateOnly representing the previous calendar occurrence of the specified DayOfWeek at or before the given date.

public static DateOnly PreviousOrSameDateOfWeek(this DateOnly date, DayOfWeek dayOfWeek)

Parameters

date DateOnly: The starting date value from which to search backward.
dayOfWeek DayOfWeek: The DayOfWeek to locate. For example, Monday returns the previous Monday on or before date.

Returns

DateOnly: A DateOnly value set to the previous occurrence of dayOfWeek at or before date.

Remarks

If date already falls on the specified dayOfWeek, the result is date itself. This is the on-or-before counterpart of PreviousDateOfWeek(DateOnly, DayOfWeek), which always retreats by at least one day.

Exceptions

ArgumentOutOfRangeException: Thrown if dayOfWeek is not a defined value of the DayOfWeek enumeration.

PreviousWeekday(DateOnly, WeekPattern)

Returns a new DateOnly representing the previous day before date whose DayOfWeek is selected in the supplied workingWeek.

public static DateOnly PreviousWeekday(this DateOnly date, WeekPattern workingWeek)

Parameters

date DateOnly: The starting date value from which to search backward.
workingWeek WeekPattern: The working-week pattern that determines which days are considered working days.

Returns

DateOnly: The first calendar day strictly before date whose day-of-week is selected in workingWeek.

Exceptions

ArgumentOutOfRangeException: Thrown when workingWeek is Empty.

PreviousWeekday(DateOnly, WorkingDaysOfWeek)

Returns a new DateOnly representing the previous calendar weekday before the specified date, based on the supplied workingWeek pattern.

public static DateOnly PreviousWeekday(this DateOnly date, WorkingDaysOfWeek workingWeek)

Parameters

date DateOnly: The starting date value from which to search backward.
workingWeek WorkingDaysOfWeek: The WorkingDaysOfWeek that determines which days are treated as working days.

Returns

DateOnly: A DateOnly value set to the first calendar day before date that is a working day under the specified workingWeek rule.

Remarks

The method evaluates each preceding day until it finds one that is selected as a working day by the specified rule. The original date is never returned, even if it already falls on a working day.

Exceptions

ArgumentOutOfRangeException: Thrown if workingWeek is not a defined value of the WorkingDaysOfWeek enumeration.

PreviousWeekday(DateOnly, WorkingDaysOfWeek, IWeekendDefinitionProvider?)

Returns a new DateOnly representing the previous calendar weekday before the specified date, using the supplied workingWeek pattern and an optional custom provider.

public static DateOnly PreviousWeekday(this DateOnly date, WorkingDaysOfWeek workingWeek, IWeekendDefinitionProvider? provider)

Parameters

date DateOnly: The starting date value from which to search backward.
workingWeek WorkingDaysOfWeek: The WorkingDaysOfWeek that determines which days are treated as working days.
provider IWeekendDefinitionProvider: An optional IWeekendDefinitionProvider that supplies custom weekend logic when workingWeek is Custom. If null, the default behavior for the supplied workingWeek applies.

Returns

DateOnly: A DateOnly value set to the first calendar day before date that is a working day under the specified workingWeek rule and the logic of provider.

Remarks

The method evaluates each preceding day prior to date until it finds one that is a working day, either by the supplied workingWeek pattern or by the custom logic of provider.

Exceptions

ArgumentOutOfRangeException: Thrown if workingWeek is not a defined value of the WorkingDaysOfWeek enumeration.

Quarter(DateOnly)

Returns the quarter number (1 - 4) of the year for the specified DateOnly, using the standard calendar quarter definition.

public static int Quarter(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

int: An integer between 1 and 4 representing the calendar quarter that contains date.

Remarks

This overload uses the standard calendar alignment defined by JanuaryToDecember: Q1 = Jan - Mar, Q2 = Apr - Jun, Q3 = Jul - Sep, Q4 = Oct - Dec.

Quarter(DateOnly, CalendarQuarterDefinition)

Returns the quarter number (1 - 4) for the specified DateOnly, using the supplied calendar quarter definition.

public static int Quarter(this DateOnly date, CalendarQuarterDefinition definition)

Parameters

date DateOnly: The date value to evaluate.
definition CalendarQuarterDefinition: The CalendarQuarterDefinition that determines how the year is segmented into quarters.

Returns

int: An integer between 1 and 4 representing the quarter that contains date.

Remarks

This overload supports both month-aligned and day-aligned quarter definitions. For provider-driven custom calendars (e.g. 4-4-5 retail calendars), use the Quarter(DateOnly, IQuarterDefinitionProvider) overload.

Exceptions

ArgumentOutOfRangeException: Thrown if definition is not a defined value of the CalendarQuarterDefinition enumeration.
InvalidOperationException: Thrown if definition is Custom; use the provider-based overload instead.

Quarter(DateOnly, IQuarterDefinitionProvider)

Returns the quarter number (1 - 4) for the specified DateOnly, using a custom IQuarterDefinitionProvider.

public static int Quarter(this DateOnly date, IQuarterDefinitionProvider provider)

Parameters

date DateOnly: The date value to evaluate.
provider IQuarterDefinitionProvider: The IQuarterDefinitionProvider that defines custom quarter boundaries. Must not be null.

Returns

int: An integer between 1 and 4 representing the quarter that contains date.

Remarks

This overload supports advanced or domain-specific quarter systems by delegating to GetQuarter(DateOnly) - for example, 4-4-5 retail calendars or regional fiscal quarters.

Exceptions

ArgumentNullException: Thrown if provider is null.
ArgumentOutOfRangeException: Thrown if the value returned by provider is not in the range 1 - 4.

ToUnixTimeMilliseconds(DateOnly)

Returns the number of milliseconds that have elapsed between the Unix epoch (1970-01-01T00:00:00Z) and the specified DateOnly.

public static long ToUnixTimeMilliseconds(this DateOnly date)

Parameters

date DateOnly: The date value to convert. The value is interpreted as UTC.

Returns

long: The total number of milliseconds since the Unix epoch.

Remarks

Use FromUnixTimeMilliseconds(long) to perform the inverse conversion.

See Also: FromUnixTimeMilliseconds(long)

ToUnixTimeSeconds(DateOnly)

Returns the number of seconds that have elapsed between the Unix epoch (1970-01-01T00:00:00Z) and the specified DateOnly.

public static long ToUnixTimeSeconds(this DateOnly date)

Parameters

date DateOnly: The date value to convert. The value is interpreted as UTC.

Returns

long: The total number of seconds since the Unix epoch.

Remarks

Use FromUnixTimeSeconds(long) to perform the inverse conversion.

See Also: FromUnixTimeSeconds(long)

WeekOfMonth(DateOnly)

Returns the 1-based week number of the month for the specified DateOnly, using the CalendarWeekRule and DayOfWeek settings of CurrentCulture.

public static int WeekOfMonth(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

int: An integer indicating the week of the month in which date falls, starting at 1.

Remarks

Week numbering is determined by CurrentCulture, specifically its CalendarWeekRule and FirstDayOfWeek. See WeekOfMonth(DateOnly, CalendarWeekRule, DayOfWeek) for the precise semantics of each rule, including the treatment of dates that precede week 1 of their month.

WeekOfMonth(DateOnly, CalendarWeekRule, DayOfWeek)

Returns the 1-based week number of the month for the specified DateOnly, using the supplied CalendarWeekRule and DayOfWeek as the week-starting day.

public static int WeekOfMonth(this DateOnly date, CalendarWeekRule weekRule, DayOfWeek weekStart)

Parameters

date DateOnly: The date value to evaluate.
weekRule CalendarWeekRule: The CalendarWeekRule that defines how the first week of the year is identified.
weekStart DayOfWeek: The DayOfWeek on which each week begins.

Returns

int: An integer indicating the week of the month in which date falls, starting at 1. Under FirstFullWeek and FirstFourDayWeek, dates that precede week 1 of their month return the week number they carry in the previous month (see remarks).

Remarks

The supplied weekRule determines where week 1 of the month begins, mirroring the semantics the GetWeekOfYear(DateTime, CalendarWeekRule, DayOfWeek) family applies to years:

FirstDay - week 1 begins on the first day of the month, however short that partial week is; each subsequent week begins on the next weekStart.

FirstFullWeek - week 1 begins on the first weekStart on or after the first day of the month. Dates before that boundary belong to the trailing week of the previous month and return that week's number (for example, 1 March 2024 with a Sunday week start returns 4, the week number of the week beginning Sunday 25 February).

FirstFourDayWeek - the week containing the first day of the month is week 1 when at least four of its days fall in that month; otherwise week 1 begins on the following weekStart and the leading dates resolve to the previous month's trailing week, as for FirstFullWeek.

The result is therefore never less than 1, but it is not always the week of the date's own month.

Exceptions

ArgumentOutOfRangeException: Thrown if weekRule is not a defined value of the CalendarWeekRule enumeration, -or- weekStart is not a defined value of the DayOfWeek enumeration.

WeekOfMonth(DateOnly, CultureInfo?)

Returns the 1-based week number of the month for the specified DateOnly, using the calendar settings of the supplied or current culture.

public static int WeekOfMonth(this DateOnly date, CultureInfo? culture)

Parameters

date DateOnly: The date value to evaluate.
culture CultureInfo: An optional CultureInfo that supplies the CalendarWeekRule and DayOfWeek settings. If null, CurrentCulture is used.

Returns

int: An integer indicating the week of the month in which date falls, starting at 1.

Remarks

This overload uses the supplied culture's CalendarWeekRule and FirstDayOfWeek to compute the result. See WeekOfMonth(DateOnly, CalendarWeekRule, DayOfWeek) for the precise semantics of each rule, including the treatment of dates that precede week 1 of their month.

WeekOfYear(DateOnly)

Returns the 1-based week number of the year that contains the specified DateOnly, using the CalendarWeekRule and DayOfWeek settings of CurrentCulture.

public static int WeekOfYear(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

int: An integer in the range 1 - 53 representing the week of the year that contains date.

Remarks

Week numbering is determined by CurrentCulture, which may follow different conventions:

U.S. system: week 1 starts on Sunday and includes January 1.
ISO 8601: week 1 starts on Monday and includes the first Thursday of the year.

WeekOfYear(DateOnly, CalendarWeekRule, DayOfWeek)

Returns the 1-based week number of the year that contains the specified DateOnly, using the supplied CalendarWeekRule and DayOfWeek as the week-starting day.

public static int WeekOfYear(this DateOnly date, CalendarWeekRule weekRule, DayOfWeek weekStart)

Parameters

date DateOnly: The date value to evaluate.
weekRule CalendarWeekRule: The CalendarWeekRule that defines how the first week of the year is identified.
weekStart DayOfWeek: The DayOfWeek on which each week begins.

Returns

int: An integer in the range 1 - 53 representing the week of the year that contains date.

Remarks

This overload enables custom calendar logic such as ISO 8601 (FirstFourDayWeek, Monday) or localized U.S./European systems.

Exceptions

ArgumentOutOfRangeException: Thrown if weekRule is not a defined value of the CalendarWeekRule enumeration, -or- weekStart is not a defined value of the DayOfWeek enumeration.

WeekOfYear(DateOnly, CultureInfo?)

Returns the 1-based week number of the year that contains the specified DateOnly, using the calendar rules of the supplied or current culture.

public static int WeekOfYear(this DateOnly date, CultureInfo? culture)

Parameters

date DateOnly: The date value to evaluate.
culture CultureInfo: An optional CultureInfo that supplies the CalendarWeekRule and DayOfWeek settings. If null, CurrentCulture is used.

Returns

int: An integer in the range 1 - 53 representing the week of the year that contains date.

Remarks

This overload allows culture-specific calculation of week numbers (e.g. for Gregorian or ISO 8601 calendars).

WeekOrdinalOfMonth(DateOnly)

Returns the WeekOrdinal represented by the specified DateOnly, indicating the ordinal occurrence of its DayOfWeek within the month.

public static WeekOrdinal WeekOrdinalOfMonth(this DateOnly date)

Parameters

date DateOnly: The date value to evaluate.

Returns

WeekOrdinal: A WeekOrdinal value indicating which occurrence of the weekday date represents within its calendar month.

Remarks

The result is calculated by counting how many full seven-day intervals have passed since the start of the month, based on Day. For example, the 1st through 7th of the month yield First, while the 8th through 14th yield Second, and so on.

Fifth is only returned when a month contains five occurrences of the given DayOfWeek.

Applies to

Product	Versions
.NET	8, 10

Table of Contents

DateOnlyExtensions Class

Definition

Remarks

Methods

Add(DateOnly, int, int, int)

Parameters

Returns

Remarks

Exceptions

AddFiscalYears(DateOnly, int, IQuarterDefinitionProvider)

Parameters

Returns

Exceptions

Age(DateOnly)

Parameters

Returns

Remarks

Age(DateOnly, DateOnly)

Parameters

Returns

Remarks

DayName(DateOnly)

Parameters

Returns

Remarks

DayName(DateOnly, CultureInfo?)

Parameters

Returns

Remarks

DaysInMonth(DateOnly)

Parameters

Returns

Remarks

DaysInMonth(DateOnly, Calendar?)

Parameters

Returns

Remarks

DaysInMonth(DateOnly, CultureInfo?)

Parameters

Returns

Remarks

DaysInYear(DateOnly)

Parameters

Returns

Remarks

DaysInYear(DateOnly, Calendar?)

Parameters

Returns

Remarks

FirstDateOfFiscalYear(int, IQuarterDefinitionProvider)

Parameters

Returns

Exceptions

FirstDateOfMonth(DateOnly)

Parameters

Returns

Remarks

FirstDateOfQuarter(DateOnly)

Parameters

Returns

Remarks

FirstDateOfQuarter(DateOnly, CalendarQuarterDefinition)

Parameters

Returns

Remarks

Exceptions

FirstDateOfQuarter(DateOnly, IQuarterDefinitionProvider)

Parameters

Returns

Remarks

Exceptions

FirstDateOfWeek(DateOnly)

Parameters

Returns

Remarks

FirstDateOfWeek(DateOnly, WorkingDaysOfWeek)

Parameters

Returns

Remarks