View Source Cldr.Calendar.Korean (ex_cldr_calendars_lunisolar v1.0.0)
Implementation of the Korean lunisolar calendar.
In a ‘regular’ Korean lunisolar calendar, one year is divided into 12 months, with one month corresponding to the time between two full moons.
Since the cycle of the moon is not an even number of days, a month in the lunar calendar can vary between 29 and 30 days and a normal year can have 353, 354, or 355 days.
The default epoch for the Korean lunisolar calendar
is ~D[-2332-02-15]
which is the traditional year of
the founding of the first Korean nation. The epoch can
be changed by setting the :korean_epoch
configuration
key in config.exs
:
config :ex_cldr_calendars,
korean_epoch: ~D[-2332-02-15]
Summary
Functions
Identifies that this calendar is month based.
Returns the calendar year as displayed on rendered calendars.
Defines the CLDR calendar type for this calendar.
Returns the year in the lunisolar sexigesimal 60-year cycle.
Returns the cyclic year as displayed on rendered calendars.
Calculates the day and era from the given
year
, month
, and day
.
Calculates the day of the year from the given
year
, month
, and day
.
Returns how many days there are in the given month.
Returns how many days there are in the given year and month.
Returns the number days in a a week.
Returns the number days in a given year.
Returns the extended year as displayed on rendered calendars.
Returns the Gregorian date for the given gregorian year and lunar month and day.
Calculates the ISO week of the year from the
given year
, month
, and day
.
Returns the ordinal month number of the leap month for a year, or nil if there is no leap month.
Returns a boolean indicating if the given year and month is a leap month.
Returns a boolean indicating if the given year and month is a leap month.
Returns a boolean indicating if the given year is a leap year.
Returns the lunar month of the year for a given date or year and month.
Returns a Date.Range.t
representing
a given month of a year.
Returns the number of months in a leap year.
Returns the number of months in a normal year.
Returns the number of months in a
given year
.
Converts the t:Calendar.iso_days
format to the
datetime format specified by this calendar.
Returns the t:Calendar.iso_days
format of
the specified date.
Returns a Date.t/0
in the Elixir.Cldr.Calendar.Korean
calendar
formed by a calendar year, a cardinal lunar month number
and a cardinal day number.
Returns the gregorian date of the Luanr New Year for a given gregorian year.
Returns the number of periods in a given
year
. A period corresponds to a month
in month-based calendars and a week in
week-based calendars.
Adds an increment
number of date_part
s
to a year-month-day
.
Returns a Date.Range.t
representing
a given quarter of a year.
Returns the quarter of the year from the given
year
, month
, and day
.
Returns the related gregorain year as displayed on rendered calendars.
Returns the Gregorian date of Korean thanksgiving (15th day of 8th lunar month) for a given Gregorian year.
Determines if the date
given is valid according to
this calendar.
Returns a Date.Range.t
representing
a given week of a year.
Calculates the week of the year from the given
year
, month
, and day
.
Calculates the week of the year from the given
year
, month
, and day
.
Returns the number of weeks in a
given year
.
Returns a Date.Range.t
representing
a given year.
Calculates the year and era from the given year
.
Calculates the year and era from the given date
.
Functions
Identifies that this calendar is month based.
@spec calendar_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.year()
Returns the calendar year as displayed on rendered calendars.
Defines the CLDR calendar type for this calendar.
This type is used in support of Cldr.Calendar. localize/3
.
@spec cyclic_year(date :: Date.t()) :: Cldr.Calendar.Lunisolar.cycle()
Returns the year in the lunisolar sexigesimal 60-year cycle.
Traditionally years are numbered only within the cycle however in this implementation the year is an offset from the epoch date. It can be converted to the current year in the current cycle with this function.
The cycle year is commonly shown on lunisolar calendars and it forms part of the traditional Chinese zodiac.
Arguments
date
which is anyDate.t/0
in theCldr.Calendar.Korean
calendar, or
*year
and month
representing the calendar year and month.
Returns
- the integer year within the sexigesimal cycle of 60 years.
Examples
iex> Cldr.Calendar.Korean.cyclic_year(~D[4356-04-01 Cldr.Calendar.Korean])
36
iex> Cldr.Calendar.Korean.cyclic_year(~D[4357-01-01 Cldr.Calendar.Korean])
37
iex> Cldr.Calendar.Korean.cyclic_year(~D[4321-01-01 Cldr.Calendar.Korean])
1
iex> Cldr.Calendar.Korean.cyclic_year(~D[4320-01-01 Cldr.Calendar.Korean])
60
@spec cyclic_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.year()
Returns the cyclic year as displayed on rendered calendars.
@spec day_of_era(Calendar.year(), Calendar.month(), Calendar.day()) :: {day :: Calendar.day(), era :: Calendar.era()}
Calculates the day and era from the given
year
, month
, and day
.
By default we consider on two eras: before the epoch and on-or-after the epoch.
@spec day_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.day()
Calculates the day of the year from the given
year
, month
, and day
.
@spec days_in_month(Calendar.month()) :: Calendar.month() | {:ambiguous, Range.t() | [pos_integer()]} | {:error, :undefined}
Returns how many days there are in the given month.
Must be implemented in derived calendars because we cannot know what the calendar format is.
@spec days_in_month(Calendar.year(), Calendar.month()) :: Calendar.month()
Returns how many days there are in the given year and month.
Returns the number days in a a week.
Returns the number days in a given year.
The year is the number of years since the epoch.
@spec extended_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.year()
Returns the extended year as displayed on rendered calendars.
Returns the Gregorian date for the given gregorian year and lunar month and day.
Arguments
gregorian_year
is any year in the Gregorian calendar.lunar_month
is either a cardinal month number between 1 and 12 or for a leap month the 2-tuple in the format{month, :leap}
.day
is any day number valid foryear
andlunar_month
.
Returns
- A gregorian date
t:Date.t()
.
@spec iso_week_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: {:error, :not_defined}
Calculates the ISO week of the year from the
given year
, month
, and day
.
By default this function always returns
{:error, :not_defined}
.
@spec leap_month(date_or_year :: Date.t() | Calendar.year()) :: Calendar.month() | nil
Returns the ordinal month number of the leap month for a year, or nil if there is no leap month.
Arguments
date_or_year
is either an integer year number or aDate.t/0
in theCldr.Calendar.Korean
calendar.
Returns
either an ordinal month number or
nil
indicating there is no leap month in the given year.
Examples
iex> Cldr.Calendar.Korean.leap_month(4356)
3
iex> Cldr.Calendar.Korean.leap_month(~D[4356-13-29 Cldr.Calendar.Korean])
3
iex> Cldr.Calendar.Korean.leap_month(4357)
nil
Returns a boolean indicating if the given year and month is a leap month.
Arguements
date
is anyDate.t/0
in theCldr.Calendar.Korean
calendar.
Returns
- A booelan indicating if the given year and month is a leap month.
Examples
iex> Cldr.Calendar.Korean.leap_month?(~D[4356-01-01 Cldr.Calendar.Korean])
false
iex> Cldr.Calendar.Korean.leap_month?(~D[4356-03-29 Cldr.Calendar.Korean])
true
@spec leap_month?(year :: Calendar.year(), month :: Calendar.month()) :: boolean()
Returns a boolean indicating if the given year and month is a leap month.
Arguements
year
is any year in theCldr.Calendar.Korean
calendar.month
is any ordinal month number in theCldr.Calendar.Korean
calendar.
Returns
- A booelan indicating if the given year and month is a leap month.
Examples
iex> Cldr.Calendar.Korean.leap_month?(4356, 1)
false
iex> Cldr.Calendar.Korean.leap_month?(4356, 3)
true
@spec leap_year?(date_or_year :: Calendar.year() | Date.t()) :: boolean()
Returns a boolean indicating 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.
Arguments
date_or_year
is either an integer year number or aDate.t/0
in theCldr.Calendar.Korean
calendar.
Returns
- A booelan indicating if the given year is a leap year.
Examples
iex> Cldr.Calendar.Korean.leap_year?(4356)
true
iex> Cldr.Calendar.Korean.leap_year?(4355)
false
@spec lunar_month_of_year(date :: Date.t()) :: Cldr.Calendar.Lunisolar.lunar_month()
Returns the lunar month of the year for a given date or year and month.
The lunar month number in the traditional lunisolar calendar is
between 1 and 12 with a leap month added when there are 13 new moons
between Winter solstices. This intercalary leap month is not
representable in its traditional form in the Date.t/0
struct.
This function takes a date, or year and month, and returns either the
month number between 1 and 12 or a 2-tuple representing the leap month.
This 2-tuple looks like {month_number, :leap}
.
The value returned from this function can be passed to Cldr.Calendar.Korean.new/3
to
define a date using traditional lunar months.
Arguments
date
which is anyDate.t/0
in theCldr.Calendar.Korean
calendar, or
*year
and month
representing the calendar year and month.
Returns
- the lunar month as either an integer between 1 and 12 or a
tuple of the form
{lunar_month, :leap}
.
Examples
iex> Cldr.Calendar.Korean.lunar_month_of_year(~D[4356-02-01 Cldr.Calendar.Korean])
2
iex> Cldr.Calendar.Korean.lunar_month_of_year(~D[4356-03-01 Cldr.Calendar.Korean])
{2, :leap}
iex> Cldr.Calendar.Korean.lunar_month_of_year(~D[4356-04-01 Cldr.Calendar.Korean])
3
@spec lunar_month_of_year(year :: Calendar.year(), month :: Calendar.month()) :: Cldr.Calendar.Lunisolar.lunar_month()
Returns a Date.Range.t
representing
a given month of a year.
Returns the number of months in a leap year.
Returns the number of months in a normal year.
Returns the number of months in a
given year
.
@spec naive_datetime_from_iso_days(Calendar.iso_days()) :: {Calendar.year(), Calendar.month(), Calendar.day(), Calendar.hour(), Calendar.minute(), Calendar.second(), Calendar.microsecond()}
Converts the t:Calendar.iso_days
format to the
datetime format specified by this calendar.
naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond)
View Source@spec naive_datetime_to_iso_days( Calendar.year(), Calendar.month(), Calendar.day(), Calendar.hour(), Calendar.minute(), Calendar.second(), Calendar.microsecond() ) :: Calendar.iso_days()
Returns the t:Calendar.iso_days
format of
the specified date.
@spec new( year :: Calendar.year(), month :: Cldr.Calendar.Lunisolar.lunar_month(), day :: Calendar.day() ) :: {:ok, Date.t()} | {:error, atom()}
Returns a Date.t/0
in the Elixir.Cldr.Calendar.Korean
calendar
formed by a calendar year, a cardinal lunar month number
and a cardinal day number.
The lunar month number is that used in traditional lunisolar
calendar notation. It is either a number between 1 and 12
(the number of months in an ordinary year) or a leap month
specified by the 2-tuple {month, :leap}
.
This function is therefore most useful for creating tradition calendar dates for holidays and other events defined in the lunisolar calendar.
Arguments
year
is any year in theCldr.Calendar.Korean
calendar.lunar_month
is either a cardinal month number between 1 and 12 or for a leap month the 2-tuple in the format{month, :leap}
.day
is any day number valid foryear
andmonth
Returns
{:ok, date}
or{:error, reason}
Examples
# Buddha's birthday is the 8th day of
# lunar month 4. In a leap year that is the
# fifth ordainal month.
iex> Cldr.Calendar.Korean.new(4356, 4, 8)
{:ok, ~D[4356-05-08 Cldr.Calendar.Korean]}
# In an ordianry year lunar month four is the same
# as the fourth ordinal month.
iex(6)> Cldr.Calendar.Korean.new(4355, 4, 8)
{:ok, ~D[4355-04-08 Cldr.Calendar.Korean]}
@spec new_year_for_gregorian_year(Calendar.year()) :: Date.t()
Returns the gregorian date of the Luanr New Year for a given gregorian year.
Arguments
gregorian_year
is any year in the Gregorian calendar.
Returns
- a
Date.t/0
representing the Gregorian date of the lunar year of the given Gregorian year.
Example
iex> Cldr.Calendar.Chinese.new_year_for_gregorian_year(2021)
~D[2021-02-12]
iex> Cldr.Calendar.Chinese.new_year_for_gregorian_year(2022)
~D[2022-02-01]
iex> Cldr.Calendar.Chinese.new_year_for_gregorian_year(2023)
~D[2023-01-22]
Returns the number of periods in a given
year
. A period corresponds to a month
in month-based calendars and a week in
week-based calendars.
Adds an increment
number of date_part
s
to a year-month-day
.
date_part
can be :months
only.
Returns a Date.Range.t
representing
a given quarter of a year.
@spec quarter_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Cldr.Calendar.quarter()
Returns the quarter of the year from the given
year
, month
, and day
.
@spec thanksgiving_for_gregorian_year(Calendar.year()) :: Date.t()
Returns the Gregorian date of Korean thanksgiving (15th day of 8th lunar month) for a given Gregorian year.
Arguments
year
is any year in the Gregorian calendar.
Returns
- The Gregorian date of the Korean thanksgiving date for the given year.
Example
iex> Cldr.Calendar.Korean.thanksgiving_for_gregorian_year(2021)
~D[2021-09-21]
iex> Cldr.Calendar.Korean.thanksgiving_for_gregorian_year(2022)
~D[2022-09-10]
iex> Cldr.Calendar.Korean.thanksgiving_for_gregorian_year(2023)
~D[2023-09-29]
Determines if the date
given is valid according to
this calendar.
Returns a Date.Range.t
representing
a given week of a year.
@spec week_of_month(Calendar.year(), Calendar.month(), Calendar.day()) :: {pos_integer(), pos_integer()} | {:error, :not_defined}
Calculates the week of the year from the given
year
, month
, and day
.
By default this function always returns
{:error, :not_defined}
.
@spec week_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: {:error, :not_defined}
Calculates the week of the year from the given
year
, month
, and day
.
By default this function always returns
{:error, :not_defined}
.
Returns the number of weeks in a
given year
.
Returns a Date.Range.t
representing
a given year.
@spec year_of_era(Calendar.year()) :: {year :: Calendar.year(), era :: Calendar.era()}
Calculates the year and era from the given year
.
@spec year_of_era(Calendar.year(), Calendar.month(), Calendar.day()) :: {year :: Calendar.year(), era :: Calendar.era()}
Calculates the year and era from the given date
.