@spec available?() :: boolean()

Returns whether the NIF backend is available.

Returns

• true if the NIF shared library was loaded successfully.

• false if the NIF is not compiled or libphonenumber is missing.

Examples

iex> is_boolean(Localize.PhoneNumber.available?())
true

@spec parse(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, String.t()}

Parses a phone number string into a Localize.PhoneNumber.Number struct.

Arguments

• number_string is the phone number string to parse. It can be in national or international format.

Options

• :territory is an explicit ISO 3166-1 alpha-2 territory code (e.g., "US", "GB", or an atom like :US). Used as the default territory when the number is not in international format.

• :locale is a locale identifier used to derive the default territory. Accepts a string (e.g., "en-US"), an atom (e.g., :en_US), or a Localize.LanguageTag.t() struct. The territory is extracted from the locale.

When neither :territory nor :locale is given, the territory is derived from Localize.get_locale/0.

Returns

• {:ok, phone_number} where phone_number is a Localize.PhoneNumber.Number struct.

• {:error, reason} if the number cannot be parsed.

Examples

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> phone_number.country_code
1

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("020 7946 0958", territory: "GB")
iex> phone_number.country_code
44

@spec possible?(t()) :: boolean()

Returns whether a parsed phone number is a possible number.

A possible number has a plausible length for its territory and type but may not actually be an allocated or valid number.

Arguments

• phone_number is a Localize.PhoneNumber.Number struct.

Returns

• true if the phone number is possible.

• false otherwise.

Examples

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> Localize.PhoneNumber.possible?(phone_number)
true

@spec territory(t()) :: String.t() | nil

Returns the territory code for a parsed phone number.

Arguments

• phone_number is a Localize.PhoneNumber.Number struct.

Returns

• A two-letter ISO 3166-1 alpha-2 territory code string (e.g., "US", "GB").

• nil if the territory cannot be determined.

Examples

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> Localize.PhoneNumber.territory(phone_number)
"US"

@spec to_string(t(), format_type()) :: {:ok, String.t()} | {:error, String.t()}

Formats a parsed phone number as a string in the specified format.

Arguments

• phone_number is a Localize.PhoneNumber.Number struct returned by parse/2.

• format_type is one of :e164, :international, :national, or :rfc3966. The default is :international.

Returns

• {:ok, formatted_string} on success.

• {:error, reason} on failure.

Examples

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> Localize.PhoneNumber.to_string(phone_number, :e164)
{:ok, "+16502530000"}

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> Localize.PhoneNumber.to_string(phone_number, :international)
{:ok, "+1 650-253-0000"}

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> Localize.PhoneNumber.to_string(phone_number)
{:ok, "+1 650-253-0000"}

@spec type(t()) :: phone_number_type()

Returns the phone number type.

Arguments

• phone_number is a Localize.PhoneNumber.Number struct.

Returns

• An atom representing the type: :fixed_line, :mobile, :fixed_line_or_mobile, :toll_free, :premium_rate, :shared_cost, :voip, :personal_number, :pager, :uan, :voicemail, or :unknown.

Examples

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> Localize.PhoneNumber.type(phone_number)
:fixed_line_or_mobile

@spec valid?(t()) :: boolean()

Returns whether a parsed phone number is valid.

A valid number has the correct length and pattern for its territory and number type.

Arguments

• phone_number is a Localize.PhoneNumber.Number struct.

Returns

• true if the phone number is valid.

• false otherwise.

Examples

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> Localize.PhoneNumber.valid?(phone_number)
true

@spec valid_for_territory?(t(), String.t()) :: boolean()

Returns whether a parsed phone number is valid for a specific territory.

Arguments

• phone_number is a Localize.PhoneNumber.Number struct.

• territory is an ISO 3166-1 alpha-2 territory code string (e.g., "US", "GB").

Returns

• true if the phone number is valid for the given territory.

• false otherwise.

Examples

iex> {:ok, phone_number} = Localize.PhoneNumber.parse("+1 650-253-0000")
iex> Localize.PhoneNumber.valid_for_territory?(phone_number, "US")
true