View Source Holidex.Countries.Canada (Holidex v0.1.3)
Provides public holiday observances for Canadian holidays. Each province and territory in Canada has the authority to establish its own holiday schedule and observance rules.
Summary
Types
An atom representing a supported holiday name.
An atom representing a Province or Territory short code.
Functions
Generates a NationalHoliday struct for the specified holiday and year.
Retrieves a list of national public holidays for the specified year.
Retrieves a list of national and regional holidays for a specific region and year.
Retrieves a list of available region codes.
Retrieves detailed information about all available regions.
Types
@type holiday_name() ::
:new_years_day
| :family_day
| :st_patricks_day
| :good_friday
| :easter_sunday
| :easter_monday
| :st_georges_day
| :victoria_day
| :national_indigenous_peoples_day
| :saint_jean_baptiste_day
| :canada_day
| :orangemans_day
| :nunavut_day
| :civic_holiday
| :discovery_day
| :labour_day
| :national_day_for_truth_and_reconciliation
| :thanksgiving_day
| :remembrance_day
| :christmas_day
| :boxing_day
An atom representing a supported holiday name.
@type region_code() ::
:ab | :bc | :mb | :nb | :nl | :nt | :nv | :nt | :on | :pe | :qc | :sk | :yt
An atom representing a Province or Territory short code.
@type year() :: 1900..2200
Functions
@spec holiday(holiday_name(), year()) :: Holidex.NationalHoliday.t() | {:error, :holiday, atom()}
Generates a NationalHoliday struct for the specified holiday and year.
This function creates a NationalHoliday struct for the given holiday and year. It also calculates the observance date, which may differ from the actual date if the holiday falls on a weekend or has special observance rules.
Parameters
- holiday_name: Atom representing the holiday (e.g., :new_years_day, :labour_day)
- year: Integer representing the year for which to generate the holiday
Returns
Holidex.NationalHoliday.t()
: A struct containing details about the holiday{:error, :holiday, atom()}
: An error tuple if the input is invalid
Examples
iex> Holidex.Countries.Canada.holiday(:new_years_day, 2024)
%Holidex.NationalHoliday{
name: "New Years Day",
categories: [:national],
date: ~D[2024-01-01],
observance_date: ~D[2024-01-01],
regional_names: %{},
regions: [:ab, :bc, :mb, :nb, :nl, :nt, :ns, :nu, :on, :pe, :qc, :sk, :yt],
description: "",
country: :ca
}
@spec holidays(year()) :: {:ok, [Holidex.NationalHoliday.t()]} | {:error, atom(), String.t()} | {:error, String.t()}
Retrieves a list of national public holidays for the specified year.
Parameters
year
- An integer representing the year for which to fetch holidays.
Returns
{:ok, list(Holidex.NationalHoliday.t())}
- A tuple containing:ok
and a list ofHolidex.NationalHoliday
structs representing the public holidays for the given year.{:error, atom(), String.t()}
- A tuple containing:error
, the method called as a tuple, and an error message string if the operation fails (e.g., invalid year, API failure, etc.).{:error, String.t()}
- A tuple containing:error
and an error message string if the operation fails (e.g., invalid year, API failure, etc.).
Examples
iex> Holidex.Countries.Canada.holidays(2024)
{:ok, [%Holidex.NationalHoliday{name: "New Year's Day", date: ~D[2024-01-01]}, ...]}
iex> Holidex.Countries.Canada.holidays(1800)
{:error, :holidays, "Year was out of range..."}
@spec holidays_by_region(region_code(), integer()) :: {:ok, [Holidex.RegionalHoliday.t()]} | {:error, atom()}
Retrieves a list of national and regional holidays for a specific region and year.
This function fetches all observed national and regional holidays and will use localized holiday names if they're available. The nationally recognized name will appear beside it's regional counterpart in parenthesis.
Parameters
- region_code: String or atom representing the region code (e.g., :on, :bc)
- year: Integer representing the year for which to retrieve holidays
Returns
{:ok, [RegionalHoliday.t()]}
: A tuple containing a list of RegionalHoliday structs{:error, atom()}
: An error tuple if the input is invalid or an error occurs during processing
Examples
iex> Holidex.Countries.Canada.holidays_by_region(:mb, 2024)
{:ok,
[
%Holidex.RegionalHoliday{
name: "New Years Day",
categories: [:national],
date: ~D[2024-01-01],
observance_date: ~D[2024-01-01],
region: :mb,
description: "",
country: :ca
},
%Holidex.RegionalHoliday{
name: "Louis Riel Day (Family Day)",
categories: [:regional],
date: ~D[2024-02-19],
observance_date: ~D[2024-02-19],
region: :mb,
description: "",
country: :ca
},
...
]
iex> Holidex.holidays_by_region(:invalid_region, 2024)
{:error, :holidays_by_region, :invalid_parameters}
@spec region_codes() :: [region_code()]
Retrieves a list of available region codes.
This function returns a list of region codes that can be used with other functions in the module to specify geographic regions for holiday data.
Returns
list(region_code())
- A list of strings representing region codes.
Examples
iex> Holidex.Countries.Canada.region_codes()
[:ab, :bc, :mb, :nb, :nl, :nt, :ns, :nu, :on, :pe, :qc, :sk, :yt]
@spec regions() :: [map()]
Retrieves detailed information about all available regions.
This function returns a list of maps, each containing detailed information about a specific region, including its name, type, and region code.
Returns
list(map())
- A list of maps, each representing a region with the following keys::name
- The name of the region (string):region_type
- The type of the region (atom, e.g., :province, :state):region_code
- The code for the region (atom)
Examples
iex> Holidex.Countries.Canada.regions()
[
%{name: "Alberta", region_type: :province, region_code: :ab},
%{name: "British Columbia", region_type: :province, region_code: :bc},
...
]