Cldr Calendars v1.1.0 Cldr.Calendar behaviour 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 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 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 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.

Link to this section Summary

Types

Specifies the type of a calendar.

Specifies the type of a calendar

Specifies the days of the week as integers.

The types of relationship between two Date.Range intervals

Represents the number of days since the calendar epoch.

The precision for date intervals

Specifies the quarter of year for a calendar date.

Specifies the week of year for a calendar date.

Functions

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

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

Returns a Date.t 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 {day_of_era, era} for a date.

Returns the day of the year for a date.

Returns the default calendar.

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

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.

Returns the last date of a year for a calendar.

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

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

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.

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

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

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

Callbacks

Returns the calendar basis.

Returns the CLDR calendar type.

Returns the number of days in a 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 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 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.

Link to this section Types

Link to this type

calendar()

View Source
calendar() :: module()

Specifies the type of a calendar.

A calendar is a module that implements the Calendar and Cldr.Calendar behaviours.

Link to this type

calendar_type()

View Source
calendar_type() :: :month | :week

Specifies the type of a calendar

Link to this type

day_of_week()

View Source
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.

Link to this type

interval_relation()

View Source
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

Link to this type

iso_day_number()

View Source
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.

Link to this type

precision()

View Source
precision() :: :years | :quarters | :months | :weeks | :days

The precision for date intervals

Link to this type

quarter()

View Source
quarter() :: 1..4

Specifies the quarter of year for a calendar date.

Specifies the week of year for a calendar date.

Link to this section Functions

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

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

Returns

When a Date.t is passed, a Date.t 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]
Link to this function

date_from_iso_days(iso_day_number, calendar)

View Source
date_from_iso_days(Calendar.iso_days() | iso_day_number(), calendar()) ::
  Date.t()

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

  • a Date.t()

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]
Link to this function

date_from_tuple(arg, calendar)

View Source

Returns a Date.t 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 the Calendar and Cldr.Calendar behaviours

Returns

  • a Date.t

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}
Link to this function

date_to_iso_days(date)

View Source
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 any Date.t()

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
Link to this function

date_to_string(date)

View Source
date_to_string(Date.t()) :: String.t()

Formats a date into a string representation

Example

iex> import Cldr.Calendar.Sigils
iex> Cldr.Calendar.date_to_string ~d[2019-12-04]
"2019-12-04 Cldr.Calendar.Gregorian"
iex> Cldr.Calendar.date_to_string ~d[2019-23-04 NRF]
"2019-W23-4 Cldr.Calendar.NRF"

Returns the {day_of_era, era} for a date.

Arguments

  • date is any Date.t()

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.

Link to this function

day_of_year(date)

View Source
day_of_year(Date.t()) :: Calendar.day()

Returns the day of the year for a date.

Arguments

  • date is any Date.t()

Returns

  • a the day of the year as an integer

Examples

iex> import Cldr.Calendar.Sigils
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 NRF]
365
iex> Cldr.Calendar.day_of_year ~d[2012-53-07 NRF]
372

See Date.days_in_month/1.

Returns the default calendar.

Link to this function

first_day_of_year(map)

View Source
first_day_of_year(date :: Date.t()) :: Date.t()

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

Arguments

  • date is any Date.t()

Returns

  • a Date.t() or

  • {:error, :invalid_date}

Examples

iex>  Cldr.Calendar.first_day_of_year ~D[2019-12-01]
~D[2019-01-01]
Link to this function

first_day_of_year(year, calendar)

View Source
first_day_of_year(year :: Calendar.year(), calendar :: calendar()) :: Date.t()

Returns the first date of a year in a calendar.

Arguments

Returns

  • a Date.t() 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}
Link to this function

first_gregorian_day_of_year(map)

View Source
Link to this function

first_gregorian_day_of_year(year, calendar)

View Source
first_gregorian_day_of_year(Calendar.year(), calendar()) ::
  Date.t() | {:error, :invalid_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]

Returns the ordinal day number representing Friday.

Link to this function

inspect(term, opts \\ [])

View Source
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
Link to this function

interval(date_from, count, precision)

View Source
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 that is the start of the sequence

  • date_to_or_count is upper bound of the sequence as a Date.t 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> import Cldr.Calendar.Sigils
Cldr.Calendar.Sigils
iex> d = ~d[2019-01-31]
~d[2019-01-31 Gregorian]
iex> d2 = ~d[2019-05-31]
~d[2019-05-31 Gregorian]
iex> Cldr.Calendar.interval d, 3, :months
[~d[2019-01-31 Gregorian], ~d[2019-02-28 Gregorian], ~d[2019-03-31 Gregorian]]
iex> Cldr.Calendar.interval d, d2, :months
[~d[2019-01-31 Gregorian], ~d[2019-02-28 Gregorian], ~d[2019-03-31 Gregorian],
 ~d[2019-04-30 Gregorian], ~d[2019-05-31 Gregorian]]
