Calendrical.FiscalYear (Calendrical v0.3.0)

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 tax year begins on 6 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.

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> {:ok, us_fy} = Calendrical.FiscalYear.calendar_for(:US)
iex> us_fy
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)

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). Subsequent calls return the same module.

Arguments

territory is any value accepted by Localize.validate_territory/1, typically an atom such as :US, :UK, :AU, :JP.

Returns

{:ok, calendar_module} on success, where calendar_module is a module implementing both the Calendar and Calendrical behaviours.
{:error, exception} if the territory is unknown or has no pre-built fiscal calendar.

Examples

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

known_fiscal_calendars()

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()

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

Each value is a keyword list with :calendar and :month_of_year keys describing the base calendar and the starting month of the fiscal year.

Returns

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

Examples

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