View Source Cldr.Calendar.Lunisolar (ex_cldr_calendars_lunisolar v1.0.0)

Template for building lunisolar calendars. See Cldr.Calendar.Chinese for an example implementation.

The functions in this module should only be called from lunisolar implementations.

Some conventions are used for naming in this module:

  • year refers to the calendar year with is the number of years since the epoch.

  • cyclical_year is the year in the sexigesimal cycle.

  • month is the ordinal month in the calendar year that is between 1 and 12 for an ordinary year and between 1 and 13 in a leap year.

  • lunar_month is a the month numbered similarly to how months are traditionally numbered. The month will be a cardinal number between 1 and 12 in all years with the addition of a leap month in leap years. The leap month is represented by {month, :keap}.

Summary

Types

A sexigesimal cycle number

A lunar month

Functions

Return iso_days of Lunar New Year at location for a Gregorian year.

Return last Chinese major solar term (zhongqi) before iso_days.

Return last minor solar term (jieqi) before iso_days.

Return sexagesimal name for date, date.

Return iso_days of latest date on or before iso_days, that has Chinese name, name.

Return iso_days, in the location zone, of winter solstice on or before iso_days.

Returns the Gregorian date for the lunar month and day in a given Gregorian year.

Return true if there is a Lunar leap month on or after lunar month starting on m_prime and at or before lunar month starting at m.

Returns the leap month number for a given year or nil if its not a leap year.

Approximately every three years (7 times in 19 years), a leap month is added to the Chinese calendar.

Returns if the given year is a leap year.

Return moment at location of the first major solar term (zhongqi) on or after iso_days. The major terms begin when the sun's longitude is a multiple of 30 degrees.

Return Universal time of (clock) midnight at start of iso_days, at location.

Return moment at location of the first minor solar term (jieqi) on or after iso_days. The minor terms begin when the sun's longitude is an odd multiple of 15 degrees.

Return sexagesimal name for month, month, of Chinese year, year.

Return the number of names from Lunar name c_name1 to the next occurrence of Lunar name c_name2.

Create a new date in the lunisolar calendar.

Return iso_day at location of first new moon before iso_days.

Return iso_day at location of first new moon on or after iso_days.

Return iso_day of Lunar New Year in sui (period from solstice to solstice) containing iso_days.

Return iso_day of Lunar New Year on or before iso_days at location.

Return true if lunar month starting on iso_days at location has no major solar term.

Return moment at location of the first date on or after iso_days when the solar longitude will be 'lambda' degrees.

Return the name of the Lunar sexagesimal cycle.

Types

@type cycle() :: pos_integer()

A sexigesimal cycle number

@type lunar_month() :: Calendar.month() | {Calendar.month(), :leap}

A lunar month

Functions

Link to this function

chinese_new_year_for_gregorian_year(gregorian_year, location_fun)

View Source

Return iso_days of Lunar New Year at location for a Gregorian year.

Link to this function

current_major_solar_term(iso_days, location_fun)

View Source

Return last Chinese major solar term (zhongqi) before iso_days.

Link to this function

current_minor_solar_term(iso_days, location_fun)

View Source

Return last minor solar term (jieqi) before iso_days.

Link to this function

cyclical_date_to_iso_days(cycle, cyclical_year, month, day, epoch, location_fun)

View Source
Link to this function

date_from_iso_days(iso_days, epoch, location_fun)

View Source
Link to this function

date_to_iso_days(year, month, day, epoch, location_fun)

View Source

Return sexagesimal name for date, date.

Link to this function

day_name_on_or_before(name, date)

View Source

Return iso_days of latest date on or before iso_days, that has Chinese name, name.

Link to this function

december_solstice_on_or_before(iso_days, location_fun)

View Source

Return iso_days, in the location zone, of winter solstice on or before iso_days.

Link to this function

gregorian_date_for_lunar(gregorian_year, lunar_month, lunar_day, epoch, location_fun)

View Source

Returns the Gregorian date for the lunar month and day in a given Gregorian year.

Link to this function

is_prior_leap_month?(m_prime, m, location_fun)

View Source