Link to this function

interval_stream(date_from, count, precision)

View Source
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 exept that it is lazily evaluated.

Arguments

  • date_from is a any Date.t that is the start of the sequence

  • date_to_or_count is upper bound of the sequence as a Date.t 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> import Cldr.Calendar.Sigils
Cldr.Calendar.Sigils
iex> d = ~d[2019-01-31]
~d[2019-01-31 Gregorian]
iex> d2 = ~d[2019-05-31]
~d[2019-05-31 Gregorian]
iex> Cldr.Calendar.interval_stream(d, 3, :months) |> Enum.to_list
[~d[2019-01-31 Gregorian], ~d[2019-02-28 Gregorian], ~d[2019-03-31 Gregorian]]
iex> Cldr.Calendar.interval_stream(d, d2, :months) |> Enum.to_list
[~d[2019-01-31 Gregorian], ~d[2019-02-28 Gregorian], ~d[2019-03-31 Gregorian],
 ~d[2019-04-30 Gregorian], ~d[2019-05-31 Gregorian]]
Link to this function

iso_days_to_day_of_week(iso_day_number)

View Source
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
Link to this function

iso_week_of_year(date)

View Source
iso_week_of_year(Date.t()) :: {Calendar.year(), week()}

Returns the ISO week number for a date.

Arguments

  • date is any Date.t()

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> import Cldr.Calendar.Sigils
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 NRF]
{2020, 4}
iex> Cldr.Calendar.iso_week_of_year ~d[2019-26-01 NRF]
{2019, 30}
iex> Cldr.Calendar.iso_week_of_year ~d[2019-12-01 C.E. Julian]
{:error, :not_defined}
Link to this function

last_day_of_year(map)

View Source
last_day_of_year(date :: Date.t()) :: Date.t()

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

Arguments

  • date is any Date.t()

Returns

  • a Date.t() or

  • {:error, :invalid_date}

Examples

iex>  Cldr.Calendar.last_day_of_year ~D[2019-01-01]
~D[2019-12-31]
Link to this function

last_day_of_year(year, calendar)

View Source
last_day_of_year(year :: Calendar.year(), calendar :: calendar()) :: Date.t()

Returns the last date of a year for a calendar.

Arguments

Returns

  • a Date.t() 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}
Link to this function

last_gregorian_day_of_year(map)

View Source
Link to this function

last_gregorian_day_of_year(year, calendar)

View Source
last_gregorian_day_of_year(Calendar.year(), calendar()) ::
  Date.t() | {:error, :invalid_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]
Link to this function

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

View Source
localize(Date.t(), atom(), Keyword.t()) ::
  String.t() | {:error, {module(), String.t()}}

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

Arguments

  • date_ is any Date.t

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

  • options is a keyword list of options

Options

Returns

  • A string representing the localized date part, or

  • A list of strings representing the days of the week for the part :days_of_week. The days are in week order for the given date's calendar

  • {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], :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"
"السبت"
Link to this function

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

View Source

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

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

  • options is a Kwyrod 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]. Sincce 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].

Returns

When a Date.t is passed, a Date.t is returned. When a Date.Range.t is passed a Date.Range.t is returned.

Examples

iex> import Cldr.Calendar.Sigils
Cldr.Calendar.Sigils
iex> Cldr.Calendar.minus ~d[2016-03-01], :days, 1
~d[2016-02-29 Gregorian]
iex> Cldr.Calendar.minus ~d[2019-03-01], :months, 1
~d[2019-02-01 Gregorian]
iex> Cldr.Calendar.minus ~d[2016-03-01], :days, 1
~d[2016-02-29 Gregorian]
iex> Cldr.Calendar.minus ~d[2019-03-01], :days, 1
~d[2019-02-28 Gregorian]
iex> Cldr.Calendar.minus ~d[2019-03-01], :months, 1
~d[2019-02-01 Gregorian]
iex> Cldr.Calendar.minus ~d[2019-03-01], :quarters, 1
~d[2018-12-01 Gregorian]
iex> Cldr.Calendar.minus ~d[2019-03-01], :years, 1
~d[2018-03-01 Gregorian]
Link to this function

modified_julian_day(date)

View Source

Returns the Modified Julian Day of a Date.t.

Arguments

  • date is any Date.t()

Returns

  • an integer 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

Returns the ordinal day number representing Monday

Link to this function

month_of_year(date)

View Source
month_of_year(Date.t()) :: Calendar.month()

Returns the month number for a date.

Arguments

  • date is any Date.t()

Returns

  • a the quarter of the year as an integer

