Class Index | File Index

Classes

Class PhoneNumber

Create a new phone number instance that parses the phone number parameter for its constituent parts, and store them as separate fields in the returned object. The options object may include any of these properties:

This function is locale-sensitive, and will assume any number passed to it is appropriate for the given locale. If the MCC is given, this method will assume that numbers without an explicit country code have been dialled within the country given by the MCC. This affects how things like area codes are parsed. If the MCC is not given, this method will use the given locale to determine the country code. If the locale is not explicitly given either, then this function uses the region of current locale as the default.

The input number may contain any formatting characters for the given locale. Each field that is returned in the json object is a simple string of digits with all formatting and whitespace characters removed.

The number is decomposed into its parts, regardless if the number contains formatting characters. If a particular part cannot be extracted from given number, the field will not be returned as a field in the object. If no fields can be extracted from the number at all, then all digits found in the string will be returned in the subscriberNumber field. If the number parameter contains no digits, an empty object is returned.

This instance can contain any of the following fields after parsing is done:

The following rules determine how the number is parsed:
  1. If the number starts with a character that is alphabetic instead of numeric, do not parse the number at all. There is a good chance that it is not really a phone number. In this case, an empty instance will be returned.
  2. If the phone number uses the plus notation or explicitly uses the international direct dialing prefix for the given locale, then the country code is identified in the number. The rules of given locale are used to parse the IDD prefix, and then the rules of the country in the prefix are used to parse the rest of the number.
  3. If a country code is provided as an argument to the function call, use that country's parsing rules for the number. This is intended for programs like a Contacts application that know what the country is of the person that owns the phone number and can pass that on as a hint.
  4. If the appropriate locale cannot be easily determined, default to using the rules for the current user's region.
Example: parsing the number "+49 02101345345-78" will give the following properties in the resulting phone number instance: 
     {
       iddPrefix: "+",
       countryCode: "49",
       areaCode: "02101",
       subscriberNumber: "345345",
       extension: "78"
     }
Note that in this example, because international direct dialing is explicitly used in the number, the part of this number after the IDD prefix and country code will be parsed exactly the same way in all locales with German rules (country code 49). Regions currently supported are:
Defined in: ilib-full-dyn.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
PhoneNumber(number, options)
Field Summary
Field Attributes Field Name and Description
 
areaCode
The area code prefix of a land line number.
 
cic
The carrier identification code used to identify alternate long distance or international carriers.
 
countryCode
The unique IDD country code for the country where the phone number is serviced.
 
emergency
Identifies an emergency number that is typically short, such as "911" in North America or "112" in many other places in the world.
 
extension
The direct dial extension number.
 
iddPrefix
The international direct dialing prefix.
 
mobilePrefix
The prefix of the subscriber number that indicates that this is the number of a mobile phone.
 
serviceCode
The prefix that identifies this number as commercial service number.
 
subscriberNumber
The unique number associated with the subscriber of this phone.
 
trunkAccess
The digits required to access the trunk.
 
vsc
The vertical service code.
Method Summary
Method Attributes Method Name and Description
 
compare(other)
This routine will compare the two phone numbers in an locale-sensitive manner to see if they possibly reference the same phone number.
 
equals(other)
Determine whether or not the other phone number is exactly equal to the current one.
 
normalize(options)
This function normalizes the current phone number to a canonical format and returns a string with that phone number.
<static>  
PhoneNumber.parseImsi(imsi, options)
Parse an International Mobile Subscriber Identity (IMSI) number into its 3 constituent parts:
  1. mcc - Mobile Country Code, which identifies the country where the phone is currently receiving service.
Class Detail
PhoneNumber(number, options)
Parameters:
{!string|PhoneNumber} number
A free-form phone number to be parsed, or another phone number instance to copy
{Object=} options
options that guide the parser in parsing the number
Field Detail
areaCode
The area code prefix of a land line number.
cic
The carrier identification code used to identify alternate long distance or international carriers.
countryCode
The unique IDD country code for the country where the phone number is serviced.
emergency
Identifies an emergency number that is typically short, such as "911" in North America or "112" in many other places in the world.
extension
The direct dial extension number.
iddPrefix
The international direct dialing prefix. This is always followed by the country code.
mobilePrefix
The prefix of the subscriber number that indicates that this is the number of a mobile phone.
serviceCode
The prefix that identifies this number as commercial service number.
subscriberNumber
The unique number associated with the subscriber of this phone.
trunkAccess
The digits required to access the trunk.
vsc
The vertical service code. These are codes that typically start with a star or hash, like "*69" for "dial back the last number that called me".
Method Detail
{number} compare(other)
This routine will compare the two phone numbers in an locale-sensitive manner to see if they possibly reference the same phone number.

