# `ExPhoneNumber`
[🔗](https://github.com/ex-phone-number/ex_phone_number/blob/v0.4.12/lib/ex_phone_number.ex#L1)

Parsing, formatting, and validating international phone numbers.

## Example Usage

    iex> ExPhoneNumber.parse("202-456-1111", "US")
    {
      :ok,
      %ExPhoneNumber.Model.PhoneNumber{
        country_code: 1,
        country_code_source: nil,
        extension: nil,
        italian_leading_zero: nil,
        national_number: 2024561111,
        number_of_leading_zeros: nil,
        preferred_domestic_carrier_code: nil,
        raw_input: nil
      }
    }

    iex> {:ok, phone_number} = ExPhoneNumber.parse("202-456-1111", "US")
    iex> ExPhoneNumber.format(phone_number, :e164)
    "+12024561111"
    iex> ExPhoneNumber.is_valid_number?(phone_number)
    true
    iex> ExPhoneNumber.is_possible_number?(phone_number)
    true
    iex> ExPhoneNumber.get_number_type(phone_number)
    :fixed_line_or_mobile

# `country_code_to_region_code_map`

Returns a map of country codes to region codes.

# `format`

Formats a parsed phone number.

`phone_number_format` is one of `:e164`, `:international`, `:national` or `:rfc3966`.

    iex> {:ok, phone_number} = ExPhoneNumber.parse("202-456-1111", "US")
    iex> ExPhoneNumber.format(phone_number, :e164)
    "+12024561111"

# `get_number_type`

Returns the type of a parsed phone number, based on the metadata of its region.

Possible types: `:fixed_line`, `:mobile`, `:fixed_line_or_mobile`, `:toll_free`,
`:premium_rate`, `:shared_cost`, `:voip`, `:personal_number`, `:pager`, `:uan`,
`:voicemail` and `:unknown`.

    iex> {:ok, phone_number} = ExPhoneNumber.parse("202-456-1111", "US")
    iex> ExPhoneNumber.get_number_type(phone_number)
    :fixed_line_or_mobile

# `is_possible_number?`

Checks whether a parsed phone number is possible, looking only at its length.

This is faster and more lenient than `is_valid_number?/1`.

    iex> {:ok, phone_number} = ExPhoneNumber.parse("202-456-1111", "US")
    iex> ExPhoneNumber.is_possible_number?(phone_number)
    true

# `is_possible_number?`

Parses `number` as if dialed from `region_code` and checks whether it is a possible number.

    iex> ExPhoneNumber.is_possible_number?("202-456-1111", "US")
    true

# `is_valid_number?`

Checks whether a parsed phone number matches a valid pattern for its region.

This does not verify that the number is actually in use.

    iex> {:ok, phone_number} = ExPhoneNumber.parse("202-456-1111", "US")
    iex> ExPhoneNumber.is_valid_number?(phone_number)
    true

# `parse`

Parses a string into a phone number struct.

`default_region` is a two-letter region code (e.g. `"US"`) used when the number
is not written in international format. For numbers starting with `+`, it can be
`""` or `nil`.

Returns `{:ok, phone_number}` or `{:error, message}`.

    iex> {:ok, phone_number} = ExPhoneNumber.parse("+1 202-456-1111", nil)
    iex> phone_number.country_code
    1
    iex> phone_number.national_number
    2024561111

---

*Consult [api-reference.md](api-reference.md) for complete listing*