Examples

iex> import Cldr.Calendar.Sigils
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 NRF]
12
iex> Cldr.Calendar.month_of_year ~d[2019-26-01 NRF]
6

See Date.months_in_year/1.

Link to this function

new(calendar_module, calendar_type, config)

View Source
new(module(), calendar_type(), Keyword.t()) ::
  {:ok, calendar()} | {:already_exists, module()}

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 am atom representing the module name of the created calendar.

  • calendar_type is an atom of either :month or :week indicating whcih 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

  • {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.

  • :locale can be any configured locale. If provided it will be used to determine the :day_of_year and :days_in_first_week option values. The default value is nil

  • :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 Gregorian month of year in which this calendar begins or ends. The default is 1.

  • :year is used to determine which calendar Greogian 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 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 configuraiton 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 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, 5, 4],   # The weeks are laid out as *months* in a `[4,5,4]` pattern
    year: :majority,             # Any given year is that in which the majority of 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, 5, 4],
    ...>   year: :majority,
    ...>   cldr_backend: nil,
    ...>   locale: nil
    {:ok, ISOWeek}

Note that Cldr.Calendar.ISOWeek is included as part of this library.

Link to this function

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

View Source

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

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

Returns

When a Date.t is passed, a Date.t 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]

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

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

  • options is a Kwyrod 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]. Sincce 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].

Returns

When a Date.t is passed, a Date.t is returned. When a Date.Range.t is passed a Date.Range.t is returned.

Examples

iex> import Cldr.Calendar.Sigils
Cldr.Calendar.Sigils
iex> Cldr.Calendar.plus ~d[2016-02-29], :days, 1
~d[2016-03-01 Gregorian]
iex> Cldr.Calendar.plus ~d[2019-03-01], :months, 1
~d[2019-04-01 Gregorian]
iex> Cldr.Calendar.plus ~d[2016-02-29], :days, 1
~d[2016-03-01 Gregorian]
iex> Cldr.Calendar.plus ~d[2019-02-28], :days, 1
~d[2019-03-01 Gregorian]
iex> Cldr.Calendar.plus ~d[2019-03-01], :months, 1
~d[2019-04-01 Gregorian]
iex> Cldr.Calendar.plus ~d[2019-03-01], :quarters, 1
~d[2019-06-01 Gregorian]
iex> Cldr.Calendar.plus ~d[2019-03-01], :years, 1
~d[2020-03-01 Gregorian]
Link to this function

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

View Source
plus(Date.t(), atom(), integer(), Keyword.t()) :: Date.t()
plus(Date.Range.t(), atom(), integer(), Keyword.t()) :: Date.Range.t()
Link to this function

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

View Source

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

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

  • options is a Keyword list of options that is passed to plus/4 or minus/4

Returns

When a Date.t is passed, a Date.t 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]
Link to this function

quarter_of_year(date)

View Source
quarter_of_year(Date.t()) :: Cldr.Calendar.quarter()

Returns the quarter number for a date.

Arguments

  • date is any Date.t()

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
Link to this function

saturday()

View Source
saturday() :: 6

Returns the ordinal day number representing Saturday.

Returns the ordinal day number representing Sunday.

Link to this function

thursday()

View Source
thursday() :: 4

Returns the ordinal day number representing Thursday.

Link to this function

tuesday()

View Source
tuesday() :: 2

Returns the ordinal day number representing Tuesday.

Link to this function

wednesday()

View Source
wednesday() :: 3

Returns the ordinal day number representing Wednesday.

Link to this function

week_of_month(date)

View Source
week_of_month(Date.t()) :: {Calendar.month(), week()}

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

Returns

  • a tuple of the form {month, week} or

  • {:error, :not_defined} if the calendar does not support the concept of weeks.

Examples

iex> import Cldr.Calendar.Sigils
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 BasicWeek])
{1, 1}
iex> Cldr.Calendar.week_of_month(~d[2018-12-31 BasicWeek])
{12, 5}
iex> Cldr.Calendar.week_of_month(~d[2018-12-31 Julian])
{:error, :not_defined}
Link to this function

week_of_year(date)

View Source
week_of_year(Date.t()) :: {Calendar.year(), week()}

Returns the {year, week_number} for a date.

Arguments

  • date is any Date.t()

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> import Cldr.Calendar.Sigils
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 NRF]
{2019, 52}
iex> Cldr.Calendar.week_of_year ~d[2019-26-01 NRF]
{2019, 26}
iex> Cldr.Calendar.week_of_year ~d[2019-12-01 C.E. Julian]
{:error, :not_defined}
Link to this function

weekday?(date, options \\ [])

