Cldr.Calendar behaviour (Cldr Calendars v2.3.0)

View Source

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 proleptic Cldr.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

any_date_time()

Super type of any date or time.

calendar()

Specifies the type of a calendar.

calendar_type()

Specifies the type of a calendar

date()

All date fields are optional however many functions will require the presence of one or more - and often all - fields be present.

date_time()

All date time fields are optional however many functions will require the presence of one or more - and often all - fields be present.

day()

Specifies the day of a date as either a positive integer or nil.

day_of_week()

Specifies the days of the week as integers.

day_of_week_to_binary()

A mapping of a day of the week ordinal to the localized string of the name of that day.

era()

Specifies the year of a date as either a positive integer or nil.

interval_relation()

The types of relationship between two Date.Range intervals

iso_day_number()

Represents the number of days since the calendar epoch.

leap_month?()

Boolean indicating is this is a leap month

month()

Specifies the month of a date as either a positive integer or nil.

naive_date_time()

All naive date time fields are optional however many functions will require the presence of one or more - and often all - fields be present.

part()

The part of a date, time or datetime that can be localized.

precision()

The precision for date intervals

quarter()

Specifies the quarter of year for a calendar date.

time()

All time fields are optional however many functions will require the presence of one or more - and often all - fields be present.

week()

Specifies the week of year for a calendar date.

year()

Specifies the year of a date as either a positive integer or nil.

Callbacks

calendar_base()

Returns the calendar basis.

calendar_year(year, month, day)

Returns a the year in a calendar year.

cldr_calendar_type()

Returns the CLDR calendar type.

cyclic_year(year, month, day)

Returns a the cyclic year in a calendar year.

days_in_month(month)

Returns the number of days in a month (withoout a year).

days_in_year(year)

Returns the number of days in a year.

extended_year(year, month, day)

Returns a the extended year in a calendar year.

iso_week_of_year(year, month, day)

Returns a tuple of {year, week_in_year} for a given year, month or week, and day for a a calendar.

month(year, month)

Returns a date range representing the days in a given month for a calendar year.

month_of_year(year, month, day)

Returns the month for a given year, month or week, and day for a a calendar.

periods_in_year(year)

Returns the number of periods (which are months in a month calendar and weeks in a week calendar) in a year

plus(year, month, day, months_or_quarters, increment, options)

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).

quarter(year, quarter)

Returns a date range representing the days in a given quarter for a calendar year.

related_gregorian_year(year, month, day)

Returns a the related year in a calendar year.

week(year, week)

Returns a date range representing the days in a given week for a calendar year.

week_of_month(year, week, day)

Returns a tuple of {month, week_in_month} for a given year, month or week, and day for a a calendar.

week_of_year(year, month, day)

Returns a tuple of {year, week_in_year} for a given year, month or week, and day for a a calendar.

weeks_in_year(year)

Returns the number of weeks in a year.

year(year)

Returns a date range representing the days in a calendar year.

Functions

calendar_for_territory(territory, config \\ [])

Returns a calendar configured according to the preferences defined for a territory.

calendar_from_locale(locale)

Return the calendar module for a locale.

calendar_from_locale(locale, backend \\ Cldr.default_backend!())

Return the calendar module for a locale.

calendar_from_territory(territory)

Returns the calendar module preferred for a territory.

calendar_module?(module)

Returns a boolean indicating if a module is a Cldr.Calendar module.

calendar_year(date)

Returns the year number for a date that is the representation used for a calendar.

current(date, atom)

Returns the current date or date range for a date period (year, quarter, month, week or day).

cyclic_year(date)

Returns the cycle year number for a date.

date_from_day_of_year(year, day_of_year, calendar \\ Cldr.Calendar.Gregorian)

Returns a Date.t/0 from a year, day_of_year and a calendar.

date_from_iso_days(iso_day_number, calendar)

Returns a date represented by a number of days since the start of the epoch.

date_from_list(list, calendar \\ Cldr.Calendar.Gregorian)

Returns a Date.t/0 from a keyword list and a calendar.

date_from_tuple(arg, calendar \\ Cldr.Calendar.Gregorian)

Returns a Date.t/0 from a date tuple of {year, month, day} and a calendar.

date_to_iso_days(date)

