Calendrical.Calendar.Lunisolar (Calendrical v2.2.0)

Copy Markdown

Makes a lunisolar calendar reckoned from the sky: a year of twelve or thirteen lunar months that begins at the second new moon after the winter solstice, with the leap month placed by the solar terms, as the Chinese, Korean, Vietnamese and traditional Japanese calendars are.

The maker supplies the whole kernel from Calendrical.Lunisolar, which is parametrised by the calendar's epoch and the place it is reckoned at, and the functions a lunisolar calendar is asked beyond the kernel: a date from a traditional month, the Gregorian date of a lunar date, the new year of a Gregorian year, and the sexagenary cycle and year of a year and the year they name. A module keeps its own extras, as the festivals, beside them.

Options

  • :epoch is the first day of the calendar's year 1, as a Date.t/0.

  • :location is the place the calendar is reckoned at, a function of the ISO day number giving {latitude, longitude, altitude, offset} as Astro takes them.

  • :cldr_calendar_type is the CLDR calendar whose data names the months, :chinese by default.

  • :era_calendar_type is the CLDR calendar whose eras the calendar counts years in, the CLDR calendar type by default.

Supported years

A calendar answers for the 40,001 years numbered, from the Gregorian year of its epoch, as Gregorian years -20,000 to 20,000: Calendrical.Chinese years -17,363 to 22,637, which run from late -20,001 to early 20,001. Beyond them the new moons the calendar is reckoned from drift from their mean timing faster than a search can follow, so:

  • valid_date?/3 is false, and a question about a date (year/1, days_in_year/1, day_of_week/4, year_of_era/3 and the rest) answers {:error, %Calendrical.InvalidDateError{}}, as for any date the calendar lacks.

  • new/3 and days_in_month/2 return {:error, %Calendrical.UnsupportedDateRangeError{}}.

  • date_to_iso_days/3, date_from_iso_days/1, leap_year?/1, leap_month/1, leap_month?/2, months_in_year/1 and, for a Gregorian year outside -20,000 to 20,000, gregorian_date_for_lunar/3 raise Calendrical.UnsupportedDateRangeError, as the sighting Islamic calendars do outside their ephemeris.

Examples

defmodule Chinese do
  use Calendrical.Calendar.Lunisolar,
    epoch: ~D[-2636-02-15],
    location: &__MODULE__.location/1

  def location(_iso_days), do: {39.9, 116.4, 44, 8 / 24}
end