View Source
weekday?(Date.t(), 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 (country).

Arguments

  • date is any Date.t()

  • options is a keyword list of options

Options

  • :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

  • :territory is any valid ISO-3166-2 territory that is validated by Cldr.validate_territory/1

  • :backend is any Cldr backend module. See the backend configuration documentation for further information. The default is Cldr.Calendar.Backend.Default which configures only the en 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 defalt locale for [`Cldr`](https://hexdocs.pm/ex_cldr/2.8.0/Cldr.html) 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("xx")
{:error, {Cldr.UnknownTerritoryError, "The territory \"xx\" 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("xx")
{:error, {Cldr.UnknownTerritoryError, "The territory \"xx\" is unknown"}}
Link to this function

weekend?(date, options \\ [])

View Source
weekend?(Date.t(), 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

  • date is any Date.t()

  • options is a keyword list of options

Options

  • :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

  • :territory is any valid ISO-3166-2 territory that is validated by Cldr.validate_territory/1

  • :backend is any Cldr backend module. See the backend configuration documentation for further information. The default is Cldr.Calendar.Backend.Default which configures only the en 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 defalt locale for [`Cldr`](https://hexdocs.pm/ex_cldr/2.8.0/Cldr.html) 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
Link to this function

weeks_in_year(map)

View Source
weeks_in_year(Date.t()) :: Cldr.Calendar.week()

Returns the number of weeks in a year.

Arguments

  • Either a Date.t() or an integer year a calendar name

Returns

  • In integer number of weeks in a year

Examples

iex> import Cldr.Calendar.Sigils
iex> Cldr.Calendar.weeks_in_year ~d[2026-W01-01 ISOWeek]
53
iex> Cldr.Calendar.weeks_in_year ~d[2019-01-01]
52
iex> Cldr.Calendar.weeks_in_year ~d[2020-01-01]
53
iex> Cldr.Calendar.weeks_in_year 2020, Cldr.Calendar.ISOWeek
53
Link to this function

weeks_in_year(year, calendar)

View Source
weeks_in_year(Calendar.year(), calendar()) :: Cldr.Calendar.week()
Link to this function

weeks_to_days(n)

View Source
weeks_to_days(integer()) :: integer()

Returns the number of days in n weeks

Example

iex> Cldr.Calendar.weeks_to_days(2)
14

Link to this section Callbacks

Link to this callback

calendar_base()

View Source
calendar_base() :: :week | :month

Returns the calendar basis.

Returns either :week or :month

Link to this callback

cldr_calendar_type()

View Source
cldr_calendar_type() :: :gregorian | :persian | :coptic | :ethiopic

Returns the CLDR calendar type.

Only algorithmic calendars are considered in this implementation

Link to this callback

days_in_year(year)

View Source
days_in_year(year :: Calendar.year()) :: Calendar.day()

Returns the number of days in a year

Link to this callback

iso_week_of_year(year, month, day)

View Source
iso_week_of_year(
  year :: Calendar.year(),
  month :: Calendar.month(),
  day :: Calendar.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.

Link to this callback

month(year, month)

View Source
month(year :: Calendar.year(), month :: Calendar.month()) :: Date.Range.t()

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

Link to this callback

month_of_year(year, month, day)

View Source
month_of_year(
  year :: Calendar.year(),
  month :: Calendar.month() | Cldr.Calendar.week(),
  day :: Calendar.day()
) :: Calendar.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.

Link to this callback

periods_in_year(year)

View Source
periods_in_year(year :: Calendar.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

Link to this callback

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

View Source
plus(
  year :: Calendar.year(),
  month :: Calendar.month() | week(),
  day :: Calendar.day(),
  months_or_quarters :: :months | :quarters,
  increment :: integer(),
  options :: Keyword.t()
) :: {Calendar.year(), Calendar.month(), Calendar.day()}

Increments a Date.t 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.

Link to this callback

quarter(year, quarter)

View Source
quarter(year :: Calendar.year(), quarter :: Cldr.Calendar.quarter()) ::
  Date.Range.t()

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

Link to this callback

week(year, week)

View Source
week(year :: Calendar.year(), week :: week()) ::
  Date.Range.t() | {:error, :not_defined}

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

Link to this callback

week_of_month(arg1, arg2, arg3)

View Source
week_of_month(Calendar.year(), Cldr.Calendar.week(), Calendar.day()) ::
  {Calendar.month(), Cldr.Calendar.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.

Link to this callback

week_of_year(year, month, day)

View Source
week_of_year(
  year :: Calendar.year(),
  month :: Calendar.month() | Cldr.Calendar.week(),
  day :: Calendar.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.

Link to this callback

weeks_in_year(year)

View Source
weeks_in_year(year :: Calendar.year()) :: week() | {:error, :not_defined}

Returns the number of weeks in a year

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