FiscalWeekQuarterProvider Class

Definition

Namespace

Bodu.Extensions

Assembly

Bodu.Core.dll

Package

Bodu.Core 1.0.1

Source

FiscalWeekQuarterProvider.cs

Provides quarter boundary logic for a week-based retail fiscal calendar using a configurable FiscalWeekPattern (5-4-4, 4-5-4, or 4-4-5 week distribution).

public sealed class FiscalWeekQuarterProvider : IQuarterDefinitionProvider

Inheritance

object

FiscalWeekQuarterProvider

Implements

IQuarterDefinitionProvider

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

This provider describes a recurring fiscal calendar rule. Each quarter consists of exactly 13 weeks, divided into three fiscal periods according to the FiscalWeekPattern supplied at construction. Quarters are defined as contiguous 13-week blocks measured from the fiscal year start:

• Q1Weeks 1-13
• Q2Weeks 14-26
• Q3Weeks 27-39
• Q4Weeks 40-52 (or 40-53 in a 53-week year)

The FiscalWeekPattern controls how the 13 weeks within each quarter are divided into three fiscal periods (fiscal months). It does not affect quarter start or end boundaries, but is exposed via the Pattern property for consumers that require intra-quarter period logic.

A fiscal year may contain a 53rd week when the span between the computed fiscal year start and the equivalent start in the following year exceeds 364 days. In a 53-week year, the extra week is always appended to Q4.

The fiscal week start day is governed by the DayOfWeek supplied to the constructor. Year-specific values - the fiscal year start date, whether a given year contains 53 weeks, and quarter boundaries - are computed on demand from either an explicit fiscalYear argument or from the input date itself.

Constructors

FiscalWeekQuarterProvider(int, DayOfWeek, bool, bool, FiscalWeekPattern)

Initializes a new instance of the FiscalWeekQuarterProvider class using the specified anchor month and alignment options.

public FiscalWeekQuarterProvider(int month, DayOfWeek dayOfWeek = DayOfWeek.Saturday, bool isFiscalYearEnd = true, bool useNearestDayOfWeek = true, FiscalWeekPattern pattern = FiscalWeekPattern.Weeks445)

Parameters

month int

The calendar month (1-12) of the fiscal year anchor.

dayOfWeek DayOfWeek

The day of the week on which each fiscal week begins. Common values are Sunday and Saturday. Defaults to Saturday.

isFiscalYearEnd bool

When true, month identifies the fiscal year's closing month, and the actual fiscal start month is the one that follows. When false, month identifies the fiscal year's opening month directly. Defaults to true.

useNearestDayOfWeek bool

true to align the fiscal year start to the occurrence of dayOfWeek nearest to the computed anchor date; false to align it to the occurrence of dayOfWeek on or before the computed anchor date. Defaults to true.

pattern FiscalWeekPattern

The week distribution pattern applied to the three fiscal periods within each quarter. Defaults to Weeks445.

Remarks

The fiscal year start for a given fiscalYear is derived from the first day of the anchor month in that year, then aligned to the configured fiscal week start day using one of two strategies:

• When useNearestDayOfWeek is true, the start date is aligned to the occurrence of dayOfWeek nearest to the computed anchor date.
• When useNearestDayOfWeek is false, the start date is aligned to the occurrence of dayOfWeek on or before the computed anchor date.

When isFiscalYearEnd is true, the anchor is the first day of the month following month. The fiscal year still begins on the occurrence of dayOfWeek selected by useNearestDayOfWeek, so the fiscal week boundary always coincides with dayOfWeek.

Exceptions

ArgumentOutOfRangeException

Thrown when month is not in the range 1-12, -or- dayOfWeek is not a defined DayOfWeek value, -or- pattern is not a defined FiscalWeekPattern value.

Properties

Pattern

Gets the week distribution pattern applied to the three fiscal periods within each quarter.

public FiscalWeekPattern Pattern { get; }

Property Value

FiscalWeekPattern

One of the FiscalWeekPattern values that describes how the 13 weeks of each quarter are divided into fiscal periods.

Methods

GetFiscalYear(DateOnly)

Returns the fiscal year that contains the supplied DateOnly.

public int GetFiscalYear(DateOnly dateOnly)

Parameters

dateOnly DateOnly

The date to identify.

Returns

int

The fiscal year number under the provider's conventions.

Exceptions

ArgumentOutOfRangeException

Thrown when dateOnly cannot be mapped to any fiscal year known to the provider.

GetFiscalYear(DateTime)

Returns the fiscal year that contains the supplied DateTime.

public int GetFiscalYear(DateTime dateTime)

Parameters

dateTime DateTime

The date to identify.

Returns

int

The fiscal year number under the provider's conventions.

Remarks

The default implementation probes the calendar years dateTime.Year - 1, dateTime.Year, and dateTime.Year + 1, returning the candidate whose Q1 start and Q4 end bracket dateTime . This works for any provider whose fiscal year is contiguous and at most one calendar year away from the observed calendar year. Implementations may override with a more efficient or more precise computation.

Exceptions

ArgumentOutOfRangeException

Thrown when dateTime cannot be mapped to any fiscal year known to the provider.

GetQuarter(DateOnly)

Returns the quarter number (1-4) that contains the specified DateOnly.

public int GetQuarter(DateOnly dateOnly)

Parameters

dateOnly DateOnly

