Calendrical.Info (Calendrical v2.2.0)

Copy Markdown

The static facts about a calendar, as data.

Every calendar answers info/0 with one of these structs, built once when the calendar is compiled. The facts are what a calendar is rather than what it computes: the CLDR calendars that name its months and its eras, its epoch, whether it has a year 0, what its year is built of, the fewest and most months a year has, the rule its own weeks follow, the cycles its years run in, the place an astronomical calendar is reckoned at, the lengths its months can have, the calendar its dates are parsed in, and, for a composite calendar, the calendars it is made of. Calendrical's derived functions read these facts and compute every other answer from them and the calendar's kernel callbacks, so a fact that changes an answer is a field here, not a function of the calendar.

Summary

Types

location()

The place an astronomical calendar is reckoned at, as a function of the ISO day number: the latitude and longitude in degrees, the altitude in metres and the offset from UTC in days, as Astro takes them.

member()

A member of a composite calendar: the calendar and the ISO day number of the first day it is in effect on, which is nil for the base calendar in effect before every other.

month_lengths()

The lengths a month can have, by month: a count of days where the month has as many in every year, the range of its lengths where every length between the fewest and the most occurs, and otherwise the list of the lengths that do.

t()
week_rule()

The rule a calendar's own weeks follow: the day they begin on, numbered 1 for Monday to 7 for Sunday or :first_day_of_year where weeks are counted from the first day of the year whatever its weekday, and the fewest days of a year or a month that its week 1 holds.

Functions

calendar_base(calendar)

Returns what a calendar's year is built of, :month or :week, as its info/0 states.

cldr_calendar_type(calendar, year, month, day)

Returns the CLDR calendar type whose data names a date's months and days: that of the member calendar in effect on the date in a composite calendar, by the order of the date's fields, and the calendar's own otherwise.

in_effect(calendar, year, month, day)

Returns the calendar whose facts govern a date: the member of a composite calendar in effect on it, by the order of the date's fields, and the calendar itself otherwise.

location(calendar)

Returns the place a calendar is reckoned at, as its info/0 states, or the Chinese calendar's meridian, the traditional reference, where it names none.

months_in_year(calendar)

Returns the number of months in a calendar's year without a year, as its info/0 states.

new(calendar, fields)

Builds the facts about a calendar from the fields given, with the defaults a calendar leaves unsaid.

parsing_calendars(calendar)

Returns the calendars a date written for a calendar may be written in: the members of a composite calendar, in the order they take effect, and the calendar itself otherwise.

years_in_cycle(calendar)

Returns the number of years after which a calendar's years repeat, as its info/0 states.

Types

location()

@type location() :: (integer() -> {number(), number(), number(), number()})

The place an astronomical calendar is reckoned at, as a function of the ISO day number: the latitude and longitude in degrees, the altitude in metres and the offset from UTC in days, as Astro takes them.

member()

@type member() :: {integer() | nil, module()}

A member of a composite calendar: the calendar and the ISO day number of the first day it is in effect on, which is nil for the base calendar in effect before every other.

month_lengths()

@type month_lengths() :: %{
  optional(Calendar.month()) =>
    Calendar.day() | Range.t() | [Calendar.day(), ...]
}

The lengths a month can have, by month: a count of days where the month has as many in every year, the range of its lengths where every length between the fewest and the most occurs, and otherwise the list of the lengths that do.

t()

@type t() :: %Calendrical.Info{
  calendar: module(),
  cldr_calendar_type: atom(),
  epoch: integer() | nil,
  era_calendar_type: atom(),
  family: module() | nil,
  location: location() | nil,
  members: [member(), ...] | nil,
  month_lengths: month_lengths() | nil,
  months_in_year: {pos_integer(), pos_integer()},
  parsing_calendar: module(),
  structure: :months | :weeks,
  weeks: week_rule(),
  year_cycle: pos_integer() | nil,
  year_zero?: boolean(),
  years_in_cycle: pos_integer() | nil
}

week_rule()

@type week_rule() :: %{
  first_day: Calendar.day_of_week() | :first_day_of_year,
  min_days_in_first_week: 1..7
}

The rule a calendar's own weeks follow: the day they begin on, numbered 1 for Monday to 7 for Sunday or :first_day_of_year where weeks are counted from the first day of the year whatever its weekday, and the fewest days of a year or a month that its week 1 holds.

Functions

calendar_base(calendar)

@spec calendar_base(module()) :: :month | :week

Returns what a calendar's year is built of, :month or :week, as its info/0 states.

Arguments

  • calendar is a calendar module.

Returns

  • :week where the calendar's structure is :weeks, :month otherwise.

Examples

iex> Calendrical.Info.calendar_base(Calendrical.Gregorian)
:month

iex> Calendrical.Info.calendar_base(Calendrical.ISOWeek)
:week

cldr_calendar_type(calendar, year, month, day)

@spec cldr_calendar_type(module(), Calendar.year(), Calendar.month(), Calendar.day()) ::
  atom()

Returns the CLDR calendar type whose data names a date's months and days: that of the member calendar in effect on the date in a composite calendar, by the order of the date's fields, and the calendar's own otherwise.

