Localize.Territory.Hemisphere (Localize v1.4.0)

Copy Markdown View Source

Returns the hemisphere a territory lies in.

A season is the other half of the year either side of the equator, so anything that writes or reckons seasons needs to know which hemisphere a place is in. hemisphere/1 answers for a territory code or for a locale, whose territory it takes from Localize.Territory.territory_from_locale/1.

A territory the equator runs through has no single answer and is :ambiguous: Brazil, Indonesia and Kenya each have summer in both halves of the year depending where in them you stand.

Where the data comes from

CLDR carries no latitude for a territory, so the classification here is the library's own. Of the 261 territory codes CLDR knows, 154 own a zone in the IANA time zone database and their hemisphere is checked against the latitude it records (test/localize/territory/hemisphere_test.exs); the rest share another territory's zone and carry no coordinate of their own.

A region (:"002", :"419") is not classified here at all. It is answered from the territories it contains, so a region cannot disagree with its own members: :"005" (South America) is :ambiguous because Brazil is, and :"053" (Australasia) is :southern because everything in it is.

Summary

Types

t()

The half of the world a territory lies in, or neither.

Functions

hemisphere(language_tag)

Returns the hemisphere a territory lies in.

hemisphere!(territory)

Returns the hemisphere a territory lies in, raising on error.

Types

t()

@type t() :: :northern | :southern | :ambiguous

The half of the world a territory lies in, or neither.

Functions

hemisphere(language_tag)

@spec hemisphere(Localize.LanguageTag.t() | atom() | String.t()) ::
  {:ok, t()} | {:error, Exception.t()}

Returns the hemisphere a territory lies in.

Arguments

Returns

  • {:ok, :northern} for a territory above the equator.

  • {:ok, :southern} for a territory below it.

  • {:ok, :ambiguous} for a territory the equator runs through, and for a region holding territories on both sides of it.

  • {:error, exception} if the territory is not known, or a locale names no territory.

Examples

iex> Localize.Territory.Hemisphere.hemisphere(:AU)
{:ok, :southern}

iex> Localize.Territory.Hemisphere.hemisphere("JP")
{:ok, :northern}

iex> Localize.Territory.Hemisphere.hemisphere(:BR)
{:ok, :ambiguous}

iex> {:ok, language_tag} = Localize.validate_locale("en-AU")
iex> Localize.Territory.Hemisphere.hemisphere(language_tag)
{:ok, :southern}

iex> Localize.Territory.Hemisphere.hemisphere(:"053")
{:ok, :southern}

iex> Localize.Territory.Hemisphere.hemisphere(:"005")
{:ok, :ambiguous}

hemisphere!(territory)

@spec hemisphere!(Localize.LanguageTag.t() | atom() | String.t()) :: t() | no_return()

Returns the hemisphere a territory lies in, raising on error.

Arguments

Returns

  • The hemisphere, one of :northern, :southern or :ambiguous.

Raises

  • Raises if the territory is not known, or a locale names no territory.

Examples

iex> Localize.Territory.Hemisphere.hemisphere!(:NZ)
:southern

iex> Localize.Territory.Hemisphere.hemisphere!(:FR)
:northern