Returns the number of days since the start of the epoch.

date_to_string(date)

Formats a date into a string representation.

datetime_from_modified_julian_date(mjd)

Returns the DateTime (defaulting to UTC timezone) for the given Modified Julian Day.

day_of_era(date)

Returns the {day_of_era, era} for a date.

day_of_week(date)

See Date.day_of_week/1.

day_of_week(date, starting_on)

See Date.day_of_week/2.

day_of_year(date)

Returns the day of the year for a date.

days_in_month(date)

See Date.days_in_month/1.

default_calendar()

Returns the default calendar.

do_cardinal_day_of_week(day, map)
extended_year(date)

Returns the extended year number for a date.

first_day_for_locale(locale)

Returns the first day of a week for a given locale where 1 means Monday and 7 means Sunday.

first_day_for_locale(locale, options \\ [])
first_day_for_territory(territory)

Returns the first day of the week for a given territory.

first_day_of_year(date)

Returns the first date of a year for a Date.t/0.

first_day_of_year(year, calendar)

Returns the first date of a year in a calendar.

first_gregorian_day_of_year(date)

Returns the gregorian date of the first day of of a year for a calendar.

first_gregorian_day_of_year(year, calendar)
friday()

Returns the cardinal day number representing Friday.

inspect(term, opts \\ [])

An inspect_fun/2 that can be configured in Inspect.Opts supporting inspection of user-defined calendars.

interval(date_from, count, precision)

Returns an Enumerable list of dates of a given precision of either :years, :quarters, :months, :weeks or :days.

interval_stream(date_from, count, precision)

Returns an a Stream function than can be lazily enumerated.

iso_day_of_week(date)

Returns the ISO day of week for a date where 1 means Monday and 7 means Sunday.

iso_days_to_day_of_week(iso_day_number)

Returns the day of the week for a given iso_day_number

iso_week_of_year(date)

Returns the ISO week number for a date.

last_day_of_year(date)

Returns the last date of a year for a Date.t/0.

last_day_of_year(year, calendar)

Returns the last date of a year for a calendar.

last_gregorian_day_of_year(date)

Returns the gregorian date of the first day of a year for a calendar.

last_gregorian_day_of_year(year, calendar)
localize(date)

Localize a date by converting it to calendar introspected from the provided or default locale.

localize(date, options)
localize(datetime, part, options \\ [])

Returns a localized string for a part of a Date.t/0.

min_days_for_locale(locale)

Returns the minimum days in the first week of a year for a given locale.

min_days_for_locale(locale, options \\ [])
min_days_for_territory(territory)
minus(date, period, amount, options \\ [])

Decrements a date or date range by an integer amount of a date period (year, quarter, month, week or day).

modified_julian_day(datetime)

Returns the Modified Julian Day of a Date.t/0.

monday()

Returns the cardinal day number representing Monday

month_names(calendar, options \\ [])

Returns a sorted list of tuples containing ordinal months and month names for a give calendar.

month_of_year(date)

Returns the month number for a date.

months_in_year(date)

See Date.months_in_year/1.

new(calendar_module, calendar_type, config)

Creates a new proleptic gregrian calendar based upon the provided configuration.

next(date_or_date_range, date_part, options \\ [])

Returns the next date or date range for a date period (year, quarter, month, week or day).

plus(value, increment)

Adds a duration to a date

plus(date, duration, options)
plus(date, period, increment, options \\ [])

Increments a date or date range by an integer amount of a date period (year, quarter, month, week or day).

previous(date_or_date_range, date_part, options \\ [])

Returns the previous date or date range for a date period (year, quarter, month, week or day).

quarter_of_year(date)

Returns the quarter number for a date.

related_gregorian_year(date)

Returns the related gregorian year number for a date.

saturday()

Returns the cardinal day number representing Saturday.

strftime(date_or_time_or_datetime, format, options \\ [])

Formats the given date, time, or datetime into a string.

strftime_options!(options \\ [])

Returns a keyword list of options than can be applied to Calendar.strftime/3 or Cldr.Calendar.strftime/3.

sunday()

Returns the cardinal day number representing Sunday.

thursday()

Returns the cardinal day number representing Thursday.

tuesday()

Returns the cardinal day number representing Tuesday.

