Cldr Calendars v0.8.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.
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 {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 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.
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 {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 calendar year.
Link to this section Types
calendar()
View Source
calendar() :: module()
calendar() :: module()
Specifies the type of a calendar.
A calendar is a module that implements
the Calendar
and Cldr.Calendar
behaviours.
calendar_type()
View Source
calendar_type() :: :month | :week
calendar_type() :: :month | :week
Specifies the type of a calendar
day_of_week()
View Source
day_of_week() :: 1..7
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.
interval_relation()
View Source
interval_relation() ::
:precedes
| :preceded_by
| :meets
| :met_by
| :overlaps
| :overlapped_by
| :finished_by
| :finishes
| :contains
| :during
| :starts
| :started_by
| :equals
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()
View Source
iso_day_number() :: integer()
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.
precision()
View Source
precision() :: :years | :quarters | :months | :weeks | :days
precision() :: :years | :quarters | :months | :weeks | :days
The precision for date intervals
quarter()
View Source
quarter() :: 1..4
quarter() :: 1..4
Specifies the quarter of year for a calendar date.
week()
View Source
week() :: pos_integer()
week() :: pos_integer()
Specifies the week of year for a calendar date.
Link to this section Functions
current(date, atom) View Source
Returns the current date or date range for a date period (year, quarter, month, week or day).
Arguments
date_or_date_range
is anyDate.t
orDate.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
date_from_iso_days(iso_day_number, calendar)
View Source
date_from_iso_days(Calendar.iso_days() | iso_day_number(), calendar()) ::
Date.t()
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 theCalendar
andCldr.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]
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 datecalendar
is any module implementing theCalendar
andCldr.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}
date_to_iso_days(date)
View Source
date_to_iso_days(Date.t()) :: iso_day_number()
date_to_iso_days(Date.t()) :: iso_day_number()
Returns the number of days since the start of the epoch.
The start of the epoch is the date 0000-01-01.
Argumenets
date
is anyDate.t()
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) View Source
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"
iex> Cldr.Calendar.date_to_string ~d[2019-23-04]NRF
"2019-W23-4"
day_of_era(date)
View Source
day_of_era(Date.t()) :: {Calendar.day(), Calendar.era()}
day_of_era(Date.t()) :: {Calendar.day(), Calendar.era()}
Returns the {day_of_era, era}
for
a date
.
Arguments
date
is anyDate.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}
day_of_week(date) View Source
See Date.day_of_week/1
.
day_of_year(date)
View Source
day_of_year(Date.t()) :: Calendar.day()
day_of_year(Date.t()) :: Calendar.day()
Returns the day
of the year
for a date
.
Arguments
date
is anyDate.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
days_in_month(date) View Source
See Date.days_in_month/1
.
default_calendar() View Source
Returns the default calendar.
first_day_of_year(map) View Source
Returns the first date of a year
for a Date.t
.
Arguments
date
is anyDate.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]
first_day_of_year(year, calendar)
View Source
first_day_of_year(year :: Calendar.year(), calendar :: calendar()) :: Date.t()
first_day_of_year(year :: Calendar.year(), calendar :: calendar()) :: Date.t()
Returns the first date of a year
in a calendar
.
Arguments
year
is any yearcalendar
is any module that implements theCalendar
andCldr.Calendar
behaviours
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}
first_gregorian_day_of_year(year, calendar)
View Source
first_gregorian_day_of_year(Calendar.year(), calendar()) ::
{:ok, Date.t()} | {:error, :invalid_date}
first_gregorian_day_of_year(Calendar.year(), calendar()) :: {:ok, Date.t()} | {:error, :invalid_date}
Returns the gregorian date of the first day of of a year
for a calendar
.
Arguments
year
is any integer year number
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}
friday()
View Source
friday() :: 5
friday() :: 5
Returns the ordinal day number representing Friday.
interval(date_from, count, precision)
View Source
interval(
date_from :: Date.t(),
date_to_or_count :: Date.t() | non_neg_integer(),
precision()
) :: [Date.t()]
interval( date_from :: Date.t(), date_to_or_count :: Date.t() | non_neg_integer(), precision() ) :: [Date.t()]
Returns an Enumerable
list of dates of a given precision
of either :years
, :quarters
, :months
, :weeks
or
:days
Arguments
date_from
is a anyDate.t
that is the start of the sequencedate_to_or_count
is upper bound of the sequence as aDate.t
or the number of dates in the sequence to be generatedprecision
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]
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 1, year: 2019}
iex> d2 = ~d[2019-05-31]
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 5, year: 2019}
iex> Cldr.Calendar.interval d, 3, :months
[
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 1, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 28, month: 2, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 3, year: 2019}
]
iex> Cldr.Calendar.interval d, d2, :months
[
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 1, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 28, month: 2, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 3, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 30, month: 4, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 5, year: 2019}
]
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())
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 anyDate.t
that is the start of the sequencedate_to_or_count
is upper bound of the sequence as aDate.t
or the number of dates in the sequence to be generatedprecision
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]
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 1, year: 2019}
iex> d2 = ~d[2019-05-31]
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 5, year: 2019}
iex> Cldr.Calendar.interval_stream(d, 3, :months) |> Enum.to_list
[
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 1, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 28, month: 2, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 3, year: 2019}
]
iex> Cldr.Calendar.interval_stream(d, d2, :months) |> Enum.to_list
[
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 1, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 28, month: 2, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 3, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 30, month: 4, year: 2019},
%Date{calendar: Cldr.Calendar.Gregorian, day: 31, month: 5, year: 2019}
]
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()
iso_days_to_day_of_week(Calendar.iso_days() | Calendar.day()) :: day_of_week()
Returns the day of the week for a given
iso_day_number
Arguments
iso_day_number
is the number of days since the start of the epoch. SeeCldr.Calendar.date_to_iso_days/1
Returns
- An integer representing a day of the week where Monday
is represented by
1
and Sunday is represented by7
Examples
iex> days = Cldr.Calendar.date_to_iso_days ~D[2019-01-01]
iex> Cldr.Calendar.iso_days_to_day_of_week(days) == Cldr.Calendar.tuesday
true
iso_week_of_year(date)
View Source
iso_week_of_year(Date.t()) :: {Calendar.year(), week()}
iso_week_of_year(Date.t()) :: {Calendar.year(), week()}
Returns the ISO week
number for
a date
.
Arguments
date
is anyDate.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]Julian
{:error, :not_defined}
last_day_of_year(map) View Source
Returns the last date of a year
for a Date.t
.
Arguments
date
is anyDate.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]
last_day_of_year(year, calendar)
View Source
last_day_of_year(year :: Calendar.year(), calendar :: calendar()) :: Date.t()
last_day_of_year(year :: Calendar.year(), calendar :: calendar()) :: Date.t()
Returns the last date of a year
for a calendar
.
Arguments
year
is any yearcalendar
is any module that implements theCalendar
andCldr.Calendar
behaviours
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}
last_gregorian_day_of_year(map) View Source
last_gregorian_day_of_year(year, calendar)
View Source
last_gregorian_day_of_year(Calendar.year(), calendar()) ::
{:ok, Date.t()} | {:error, :invalid_date}
last_gregorian_day_of_year(Calendar.year(), calendar()) :: {:ok, Date.t()} | {:error, :invalid_date}
Returns the gregorian date of the first day of a year
for a calendar
.
Arguments
year
is any integer year number
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}
localize(date, part, options \\ []) View Source
Returns a localized string for a part of
a Date.t
.
Arguments
date_
is anyDate.t
part
is one of:era
,:quarter
,:month
,:day_of_week
or:days_of_week
options
is a keyword list of options
Options
:locale
is any valid locale name in the list returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
. The default isCldr.get_locale()
.backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_backend/0
.:format
is one of:wide
,:abbreviated
or:narrow
. The default is:abbreviated
.
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"
"السبت"
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 anyDate.t
orDate.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 totrue
will coerce the month and/or day to be a valid date. This affects,for example, moving to the previous month from~D[2019-03-31]
. Sincce there is no date~D[2019-02-31]
this would normally return{:error, :invalid_date}
. Settingcoerce: 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
iex> Cldr.Calendar.minus ~d[2016-03-01], :days, 1
%Date{calendar: Cldr.Calendar.Gregorian, day: 29, month: 2, year: 2016}
iex> Cldr.Calendar.minus ~d[2019-03-01], :months, 1
%Date{calendar: Cldr.Calendar.Gregorian, day: 1, month: 2, year: 2019}
iex> Cldr.Calendar.minus ~d[2016-03-01], :days, 1
%Date{calendar: Cldr.Calendar.Gregorian, day: 29, month: 2, year: 2016}
iex> Cldr.Calendar.minus ~d[2019-03-01], :days, 1
%Date{calendar: Cldr.Calendar.Gregorian, day: 28, month: 2, year: 2019}
iex> Cldr.Calendar.minus ~d[2019-03-01], :months, 1
%Date{calendar: Cldr.Calendar.Gregorian, day: 1, month: 2, year: 2019}
iex> Cldr.Calendar.minus ~d[2019-03-01], :quarters, 1
%Date{calendar: Cldr.Calendar.Gregorian, day: 1, month: 12, year: 2018}
iex> Cldr.Calendar.minus ~d[2019-03-01], :years, 1
%Date{calendar: Cldr.Calendar.Gregorian, day: 1, month: 3, year: 2018}
modified_julian_day(date) View Source
Returns the Modified Julian Day of
a Date.t
.
Arguments
date
is anyDate.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
monday()
View Source
monday() :: 1
monday() :: 1
Returns the ordinal day number representing Monday
month_of_year(date)
View Source
month_of_year(Date.t()) :: Calendar.month()
month_of_year(Date.t()) :: Calendar.month()
Returns the month
number for
a date
.
Arguments
date
is anyDate.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
months_in_year(date) View Source
new(calendar_module, calendar_type, config)
View Source
new(atom(), calendar_type(), Keyword.t()) :: {:ok, calendar()} | no_return()
new(atom(), calendar_type(), Keyword.t()) :: {:ok, calendar()} | no_return()
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 createdconfig
is a keyword list defining the configuration of the calendar.
Returns
{:ok, module}
wheremodule
is the new calendar module that conforms to theCalendar
andCldr.Calendar
behaviours
Configuration
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 anyDate.t
orDate.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
plus(value, increment) View Source
Increments a date or date range by an integer amount of a date period (year, quarter, month, week or day).
Arguments
date_or_date_range
is anyDate.t
orDate.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 totrue
will coerce the month and/or day to be a valid date. This affects,for example, moving to the previous month from~D[2019-03-31]
. Sincce there is no date~D[2019-02-31]
this would normally return{:error, :invalid_date}
. Settingcoerce: 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
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()
plus(Date.t(), atom(), integer(), Keyword.t()) :: Date.t()
plus(Date.Range.t(), atom(), integer(), Keyword.t()) :: Date.Range.t()
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 anyDate.t
orDate.Range.t
period
is:year
,:quarter
,:month
,:week
or:day
options
is a Keyword list of options that is passed toplus/4
orminus/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
quarter_of_year(date)
View Source
quarter_of_year(Date.t()) :: Cldr.Calendar.quarter()
quarter_of_year(Date.t()) :: Cldr.Calendar.quarter()
Returns the quarter
number for
a date
.
Arguments
date
is anyDate.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
saturday()
View Source
saturday() :: 6
saturday() :: 6
Returns the ordinal day number representing Saturday.
sunday()
View Source
sunday() :: 7
sunday() :: 7
Returns the ordinal day number representing Sunday.
thursday()
View Source
thursday() :: 4
thursday() :: 4
Returns the ordinal day number representing Thursday.
tuesday()
View Source
tuesday() :: 2
tuesday() :: 2
Returns the ordinal day number representing Tuesday.
wednesday()
View Source
wednesday() :: 3
wednesday() :: 3
Returns the ordinal day number representing Wednesday.
week_of_year(date)
View Source
week_of_year(Date.t()) :: {Calendar.year(), week()}
week_of_year(Date.t()) :: {Calendar.year(), week()}
Returns the {year, week_number}
for a date
.
Arguments
date
is anyDate.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]Julian
{:error, :not_defined}
weekday?(date, options \\ []) View Source
Returns whether a given date is a weekday.
Weekdays are locale-specific and depend on the policies of a given territory (country).
Arguments
date
is anyDate.t()
options
is a keyword list of options
Options
:locale
is any locale or locale name validated byCldr.validate_locale/2
. The default isCldr.get_locale()
which returns the locale set for the current process:territory
is any valid ISO-3166-2 territory that is validated byCldr.validate_territory/1
:backend
is anyCldr
backend module. See the backend configuration documentation for further information. The default isCldr.Calendar.Backend.Default
which configures only theen
locale.
Notes
When identifying which territory context within which to determine whether a given day is a weekday or not the following order applies:
A territory specified by the
:territory
optionThe territory defined as part of the
:locale
optionThe territory defined as part of the current processes default locale.
Examples
# The defalt locale for [`Cldr`](https://hexdocs.pm/ex_cldr/2.7.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
weekdays(territory) View Source
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"}}
weekend(territory) View Source
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"}}
weekend?(date, options \\ []) View Source
Returns whether a given date is a weekend day.
Weekend days are locale-specific and depend on the policies of a given territory (country).
Arguments
date
is anyDate.t()
options
is a keyword list of options
Options
:locale
is any locale or locale name validated byCldr.validate_locale/2
. The default isCldr.get_locale()
which returns the locale set for the current process:territory
is any valid ISO-3166-2 territory that is validated byCldr.validate_territory/1
:backend
is anyCldr
backend module. See the backend configuration documentation for further information. The default isCldr.Calendar.Backend.Default
which configures only theen
locale.
Notes
When identifying which territory context within which to determine whether a given day is a weekend or not the following order applies:
A territory specified by the
:territory
optionThe territory defined as part of the
:locale
optionThe territory defined as part of the current processes default locale.
Examples
# The defalt locale for [`Cldr`](https://hexdocs.pm/ex_cldr/2.7.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
weeks_to_days(n) View Source
Returns the number of days in n
weeks
Example
iex> Cldr.Calendar.weeks_to_days(2)
14
Link to this section Callbacks
calendar_base()
View Source
calendar_base() :: :week | :month
calendar_base() :: :week | :month
Returns the calendar basis.
Returns either :week or :month
cldr_calendar_type()
View Source
cldr_calendar_type() :: :gregorian | :persian | :coptic | :ethiopic
cldr_calendar_type() :: :gregorian | :persian | :coptic | :ethiopic
Returns the CLDR calendar type.
Only algorithmic calendars are considered in this implementation
days_in_year(year)
View Source
days_in_year(year :: Calendar.year()) :: Calendar.day()
days_in_year(year :: Calendar.year()) :: Calendar.day()
Returns the number of days in a year
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}
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.
month(year, month)
View Source
month(year :: Calendar.year(), month :: Calendar.month()) :: Date.Range.t()
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.
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()
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_in_year
is calculated based upon the calendar configuration.
plus(year, month, day, months_or_quarters, increment, options)
View Source
plus(
year :: Calendar.year(),
month :: Calendar.month() | Cldr.Calendar.week(),
day :: Calendar.day(),
months_or_quarters :: :months | :quarters,
increment :: integer(),
options :: Keyword.t()
) :: {Calendar.year(), Calendar.month(), Calendar.day()}
plus( year :: Calendar.year(), month :: Calendar.month() | Cldr.Calendar.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.
quarter(year, quarter)
View Source
quarter(year :: Calendar.year(), quarter :: Cldr.Calendar.quarter()) ::
Date.Range.t()
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.
week(year, week)
View Source
week(year :: Calendar.year(), week :: Cldr.Calendar.week()) ::
Date.Range.t() | {:error, :not_defined}
week(year :: Calendar.year(), week :: Cldr.Calendar.week()) :: Date.Range.t() | {:error, :not_defined}
Returns a date range representing the days in a given week for a calendar year.
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}
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.
year(year)
View Source
year(year :: Calendar.year()) :: Date.Range.t()
year(year :: Calendar.year()) :: Date.Range.t()
Returns a date range representing the days in a calendar year.