FORMAT_PHONE

The FORMAT_PHONE function outputs a phone number with desired formatting.

The FORMAT_PHONE function takes a phone number and returns a string containing the same phone number formatted in either an international, national, or RFC3966 tel: URI format.

Declaration

FORMAT_PHONE(phone_number_string, format_string, region) -> formatted_phone_number

Parameters

phone_number_string (required, type: string)

A string containing a phone number.

format_string (required, type: string)

The format to return the phone number in (any of "E164", "INTERNATIONAL", "NATIONAL", "RFC3966").

region (optional, type: string, default: the 2-digit country code indicated by phone_number_string)

A string representing the 2-digit country code. If phone_number_string is not in proper E.164 format and doesn't contain a country code, the region indicated by region will be used to determine the country code. (Note that an E.164 country code and a 2-digit country code will not be represented by the same string.)

Return Values

formatted_phone_number (type: string)

A string containing the formatted phone number.

Examples

When displaying a phone number to a user, it is common to group the digits of the phone number so that it can more easily be read. The format strings "NATIONAL" will omit the country code of the phone number and group the digits in the phone number according to the conventions for the country. Compare how a U.S. phone number is presented compared to an Australian phone number.

FORMAT_PHONE("[phone]", "NATIONAL") -> "[phone]"

FORMAT_PHONE("[phone]", "NATIONAL") -> "[phone]"

The "NATIONAL" format string should only be used it will be obvious to a user which country the phone number belongs to. For example, when displaying a user's own phone number, using national formatting is fine as the user will recognize their own number. However, when displaying an unknown phone number, or when displaying multiple phone numbers from different countries, using the format string "INTERNATIONAL", will be more clear.

FORMAT_PHONE("[phone]", "INTERNATIONAL") -> "[phone]"

FORMAT_PHONE("[phone]", "INTERNATIONAL") -> "[phone]"

The format string "RFC3966" is needed when communicating with external systems that require the format.

FORMAT_PHONE("[phone]", "RFC3966") -> "tel:[phone]"

FORMAT_PHONE("[phone]", "RFC3966") -> "tel:[phone]"

If a phone number has been collected from a user, it may not be in proper E.164 format. The string "7167762323" is ambiguous without a country code. However, information on the country can be provided separately via the variable region. Note that if a value is given for region, a value must be given for format_string:

FORMAT_PHONE("7167762323", "E164", "US") -> "[phone]"

Providing a value for region will not overrun information given by a country code in a given phone number. The following example takes an Australian phone number in E.164 format and outputs the same Australian phone number in E.164 format, even though the given value for region indicates that the phone number is from the US region:

FORMAT_PHONE("[phone]", "E164", "US") -> "[phone]"