validate_calendar(calendar_module)

Validates if the argument is a Cldr.Calendar calendar module.

wednesday()

Returns the cardinal day number representing Wednesday.

week_of_month(date)

Returns the {month, week_number} for a date.

week_of_year(date)

Returns the {year, week_number} for a date.

weekday?(date, options \\ [])

Returns whether a given date is a weekday.

weekdays(territory)

Returns a list of the days of the week that are considered a weekend for a given territory (country).

weekend(territory)

Returns a list of the days of the week that are considered a weekend for a given territory (region, country).

weekend?(date, options \\ [])

Returns whether a given date is a weekend day.

weeks_in_year(date)

Returns the number of weeks in a year.

weeks_in_year(year, calendar)
weeks_to_days(n)

Returns the number of days in n weeks

year_of_era(date)

Returns the {year_of_era, era} for a date.

Types

any_date_time()

@type any_date_time() :: date() | time() | naive_date_time() | date_time()

Super type of any date or time.

calendar()

@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.

calendar_type()

@type calendar_type() :: :month | :week

Specifies the type of a calendar

date()

@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.

date_time()

@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.

day()

@type day() :: Calendar.day() | nil

Specifies the day of a date as either a positive integer or nil.

day_of_week()

@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 representing 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.

day_of_week_to_binary()

@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.

era()

@type era() :: non_neg_integer() | nil

Specifies the year of a date as either a positive integer or nil.

interval_relation()

@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

iso_day_number()

@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.

leap_month?()

@type leap_month?() :: boolean()

Boolean indicating is this is a leap month

month()

@type month() :: Calendar.month() | nil

Specifies the month of a date as either a positive integer or nil.

naive_date_time()

@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.

part()

@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.

precision()

@type precision() :: :years | :quarters | :months | :weeks | :days

The precision for date intervals

quarter()

@type quarter() :: 1..4

Specifies the quarter of year for a calendar date.

time()

@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.

week()

@type week() :: pos_integer()

Specifies the week of year for a calendar date.

year()

@type year() :: Calendar.year() | nil

Specifies the year of a date as either a positive integer or nil.

Callbacks

calendar_base()

@callback calendar_base() :: :week | :month

Returns the calendar basis.

Returns either :week or :month.

calendar_year(year, month, day)

@callback calendar_year(year :: year(), month :: month(), day :: day()) :: Calendar.year()

Returns a the year in a calendar year.

cldr_calendar_type()

@callback cldr_calendar_type() ::
  :gregorian
  | :persian
  | :coptic
  | :ethiopic
  | :ethiopic_amete_alem
  | :chinese
  | :japanese
  | :dangi

Returns the CLDR calendar type.

Only algorithmic calendars are considered in this implementation.

cyclic_year(year, month, day)

@callback cyclic_year(year :: year(), month :: month(), day :: day()) :: Calendar.year()

Returns a the cyclic year in a calendar year.

days_in_month(month)

@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).

days_in_year(year)

@callback days_in_year(year :: year()) :: Calendar.day()

Returns the number of days in a year.

extended_year(year, month, day)

@callback extended_year(year :: year(), month :: month(), day :: day()) :: Calendar.year()

Returns a the extended year in a calendar year.

iso_week_of_year(year, month, day)

@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.

month(year, month)

@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.

month_of_year(year, month, day)

@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.

periods_in_year(year)

@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

plus(year, month, day, months_or_quarters, increment, options)

@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.

quarter(year, quarter)

@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.

related_gregorian_year(year, month, day)

@callback related_gregorian_year(year :: year(), month :: month(), day :: day()) ::
  Calendar.year()

Returns a the related year in a calendar year.

week(year, week)

@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.

week_of_month(year, week, day)

@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.

week_of_year(year, month, day)

@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.

weeks_in_year(year)

@callback weeks_in_year(year :: year()) ::
  {week(), Calendar.day()} | {:error, :not_defined}

Returns the number of weeks in a year.

year(year)

@callback year(year :: year()) :: Date.Range.t() | {:error, :not_defined}

Returns a date range representing the days in a calendar year.

Functions

calendar_for_territory(territory, config \\ [])

Returns a calendar configured according to the preferences defined for a territory.