Return true if there is a Lunar leap month on or after lunar month starting on m_prime and at or before lunar month starting at m.

Link to this function

leap_month(year, epoch, location_fun)

View Source

Returns the leap month number for a given year or nil if its not a leap year.

Link to this function

leap_month?(year, month, epoch, location_fun)

View Source

Approximately every three years (7 times in 19 years), a leap month is added to the Chinese calendar.

To determine when, find the number of new moons between the 11th month in one year and the 11th month in the following year.

A leap month is inserted if there are 13 New Moons from the start of the 11th month in the first year to the start of the 11th month in the next year.

The Chinese calendar uses a solar term system that has 12 principal terms to indicate when the Sun's longitude is a multiple of 30 degrees.

Unlike all other months, the leap month does not contain a principal term (Zhongqi).

Link to this function

leap_month?(cycle, cyclical_year, month, epoch, location_fun)

View Source
Link to this function

leap_year?(year, epoch, location_fun)

View Source

Returns if the given year is a leap year.

Leap years have 13 months. To determine if a year is a leap year, calculate the number of new moons between the 11th month in one year (i.e., the month containing the Winter Solstice) and the 11th month in the following year.

If there are 13 new moons from the start of the 11th month in the first year to the start of the 11th month in the second year, a leap month must be inserted.

In leap years, at least one month does not contain a Principal Term. The first such month is the leap month.

The additional complexity is that a leap year is calculated for the solar year, but the calendar is managed in lunar years and months. Therefore when a leap year is detected, the leap month could be in the current lunar year or the next lunar year.

Link to this function

location(iso_days, location_fun)

View Source
Link to this function

major_solar_term_on_or_after(iso_days, location_fun)

View Source

Return moment at location of the first major solar term (zhongqi) on or after iso_days. The major terms begin when the sun's longitude is a multiple of 30 degrees.

Link to this function

midnight_in_location(iso_days, location_fun)

View Source

Return Universal time of (clock) midnight at start of iso_days, at location.

Link to this function

minor_solar_term_on_or_after(iso_days, location_fun)

View Source

Return moment at location of the first minor solar term (jieqi) on or after iso_days. The minor terms begin when the sun's longitude is an odd multiple of 15 degrees.

Return sexagesimal name for month, month, of Chinese year, year.

Link to this function

name_difference(c_name1, c_name2)

View Source

Return the number of names from Lunar name c_name1 to the next occurrence of Lunar name c_name2.

Link to this function

new(year, month, day, epoch, location_fun)

View Source

Create a new date in the lunisolar calendar.

Arguments

  • year is a year in the lunisolar calendar.

  • month is a month in the lunisolar calendar as either a positive integer or a tuple of the form {month, :leap} representing the leap month.

  • day is a day of month.

  • epoch is the epoch in iso days for the lunisolar calendar.

  • location_fun is a 1-arity function that returns the tuple of the form {latitude, longitude, altitude, hour_offset} for the lunisolar calendar.

Returns

  • iso_days begin the iso_days for the given date in based upon the given location.
Link to this function

new_moon_before(iso_days, location_fun)

View Source

Return iso_day at location of first new moon before iso_days.

Link to this function

new_moon_on_or_after(iso_days, location_fun)

View Source

Return iso_day at location of first new moon on or after iso_days.

Link to this function

new_year_in_sui(iso_days, location_fun)

View Source

Return iso_day of Lunar New Year in sui (period from solstice to solstice) containing iso_days.

Link to this function

new_year_on_or_before(iso_days, location_fun)

View Source

Return iso_day of Lunar New Year on or before iso_days at location.

Link to this function

no_major_solar_term?(iso_days, location_fun)

View Source

Return true if lunar month starting on iso_days at location has no major solar term.

Link to this function

solar_longitude_on_or_after(lambda, iso_days, location_fun)

View Source
@spec solar_longitude_on_or_after(Astro.angle(), number(), function()) ::
  Astro.Time.time()

Return moment at location of the first date on or after iso_days when the solar longitude will be 'lambda' degrees.

Return the name of the Lunar sexagesimal cycle.