View Source Holidex.Countries.Canada (Holidex v0.1.4)

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 of Holidex.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..."}
Link to this function

holidays_by_region(region_code, year)

View Source
@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},
  ...
]