calendar_from_locale(locale)

Return the calendar module for a locale.

Arguments

  • locale is any locale or locale name validated by Cldr.validate_locale/2. The default is Cldr.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}

calendar_from_locale(locale, backend \\ Cldr.default_backend!())

Return the calendar module for a locale.

Arguments

Returns

  • {:ok, calendar_module} or

  • {:error, {exception, reason}}

Examples 

iex> Cldr.Calendar.calendar_from_locale("en-US", MyApp.Cldr)
{:ok, Cldr.Calendar.US}

iex> Cldr.Calendar.calendar_from_locale("en-GB-u-ca-gregory", MyApp.Cldr)
{:ok, Cldr.Calendar.Gregorian}

iex> Cldr.Calendar.calendar_from_locale("fa-IR", MyApp.Cldr)
{:ok, Cldr.Calendar.Persian}

iex> Cldr.Calendar.calendar_from_locale("fa-IR-u-ca-gregory", MyApp.Cldr)
{:ok, Cldr.Calendar.Gregorian}

calendar_from_territory(territory)

Returns the calendar module preferred for a territory.

Arguments

  • territory is any valid ISO3166-2 code as an String.t/0 or upcased atom.

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:

  1. That another calendar is preferred over :gregorian for a territory

  2. That 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.

calendar_module?(module)

Returns a boolean indicating if a module is a Cldr.Calendar module.

calendar_year(date)

@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 any Date.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

current(date, atom)

Returns the current date or date range for a date period (year, quarter, month, week or day).

Arguments

  • date_or_date_range is any Date.t/0 or Date.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]

cyclic_year(date)

@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 any Date.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)

Returns a Date.t/0 from a year, day_of_year and a calendar.

Arguments

Returns

date_from_iso_days(iso_day_number, calendar)

@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 the Calendar and Cldr.Calendar behaviours.

Returns

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]

date_from_list(list, calendar \\ Cldr.Calendar.Gregorian)

Returns a Date.t/0 from a keyword list and a calendar.

Arguments

Returns

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}

date_from_tuple(arg, calendar \\ Cldr.Calendar.Gregorian)

Returns a Date.t/0 from a date tuple of {year, month, day} and a calendar.

Arguments

Returns

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}

date_to_iso_days(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

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

date_to_string(date)

@spec date_to_string(Date.t()) :: String.t()

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"

datetime_from_modified_julian_date(mjd)

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

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]

day_of_era(date)

@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 any Date.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}

day_of_week(date)

See Date.day_of_week/1.

day_of_week(date, starting_on)

See Date.day_of_week/2.

day_of_year(date)

@spec day_of_year(date()) :: Calendar.day() | {:error, {module(), String.t()}}

Returns the day of the year for a date.

Arguments

  • date is any Date.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

days_in_month(date)

See Date.days_in_month/1.

default_calendar()

Returns the default calendar.

do_cardinal_day_of_week(day, map)

extended_year(date)

@spec extended_year(date()) :: Calendar.year() | {:error, {module(), String.t()}}

Returns the extended year number for a date.

Arguments

  • date is any Date.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

first_day_for_locale(locale)

Returns the first day of a week for a given locale where 1 means Monday and 7 means Sunday.

Note that the first day of the first week is commonly not aligned with the first day of the year.

first_day_for_locale(locale, options \\ [])

first_day_for_territory(territory)

Returns the first day of the week for a given territory.

Arguments

  • territory is any valid ISO3166-2 code.

Returns

  • The first day of the week for this territory. Here 1 means Monday and 7 means Sunday.

first_day_of_year(date)

@spec first_day_of_year(date :: date()) :: Date.t() | {:error, :invalid_date}

Returns the first date of a year for a Date.t/0.

Arguments

Returns

Examples 

iex>  Cldr.Calendar.first_day_of_year(~D[2019-12-01])
~D[2019-01-01]

first_day_of_year(year, calendar)

@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

Returns

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}

first_gregorian_day_of_year(date)

Returns the gregorian date of the first day of of a year for a calendar.

Arguments

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]

first_gregorian_day_of_year(year, calendar)

@spec first_gregorian_day_of_year(year() | date(), calendar()) ::
  Date.t() | {:error, :invalid_date}

friday()

