AntlPhonenumber (AntlPhonenumber v0.1.3) View Source

AntlPhonenumber is a third-party port of the google libphonenumber library.
The library is based on google libphonenumber cpp implementation and implements NIF functions.

Installation

If available in Hex, the package can be installed by adding antl_phonenumber to your list of dependencies in mix.exs:

def deps do
  [
    {:antl_phonenumber, "~> 0.1.1"}
  ]
end

The library supposes that google libphonenumber is installed. Please refer to the installation doc of C++ version to build the library.

Usage

AntlPhonenumber provides a set of predicates and functions to check or manipulate a number.

Ecto types

It also provides a PlusE164 Ecto type ensuring the number will be dump and load only in plus e164 format and a E164 Ecto type ensuring the number will be dump and load only in e164 format.
A number in any other format won't be cast, as country code is required to format it in plus e164 format.
However, if iso_country_code is specified, the type will ensure the number belongs to the given country code and casting will be performed accordingly to this country code.
In that case, any number of another country (a.k.a any plus_e164 of another country) will cause casting to fail.

Example:

    import AntlPhonenumber.Ecto.PlusE164

    embedded_schema do
      field(:number, PlusE164)
      field(:french_number, PlusE164, iso_country_code: "FR")

       field(:e164, E164)
      field(:french_e164, E164, iso_country_code: "FR")
    end

PlusE164 and E164 fit our needs but any type can be created to express a combination of number characteristics.
For instance, one could need a type for local french numbers. It is easy to implement another type based on existing implementation.

Ecto changeset

Changeset validations are also a AntlPhonenumber feature.
For the moment, the validators are:

  validate_iso_country_code/3
  validate_type/3

Ranges

Number ranges are also supported and implement the Enumerable protocol so we can apply Enum functions on them. The ranges can be ascendant or descendant.
For example:

  range = AntlPhonenumber.Range.new("+33148413200", "+33148413210", "FR")
  range = AntlPhonenumber.Range.new("0148413200", "0148413210", "FR")
  range = AntlPhonenumber.Range.new("0148413210", "0148413200", "FR")

Testing

Google provides number examples. The function get_plus_e164_example/2, receiving a country code and a number type allow to request an example number.
It is useful for testing.

  AntlPhonenumber.get_plus_e164_example("FR", :mobile)

Link to this section Summary

Functions

Returns the country prefix of the number. Note that the number must be formatted in plus_e164 format.

Returns the country code of the number. Note that the number must be formatted in plus_e164 format.

Get from Google a plus e164 number.

Returns the type of the number. It can be one of the list below: (premium_rate,toll_free,mobile,fixed_line,shared_cost,voip,personal_number,pager,uan,voicemail). Note that if the number is not formatted in plus_e164 nor in e164 format, a reference iso_country_code is required.

Returns true if the number is well-formatted in plus_e164 format. Otherwise, returns false.

Returns true if the number is possible. Otherwise, returns false.

Format a number to e164 (without plus) format. Note that if the number is not formatted in plus_e164 format nor in e164 , a reference iso_country_code is required.

Same as c:to_e164/1 and c:to_e164/2, but raises on parsing/formatting error.

Returns the country code corresponding to the country prefix.

Format a number to local format. Note that if the number is not formatted in plus_e164 nor in e164 format, a reference iso_country_code is required.

Format a number to plus_e164 format. Note that if the number is not formatted in plus_e164 nor in e164 format, a reference iso_country_code is required.

Same as c:to_plus_e164/1 and c:to_plus_e164/2, but raises on parsing/formatting error.

Returns true if the number is valid. Otherwise, returns false.

Returns true if the number is well-formatted in plus_e164 format and is valid. Otherwise, returns false.

Link to this section Functions

Link to this function

get_country_code!(number)

View Source

Specs

get_country_code!(binary()) :: binary()

Returns the country prefix of the number. Note that the number must be formatted in plus_e164 format.

Link to this function

get_iso_country_code!(number)

View Source

Specs

get_iso_country_code!(binary()) :: binary()

Returns the country code of the number. Note that the number must be formatted in plus_e164 format.

Link to this function

get_plus_e164_example(iso_country_code, type)

View Source

Specs

get_plus_e164_example(binary(), atom()) :: binary()

Get from Google a plus e164 number.

Returns the type of the number. It can be one of the list below: (premium_rate,toll_free,mobile,fixed_line,shared_cost,voip,personal_number,pager,uan,voicemail). Note that if the number is not formatted in plus_e164 nor in e164 format, a reference iso_country_code is required.

Link to this function

get_type(number, ref_iso_country_code)

View Source

Specs

get_type(binary(), binary() | nil) :: {:ok, atom()} | {:error, binary()}
Link to this function

move(number, iso_country_code, steps)

View Source

Specs

plus_e164?(binary()) :: boolean()

Returns true if the number is well-formatted in plus_e164 format. Otherwise, returns false.

Returns true if the number is possible. Otherwise, returns false.

Note that if the number is not formatted in plus_e164 nor in e164 format, a reference iso_country_code is required to determine the possibility of the number.

Link to this function

possible?(number, ref_iso_country_code)

View Source

Specs

possible?(binary(), binary() | nil) :: boolean()

Format a number to e164 (without plus) format. Note that if the number is not formatted in plus_e164 format nor in e164 , a reference iso_country_code is required.

Link to this function

to_e164(number, ref_iso_country_code)

View Source

Specs

to_e164(binary(), binary() | nil) :: {:ok, binary()} | {:error, binary()}

Same as c:to_e164/1 and c:to_e164/2, but raises on parsing/formatting error.

Link to this function

to_e164!(number, ref_iso_country_code)

View Source

Specs

to_e164!(binary(), binary() | nil) :: binary()
Link to this function

to_iso_country_code!(iso_country_code)

View Source

Specs

to_iso_country_code!(binary()) :: binary()

Returns the country code corresponding to the country prefix.

Specs

to_local(binary()) :: binary()

Format a number to local format. Note that if the number is not formatted in plus_e164 nor in e164 format, a reference iso_country_code is required.

Link to this function

to_local(plus_e164, ref_iso_country_code)

View Source

Specs

to_local(binary(), binary()) :: binary()

Format a number to plus_e164 format. Note that if the number is not formatted in plus_e164 nor in e164 format, a reference iso_country_code is required.

Link to this function

to_plus_e164(number, ref_iso_country_code)

View Source

Specs

to_plus_e164(binary(), binary() | nil) :: {:ok, binary()} | {:error, binary()}

Same as c:to_plus_e164/1 and c:to_plus_e164/2, but raises on parsing/formatting error.

Link to this function

to_plus_e164!(number, ref_iso_country_code)

View Source

Specs

to_plus_e164!(binary(), binary() | nil) :: binary()

Returns true if the number is valid. Otherwise, returns false.

Note that if the number is not formatted in plus_e164 nor in e164 format, a reference iso_country_code is required to determine the validity of the number.

Link to this function

valid?(number, ref_iso_country_code)

View Source

Specs

valid?(binary(), binary() | nil) :: boolean()
Link to this function

valid_plus_e164_number?(number)

View Source

Specs

valid_plus_e164_number?(binary()) :: boolean()

Returns true if the number is well-formatted in plus_e164 format and is valid. Otherwise, returns false.