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

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

# `calendar_for`

```elixir
@spec calendar_for(atom() | String.t()) ::
  {:ok, module()} | {:error, Exception.t() | String.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

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

### Returns

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

* `{:error, exception}` if the territory is unknown or has no pre-built
  fiscal calendar.

### Examples

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

# `known_fiscal_calendars`

```elixir
@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`

```elixir
@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 `: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*