Calendrical.FiscalYear (Calendrical v2.2.0)

Copy Markdown

Pre-built fiscal-year calendars for ISO 3166 territories.

Many jurisdictions use a fiscal (financial, accounting, tax) year that does not start on 1 January. For example, the United States federal fiscal year begins on 1 October, and the United Kingdom government financial year on 1 April.

This module embeds the fiscal-year start month for ~50 territories at compile time (sourced from priv/fiscal_years_by_territory.csv) and provides a factory, calendar_for/1, that returns a Calendrical month-based calendar configured for that territory.

Only the start month is modelled, so a fiscal year that begins part-way through a month is not one of these calendars. The United Kingdom has one of each: its government financial year begins on 1 April, which :GB is, and its personal tax year on 6 April, which no calendar here expresses. The two are commonly written alike — "2026/27", "2026-27" or "tax year 2026 to 2027" — so a label naming which year is meant is worth carrying.

The returned calendar is a fully-fledged Calendar implementation: it can be used with Date.new/4, Date.shift/2, Calendrical.Interval, Calendrical.localize/3, the Calendar.strftime/3 formatter, and the native ~D sigil with calendar suffix.

Examples

iex> Calendrical.FiscalYear.calendar_for(:US)
{:ok, Calendrical.FiscalYear.US}

iex> :US in Calendrical.FiscalYear.known_fiscal_calendars()
true

Summary

Functions

calendar_for(territory)

Returns a Calendrical fiscal-year calendar module for the given ISO 3166 territory code.

known_fiscal_calendars()

Returns the list of ISO 3166 territory codes for which a pre-built fiscal calendar is available.

known_fiscal_years()

Returns the map of all known fiscal-year configurations keyed by ISO 3166 territory code.

Functions

calendar_for(territory)

@spec calendar_for(atom() | String.t()) :: {:ok, module()} | {:error, Exception.t()}

Returns a Calendrical fiscal-year calendar module for the given ISO 3166 territory code.

The calendar module is created on first use and cached as a normal Elixir module (e.g. Calendrical.FiscalYear.US). The call is idempotent: later calls for the same territory return the same module.

Arguments

Returns

  • {:ok, calendar_module} where calendar_module implements both the Calendar and Calendrical behaviours.

  • {:error, %Localize.UnknownTerritoryError{}} for a value that is no territory.

  • {:error, %Calendrical.UnknownFiscalYearError{}} for a territory with no fiscal calendar.

Examples

iex> Calendrical.FiscalYear.calendar_for(:US)
{:ok, Calendrical.FiscalYear.US}

known_fiscal_calendars()

@spec known_fiscal_calendars() :: [atom(), ...]

Returns the list of ISO 3166 territory codes for which a pre-built fiscal calendar is available.

Returns

  • A list of atoms (territory codes).

Examples

iex> :US in Calendrical.FiscalYear.known_fiscal_calendars()
true

known_fiscal_years()

@spec known_fiscal_years() :: %{required(atom()) => Keyword.t()}

Returns the map of all known fiscal-year configurations keyed by ISO 3166 territory code.

Each value is a keyword list with :base and :year_begins keys, the options of Calendrical.Calendar.Shifted that build the fiscal year: its base calendar and the month and day it begins on.

Returns

  • A map of %{atom() => Keyword.t()}.

Examples

iex> map = Calendrical.FiscalYear.known_fiscal_years()
iex> Map.has_key?(map, :US)
true