Calendrical.
Copy Markdown
Era arithmetic for CLDR calendars.
Era definitions come from the era data in CLDR,
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.
Summary
Types
A CLDR calendar type, such as :gregorian or :persian.
Functions
Returns the day of era and era number for a date.
Returns the resolved era data for a CLDR calendar type.
Returns the year of era and era number for a date.
Types
@type cldr_calendar_type() :: atom()
A CLDR calendar type, such as :gregorian or :persian.
Functions
@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_typeis the CLDR calendar type of the calendar, such as:persianor:japanese.iso_daysis the date as a count of days since the proleptic ISO epoch.
Returns
- A two-tuple
{day_of_era, era}whereday_of_erais 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}@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_typeis the CLDR calendar type of the calendar, such as:persianor:japanese.
Returns
- A map with the era records (most recent era first), the year-numbering mode and the forward/before era numbers.
@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_typeis the CLDR calendar type of the calendar, such as:persianor:japanese.iso_daysis the date as a count of days since the proleptic ISO epoch.yearis 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}