@spec friday() :: 5

Returns the cardinal day number representing Friday.

inspect(term, opts \\ [])

@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

interval(date_from, count, precision)

@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 any Date.t/0 that is the start of the sequence.

  • date_to_or_count is upper bound of the sequence as a Date.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]]

interval_stream(date_from, count, precision)

@spec interval_stream(
  date_from :: Date.t(),
  date_to_or_count :: Date.t() | non_neg_integer(),
  precision()
) :: fun()

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 any Date.t/0 that is the start of the sequence.

  • date_to_or_count is upper bound of the sequence as a Date.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]]

iso_day_of_week(date)

@spec iso_day_of_week(date()) :: Calendar.day_of_week()

Returns the ISO day of week for a date where 1 means Monday and 7 means Sunday.

Arguments

  • date is any Date.t/0 or a map with one or more of the fields :year, :month, :day and optionally :calendar.

Returns

  • An integer ISO day of week in the range 1..7 where 1 is Monday and 7 is Sunday.

Examples 

iex> {:ok, us_calendar} = Cldr.Calendar.calendar_from_locale("en")
iex> {:ok, us_date} = Date.new(2025, 1, 1, us_calendar)
iex> Cldr.Calendar.iso_day_of_week(us_date)
3

iso_days_to_day_of_week(iso_day_number)

@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

Returns

  • An integer representing a day of the week where Monday is represented by 1 and Sunday is represented by 7.

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

iso_week_of_year(date)

@spec iso_week_of_year(date()) ::
  {Calendar.year(), week()} | {:error, {module(), String.t()}}

Returns the ISO week number for a date.

Arguments

  • date is any Date.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}

last_day_of_year(date)

@spec last_day_of_year(date :: date()) :: Date.t()

Returns the last date of a year for a Date.t/0.

Arguments

Returns

Examples 

iex>  Cldr.Calendar.last_day_of_year(~D[2019-01-01])
~D[2019-12-31]

last_day_of_year(year, calendar)

@spec last_day_of_year(year :: year(), calendar :: calendar()) :: Date.t()

Returns the last date of a year for a calendar.

Arguments

Returns

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}

last_gregorian_day_of_year(date)

Returns the gregorian date of the first day of a year for a calendar.

Arguments

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]

last_gregorian_day_of_year(year, calendar)

@spec last_gregorian_day_of_year(date() | year(), calendar()) ::
  Date.t() | {:error, :invalid_date}

localize(date)

(since 1.19.0) 
@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

Options

Returns

  • {:ok, date} where date 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}}

localize(date, options)

(since 1.19.0) 
@spec localize(any_date_time(), Keyword.t() | atom()) ::
  {:ok, any_date_time()}
  | {:error, :incompatible_calendars}
  | {:error, {module(), String.t()}}

localize(datetime, part, options \\ [])

@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 any Date.t/0.

  • part is one of :era, :quarter, :month, :day_of_week or :days_of_week.

  • options is a Keyword.t/0 list of options.

Options

  • :locale is any valid locale name in the list returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2. The default is Cldr.get_locale().

  • :backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is default_backend!/0.

  • :format is one of :wide, :abbreviated or :narrow. The default is :abbreviated.

  • :era will, if set to :variant localize the era using the variant data. In the :en locale, this will produce CE and BCE rather than the default AD and BC.

  • :am_pm will, if set to :variant localize the "AM"/"PM" time period indicator with the variant data. In the :en locale, this will produce am and pm rather than the default AM and PM.

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")
"السبت"

min_days_for_locale(locale)

Returns the minimum days in the first week of a year for a given locale.

min_days_for_locale(locale, options \\ [])

min_days_for_territory(territory)

minus(date, period, amount, options \\ [])

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 any Date.t/0 or Date.Range.t

  • period is :years, :quarters, :months, :weeks or :days.

  • options is a Keyword.t/0 list of options.

Options

  • :coerce is a boolean which, when set to true 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}. Setting coerce: 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]

modified_julian_day(datetime)

Returns the Modified Julian Day of a Date.t/0.

Arguments

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

monday()

@spec monday() :: 1

Returns the cardinal day number representing Monday

month_names(calendar, options \\ [])

