# `Calendrical.FiscalYear`

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

# `calendar_for`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*