View Source Cldr.Calendar behaviour (Cldr Calendars v1.26.1)
Calendar functions for calendars compatible with
Elixir's Calendar
behaviour.
Cldr.Calendar
supports the creation of calendars
that are variations on the proleptic Cldr.Calendar.Gregorian
calendar. It also adds additional functions, defined
by the Cldr.Calendar
behaviour, to support these
derived calendars.
The common purpose of these derived calendars is to support the creation and use of financial year calendars that are commonly used in business.
There are two general types of calendars supported:
month
calendars that mirror the monthly structure of the prolepticCldr.Calendar.Gregorian
calendar but which are deemed to start the year in a month other than January.week
calendars that are defined to have a 52 week structure (53 weeks in a long year). These calendars can be configured to start or end on the first, last or nearest day to the beginning or end of a Cldr.Calendar.Gregorian month. The main intent behind this structure is to have each year start and end on the same day of the week with a consistent 13-week quarterly structure than enables a more straight forware comparison with same-period-last-year financial performance.
Summary
Types
Super type of any date or time
Specifies the type of a calendar.
Specifies the type of a calendar
All date fields are optional however many functions will require the presence of one or more - and often all - fields be present.
All date time fields are optional however many functions will require the presence of one or more - and often all - fields be present.
Specifies the day of a date as either a positive integer or nil.
Specifies the days of the week as integers.
A mapping of a day of the week ordinal to the localized string of the name of that day.
Specifies the year of a date as either a positive integer or nil.
The types of relationship between two Date.Range intervals
Represents the number of days since the calendar epoch.
Boolean indicating is this is a leap month
Specifies the month of a date as either a positive integer or nil.
All naive date time fields are optional however many functions will require the presence of one or more - and often all - fields be present.
The part of a date, time or datetime that can be localized.
The precision for date intervals
Specifies the quarter of year for a calendar date.
All time fields are optional however many functions will require the presence of one or more - and often all - fields be present.
Specifies the week of year for a calendar date.
Specifies the year of a date as either a positive integer or nil.
Callbacks
Returns the calendar basis.
Returns a the year in a calendar year.
Returns the CLDR calendar type.
Returns a the cyclic year in a calendar year.
Returns the number of days in a month (withoout a year)
Returns the number of days in a year
Returns a the extended year in a calendar year.
Returns a tuple of {year, week_in_year}
for a given year
, month
or week
, and day
for a a calendar.
Returns a date range representing the days in a given month for a calendar year.
Returns the month
for a given year
, month
or week
, and day
for a a calendar.
Returns the number of periods (which are months in a month calendar and weeks in a week calendar) in a year
Increments a Date.t/0
or Date.Range.t
by a specified positive
or negative integer number of periods (year, quarter, month,
week or day).
Returns a date range representing the days in a given quarter for a calendar year.
Returns a the related year in a calendar year.
Returns a date range representing the days in a given week for a calendar year.
Returns a tuple of {month, week_in_month}
for a given year
, month
or week
, and day
for a a calendar.
Returns a tuple of {year, week_in_year}
for a given year
, month
or week
, and day
for a a calendar.
Returns the number of weeks in a year
Returns a date range representing the days in a calendar year.
Functions
Returns a calendar configured according to the preferences defined for a locale.
Returns a calendar configured according to the preferences defined for a territory.
Return the calendar module for a locale.
Returns the calendar module preferred for a territory.
Returns a boolean indicating if a module
is a Cldr.Calendar
module
Returns the year
number for
a date
that is the representation
used for a calendar.
Returns the current date or date range for a date period (year, quarter, month, week or day).
Returns the cycle year
number for a date
.
Returns a Date.t/0
from a year, day_of_year
and a calendar.
Returns a date represented by a number of days since the start of the epoch.
Returns a Date.t/0
from a keyword list
and a calendar.
Returns a Date.t/0
from a date tuple of
{year, month, day}
and a calendar.
Returns the number of days since the start of the epoch.
Formats a date into a string representation.
Returns the DateTime (defaulting to UTC timezone) for the given Modified Julian Day.
Returns the {day_of_era, era}
for
a date
.
Returns the day
of the year
for a date
.
Returns the default calendar.
Returns the extended year
number for
a date
.
Returns the first day of a week for a given locale.
Returns the first date of a year
for a Date.t/0
.
Returns the first date of a year
in a calendar
.
Returns the gregorian date of the first day of of a year
for a calendar
.
Returns the ordinal day number representing Friday.
An inspect_fun/2
that can be configured in
Inspect.Opts
supporting inspection of user-defined
calendars.
Returns an Enumerable
list of dates of a given precision
of either :years
, :quarters
, :months
, :weeks
or
:days
.
Returns an a Stream
function than can be lazily
enumerated.
Returns the day of the week for a given
iso_day_number
Returns the ISO week
number for
a date
.
Returns the last date of a year
for a Date.t/0
.
Returns the last date of a year
for a calendar
.
Returns the gregorian date of the first day of a year
for a calendar
.
Localize a date by converting it to calendar introspected from the provided or default locale.
Returns a localized string for a part of
a Date.t/0
.
Returns the minimum days in the first week of a year for a given locale.
Decrements a date or date range by an integer amount of a date period (year, quarter, month, week or day).
Returns the Modified Julian Day of
a Date.t/0
.
Returns the ordinal day number representing Monday
Returns the month
number for
a date
.
Creates a new calendar based upon the provided configuration.
Returns the next date or date range for a date period (year, quarter, month, week or day).
Adds a duration to a date
Increments a date or date range by an integer amount of a date period (year, quarter, month, week or day).
Returns the previous date or date range for a date period (year, quarter, month, week or day).
Returns the quarter
number for
a date
.
Returns the related gregorian year
number for a date
.
Returns the ordinal day number representing Saturday.
Returns the ordinal day number representing Sunday.
Returns the ordinal day number representing Thursday.
Returns the ordinal day number representing Tuesday.
Validates if the argument is a Cldr.Calendar calendar module.
Returns the ordinal day number representing Wednesday.
Returns the {month, week_number}
for a date
.
Returns the {year, week_number}
for a date
.
Returns whether a given date is a weekday.
Returns a list of the days of the week that are considered a weekend for a given territory (country).
Returns a list of the days of the week that are considered a weekend for a given territory (country).
Returns whether a given date is a weekend day.
Returns the number of weeks in a year.
Returns the number of days in n
weeks
Returns the {year_of_era, era}
for
a date
.
Types
@type any_date_time() :: date() | time() | naive_date_time() | date_time()
Super type of any date or time
@type calendar() :: module() | nil
Specifies the type of a calendar.
A calendar is a module that implements
the Calendar
and Cldr.Calendar
behaviours. Calendar functions will
default to Cldr.Calendar.Gregorian
in most cases.
@type calendar_type() :: :month | :week
Specifies the type of a calendar
@type date() :: %{ optional(:year) => year(), optional(:month) => month(), optional(:day) => day(), optional(:calendar) => calendar(), optional(any()) => any() }
All date fields are optional however many functions will require the presence of one or more - and often all - fields be present.
@type date_time() :: %{ optional(:calendar) => calendar(), optional(:day) => day(), optional(:hour) => Calendar.hour(), optional(:microsecond) => Calendar.microsecond(), optional(:minute) => Calendar.minute(), optional(:month) => month(), optional(:second) => Calendar.second(), optional(:std_offset) => Calendar.std_offset(), optional(:time_zone) => Calendar.time_zone(), optional(:utc_offset) => Calendar.utc_offset(), optional(:year) => year(), optional(:zone_abbr) => Calendar.zone_abbr(), optional(any()) => any() }
All date time fields are optional however many functions will require the presence of one or more - and often all - fields be present.
@type day() :: Calendar.day() | nil
Specifies the day of a date as either a positive integer or nil.
@type day_of_week() :: 1..7
Specifies the days of the week as integers.
Days of the week are encoded as the integers 1
through
7
with 1
representig Monday and 7 representing Sunday.
Note that a calendar can be configured to start
on any day of the week. day_of_week
is only a
way of encoding the days as an integer.
@type day_of_week_to_binary() :: {day_of_week(), String.t()}
A mapping of a day of the week ordinal to the localized string of the name of that day.
@type era() :: non_neg_integer() | nil
Specifies the year of a date as either a positive integer or nil.
@type interval_relation() ::
:precedes
| :preceded_by
| :meets
| :met_by
| :overlaps
| :overlapped_by
| :finished_by
| :finishes
| :contains
| :during
| :starts
| :started_by
| :equals
The types of relationship between two Date.Range intervals
@type iso_day_number() :: integer()
Represents the number of days since the calendar epoch.
The Calendar epoch is 0000-01-01
in the proleptic gregorian calendar.
@type leap_month?() :: boolean()
Boolean indicating is this is a leap month
@type month() :: Calendar.month() | nil
Specifies the month of a date as either a positive integer or nil.
@type naive_date_time() :: %{ optional(:calendar) => calendar(), optional(:day) => day(), optional(:hour) => Calendar.hour(), optional(:microsecond) => Calendar.microsecond(), optional(:minute) => Calendar.minute(), optional(:month) => month(), optional(:second) => Calendar.second(), optional(:year) => year(), optional(any()) => any() }
All naive date time fields are optional however many functions will require the presence of one or more - and often all - fields be present.
@type part() ::
:day_periods
| :am_pm
| :days_of_week
| :day_of_week
| :month
| :quarter
| :era
The part of a date, time or datetime that can be localized.
@type precision() :: :years | :quarters | :months | :weeks | :days
The precision for date intervals
@type quarter() :: 1..4
Specifies the quarter of year for a calendar date.
@type time() :: %{ optional(:calendar) => Calendar.calendar(), optional(:hour) => Calendar.hour(), optional(:microsecond) => Calendar.microsecond(), optional(:minute) => Calendar.minute(), optional(:second) => Calendar.second(), optional(any()) => any() }
All time fields are optional however many functions will require the presence of one or more - and often all - fields be present.
@type week() :: pos_integer()
Specifies the week of year for a calendar date.
@type year() :: Calendar.year() | nil
Specifies the year of a date as either a positive integer or nil.
Callbacks
@callback calendar_base() :: :week | :month
Returns the calendar basis.
Returns either :week or :month
@callback calendar_year(year :: year(), month :: month(), day :: day()) :: Calendar.year()
Returns a the year in a calendar year.
@callback cldr_calendar_type() ::
:gregorian | :persian | :coptic | :ethiopic | :chinese | :japanese | :dangi
Returns the CLDR calendar type.
Only algorithmic calendars are considered in this implementation
@callback cyclic_year(year :: year(), month :: month(), day :: day()) :: Calendar.year()
Returns a the cyclic year in a calendar year.
@callback days_in_month(month :: month()) :: Calendar.day() | {:ambiguous, Range.t() | [pos_integer()]} | {:error, :undefined}
Returns the number of days in a month (withoout a year)
@callback days_in_year(year :: year()) :: Calendar.day()
Returns the number of days in a year
@callback extended_year(year :: year(), month :: month(), day :: day()) :: Calendar.year()
Returns a the extended year in a calendar year.
@callback iso_week_of_year( year :: year(), month :: month() | week(), day :: day() ) :: {Calendar.year(), Calendar.week()} | {:error, :not_defined}
Returns a tuple of {year, week_in_year}
for a given year
, month
or week
, and day
for a a calendar.
The iso_week_of_year
is calculated based on the ISO calendar.
@callback month(year :: year(), month :: month()) :: Date.Range.t() | {:error, :not_defined}
Returns a date range representing the days in a given month for a calendar year.
@callback month_of_year( year :: year(), month :: month() | week(), day :: day() ) :: Calendar.month() | {Calendar.month(), leap_month?()}
Returns the month
for a given year
, month
or week
, and day
for a a calendar.
The month_of_year
is calculated based upon the calendar configuration.
@callback periods_in_year(year :: year()) :: week() | Calendar.month()
Returns the number of periods (which are months in a month calendar and weeks in a week calendar) in a year
@callback plus( year :: year(), month :: month() | week(), day :: day(), months_or_quarters :: :months | :quarters, increment :: integer(), options :: Keyword.t() ) :: {Calendar.year(), Calendar.month(), Calendar.day()}
Increments a Date.t/0
or Date.Range.t
by a specified positive
or negative integer number of periods (year, quarter, month,
week or day).
Calendars need only implement this callback for :months
and :quarters
since all other date periods can be derived.
@callback quarter(year :: year(), quarter :: quarter()) :: Date.Range.t() | {:error, :not_defined}
Returns a date range representing the days in a given quarter for a calendar year.
@callback week(year :: year(), week :: week()) :: Date.Range.t() | {:error, :not_defined}
Returns a date range representing the days in a given week for a calendar year.
@callback week_of_month(year(), week(), day()) :: {Calendar.month(), week()} | {:error, :not_defined}
Returns a tuple of {month, week_in_month}
for a given year
, month
or week
, and day
for a a calendar.
The week_in_month
is calculated based upon the calendar configuration.
@callback week_of_year( year :: year(), month :: month() | week(), day :: day() ) :: {Calendar.year(), Calendar.week()} | {:error, :not_defined}
Returns a tuple of {year, week_in_year}
for a given year
, month
or week
, and day
for a a calendar.
The week_in_year
is calculated based upon the calendar configuration.
@callback weeks_in_year(year :: year()) :: {week(), Calendar.day()} | {:error, :not_defined}
Returns the number of weeks in a year
@callback year(year :: year()) :: Date.Range.t() | {:error, :not_defined}
Returns a date range representing the days in a calendar year.
Functions
Returns a calendar configured according to the preferences defined for a locale.
Returns a calendar configured according to the preferences defined for a territory.
Return the calendar module for a locale.
Arguments
:locale
is any locale or locale name validated byCldr.validate_locale/2
. The default isCldr.get_locale()
which returns the locale set for the current process.
Returns
{:ok, calendar_module}
or{:error, {exception, reason}}
Examples
iex> Cldr.Calendar.calendar_from_locale "en-US"
{:ok, Cldr.Calendar.US}
iex> Cldr.Calendar.calendar_from_locale "en-GB-u-ca-gregory"
{:ok, Cldr.Calendar.Gregorian}
iex> Cldr.Calendar.calendar_from_locale "fa-IR"
{:ok, Cldr.Calendar.Persian}
iex> Cldr.Calendar.calendar_from_locale "fa-IR-u-ca-gregory"
{:ok, Cldr.Calendar.Gregorian}
Returns the calendar module preferred for a territory.
Arguments
territory
is any valid ISO3166-2 code as anString.t/0
or upcasedatom
.
Returns
{:ok, calendar_module}
or{:error, {exception, reason}}
Examples
iex> Cldr.Calendar.calendar_from_territory :US
{:ok, Cldr.Calendar.US}
iex> Cldr.Calendar.calendar_from_territory :YY
{:error, {Cldr.UnknownTerritoryError, "The territory :YY is unknown"}}
Notes
The overwhelming majority of territories have
:gregorian
as their first preferred calendar
and therefore Cldr.Calendar.Gregorian
or
a derivation of it will be returned for most
territories.
Returning any other calendar module would require:
That another calendar is preferred over
:gregorian
for a territoryThat a calendar module is available to support that calendar.
As an example, Iran (territory :IR
) prefers the
:persian
calendar. If the optional library
ex_cldr_calendars_persian
is installed, the calendar module Cldr.Calendar.Persian
will
be returned. If it is not installed, Cldr.Calendar.Gregorian
will be returned as :gregorian
is the second preference
for :IR
.
Returns a boolean indicating if a module
is a Cldr.Calendar
module
@spec calendar_year(date()) :: Calendar.year() | {:error, {module(), String.t()}}
Returns the year
number for
a date
that is the representation
used for a calendar.
The calendar year may be different the the year in the struct. The struct year is designed for convertability and for date/time arithmetic.
The representation in rendered calendar may be different. For example, in the Chinese calendar the cardinal year since epoch is stored in the struct but the calendar year used for representation is the sexigesimal year (a number between 1 and 60).
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
- the calendar year as an integer.
Examples
iex> Cldr.Calendar.calendar_year ~D[2019-01-01]
2019
iex> Cldr.Calendar.calendar_year Cldr.Calendar.first_day_of_year(2019, Cldr.Calendar.NRF)
2019
iex> Cldr.Calendar.calendar_year Cldr.Calendar.last_day_of_year(2019, Cldr.Calendar.NRF)
2019
Returns the current date or date range for a date period (year, quarter, month, week or day).
Arguments
date_or_date_range
is anyDate.t/0
orDate.Range.t
.period
is:year
,:quarter
,:month
,:week
or:day
.
Returns
When a Date.t/0
is passed, a Date.t/0
is
returned. When a Date.Range.t
is passed
a Date.Range.t
is returned.
Examples
iex> Cldr.Calendar.current ~D[2019-01-01], :day
~D[2019-01-01]
@spec cyclic_year(date()) :: Calendar.year() | {:error, {module(), String.t()}}
Returns the cycle year
number for a date
.
A related gregorian year is the gregorian year that is most closely associated with a date that is in another calendar.
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
- the cyclic year as an integer.
Examples
iex> Cldr.Calendar.cyclic_year ~D[2019-01-01]
2019
iex> Cldr.Calendar.cyclic_year Cldr.Calendar.first_day_of_year(2019, Cldr.Calendar.NRF)
2019
iex> Cldr.Calendar.cyclic_year Cldr.Calendar.last_day_of_year(2019, Cldr.Calendar.NRF)
2019
date_from_day_of_year(year, day_of_year, calendar \\ Cldr.Calendar.Gregorian)
View SourceReturns a Date.t/0
from a year, day_of_year
and a calendar.
Arguments
year
is any integer year that is valid incalendar
.day_of_year
is any valid ordinal day ofyear
.calendar
is any module implementing theCalendar
andCldr.Calendar
behaviours. The default isCldr.Calendar.Gregorian
.
Returns
a
Date.t/0
or{:error, :invalid_date}
@spec date_from_iso_days(Calendar.iso_days() | iso_day_number(), calendar()) :: Date.t() | {:error, :incompatible_calendars | :invalid_date}
Returns a date represented by a number of days since the start of the epoch.
The start of the epoch is the date
0000-01-01
.
Argumenets
iso_days
is an integer representing the number of days since the start of the epoch.calendar
is any module that implements theCalendar
andCldr.Calendar
behaviours.
Returns
- a
Date.t/0
Example
iex> Cldr.Calendar.date_from_iso_days 737425, Calendar.ISO
~D[2019-01-01]
iex> Cldr.Calendar.date_from_iso_days 366, Calendar.ISO
~D[0001-01-01]
iex> Cldr.Calendar.date_from_iso_days 0, Calendar.ISO
~D[0000-01-01]
Returns a Date.t/0
from a keyword list
and a calendar.
Arguments
[year: year, month: month, day: day}
is a keyword list representing a date.calendar
is any module implementing theCalendar
andCldr.Calendar
behaviours. The default isCldr.Calendar.Gregorian
.
Returns
a
Date.t/0
or{:error, :invalid_date}
Examples
iex> Cldr.Calendar.date_from_list [year: 2019, month: 3, day: 25], Cldr.Calendar.Gregorian
%Date{calendar: Cldr.Calendar.Gregorian, day: 25, month: 3, year: 2019}
iex> Cldr.Calendar.date_from_list [year: 2019, month: 2, day: 29], Cldr.Calendar.Gregorian
{:error, :invalid_date}
Returns a Date.t/0
from a date tuple of
{year, month, day}
and a calendar.
Arguments
{year, month, day}
is a tuple representing a date.calendar
is any module implementing theCalendar
andCldr.Calendar
behaviours. The default isCldr.Calendar.Gregorian
.
Returns
- a
Date.t/0
.
Examples
iex> Cldr.Calendar.date_from_tuple {2019, 3, 25}, Cldr.Calendar.Gregorian
%Date{calendar: Cldr.Calendar.Gregorian, day: 25, month: 3, year: 2019}
iex> Cldr.Calendar.date_from_tuple {2019, 2, 29}, Cldr.Calendar.Gregorian
{:error, :invalid_date}
@spec date_to_iso_days(Date.t()) :: iso_day_number()
Returns the number of days since the start of the epoch.
The start of the epoch is the date 0000-01-01.
Argumenets
date
is anyDate.t/0
.
Returns
- The integer number of days since the epoch
for the given
date
.
Example
iex> Cldr.Calendar.date_to_iso_days ~D[2019-01-01]
737425
iex> Cldr.Calendar.date_to_iso_days ~D[0001-01-01]
366
iex> Cldr.Calendar.date_to_iso_days ~D[0000-01-01]
0
Formats a date into a string representation.
Note that the output is not decorated with the calendar module name.
Example
iex> Cldr.Calendar.date_to_string ~D[2019-12-04]
"2019-12-04"
iex> Cldr.Calendar.date_to_string ~D[2019-23-04 Cldr.Calendar.NRF]
"2019-W23-4"
Returns the DateTime (defaulting to UTC timezone) for the given Modified Julian Day.
Arguments
mjd
is a number representing days passed since November 17, 1858 (Julian Calendar)
Returns
- a
DateTime.t/0
at UTC timezone.
Examples
iex> Cldr.Calendar.datetime_from_modified_julian_date(59848)
~U[2022-09-26 00:00:00.000Z]
iex> Cldr.Calendar.datetime_from_modified_julian_date(59848.75)
~U[2022-09-26 18:00:00.000Z]
@spec day_of_era(date()) :: {Calendar.day(), Calendar.era()} | {:error, {module(), String.t()}}
Returns the {day_of_era, era}
for
a date
.
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
- a the days since the start of the era and the era of the year as a tuple.
Examples
iex> Cldr.Calendar.day_of_era ~D[2019-01-01]
{737060, 1}
iex> Cldr.Calendar.day_of_era Cldr.Calendar.first_day_of_year(2019, Cldr.Calendar.NRF)
{737093, 1}
iex> Cldr.Calendar.day_of_era Cldr.Calendar.last_day_of_year(2019, Cldr.Calendar.NRF)
{737456, 1}
See Date.day_of_week/1
.
@spec day_of_year(date()) :: Calendar.day() | {:error, {module(), String.t()}}
Returns the day
of the year
for a date
.
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
- a the day of the year as an integer
Examples
iex> Cldr.Calendar.day_of_year ~D[2019-01-01]
1
iex> Cldr.Calendar.day_of_year ~D[2016-12-31]
366
iex> Cldr.Calendar.day_of_year ~D[2019-12-31]
365
iex> Cldr.Calendar.day_of_year ~D[2019-52-07 Cldr.Calendar.NRF]
365
iex> Cldr.Calendar.day_of_year ~D[2012-53-07 Cldr.Calendar.NRF]
372
See Date.days_in_month/1
.
Returns the default calendar.
@spec extended_year(date()) :: Calendar.year() | {:error, {module(), String.t()}}
Returns the extended year
number for
a date
.
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
- the extended calendar year as an integer.
Examples
iex> Cldr.Calendar.extended_year ~D[2019-01-01]
2019
iex> Cldr.Calendar.extended_year Cldr.Calendar.first_day_of_year(2019, Cldr.Calendar.NRF)
2019
iex> Cldr.Calendar.extended_year Cldr.Calendar.last_day_of_year(2019, Cldr.Calendar.NRF)
2019
Returns the first day of a week for a given locale.
Note that the first of the first week is commonly not aligned with the first day of the year.
Returns the first date of a year
for a Date.t/0
.
Arguments
date
is anyDate.t/0
.
Returns
a
Date.t/0
or{:error, :invalid_date}
Examples
iex> Cldr.Calendar.first_day_of_year ~D[2019-12-01]
~D[2019-01-01]
@spec first_day_of_year(year :: year(), calendar :: calendar()) :: Date.t() | {:error, :invalid_date}
Returns the first date of a year
in a calendar
.
Arguments
year
is any year.calendar
is any module that implements theCalendar
andCldr.Calendar
behaviours.
Returns
a
Date.t/0
or{:error, :invalid_date}
Examples
iex> Cldr.Calendar.first_day_of_year 2019, Cldr.Calendar.Gregorian
%Date{calendar: Cldr.Calendar.Gregorian, day: 1, month: 1, year: 2019}
iex> Cldr.Calendar.first_day_of_year 2019, Cldr.Calendar.NRF
%Date{calendar: Cldr.Calendar.NRF, day: 1, month: 1, year: 2019}
Returns the gregorian date of the first day of of a year
for a calendar
.
Arguments
year
is any integer year number.calendar
is any module that implements theCalendar
andCldr.Calendar
behaviours orCalendar.ISO
Examples
iex> Cldr.Calendar.first_gregorian_day_of_year 2019, Cldr.Calendar.Gregorian
%Date{calendar: Cldr.Calendar.Gregorian, day: 1, month: 1, year: 2019}
iex> Cldr.Calendar.first_gregorian_day_of_year 2019, Cldr.Calendar.NRF
%Date{calendar: Cldr.Calendar.Gregorian, day: 3, month: 2, year: 2019}
iex> Cldr.Calendar.first_gregorian_day_of_year ~D[2019-12-01]
~D[2019-01-01]
@spec friday() :: 5
Returns the ordinal day number representing Friday.
@spec inspect(term(), list()) :: Inspect.Algebra.t()
An inspect_fun/2
that can be configured in
Inspect.Opts
supporting inspection of user-defined
calendars.
This function can be configured in IEx
for Elixir version 1.9
and later by:
IEx.configure(inspect: [inspect_fun: &Cldr.Calendar.inspect/2])
:ok
@spec interval( date_from :: Date.t(), date_to_or_count :: Date.t() | non_neg_integer(), precision() ) :: [Date.t()]
Returns an Enumerable
list of dates of a given precision
of either :years
, :quarters
, :months
, :weeks
or
:days
.
Arguments
date_from
is a anyDate.t/0
that is the start of the sequence.date_to_or_count
is upper bound of the sequence as aDate.t/0
or the number of dates in the sequence to be generated.precision
is one of:years
,:quarters
,:months
,:weeks
or:days
.
The sequence is generated starting with date_from
until the next date
in the sequence would be after date_to
.
Notes
The sequence can be in ascending or descending date order
based upon whether date_from
is greater than date_to
.
Returns
- A list of dates
Examples
iex> d = ~D[2019-01-31]
~D[2019-01-31]
iex> d2 = ~D[2019-05-31]
~D[2019-05-31]
iex> Cldr.Calendar.interval d, 3, :months
[~D[2019-01-31], ~D[2019-02-28], ~D[2019-03-31]]
iex> Cldr.Calendar.interval d, d2, :months
[~D[2019-01-31], ~D[2019-02-28], ~D[2019-03-31],
~D[2019-04-30], ~D[2019-05-31]]
@spec interval_stream( date_from :: Date.t(), date_to_or_count :: Date.t() | non_neg_integer(), precision() ) :: (... -> any())
Returns an a Stream
function than can be lazily
enumerated.
This function has the same arguments and provides
the same functionality as interval/3
except that
it is lazily evaluated.
Arguments
date_from
is a anyDate.t/0
that is the start of the sequence.date_to_or_count
is upper bound of the sequence as aDate.t/0
or the number of dates in the sequence to be generated.precision
is one of:years
,:quarters
,:months
,:weeks
or:days
.
The sequence is generated starting with date_from
until the next date
in the sequence would be after date_to
.
Notes
The sequence can be in ascending or descending date order
based upon whether date_from
is greater than date_to
.
Returns
- A list of dates.
Examples
iex> d = ~D[2019-01-31]
~D[2019-01-31]
iex> d2 = ~D[2019-05-31]
~D[2019-05-31]
iex> Cldr.Calendar.interval_stream(d, 3, :months) |> Enum.to_list
[~D[2019-01-31], ~D[2019-02-28], ~D[2019-03-31]]
iex> Cldr.Calendar.interval_stream(d, d2, :months) |> Enum.to_list
[~D[2019-01-31], ~D[2019-02-28], ~D[2019-03-31],
~D[2019-04-30], ~D[2019-05-31]]
@spec iso_days_to_day_of_week(Calendar.iso_days() | Calendar.day()) :: day_of_week()
Returns the day of the week for a given
iso_day_number
Arguments
iso_day_number
is the number of days since the start of the epoch. SeeCldr.Calendar.date_to_iso_days/1
.
Returns
- An integer representing a day of the week where Monday
is represented by
1
and Sunday is represented by7
.
Examples
iex> days = Cldr.Calendar.date_to_iso_days ~D[2019-01-01]
iex> Cldr.Calendar.iso_days_to_day_of_week(days) == Cldr.Calendar.tuesday()
true
@spec iso_week_of_year(date()) :: {Calendar.year(), week()} | {:error, {module(), String.t()}}
Returns the ISO week
number for
a date
.
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
a the ISO week of the year as an integer or
{:error, :not_defined}
is the calendar does not support the concept of weeks.
Examples
iex> Cldr.Calendar.iso_week_of_year ~D[2019-01-01]
{2019, 1}
iex> Cldr.Calendar.iso_week_of_year ~D[2019-02-01]
{2019, 5}
iex> Cldr.Calendar.iso_week_of_year ~D[2019-52-01 Cldr.Calendar.NRF]
{2020, 4}
iex> Cldr.Calendar.iso_week_of_year ~D[2019-26-01 Cldr.Calendar.NRF]
{2019, 30}
iex> Cldr.Calendar.iso_week_of_year ~D[2019-12-01 Cldr.Calendar.Julian]
{:error, :not_defined}
Returns the last date of a year
for a Date.t/0
.
Arguments
date
is anyDate.t/0
.
Returns
a
Date.t/0
or{:error, :invalid_date}
Examples
iex> Cldr.Calendar.last_day_of_year ~D[2019-01-01]
~D[2019-12-31]
Returns the last date of a year
for a calendar
.
Arguments
year
is any year.calendar
is any module that implements theCalendar
andCldr.Calendar
behaviours
Returns
a
Date.t/0
or{:error, :invalid_date}
Examples
iex> Cldr.Calendar.last_day_of_year(2019, Cldr.Calendar.Gregorian)
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 12, year: 2019}
iex> Cldr.Calendar.last_day_of_year(2019, Cldr.Calendar.NRF)
%Date{calendar: Cldr.Calendar.NRF, day: 7, month: 52, year: 2019}
Returns the gregorian date of the first day of a year
for a calendar
.
Arguments
year
is any integer year number or adate/0
.calendar
is any module that implements theCalendar
andCldr.Calendar
behaviours orCalendar.ISO
.
Examples
iex> Cldr.Calendar.last_gregorian_day_of_year 2019, Cldr.Calendar.Gregorian
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 12, year: 2019}
iex> Cldr.Calendar.last_gregorian_day_of_year 2019, Cldr.Calendar.NRF
%Date{calendar: Cldr.Calendar.Gregorian, day: 1, month: 2, year: 2020}
iex> Cldr.Calendar.last_gregorian_day_of_year ~D[2019-12-01]
~D[2019-12-31]
@spec localize(any_date_time()) :: {:ok, any_date_time()} | {:error, :incompatible_calendars} | {:error, {module(), String.t()}}
Localize a date by converting it to calendar introspected from the provided or default locale.
Arguments
date
is anyDate.t/0
.options
is aKeyword.t/0
list of options. The default is[]
.
Options
:locale
is any valid locale name in the list returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
. The default isCldr.get_locale()
.:backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isdefault_backend!/0
.
Returns
{:ok, date}
wheredate
is converted into the calendar associated with the current or provided locale.
Examples
iex> Cldr.Calendar.localize ~D[2022-06-09], locale: "fr"
{:ok, %Date{year: 2022, month: 6, day: 9, calendar: Cldr.Calendar.FR}}
@spec localize(any_date_time(), Keyword.t() | atom()) :: {:ok, any_date_time()} | {:error, :incompatible_calendars} | {:error, {module(), String.t()}}
@spec localize(any_date_time(), atom(), Keyword.t()) :: String.t() | {:error, :incompatible_calendars} | {:error, {module(), String.t()}}
@spec localize(datetime :: any_date_time(), part :: part(), options :: Keyword.t()) :: String.t() | {:error, {module(), String.t()}}
Returns a localized string for a part of
a Date.t/0
.
Arguments
date
is anyDate.t/0
.part
is one of:era
,:quarter
,:month
,:day_of_week
or:days_of_week
.options
is aKeyword.t/0
list of options.
Options
:locale
is any valid locale name in the list returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
. The default isCldr.get_locale()
.:backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isdefault_backend!/0
.:format
is one of:wide
,:abbreviated
or:narrow
. The default is:abbreviated
.:era
will, if set to:variant
will localize the era using the variant data. In the:en
locale, this will produceCE
andBCE
rather than the defaultAD
andBC
.
Returns
A string representing the localized date part, or
A list of strings representing the days of the week for when
part
is:days_of_week
. The days are in week order for the given date's calendar, or{error, {exception_module, message}}
if an error is detected
Examples
iex> Cldr.Calendar.localize ~D[2019-01-01], :era
"AD"
iex> Cldr.Calendar.localize ~D[2019-01-01], :era, era: :variant
"CE"
iex> Cldr.Calendar.localize ~D[2019-01-01], :day_of_week
"Tue"
iex> Cldr.Calendar.localize ~D[0001-01-01], :day_of_week
"Mon"
iex> Cldr.Calendar.localize ~D[2019-01-01], :days_of_week
[{1, "Mon"}, {2, "Tue"}, {3, "Wed"}, {4, "Thu"}, {5, "Fri"}, {6, "Sat"}, {7, "Sun"}]
iex> Cldr.Calendar.localize ~D[2019-06-01], :era
"AD"
iex> Cldr.Calendar.localize ~D[2019-06-01], :quarter
"Q2"
iex> Cldr.Calendar.localize ~D[2019-06-01], :month
"Jun"
iex> Cldr.Calendar.localize ~D[2019-06-01], :day_of_week
"Sat"
iex> Cldr.Calendar.localize ~D[2019-06-01], :day_of_week, format: :wide
"Saturday"
iex> Cldr.Calendar.localize ~D[2019-06-01], :day_of_week, format: :narrow
"S"
iex> Cldr.Calendar.localize ~D[2019-06-01], :day_of_week, locale: "ar"
"السبت"
Returns the minimum days in the first week of a year for a given locale.
Decrements a date or date range by an integer amount of a date period (year, quarter, month, week or day).
Arguments
date_or_date_range
is anyDate.t/0
orDate.Range.t
period
is:years
,:quarters
,:months
,:weeks
or:days
.options
is aKeyword.t/0
list of options.
Options
:coerce
is a boolean which, when set totrue
will coerce the month and/or day to be a valid date. This affects,for example, moving to the previous month from~D[2019-03-31]
. Since there is no date~D[2019-02-31]
this would normally return{:error, :invalid_date}
. Settingcoerce: true
it will return~D[2019-02-28]
.coerce: true
is the default.
Returns
When a Date.t/0
is passed, a Date.t/0
is
returned. When a Date.Range.t
is passed
a Date.Range.t
is returned.
Examples
iex> Cldr.Calendar.minus ~D[2016-03-01], :days, 1
~D[2016-02-29]
iex> Cldr.Calendar.minus ~D[2019-03-01], :months, 1
~D[2019-02-01]
iex> Cldr.Calendar.minus ~D[2016-03-01], :days, 1
~D[2016-02-29]
iex> Cldr.Calendar.minus ~D[2019-03-01], :days, 1
~D[2019-02-28]
iex> Cldr.Calendar.minus ~D[2019-03-01], :months, 1
~D[2019-02-01]
iex> Cldr.Calendar.minus ~D[2019-03-01], :quarters, 1
~D[2018-12-01]
iex> Cldr.Calendar.minus ~D[2019-03-01], :years, 1
~D[2018-03-01]
Returns the Modified Julian Day of
a Date.t/0
.
Arguments
date_or_datetime
is anyDate.t/0
or aDateTime.t/0
. If aDateTime.t/0
is given, the result will be given in the current timezone.
Returns
- an number representing the
Modified Julian Day of the
date
.
Notes
The Modified Julian Day is the number of days since November 17, 1858. Therefore this function only returns valid values for dates after this date.
Examples
iex> Cldr.Calendar.modified_julian_day ~D[2019-01-01]
58484.0
iex> Cldr.Calendar.modified_julian_day ~U[2019-01-01 12:00:00Z]
58484.5
iex> Cldr.Calendar.modified_julian_day(~U[2022-09-26 18:00:00.000Z])
59848.75
# If the given DateTime is not UTC, the result is given in
# the local timezone
iex> dt = DateTime.shift_zone!(~U[2019-01-01 14:00:00Z], "America/Sao_Paulo")
#DateTime<2019-01-01 12:00:00-02:00 -02 America/Sao_Paulo>
iex> Cldr.Calendar.modified_julian_day(dt)
58484.5
@spec monday() :: 1
Returns the ordinal day number representing Monday
@spec month_of_year(date()) :: Calendar.month() | {Calendar.month(), leap_month :: :leap} | {:error, {module(), String.t()}}
Returns the month
number for
a date
.
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
- the month of the year as an integer
Examples
iex> Cldr.Calendar.month_of_year ~D[2019-01-01]
1
iex> Cldr.Calendar.month_of_year ~D[2019-12-01]
12
iex> Cldr.Calendar.month_of_year ~D[2019-52-01 Cldr.Calendar.NRF]
12
iex> Cldr.Calendar.month_of_year ~D[2019-26-01 Cldr.Calendar.NRF]
6
@spec new(module(), calendar_type(), Keyword.t()) :: {:ok, calendar()} | {:module_already_exists, module()} | {:error, String.t()}
Creates a new calendar based upon the provided configuration.
If a module exists with the calendar_module
name then it
is returned, not recreated.
Arguments
calendar_module
is an atom representing the module name of the created calendar.calendar_type
is an atom of either:month
or:week
indicating which type of calendar is to be created.config
is a Keyword list defining the configuration of the calendar.
Returns
{:ok, module}
wheremodule
is the new calendar module that conforms to theCalendar
andCldr.Calendar
behaviours or{:module_already_exists, module}
if a module of the given calendar name already exists. It is not guaranteed that the module is in fact a calendar module in this case.
Configuration options
The following options can be provided to create a new calendar.
:cldr_backend
defines a default backend module to be used for this calendar. The default isnil
.:weeks_in_month
defines the layout of weeks in a quarter for a week- or month- based calendar. The value must be one of[4, 4, 5]
,[4,5,4]
or[5,4,4]
. The default is[4,4,5]
. This option is ignored for:month
based calendars that have the parameterday_of_year: :first
.:begins_or_ends
determines whether the calendar year begins or ends on the given:day_of_week
and:month_of_year
. The default is:begins
.:first_or_last
determines whether the calendar year starts (or ends) on the first, last or nearest:day-of_week
and:month_of_year
. The default is:first
:day_of_week
determines the day of the week on which this calendar begins or ends. It may be a number in the range1..7
representing Monday to Sunday. It may also be:first
indicating the the weeks are calculated from the first day of the calendar day irrespective of the day of the week. In this case the last week of the year may be less than 7 days in length. The default is1
.:month_of_year
determines the Cldr.Calendar.Gregorian month of year in which this calendar begins or ends. The default is1
.:year
is used to determine which calendar Greogian year is applicable for a given calendar date. The valid options are:first
,:last
andmajority
. The default is:majority
.:min_days_in_first_week
is used to determine how many days of the Cldr.Calendar.Gregorian year must be in the first week of a calendar year. This is used when determining when the year starts for week-based years. The default is4
which is consistent with the ISO Week calendar
Examples
Each calendar has a function __config__/0
generated within
it and therefore the configuration of the included calendars
in ex_cldr_calendars
provide insight into the behaviour
of the configuration parameters.
As an example here we define the ISO Week calendar calendar in full:
defmodule ISOWeek do
use Cldr.Calendar.Base.Week,
day_of_week: 1, # Weeks begin or end on Monday
month_of_year: 1, # Years begin or end in January
min_days_in_first_week, 4, # 4 Cldr.Calendar.Gregorian days of the year must be in the first week
begins_or_ends: :begins, # The year *begins* on the `day_of_week` and `month_of_year`
first_or_last: :first, # They year *begins* on the *first* `day_of_week` and `month_of_year`
weeks_in_month: [4, 4, 5], # The weeks are laid out as *months* in a `[4,4,5]` pattern
year: :majority, # Any given year is that in which the majority of Cldr.Calendar.Gregorian months fall
cldr_backend: nil, # No default `cldr_backend` is configured.
locale: nil # No `locale` is used to aid configuration
end
This can be generated at runtime by:
iex> Cldr.Calendar.new ISOWeek, :week,
...> day_of_week: 1,
...> month_of_year: 1,
...> min_days_in_first_week: 4,
...> begins_or_ends: :begins,
...> first_or_last: :first,
...> weeks_in_month: [4, 4, 5],
...> year: :majority,
...> cldr_backend: nil
{:ok, ISOWeek}
Note that Cldr.Calendar.ISOWeek
is included as part of this
library.
Returns the next date or date range for a date period (year, quarter, month, week or day).
Arguments
date_or_date_range
is anyDate.t/0
orDate.Range.t
.period
is:year
,:quarter
,:month
,:week
or:day
.
Returns
When a Date.t/0
is passed, a Date.t/0
is
returned. When a Date.Range.t
is passed
a Date.Range.t
is returned.
Examples
iex> Cldr.Calendar.next ~D[2019-01-01], :day
~D[2019-01-02]
iex> Cldr.Calendar.next ~D[2019-01-01], :month
~D[2019-02-01]
iex> Cldr.Calendar.next ~D[2019-01-01], :quarter
~D[2019-04-01]
iex> Cldr.Calendar.next ~D[2019-01-01], :year
~D[2020-01-01]
@spec plus(integer(), integer()) :: integer() | {:error, :invalid_date}
@spec plus(Calendar.date(), Cldr.Calendar.Duration.t()) :: Calendar.date()
Adds a duration to a date
Arguments
date
is any map that conforms tot:Calendar.date.t/0
.duration
is any duration returned byCldr.Calendar.Duration.new!/2
.options
is a Keyword list of options.
Options
- Options are those applicable to
Cldr.Calendar.plus/4
.
Returns
- A
t:Calendar.date.t/0
advanced by the duration.
Examples
iex> Cldr.Calendar.plus ~D[2020-01-01],
...> Cldr.Calendar.Duration.new!(~D[2020-01-01], ~D[2020-02-01])
~D[2020-02-01]
iex> Cldr.Calendar.plus ~D[2020-01-01],
...> Cldr.Calendar.Duration.new!(~D[2020-01-01], ~D[2020-01-02])
~D[2020-01-02]
iex> Cldr.Calendar.plus ~D[2020-01-01],
...> Cldr.Calendar.Duration.new!(~D[2020-01-01], ~D[2020-02-01])
~D[2020-02-01]
iex> Cldr.Calendar.plus ~D[2020-01-01],
...> Cldr.Calendar.Duration.new!(~D[2020-01-01], ~D[2021-02-01])
~D[2021-02-01]
@spec plus(Calendar.date() | Date.Range.t(), atom(), integer(), Keyword.t()) :: Calendar.date() | {:error, :invalid_date}
Increments a date or date range by an integer amount of a date period (year, quarter, month, week or day).
Arguments
date_or_date_range
is anyDate.t/0
orDate.Range.t
.period
is:years
,:quarters
,:months
,:weeks
or:days
.options
is aKeyword.t/0
list of options.
Options
:coerce
is a boolean which, when set totrue
will coerce the month and/or day to be a valid date. This affects,for example, moving to the previous month from~D[2019-03-31]
. Since there is no date~D[2019-02-31]
this would normally return{:error, :invalid_date}
. Settingcoerce: true
it will return~D[2019-02-28]
.coerce: true
is the default.
Returns
When a Date.t/0
is passed, a Date.t/0
is
returned. When a Date.Range.t
is passed
a Date.Range.t
is returned.
Examples
iex> Cldr.Calendar.plus ~D[2016-02-29], :days, 1
~D[2016-03-01]
iex> Cldr.Calendar.plus ~D[2019-03-01], :months, 1
~D[2019-04-01]
iex> Cldr.Calendar.plus ~D[2016-02-29], :days, 1
~D[2016-03-01]
iex> Cldr.Calendar.plus ~D[2019-02-28], :days, 1
~D[2019-03-01]
iex> Cldr.Calendar.plus ~D[2019-03-01], :months, 1
~D[2019-04-01]
iex> Cldr.Calendar.plus ~D[2019-03-01], :quarters, 1
~D[2019-06-01]
iex> Cldr.Calendar.plus ~D[2019-03-01], :years, 1
~D[2020-03-01]
Returns the previous date or date range for a date period (year, quarter, month, week or day).
Arguments
date_or_date_range
is anyDate.t/0
orDate.Range.t
.period
is:year
,:quarter
,:month
,:week
or:day
.options
is aKeyword.t/0
list of options that is passed toplus/4
orminus/4
.
Returns
When a Date.t/0
is passed, a Date.t/0
is
returned. When a Date.Range.t
is passed
a Date.Range.t
is returned.
Examples
iex> Cldr.Calendar.previous ~D[2019-01-01], :day
~D[2018-12-31]
iex> Cldr.Calendar.previous ~D[2019-01-01], :quarter
~D[2018-10-01]
iex> Cldr.Calendar.previous ~D[2019-01-01], :month
~D[2018-12-01]
iex> Cldr.Calendar.previous ~D[2019-01-01], :year
~D[2018-01-01]
Returns the quarter
number for
a date
.
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
- a the quarter of the year as an integer
Examples
iex> Cldr.Calendar.quarter_of_year ~D[2019-01-01]
1
iex> Cldr.Calendar.quarter_of_year Cldr.Calendar.first_day_of_year(2019, Cldr.Calendar.NRF)
1
iex> Cldr.Calendar.quarter_of_year Cldr.Calendar.last_day_of_year(2019, Cldr.Calendar.NRF)
4
@spec saturday() :: 6
Returns the ordinal day number representing Saturday.
@spec sunday() :: 7
Returns the ordinal day number representing Sunday.
@spec thursday() :: 4
Returns the ordinal day number representing Thursday.
@spec tuesday() :: 2
Returns the ordinal day number representing Tuesday.
Validates if the argument is a Cldr.Calendar calendar module.
Arguments
calendar_module
is a module that implements theCldr.Calendar
behaviour.
Returns
{:ok, calendar_module}
or{:error, {exception, reason}}
Examples
iex> Cldr.Calendar.validate_calendar Cldr.Calendar.Gregorian
{:ok, Cldr.Calendar.Gregorian}
iex> Cldr.Calendar.validate_calendar :not_a_calendar
{:error,
{Cldr.InvalidCalendarModule, ":not_a_calendar is not a calendar module."}}
@spec wednesday() :: 3
Returns the ordinal day number representing Wednesday.
@spec week_of_month(date()) :: {Calendar.month(), week()} | {:error, {module(), String.t()}}
Returns the {month, week_number}
for a date
.
The nature of a week depends on the calendar configuration and therefore some results may be surprising. For example the date of December 31st 2018 is actually in month one of the ISO Week calendar of 2019.
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
a tuple of the form
{month, week}
or{:error, :not_defined}
if the calendar does not support the concept of weeks.
Examples
iex> Cldr.Calendar.week_of_month(~D[2019-01-01])
{1, 1}
iex> Cldr.Calendar.week_of_month(~D[2018-12-31])
{1, 1}
iex> Cldr.Calendar.week_of_month(~D[2019-01-01 Cldr.Calendar.BasicWeek])
{1, 1}
iex> Cldr.Calendar.week_of_month(~D[2018-12-31 Cldr.Calendar.BasicWeek])
{12, 5}
iex> Cldr.Calendar.week_of_month(~D[2018-12-31 Cldr.Calendar.Julian])
{:error, :not_defined}
@spec week_of_year(date()) :: {Calendar.year(), week()} | {:error, {module(), String.t()}}
Returns the {year, week_number}
for a date
.
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
a the week of the year as an integer or
{:error, :not_defined}
if the calendar does not support the concept of weeks.
Examples
iex> Cldr.Calendar.week_of_year ~D[2019-01-01]
{2019, 1}
iex> Cldr.Calendar.week_of_year ~D[2019-12-01]
{2019, 48}
iex> Cldr.Calendar.week_of_year ~D[2019-52-01 Cldr.Calendar.NRF]
{2019, 52}
iex> Cldr.Calendar.week_of_year ~D[2019-26-01 Cldr.Calendar.NRF]
{2019, 26}
iex> Cldr.Calendar.week_of_year ~D[2019-12-01 Cldr.Calendar.Julian]
{:error, :not_defined}
Returns whether a given date is a weekday.
Weekdays are locale-specific and depend on the policies of a given territory (country).
Arguments
date
is anyDate.t/0
.options
is aKeyword.t/0
list of options.
Options
:locale
is any locale or locale name validated byCldr.validate_locale/2
. The default isCldr.get_locale()
which returns the locale set for the current process.:territory
is any valid ISO-3166-2 territory that is validated byCldr.validate_territory/1
.:backend
is anyCldr
backend module. See the backend configuration documentation for further information. The default isCldr.Calendar.Backend.Default
which configures only theen
locale.
Notes
When identifying which territory context within which to determine whether a given day is a weekday or not the following order applies:
A territory specified by the
:territory
option.The territory defined as part of the
:locale
option.The territory defined as part of the current processes default locale.
Examples
# The default locale for `Cldr` is `en-001` for which
# the territory is `001` (the world). The weekdays
# for `001` are Monday to Friday
iex> Cldr.Calendar.weekday? ~D[2019-03-23], locale: :en
false
iex> Cldr.Calendar.weekday? ~D[2019-03-23], territory: "IS"
false
# Saturday is a weekday in India
iex> Cldr.Calendar.weekday? ~D[2019-03-23], locale: :"en-IN", backend: MyApp.Cldr
true
# Friday is not a weekday in Saudi Arabia
iex> Cldr.Calendar.weekday? ~D[2019-03-22], locale: :"ar-SA", backend: MyApp.Cldr
false
# Friday is not a weekday in Israel
iex> Cldr.Calendar.weekday? ~D[2019-03-22], locale: :he, backend: MyApp.Cldr
false
Returns a list of the days of the week that are considered a weekend for a given territory (country).
Arguments
territory
is any valid ISO3166-2 code.
Returns
- A list of integers representing the days of the week that are week days.
Notes
The list of days may not my monotonic. See the example for Saudi Arabia below.
Examples
iex> Cldr.Calendar.weekdays("US")
[1, 2, 3, 4, 5]
iex> Cldr.Calendar.weekdays("IN")
[1, 2, 3, 4, 5, 6]
iex> Cldr.Calendar.weekdays("SA")
[1, 2, 3, 4, 7]
iex> Cldr.Calendar.weekdays("yy")
{:error, {Cldr.UnknownTerritoryError, "The territory \"yy\" is unknown"}}
Returns a list of the days of the week that are considered a weekend for a given territory (country).
Arguments
territory
is any valid ISO3166-2 code.
Returns
- A list of integers representing the days of the week that are weekend days.
Examples
iex> Cldr.Calendar.weekend("US")
[6, 7]
iex> Cldr.Calendar.weekend("IN")
[7]
iex> Cldr.Calendar.weekend("SA")
[5, 6]
iex> Cldr.Calendar.weekend("yy")
{:error, {Cldr.UnknownTerritoryError, "The territory \"yy\" is unknown"}}
Returns whether a given date is a weekend day.
Weekend days are locale-specific and depend on the policies of a given territory (country).
Arguments
date
is anyDate.t/0
.options
is aKeyword.t/0
list of options.
Options
:locale
is any locale or locale name validated byCldr.validate_locale/2
. The default isCldr.get_locale()
which returns the locale set for the current process.:territory
is any valid ISO-3166-2 territory that is validated byCldr.validate_territory/1
.:backend
is anyCldr
backend module. See the backend configuration documentation for further information. The default isCldr.Calendar.Backend.Default
which configures only theen
locale.
Notes
When identifying which territory context within which to determine whether a given day is a weekend or not the following order applies:
A territory specified by the
:territory
option.The territory defined as part of the
:locale
option.The territory defined as part of the current processes default locale.
Examples
# The default locale for `Cldr` is `en-001` for which
# the territory is `001` (the world). The weekend
# for `001` is Saturday and Sunday
iex> Cldr.Calendar.weekend? ~D[2019-03-23]
true
iex> Cldr.Calendar.weekend? ~D[2019-03-23], locale: :en
true
iex> Cldr.Calendar.weekend? ~D[2019-03-23], territory: "IS"
true
# In India the official weekend is only Sunday
iex> Cldr.Calendar.weekend? ~D[2019-03-23], locale: "en-IN", backend: MyApp.Cldr
false
# In Israel the weekend starts on Friday
iex> Cldr.Calendar.weekend? ~D[2019-03-22], locale: :he, backend: MyApp.Cldr
true
# As it also does in Saudia Arabia
iex> Cldr.Calendar.weekend? ~D[2019-03-22], locale: :"ar-SA", backend: MyApp.Cldr
true
# Sunday is not a weekend day in Saudi Arabia
iex> Cldr.Calendar.weekend? ~D[2019-03-24], locale: :"ar-SA", backend: MyApp.Cldr
false
@spec weeks_in_year(date()) :: {week(), Calendar.day_of_week()} | {:error, {module(), String.t()}}
Returns the number of weeks in a year.
Arguments
date
is anyDate.t/0
or an integer year or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
{weeks_in_year, days_in_last_week}
Examples
# For the default Calendar.ISO calendar the number of
# weeks in a year is either 52 or 53 with each week
# being 7 days. The first week may start in the Gregorian
# year prior and end in the following Gregorian year.
iex> Cldr.Calendar.weeks_in_year ~D[2022-01-01]
{52, 7}
iex> Cldr.Calendar.weeks_in_year ~D[2023-01-01]
{53, 7}
# For week calculations, the Cldr.Calendar.ISO and Cldr.Calendar.ISOWeek
# have the same definition.
iex> Cldr.Calendar.weeks_in_year 2023, Cldr.Calendar.ISO
{52, 7}
iex> Cldr.Calendar.weeks_in_year 2020, Cldr.Calendar.ISOWeek
{53, 7}
iex> Cldr.Calendar.weeks_in_year ~D[2026-W01-1 Cldr.Calendar.ISOWeek]
{53, 7}
# For calendars that are configured to have the first week
# start on the first day of the year there will be a final
# week 53 with either 1 or 2 days.
iex> Cldr.Calendar.SequentialWeeks.weeks_in_year 2023
{53, 1}
iex> Cldr.Calendar.SequentialWeeks.weeks_in_year 2020
{53, 2}
Returns the number of days in n
weeks
Example
iex> Cldr.Calendar.weeks_to_days(2)
14
@spec year_of_era(date()) :: {Calendar.day(), Calendar.era()} | {:error, {module(), String.t()}}
Returns the {year_of_era, era}
for
a date
.
This function differs slightly
from Date.year_of_era/1
. See the notes
below
Arguments
date
is anyDate.t/0
or a map with one or more of the fields:year
,:month
,:day
and optionally:calendar
.
Returns
- a the year since the start of the era and the era of the year as a tuple.
Notes
Unlike
Date.year_of_era/1
, this function supports eras that change part way through the calendar year. This is common in the Japanese calendar where the eras change when a new emperor is ordained which can happen at any time of year. Therefore this function is consistent withDate.year_of_era/1
for the Gregorian and related calendars, but returns a different (and more accurate) result for the Japanese calendar.This is also true for fiscal year calendars that start on a day other than January 1st. The year of era will depend on whether the calendar was configured with
year: :beginning
,year: :ending
oryear: :majority
.
Examples
iex> Cldr.Calendar.year_of_era ~D[2019-01-01]
{2019, 1}
iex> Cldr.Calendar.year_of_era Cldr.Calendar.first_day_of_year(2019, Cldr.Calendar.NRF)
{2019, 1}
iex> Cldr.Calendar.year_of_era Cldr.Calendar.last_day_of_year(2019, Cldr.Calendar.NRF)
{2019, 1}