(since 2.3.0) 
@spec month_names(calendar :: calendar(), options :: Keyword.t()) ::
  [{pos_integer(), String.t()}] | {:error, {module(), String.t()}}

Returns a sorted list of tuples containing ordinal months and month names for a give calendar.

Arguments

  • calendar is any calendar module

  • options is a keyword list of options.

Options

  • :locale is any locale returned by Cldr.known_locale_names/1. The default is Cldr.get_locale/0.

  • :type is one of :standalone or :format. The default is :format.

  • :format is one of :abbreviated, Lwide or :narrow. The default is :abbreviated.

Returns

  • A sorted list of tuples of the format {ordinal month number, month name}.

Examples 

iex> Cldr.Calendar.month_names(Calendar.ISO, format: :wide)
%{
  1 => "January",
  2 => "February",
  3 => "March",
  4 => "April",
  5 => "May",
  6 => "June",
  7 => "July",
  8 => "August",
  9 => "September",
  10 => "October",
  11 => "November",
  12 => "December"
}

iex> Cldr.Calendar.month_names(Calendar.ISO, locale: :de)
%{
  1 => "Jan.",
  2 => "Feb.",
  3 => "März",
  4 => "Apr.",
  5 => "Mai",
  6 => "Juni",
  7 => "Juli",
  8 => "Aug.",
  9 => "Sept.",
  10 => "Okt.",
  11 => "Nov.",
  12 => "Dez."
}

iex> Cldr.Calendar.month_names(Cldr.Calendar.Gregorian, locale: :fr, format: :narrow)
%{
  1 => "J",
  2 => "F",
  3 => "M",
  4 => "A",
  5 => "M",
  6 => "J",
  7 => "J",
  8 => "A",
  9 => "S",
  10 => "O",
  11 => "N",
  12 => "D"
}

month_of_year(date)

@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 any Date.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

months_in_year(date)

See Date.months_in_year/1.

new(calendar_module, calendar_type, config)

@spec new(module(), calendar_type(), Keyword.t()) ::
  {:ok, calendar()} | {:module_already_exists, module()} | {:error, String.t()}

Creates a new proleptic gregrian 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} where module is the new calendar module that conforms to the Calendar and Cldr.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 is nil.

  • :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 parameter day_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 range 1..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 is 1.

  • :month_of_year determines the Cldr.Calendar.Gregorian month of year in which this calendar begins or ends. The default is 1.

  • :year is used to determine which calendar Gregogian year is applicable for a given calendar date. The valid options are :first, :last and :majority. 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 is 4 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.

next(date_or_date_range, date_part, options \\ [])

Returns the next date or date range for a date period (year, quarter, month, week or day).

Arguments

  • date_or_date_range is any Date.t/0 or Date.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]

plus(value, increment)

@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 to t:Calendar.date.t/0.

  • duration is any duration returned by Cldr.Calendar.Duration.new!/2.

  • options is a Keyword list of options.

Options

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]

plus(date, duration, options)

plus(date, period, increment, options \\ [])

@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 any Date.t/0 or Date.Range.t.

  • period is :years, :quarters, :months, :weeks or :days.

  • options is a Keyword.t/0 list of options.

Options

  • :coerce is a boolean which, when set to true 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}. Setting coerce: 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]

previous(date_or_date_range, date_part, options \\ [])

Returns the previous date or date range for a date period (year, quarter, month, week or day).

Arguments

  • date_or_date_range is any Date.t/0 or Date.Range.t.

  • period is :year, :quarter, :month, :week or :day.

  • options is a Keyword.t/0 list of options that is passed to plus/4 or minus/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]

quarter_of_year(date)

@spec quarter_of_year(date()) :: quarter() | {:error, {module(), String.t()}}

Returns the quarter number for a date.

Arguments

  • date is any Date.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

saturday()

@spec saturday() :: 6

Returns the cardinal day number representing Saturday.

strftime(date_or_time_or_datetime, format, options \\ [])

Formats the given date, time, or datetime into a string.

This function is a thin wrapper around Calendar.strftime/3 intended to ease formatting for localized calendars. Localized strings will be automatically injected as options to Calendar.strftime/3.

See Calendar.strftime/3 for details of formatting strings and other options.

Examples:

