# `Calendrical.Era`

Era arithmetic for CLDR calendars.

Era definitions come from the [era data in CLDR](https://github.com/unicode-org/cldr/blob/main/common/supplemental/supplementalData.xml),
where era boundaries are expressed as proleptic Gregorian dates —
with one exception: Japanese eras before Meiji are lunisolar
passthroughs (the proclamation's traditional `年月日` numerals
copied into the Western fields unconverted) and are resolved
through `Calendrical.LunarJapanese`. On first access the
boundaries for a calendar type are resolved to ISO day counts and
cached in `:persistent_term`, so lookups are lock-free and
copy-free with no compile-time code generation.

Two year-numbering styles cover all CLDR calendars:

* Most calendars number their years from the epoch of their
  primary era, so the year of era is the calendar year itself
  (`{year, era}`). Years at or before zero belong to a
  "before" era when CLDR defines one (BCE, before ROC, before
  Hijra) and count backwards: year 0 is year 1 of that era.

* The Japanese calendar numbers years in Gregorian years while
  eras begin mid-year, so the era is selected by the date and
  the year of era is counted from each era's first Gregorian
  year.

# `cldr_calendar_type`

```elixir
@type cldr_calendar_type() :: atom()
```

A CLDR calendar type, such as `:gregorian` or `:persian`.

# `day_of_era`

```elixir
@spec day_of_era(cldr_calendar_type(), integer()) :: {Calendar.day(), Calendar.era()}
```

Returns the day of era and era number for a date.

### Arguments

* `cldr_calendar_type` is the CLDR calendar type of the
  calendar, such as `:persian` or `:japanese`.

* `iso_days` is the date as a count of days since the
  proleptic ISO epoch.

### Returns

* A two-tuple `{day_of_era, era}` where `day_of_era` is the
  count of days since the era began.

### Examples

    iex> iso_days = Date.to_gregorian_days(~D[2019-05-01])
    iex> Calendrical.Era.day_of_era(:japanese, iso_days)
    {1, 236}

# `era_data`

```elixir
@spec era_data(cldr_calendar_type()) :: map()
```

Returns the resolved era data for a CLDR calendar type.

The data is computed on first access and cached in
`:persistent_term`.

### Arguments

* `cldr_calendar_type` is the CLDR calendar type of the
  calendar, such as `:persian` or `:japanese`.

### Returns

* A map with the era records (most recent era first), the
  year-numbering mode and the forward/before era numbers.

# `year_of_era`

```elixir
@spec year_of_era(cldr_calendar_type(), integer(), Calendar.year()) ::
  {Calendar.year(), Calendar.era()}
```

Returns the year of era and era number for a date.

### Arguments

* `cldr_calendar_type` is the CLDR calendar type of the
  calendar, such as `:persian` or `:japanese`.

* `iso_days` is the date as a count of days since the
  proleptic ISO epoch.

* `year` is the year of the date in the calendar's own
  numbering.

### Returns

* A two-tuple `{year_of_era, era}`.

### Examples

    iex> iso_days = Date.to_gregorian_days(~D[2019-05-01])
    iex> Calendrical.Era.year_of_era(:japanese, iso_days, 2019)
    {1, 236}

    iex> Calendrical.Era.year_of_era(:persian, 0, 1405)
    {1405, 0}

---

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