Arguments

  • calendar is a calendar module.

  • year, month and day are a date of the calendar.

Returns

  • A CLDR calendar type.

Examples

iex> Calendrical.Info.cldr_calendar_type(Calendrical.Gregorian, 2026, 1, 1)
:gregorian

iex> Calendrical.Info.cldr_calendar_type(Calendrical.Reform.Japan, 1870, 1, 1)
:chinese

iex> Calendrical.Info.cldr_calendar_type(Calendrical.Reform.Japan, 1900, 1, 1)
:japanese

in_effect(calendar, year, month, day)

@spec in_effect(module(), Calendar.year(), Calendar.month(), Calendar.day()) ::
  module()

Returns the calendar whose facts govern a date: the member of a composite calendar in effect on it, by the order of the date's fields, and the calendar itself otherwise.

Arguments

  • calendar is a calendar module.

  • year, month and day are a date of the calendar.

Returns

  • A calendar module.

Examples

iex> Calendrical.Info.in_effect(Calendrical.Reform.England, 1700, 1, 1)
Calendrical.Julian.March25

iex> Calendrical.Info.in_effect(Calendrical.Hebrew, 5786, 1, 1)
Calendrical.Hebrew

location(calendar)

@spec location(module()) :: location()

Returns the place a calendar is reckoned at, as its info/0 states, or the Chinese calendar's meridian, the traditional reference, where it names none.

Arguments

  • calendar is a calendar module.

Returns

Examples

iex> Calendrical.Info.location(Calendrical.Chinese) == (&Calendrical.Chinese.location/1)
true

iex> Calendrical.Info.location(Calendrical.Gregorian) == (&Calendrical.Chinese.location/1)
true

months_in_year(calendar)

@spec months_in_year(module()) ::
  pos_integer() | {:ambiguous, Range.t()} | {:error, Exception.t()}

Returns the number of months in a calendar's year without a year, as its info/0 states.

Arguments

  • calendar is a calendar module.

Returns

  • The count where every year has as many months, {:ambiguous, fewest..most} where a leap year has more, or

  • {:error, %Calendrical.NotDefinedError{}} for a composite calendar, whose years change calendar and so are not alike enough to count without a year; Calendrical.Month.months_in_year_bounds/1 gives its bounds.

Examples

iex> Calendrical.Info.months_in_year(Calendrical.Gregorian)
12

iex> Calendrical.Info.months_in_year(Calendrical.Hebrew)
{:ambiguous, 12..13}

iex> Calendrical.Info.months_in_year(Calendrical.Reform.England)
{:error, %Calendrical.NotDefinedError{calendar: Calendrical.Reform.England, question: :months_in_year}}

new(calendar, fields)

@spec new(module(), keyword() | map()) :: t()

Builds the facts about a calendar from the fields given, with the defaults a calendar leaves unsaid.

:family names the module that answers calendar_from_cldr_calendar_type/1 for the calendars of this calendar's family, Calendrical for every calendar Calendrical builds: Localize asks it for the calendar a locale's -u-ca- names, without asking the calendar module itself.

Arguments

  • calendar is the calendar module the facts describe.

  • fields is a keyword list or map of the struct's fields. The defaults are the Gregorian calendar's names and eras, a year 0, a year of months, twelve months, weeks from Monday holding at least one day of the year, no cycles, no place, no stated month lengths, the calendar itself for parsing and no members.

Returns

  • A t/0. :era_calendar_type defaults to :cldr_calendar_type where it is not given, and :parsing_calendar to calendar.

Examples

iex> info = Calendrical.Info.new(Calendrical.Hebrew, cldr_calendar_type: :hebrew, months_in_year: {12, 13})
iex> {info.era_calendar_type, info.parsing_calendar, info.months_in_year}
{:hebrew, Calendrical.Hebrew, {12, 13}}

parsing_calendars(calendar)

@spec parsing_calendars(module()) :: [module(), ...]

Returns the calendars a date written for a calendar may be written in: the members of a composite calendar, in the order they take effect, and the calendar itself otherwise.

Arguments

  • calendar is a calendar module.

Returns

  • A list of calendar modules.

Examples

iex> Calendrical.Info.parsing_calendars(Calendrical.Gregorian)
[Calendrical.Gregorian]

iex> Calendrical.Info.parsing_calendars(Calendrical.Reform.Japan)
[Calendrical.LunarJapanese, Calendrical.Japanese]

years_in_cycle(calendar)

@spec years_in_cycle(module()) :: pos_integer() | {:error, Exception.t()}

Returns the number of years after which a calendar's years repeat, as its info/0 states.

Arguments

  • calendar is a calendar module.

Returns

  • The number of years in the cycle, or

  • {:error, %Calendrical.NotDefinedError{}} where the calendar states none.

Examples

iex> Calendrical.Info.years_in_cycle(Calendrical.Gregorian)
400

iex> Calendrical.Info.years_in_cycle(Calendrical.Chinese)
{:error, %Calendrical.NotDefinedError{calendar: Calendrical.Chinese, question: :years_in_cycle}}