Cldr.Calendar.new

You're seeing just the function new, go back to Cldr.Calendar module for more information.
Link to this function

new(calendar_module, calendar_type, config)

View Source

Specs

new(module(), calendar_type(), Keyword.t()) ::
  {:ok, calendar()} | {:module_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

  • {: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 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 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 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 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, 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 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, 5, 4],
    ...>   year: :majority,
    ...>   cldr_backend: nil
    {:ok, ISOWeek}

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