The area code prefix of a land line number.

The carrier identification code used to identify alternate long distance or international carriers.

The unique IDD country code for the country where the phone number is serviced.

Identifies an emergency number that is typically short, such as "911" in North America or "112" in many other places in the world.

The direct dial extension number.

The international direct dialing prefix. This is always followed by the country code.

The prefix of the subscriber number that indicates that this is the number of a mobile phone.

The prefix that identifies this number as commercial service number.

The unique number associated with the subscriber of this phone.

The digits required to access the trunk.

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".

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:

• vsc
• iddPrefix
• cic
• trunkAccess

The values of the following fields matter if they do not match:

• countryCode - A difference causes a moderately strong problem except for certain countries where there is a way to access the same subscriber via IDD and via intranetwork dialling
• mobilePrefix - A difference causes a possible non-match
• serviceCode - A difference causes a possible non-match
• areaCode - A difference causes a possible non-match
• subscriberNumber - A difference causes a very strong non-match
• extension - A difference causes a minor non-match

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.

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:

• mcc the mobile carrier code of the current network upon which this phone is operating. This is translated into an IDD country code. This is useful if the number being normalized comes from CNAP (callerid) and the MCC is known.
• defaultAreaCode the area code of the phone number of the current device, if available. Local numbers in a person's contact list are most probably in this same area code.
• country the 2 letter ISO 3166 code of the country if it is known from some other means such as parsing the physical address of the person associated with the phone number, or the from the domain name of the person's email address
• networkType specifies whether the phone is currently connected to a CDMA network or a UMTS network. Valid values are the strings "cdma" and "umts". If one of those two strings are not specified, or if this property is left off completely, this method will assume UMTS.

The following are a list of options that control the behaviour of the normalization:

• assistedDialing if this is set to true, the number will be normalized so that it can dialled directly on the type of network this phone is currently connected to. This allows customers to dial numbers or use numbers in their contact list that are specific to their "home" region when they are roaming and those numbers would not otherwise work with the current roaming carrier as they are. The home region is specified as the phoneRegion system preference that is settable in the regional settings app. With assisted dialling, this method will add or remove international direct dialling prefixes and country codes, as well as national trunk access codes, as required by the current roaming carrier and the home region in order to dial the number properly. If it is not possible to construct a full international dialling sequence from the options and hints given, this function will not modify the phone number, and will return "undefined". If assisted dialling is false or not specified, then this method will attempt to add all the information it can to the number so that it is as fully specified as possible. This allows two numbers to be compared more easily when those two numbers were otherwise only partially specified.
• sms set this option to true for the following conditions:
  • assisted dialing is turned on
  • the phone number represents the destination of an SMS message
  • the phone is UMTS
  • the phone is SIM-locked to its carrier
  This enables special international direct dialling codes to route the SMS message to the correct carrier. If assisted dialling is not turned on, this option has no affect.
• manualDialing set this option to true if the user is entering this number on the keypad directly, and false when the number comes from a stored location like a contact entry or a call log entry. When true, this option causes the normalizer to not perform any normalization on numbers that look like local numbers in the home country. If false, all numbers go through normalization. This option only has an effect when the assistedDialing option is true as well, otherwise it is ignored.

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:

• Normalize the international direct dialing prefix to be a plus or the international direct dialling access code for the current country, depending on the network type.
• If a number is a local number (ie. it is missing its area code), use a default area code from the hints if available. CDMA phones always know their area code, and GSM/UMTS phones know their area code in many instances, but not always (ie. not on Vodaphone or Telcel phones). If the default area code is not available, do not add it.
• In assisted dialling mode, if a number is missing its country code, use the current MCC number if it is available to figure out the current country code, and prepend that to the number. If it is not available, leave it off. Also, use that country's settings to parse the number instead of the current format locale.
• For North American numbers with an area code but no trunk access code, add in the trunk access code.
• For other countries, if the country code is added in step 3, remove the trunk access code when required by that country's conventions for international calls. If the country requires a trunk access code for international calls and it doesn't exist, add one.

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.

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:

• onLoad - a callback function to call when the parsing is done. When the onLoad option is given, this method will attempt to load the locale data using the ilib loader callback. When it is done (even if the data is already preassembled), the onLoad function is called with the parsing results as a parameter, so this callback can be used with preassembled or dynamic, synchronous or asynchronous loading or a mix of the above.
• sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the results returned from this constructor will not be usable for a while.
• loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.