In many places, there are multiple ways to reach the same phone number. In North America for example, you might have a number with the trunk access code of "1" and another without, and they reference the exact same phone number. This is considered a strong match. For a different pair of numbers, one may be a local number and the other a full phone number with area code, which may reference the same phone number if the local number happens to be located in that area code. However, you cannot say for sure if it is in that area code, so it will be considered a somewhat weaker match.

Similarly, in other countries, there are sometimes different ways of reaching the same destination, and the way that numbers match depends on the locale.

The various phone number fields are handled differently for matches. There are various fields that do not need to match at all. For example, you may type equally enter "00" or "+" into your phone to start international direct dialling, so the iddPrefix field does not need to match at all.

Typically, fields that require matches need to match exactly if both sides have a value for that field. If both sides specify a value and those values differ, that is a strong non-match. If one side does not have a value and the other does, that causes a partial match, because the number with the missing field may possibly have an implied value that matches the other number. For example, the numbers "650-555-1234" and "555-1234" have a partial match as the local number "555-1234" might possibly have the same 650 area code as the first number, and might possibly not. If both side do not specify a value for a particular field, that field is considered matching.

The values of following fields are ignored when performing matches:

The values of the following fields matter if they do not match:
Parameters:
{string|PhoneNumber} other
other phone number to compare this one to
Returns:
{number} non-negative integer describing the percentage quality of the match. 100 means a very strong match (100%), and lower numbers are less and less strong, down to 0 meaning not at all a match.
{boolean} equals(other)
Determine whether or not the other phone number is exactly equal to the current one.

The difference between the compare method and the equals method is that the compare method compares normalized numbers with each other and returns the degree of match, whereas the equals operator returns true iff the two numbers contain the same fields and the fields are exactly the same. Functions and other non-phone number properties are not compared.

Parameters:
{string|PhoneNumber} other
another phone number to compare to this one
Returns:
{boolean} true if the numbers are the same, false otherwise
{string|undefined} normalize(options)
This function normalizes the current phone number to a canonical format and returns a string with that phone number. If parts are missing, this function attempts to fill in those parts.

The options object contains a set of properties that can possibly help normalize this number by providing "extra" information to the algorithm. The options parameter may be null or an empty object if no hints can be determined before this call is made. If any particular hint is not available, it does not need to be present in the options object.

The following is a list of hints that the algorithm will look for in the options object:

The following are a list of options that control the behaviour of the normalization: If both a set of options and a locale are given, and they offer conflicting information, the options will take precedence. The idea is that the locale tells you the region setting that the user has chosen (probably in firstuse), whereas the the hints are more current information such as where the phone is currently operating (the MCC).

This function performs the following types of normalizations with assisted dialling turned on:

  1. If the current location of the phone matches the home country, this is a domestic call.
    • Remove any iddPrefix and countryCode fields, as they are not needed
    • Add in a trunkAccess field that may be necessary to call a domestic numbers in the home country
  2. If the current location of the phone does not match the home country, attempt to form a whole international number.
    • Add in the area code if it is missing from the phone number and the area code of the current phone is available in the hints
    • Add the country dialling code for the home country if it is missing from the phone number
    • Add or replace the iddPrefix with the correct one for the current country. The phone number will have been parsed with the settings for the home country, so the iddPrefix may be incorrect for the current country. The iddPrefix for the current country can be "+" if the phone is connected to a UMTS network, and either a "+" or a country-dependent sequences of digits for CDMA networks.
This function performs the following types of normalization with assisted dialling turned off: This method modifies the current object, and also returns a string containing the normalized phone number that can be compared directly against other normalized numbers. The canonical format for phone numbers that is returned from thhomeLocaleis method is simply an uninterrupted and unformatted string of dialable digits.
Parameters:
{{ mcc:string|defaultAreaCode:string|country:string|networkType:string|assistedDialing:boolean|sms:boolean|manualDialing:boolean }} options
an object containing options to help in normalizing.
Returns:
{string|undefined} the normalized string, or undefined if the number could not be normalized
<static> {{mcc:string|mnc:string|msin:string}|undefined} PhoneNumber.parseImsi(imsi, options)
Parse an International Mobile Subscriber Identity (IMSI) number into its 3 constituent parts:
  1. mcc - Mobile Country Code, which identifies the country where the phone is currently receiving service.
  2. mnc - Mobile Network Code, which identifies the carrier which is currently providing service to the phone
  3. msin - Mobile Subscription Identifier Number. This is a unique number identifying the mobile phone on the network, which usually maps to an account/subscriber in the carrier's database.
Because this function may need to load data to identify the above parts, you can pass an options object that controls how the data is loaded. The options may contain any of the following properties:
Parameters:
{string} imsi
IMSI number to parse
{Object} options
options controlling the loading of the locale data
Returns:
{{mcc:string|mnc:string|msin:string}|undefined} components of the IMSI number, when the locale data is loaded synchronously, or undefined if asynchronous
Documentation generated by JsDoc Toolkit 2.4.0 on Tue Feb 02 2016 15:53:55 GMT-0800 (PST)