iex> Cldr.Calendar.strftime(~D[2025-01-26 Cldr.Calendar.IL], "%a", locale: :he)
"יום א׳"

strftime_options!(options \\ [])

Returns a keyword list of options than can be applied to Calendar.strftime/3 or Cldr.Calendar.strftime/3.

strftime_options! returns a keyword list than can be used as options to return localised names for days, months and am/pm.

Arguments

  • options is a set of keyword options. The default is [].

Options

Example 

iex: Cldr.Calendar.strftime_options!()
[
  am_pm_names: #Function<0.32021692/1 in MyApp.Cldr.Calendar.strftime_options/2>,
  month_names: #Function<1.32021692/1 in MyApp.Cldr.Calendar.strftime_options/2>,
  abbreviated_month_names: #Function<2.32021692/1 in MyApp.Cldr.Calendar.strftime_options/2>,
  day_of_week_names: #Function<3.32021692/1 in MyApp.Cldr.Calendar.strftime_options/2>,
  abbreviated_day_of_week_names: #Function<4.32021692/1 in MyApp.Cldr.Calendar.strftime_options/2>
]

Typical usage 

iex> Calendar.strftime(~D[2025-01-26 Cldr.Calendar.IL], "%a",
...>   Cldr.Calendar.strftime_options!(calendar: Cldr.Calendar.IL, locale: "en"))
"Sun"

sunday()

@spec sunday() :: 7

Returns the cardinal day number representing Sunday.

thursday()

@spec thursday() :: 4

Returns the cardinal day number representing Thursday.

tuesday()

@spec tuesday() :: 2

Returns the cardinal day number representing Tuesday.

validate_calendar(calendar_module)

Validates if the argument is a Cldr.Calendar calendar module.

If the calendar is Calendar.ISO then the validated calendar is returned as Cldr.Calendar.Gregorian.

Arguments

  • calendar_module is a module that implements the Cldr.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(Calendar.ISO)
{:ok, Cldr.Calendar.Gregorian}

iex> Cldr.Calendar.validate_calendar(:not_a_calendar)
{:error,
 {Cldr.InvalidCalendarModule, ":not_a_calendar is not a calendar module."}}

wednesday()

@spec wednesday() :: 3

Returns the cardinal day number representing Wednesday.

week_of_month(date)

@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 any Date.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}

week_of_year(date)

@spec week_of_year(date()) ::
  {Calendar.year(), week()} | {:error, {module(), String.t()}}

Returns the {year, week_number} for a date.

Arguments

  • date is any Date.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}

weekday?(date, options \\ [])

@spec weekday?(date(), Keyword.t()) :: boolean() | {:error, {module(), String.t()}}

Returns whether a given date is a weekday.

Weekdays are locale-specific and depend on the policies of a given territory (region, country).

Arguments

Options

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

iex> Cldr.Calendar.weekday?(~D[2019-03-22 Cldr.Calendar.IL], locale: :he, backend: MyApp.Cldr)
false

weekdays(territory)

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. Here 1 means Monday and 7 means Sunday.

Notes

The list of days may not be 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"}}

weekend(territory)

Returns a list of the days of the week that are considered a weekend for a given territory (region, country).

Arguments

  • territory is any valid ISO3166-2 code.

Returns

  • A list of integers representing the days of the week that are weekend days. Here 1 means Monday and 7 means Sunday.

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"}}

weekend?(date, options \\ [])

@spec weekend?(date(), Keyword.t()) :: boolean() | {:error, {module(), String.t()}}

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

Options

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

iex> Cldr.Calendar.weekend?(~D[2019-03-22 Cldr.Calendar.IL], 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

weeks_in_year(date)

@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 any Date.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}

weeks_in_year(year, calendar)

@spec weeks_in_year(year(), calendar()) ::
  {week(), Calendar.day_of_week()} | {:error, {module(), String.t()}}

weeks_to_days(n)

@spec weeks_to_days(integer()) :: integer()

Returns the number of days in n weeks

Example 

iex> Cldr.Calendar.weeks_to_days(2)
14

year_of_era(date)

@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 any Date.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

  1. 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 with Date.year_of_era/1 for the Gregorian and related calendars, but returns a different (and more accurate) result for the Japanese calendar.

  2. 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 or year: :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}