The input DateOnly for which to determine the quarter.

Returns

int

An integer in the range 1 to 4 representing the quarter that includes dateOnly.

Exceptions

ArgumentOutOfRangeException

Thrown when dateOnly cannot be mapped to a recognized fiscal year.

GetQuarter(DateTime)

Returns the quarter number (1-4) that contains the specified DateTime.

public int GetQuarter(DateTime dateTime)

Parameters

dateTime DateTime

The input DateTime for which to determine the quarter.

Returns

int

An integer in the range 1 to 4 representing the quarter that includes dateTime.

Exceptions

ArgumentOutOfRangeException

Thrown when dateTime cannot be mapped to a recognized fiscal year.

GetQuarterEnd(DateTime)

Returns the last day of the quarter that contains the specified DateTime.

public DateTime GetQuarterEnd(DateTime dateTime)

Parameters

dateTime DateTime

The input DateTime for which to determine the end of the quarter.

Returns

DateTime

A DateTime set to midnight (00:00:00) on the final day of the quarter that includes dateTime. The result preserves the original Kind.

Exceptions

ArgumentOutOfRangeException

Thrown when dateTime cannot be mapped to a recognized fiscal year.

GetQuarterEnd(int, int)

Returns the last day of the specified quarter number (1-4) within the given fiscal year.

public DateTime GetQuarterEnd(int quarter, int fiscalYear)

Parameters

quarter int

The quarter number (1-4).

fiscalYear int

The fiscal year whose quarter boundary is being requested.

Returns

DateTime

A DateTime set to midnight (00:00:00) on the last day of the specified quarter.

Exceptions

ArgumentOutOfRangeException

Thrown when quarter is not between 1 and 4.

GetQuarterEndDate(DateOnly)

Returns the last day of the quarter that contains the specified DateOnly.

public DateOnly GetQuarterEndDate(DateOnly dateOnly)

Parameters

dateOnly DateOnly

The input DateOnly for which to determine the end of the quarter.

Returns

DateOnly

A DateOnly representing the final day of the quarter that includes dateOnly.

Exceptions

ArgumentOutOfRangeException

Thrown when dateOnly cannot be mapped to a recognized fiscal year.

GetQuarterEndDate(int, int)

Returns the last day of the specified quarter number (1-4) within the given fiscal year.

public DateOnly GetQuarterEndDate(int quarter, int fiscalYear)

Parameters

quarter int

The quarter number (1-4).

fiscalYear int

The fiscal year whose quarter boundary is being requested.

Returns

DateOnly

A DateOnly representing the final day of the specified quarter.

Exceptions

ArgumentOutOfRangeException

Thrown when quarter is not between 1 and 4.

GetQuarterStart(DateTime)

Returns the first day of the quarter that contains the specified DateTime.

public DateTime GetQuarterStart(DateTime dateTime)

Parameters

dateTime DateTime

The input DateTime for which to determine the start of the quarter.

Returns

DateTime

A DateTime set to midnight (00:00:00) on the first day of the quarter that includes dateTime. The result preserves the original Kind.

Exceptions

ArgumentOutOfRangeException

Thrown when dateTime cannot be mapped to a recognized fiscal year.

GetQuarterStart(int, int)

Returns the first day of the specified quarter number (1-4) within the given fiscal year.

public DateTime GetQuarterStart(int quarter, int fiscalYear)

Parameters

quarter int

The quarter number (1-4).

fiscalYear int

The fiscal year whose quarter boundary is being requested.

Returns

DateTime

A DateTime set to midnight (00:00:00) on the first day of the specified quarter.

Exceptions

ArgumentOutOfRangeException

Thrown when quarter is not between 1 and 4.

GetQuarterStartDate(DateOnly)

Returns the first day of the quarter that contains the specified DateOnly.

public DateOnly GetQuarterStartDate(DateOnly dateOnly)

Parameters

dateOnly DateOnly

The input DateOnly for which to determine the start of the quarter.

Returns

DateOnly

A DateOnly representing the first day of the quarter that includes dateOnly.

Exceptions

ArgumentOutOfRangeException

Thrown when dateOnly cannot be mapped to a recognized fiscal year.

GetQuarterStartDate(int, int)

Returns the first day of the specified quarter number (1-4) within the given fiscal year.

public DateOnly GetQuarterStartDate(int quarter, int fiscalYear)

Parameters

quarter int

The quarter number (1-4).

fiscalYear int

The fiscal year whose quarter boundary is being requested.

Returns

DateOnly

A DateOnly representing the first day of the specified quarter.

Exceptions

ArgumentOutOfRangeException

Thrown when quarter is not between 1 and 4.

GetWeeksInFiscalYear(int)

Returns the total number of weeks in the specified fiscal year.

public int GetWeeksInFiscalYear(int fiscalYear)

Parameters

fiscalYear int

The fiscal year to query.

Returns

int

53 in a 53-week fiscal year; otherwise, 52.

Is53WeekFiscalYear(int)

Returns a value indicating whether the specified fiscal year contains 53 weeks rather than the standard 52.

public bool Is53WeekFiscalYear(int fiscalYear)

Parameters

fiscalYear int

The fiscal year to test.

Returns

bool

true if the fiscal year spans 371 days (53 complete weeks); false if it spans 364 days (52 complete weeks).

Applies to

Product	Versions
.NET	8, 10