phone-number.core
added in 8.12.4-0
Clojure interface to Libphonenumber.
*default-dialing-region*
dynamic
added in 8.12.4-1
Sets a default dialing region (from where calls are originating) for functions that explicitly require dialing region code to be present (usually operating on short numbers). Default is nil.
*inferred-namespaces*
dynamic
added in 8.12.4-0
Decides whether keywords which are not fully-qualified should be automatically qualified (by attaching default namespaces) when passed as arguments to functions that operate on phone number types, phone number formats, region codes and time zone formats. Defaults to true.
*info-dialing-region-derived*
dynamic
added in 8.12.4-1
Decides whether some of the results of the info function should be calculated using dialing region code derived from the given region code if the dialing region was not passed as an argument nor obtained from the *default-dialing-region* dynamic variable. Default is true.
*info-removed-nils*
dynamic
added in 8.12.4-0
Decides whether the results of the info function should contain properties having nil values. They are removed by default due to true value of this switch.
allowed-removable-characters
added in 8.12.4-1
A set of removable (like punctuation) characters in a phone number which is a string. Used during input validation.
calling-code
added in 8.12.4-0
(calling-code phone-number)(calling-code phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns its calling code as an integer number.
+
If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
calling-code-prefix
added in 8.12.16-1
(calling-code-prefix phone-number)(calling-code-prefix phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns its calling code prefix (including a plus symbol) as a string.
+
If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
calling-codes
added in 8.12.4-0
A set of all possible country calling codes.
calling-codes-for-region
added in 8.12.16-1
(calling-codes-for-region region-code)
Returns a set of all calling codes (integer numbers) associated with the given region code (keyword) which may also be :phone-number.region/world pseudo-region.
carrier
added in 8.12.4-0
(carrier phone-number)(carrier phone-number region-code)(carrier phone-number locale-specification-FQ)(carrier phone-number region-code locale-specification)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns its possible carrier name as a string or nil if the carrier name happens to be empty.
If the second argument is present then it may be a valid region code (a keyword) to be used when the given phone number does not contain region information. It is acceptable to pass nil as a value to tell the function that there is no explicit region information and it should extract it from a number.
If the third argument is present then it should be a string specifying locale information or a java.util.Locale object. It will be used during rendering carrier name. When nil is passed then the default locale settings will be used.
-
If there are 2 arguments and the second argument is a keyword but IS NOT a fully-qualified, valid locale specification (locale-specification-FQ having namespace set to phone-number.locale) then it will be treated as a region code. Using namespaced keyword for a locale (or using object other than keyword) is required to avoid ambiguity since simple region codes and locale specs can be expressed using the very same keyword names. Optionally (but a bad habit) you may use simple keyword with locale and variant (e.g. :pl_PL) that will not match any region but match locale object.
costs
added in 8.12.4-0
A set of all possible phone number cost classes as a set of keywords.
country-codes
added in 8.12.4-0
A set of all possible country calling codes.
example
added in 8.12.4-0
(example region-code)(example region-code number-type)
For the given region code and optional number type returns an example phone number that is valid (being a PhoneNumber kind of object). This is not a random number generator; it will always generate the same example number for the same arguments.
example-non-geo
added in 8.12.4-0
(example-non-geo calling-code _)(example-non-geo calling-code)
For the given network global calling code (given as a positive, natural number) returns the example phone number that is valid (being a PhoneNumber kind of object). This is not a random number generator; it will always generate the same example number for the same arguments.
find-numbers
added in 8.12.4-0
(find-numbers text)(find-numbers text region-code)(find-numbers text leniency)(find-numbers text region-code leniency)(find-numbers text region-code locale-specification)(find-numbers text region-code max-tries)(find-numbers text leniency max-tries)(find-numbers text leniency locale-specification)(find-numbers text region-code leniency max-tries)(find-numbers text region-code locale-specification dialing-region)(find-numbers text region-code leniency max-tries locale-specification)(find-numbers text region-code leniency max-tries dialing-region-FQ)(find-numbers text region-code leniency max-tries locale-specification dialing-region)
Searches for phone numbers in the given text. Returns a lazy sequence of maps where each element is a map representing a match and having the following keys:
+
If there are 2 arguments and the second argument is a keyword but IS NOT a fully-qualified, valid locale specification (locale-specification-FQ having namespace set to phone-number.locale) then it will be treated as a region code. Using namespaced keyword for a locale (or using object other than keyword) is required to avoid ambiguity since simple region codes and locale specs can be expressed using the very same keyword names. Optionally (but a bad habit) you may use simple keyword with locale and variant (e.g. :pl_PL) that will not match any region but match locale object.
costs
added in 8.12.4-0
A set of all possible phone number cost classes as a set of keywords.
country-codes
added in 8.12.4-0
A set of all possible country calling codes.
example
added in 8.12.4-0
(example region-code)(example region-code number-type)
For the given region code and optional number type returns an example phone number that is valid (being a PhoneNumber kind of object). This is not a random number generator; it will always generate the same example number for the same arguments.
example-non-geo
added in 8.12.4-0
(example-non-geo calling-code _)(example-non-geo calling-code)
For the given network global calling code (given as a positive, natural number) returns the example phone number that is valid (being a PhoneNumber kind of object). This is not a random number generator; it will always generate the same example number for the same arguments.
find-numbers
added in 8.12.4-0
(find-numbers text)(find-numbers text region-code)(find-numbers text leniency)(find-numbers text region-code leniency)(find-numbers text region-code locale-specification)(find-numbers text region-code max-tries)(find-numbers text leniency max-tries)(find-numbers text leniency locale-specification)(find-numbers text region-code leniency max-tries)(find-numbers text region-code locale-specification dialing-region)(find-numbers text region-code leniency max-tries locale-specification)(find-numbers text region-code leniency max-tries dialing-region-FQ)(find-numbers text region-code leniency max-tries locale-specification dialing-region)
Searches for phone numbers in the given text. Returns a lazy sequence of maps where each element is a map representing a match and having the following keys:
:phone-number.match/start - start index of a phone number substring:phone-number.match/end - end index of a phone number substringThe locale-specification and dialing-region are not used during searching but when the map under :phone-number/info key is generated. They are passed to the info function. Note that setting dialing-region explicitly to nil will disable it from being derived from the detected region (yet it will still default to current value of the phone-number/*default-dialing-region* if it’s set) value. To preserve default behaviour (derivation plus using the default from a dynamic variable) and explicitly pass this argument, use false.
All keyword arguments except locale-specification (which can also be of other type) are namespace inferred if *inferred-namespace* dynamic variable is set in the calling context.
Some arities can have different variants (depending on the given arguments). It’s possible to detect when keywords describing different things are not conflicting. The exception is when we have two final arguments which cannot be easily distinguished without namespacing since they may have overlapping values (like :pl as a dialing region and :pl as a locale specification). To use shortened arity with them and allow function to properly detect what kind of data it’s dealing with, please use fully-qualified keywords to describe a dialing region. Keyword without a proper namespace will be treated as locale specification on this argument position.
-For the sake of efficiency it is possible to entirely disable generation of a map under the :phone-number/info key. To do that just use arity with locale-specification and set the value of this argument to false. For argument values that you wish to be kept as default, use nil.
generate
added in 8.12.4-0
(generate)(generate region-code)(generate region-code number-type)(generate region-code number-type predicate)(generate region-code number-type predicate retries)(generate region-code number-type predicate retries min-digits)(generate region-code number-type predicate retries min-digits locale-specification)(generate region-code number-type predicate retries min-digits locale-specification random-seed)(generate region-code number-type predicate retries min-digits locale-specification random-seed early-shrinking)(generate region-code number-type predicate retries min-digits locale-specification random-seed early-shrinking preserve-raw)
Generates random phone number in a form of a map with the following keys:
+
If there are 2 arguments and the second argument is a valid format specification it will be used without setting the region. If the format specification doesn’t look like a valid format then it will be assumed it is a region code and format will be set to a default.
generate
added in 8.12.4-0
(generate)(generate region-code)(generate region-code number-type)(generate region-code number-type predicate)(generate region-code number-type predicate retries)(generate region-code number-type predicate retries min-digits)(generate region-code number-type predicate retries min-digits locale-specification)(generate region-code number-type predicate retries min-digits locale-specification random-seed)(generate region-code number-type predicate retries min-digits locale-specification random-seed early-shrinking)(generate region-code number-type predicate retries min-digits locale-specification random-seed early-shrinking preserve-raw)
Generates random phone number in a form of a map with the following keys:
:phone-number/number - a PhoneNumber object:phone-number/info - a map with phone number information (evaluated on access)When the sixth argument is present it should be a valid locale specification or a java.util.Locale object that will be passed to the info function in order to render localized versions of time zone information and geographical locations.
The seventh argument should be a long value that will seed the pseudo-random number generator used to produce digits and to choose region and/or phone number type when not given. It can be used to create a deterministic sequence of samples.
The eight, optional argument enables more aggressive shrinking of randomly generated part. If it is set to a truthy value (not nil and not false) then each sampling step that involves generation of random digits will have 50% chances of producing less digits than required (at least 1 digit remaining). The number of digits is chosen randomly. It is advised to enable shrinking when expecting highly improbable phone numbers, for instance with the impossible? predicate.
-The last, optional argument chooses whether raw input should be preserved within the PhoneNumber objects when generating samples. By default it is not preserved.
geographical?
added in 8.12.4-0
(geographical? phone-number)(geographical? phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns true if it is a geographical number as defined by Libphonenumber. Otherwise it returns false. If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
has-calling-code?
added in 8.12.4-0
(has-calling-code? phone-number)(has-calling-code? phone-number region-code)
For the given phone number returns true if the calling code is present in it, false otherwise. The region code can be explicit part of a number (as its prefix) or can be inferred by making use of the region-code argument.
-
This function will always return true if a phone number was successfully parsed.
has-known-type?
added in 8.12.4-0
(has-known-type? phone-number)(has-known-type? phone-number region-code)
Returns true if the given number is of a known type, false otherwise.
has-location?
added in 8.12.4-0
(has-location? phone-number)(has-location? phone-number region-code)
For the given phone number returns true if the approximate geographic location is present in it, false otherwise.
has-region?
added in 8.12.4-0
(has-region? phone-number)(has-region? phone-number region-code)
For the given phone number returns true if the region code is present in it, false otherwise. The region code can be explicit part of a number (as its prefix) or can be inferred by making use of the region-code argument.
has-time-zone?
added in 8.12.4-0
(has-time-zone? phone-number)(has-time-zone? phone-number region-code)
For the given phone number returns true if any time zone information is present in it, false otherwise.
impossible?
added in 8.12.4-0
(impossible? phone-number)(impossible? phone-number region-code)
Returns true if the given phone number (expressed as a string, a number, a map or a PhoneNumber object) is not possible.
info
added in 8.12.4-0
(info phone-number)(info phone-number region-code)(info phone-number locale-specification-FQ)(info phone-number region-code locale-specification)(info phone-number region-code dialing-region-FQ)(info phone-number region-code locale-specification dialing-region)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns a map containing all possible information about the number with keywords as keys.
+
The last, optional argument chooses whether raw input should be preserved within the PhoneNumber objects when generating samples. By default it is not preserved.
geographical?
added in 8.12.4-0
(geographical? phone-number)(geographical? phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns true if it is a geographical number as defined by Libphonenumber. Otherwise it returns false. If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
has-calling-code?
added in 8.12.4-0
(has-calling-code? phone-number)(has-calling-code? phone-number region-code)
For the given phone number returns true if the calling code is present in it, false otherwise. The region code can be explicit part of a number (as its prefix) or can be inferred by making use of the region-code argument.
+
This function will always return true if a phone number was successfully parsed.
has-known-type?
added in 8.12.4-0
(has-known-type? phone-number)(has-known-type? phone-number region-code)
Returns true if the given number is of a known type, false otherwise.
has-location?
added in 8.12.4-0
(has-location? phone-number)(has-location? phone-number region-code)
For the given phone number returns true if the approximate geographic location is present in it, false otherwise.
has-region?
added in 8.12.4-0
(has-region? phone-number)(has-region? phone-number region-code)
For the given phone number returns true if the region code is present in it, false otherwise. The region code can be explicit part of a number (as its prefix) or can be inferred by making use of the region-code argument.
has-time-zone?
added in 8.12.4-0
(has-time-zone? phone-number)(has-time-zone? phone-number region-code)
For the given phone number returns true if any time zone information is present in it, false otherwise.
impossible?
added in 8.12.4-0
(impossible? phone-number)(impossible? phone-number region-code)
Returns true if the given phone number (expressed as a string, a number, a map or a PhoneNumber object) is not possible.
info
added in 8.12.4-0
(info phone-number)(info phone-number region-code)(info phone-number locale-specification-FQ)(info phone-number region-code locale-specification)(info phone-number region-code dialing-region-FQ)(info phone-number region-code locale-specification dialing-region)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns a map containing all possible information about the number with keywords as keys.
Required keys:
:phone-number/calling-code
:phone-number/geographical?
@@ -99,24 +99,24 @@
If the third argument is a dialing region code (dialing-region-FQ) then it should be a fully-qualified keyword (using phone-number.region namespace) in order to distinguish it from a locale specification (which is favored as this argument).
If there are four arguments then the last one should be a dialing region code intended to be used with short numbers (like 112 etc.). It describes originating region to help validate the possibility of reaching the destination number. When this argument is missing or its value is nil and the dynamic variable *default-dialing-region* is not nil then its value will be used to set the dialing region. If the dynamic variable is also nil (which is the default) then the dynamic variable *info-dialing-region-derived* is checked to be set to truthy value (not nil and not false). If that is true then the dialing region will be derived from a region code of the number.
The :phone-number/valid? key holds the return value of valid? function call without any dialing region applied (even if it is passed as an argument or extracted from a map given as input to the info function). There is also the :phone-number.dialing-region/valid-for? key which holds the validity information taking dialing region (passed, extracted or default) into account.
-It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are analysed. It is also advised to submit a dialing region code when more precise analysis is required.
invalid-example
added in 8.12.4-0
(invalid-example region-code)
For the given region code returns the example phone number that is invalid (being a PhoneNumber kind of object). This is not a random number generator; it will always generate the same example number for the same arguments.
invalid?
added in 8.12.4-0
(invalid? phone-number)(invalid? phone-number region-code)
Returns true if the given phone number (expressed as a string, a number, a map or a PhoneNumber object) is not valid.
is-fixed-line-or-mobile?
added in 8.12.4-0
(is-fixed-line-or-mobile? phone-number)(is-fixed-line-or-mobile? phone-number region-code)
Returns true if the given number is a kind of fixed-line number or a mobile number, false otherwise. Returns true also when there is a chance that a number is either mobile or fixed-line but it cannot be certainly decided.
is-fixed-line?
added in 8.12.4-0
(is-fixed-line? phone-number)(is-fixed-line? phone-number region-specification)
Returns true when type is :phone-number.type/fixed-line, false otherwise.
is-maybe-fixed-line?
added in 8.12.4-0
(is-maybe-fixed-line? phone-number)(is-maybe-fixed-line? phone-number region-code)
Returns true if the given number is a kind of a fixed-line number or a number that belongs to a class where it cannot be fully decided whether it is mobile or fixed-line. Returns false otherwise.
is-maybe-mobile?
added in 8.12.4-0
(is-maybe-mobile? phone-number)(is-maybe-mobile? phone-number region-code)
Returns true if the given number is a kind of a mobile number or a number that belongs to a class where it cannot be fully decided whether it is mobile or fixed-line. Returns false otherwise.
is-maybe-short?
added in 8.12.4-0
is-mobile?
added in 8.12.4-0
(is-mobile? phone-number)(is-mobile? phone-number region-specification)
Returns true when type is :phone-number.type/mobile, false otherwise.
is-personal?
added in 8.12.4-0
(is-personal? phone-number)(is-personal? phone-number region-specification)
Returns true when type is :phone-number.type/personal, false otherwise.
is-premium-rate?
added in 8.12.4-0
(is-premium-rate? phone-number)(is-premium-rate? phone-number region-specification)
Returns true when type is :phone-number.type/premium-rate, false otherwise.
is-shared-cost?
added in 8.12.4-0
(is-shared-cost? phone-number)(is-shared-cost? phone-number region-specification)
Returns true when type is :phone-number.type/shared-cost, false otherwise.
is-short?
added in 8.12.4-0
is-toll-free?
added in 8.12.4-0
(is-toll-free? phone-number)(is-toll-free? phone-number region-specification)
Returns true when type is :phone-number.type/toll-free, false otherwise.
is-uan?
added in 8.12.4-0
(is-uan? phone-number)(is-uan? phone-number region-specification)
Returns true when type is :phone-number.type/uan, false otherwise.
is-uncertain-fixed-line-or-mobile?
added in 8.12.4-0
(is-uncertain-fixed-line-or-mobile? phone-number)(is-uncertain-fixed-line-or-mobile? phone-number region-code)
Returns true if the given number belongs to a class of numbers that cannot be certainly decided as being mobile or fixed-line, false otherwise. Please note that it will return false for mobile or fixed-line numbers that are certainly classified as such.
is-unknown?
added in 8.12.4-0
(is-unknown? phone-number)(is-unknown? phone-number region-specification)
Returns true when type is :phone-number.type/unknown, false otherwise.
is-voicemail?
added in 8.12.4-0
(is-voicemail? phone-number)(is-voicemail? phone-number region-specification)
Returns true when type is :phone-number.type/voicemail, false otherwise.
is-voip?
added in 8.12.4-0
(is-voip? phone-number)(is-voip? phone-number region-specification)
Returns true when type is :phone-number.type/voip, false otherwise.
leniencies
added in 8.12.4-3
A set of all possible phone number leniencies as a set of keywords.
locales
added in 8.12.4-3
A set of all possible phone number locales as a set of keywords.
location
added in 8.12.4-0
(location phone-number)(location phone-number region-code)(location phone-number locale-specification-FQ)(location phone-number region-code locale-specification)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns its possible geographic location as a string or nil if the location happens to be empty.
+
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are analysed. It is also advised to submit a dialing region code when more precise analysis is required.
invalid-example
added in 8.12.4-0
(invalid-example region-code)
For the given region code returns the example phone number that is invalid (being a PhoneNumber kind of object). This is not a random number generator; it will always generate the same example number for the same arguments.
invalid?
added in 8.12.4-0
(invalid? phone-number)(invalid? phone-number region-code)
Returns true if the given phone number (expressed as a string, a number, a map or a PhoneNumber object) is not valid.
is-fixed-line-or-mobile?
added in 8.12.4-0
(is-fixed-line-or-mobile? phone-number)(is-fixed-line-or-mobile? phone-number region-code)
Returns true if the given number is a kind of fixed-line number or a mobile number, false otherwise. Returns true also when there is a chance that a number is either mobile or fixed-line but it cannot be certainly decided.
is-fixed-line?
added in 8.12.4-0
(is-fixed-line? phone-number)(is-fixed-line? phone-number region-specification)
Returns true when type is :phone-number.type/fixed-line, false otherwise.
is-maybe-fixed-line?
added in 8.12.4-0
(is-maybe-fixed-line? phone-number)(is-maybe-fixed-line? phone-number region-code)
Returns true if the given number is a kind of a fixed-line number or a number that belongs to a class where it cannot be fully decided whether it is mobile or fixed-line. Returns false otherwise.
is-maybe-mobile?
added in 8.12.4-0
(is-maybe-mobile? phone-number)(is-maybe-mobile? phone-number region-code)
Returns true if the given number is a kind of a mobile number or a number that belongs to a class where it cannot be fully decided whether it is mobile or fixed-line. Returns false otherwise.
is-maybe-short?
added in 8.12.4-0
is-mobile?
added in 8.12.4-0
(is-mobile? phone-number)(is-mobile? phone-number region-specification)
Returns true when type is :phone-number.type/mobile, false otherwise.
is-personal?
added in 8.12.4-0
(is-personal? phone-number)(is-personal? phone-number region-specification)
Returns true when type is :phone-number.type/personal, false otherwise.
is-premium-rate?
added in 8.12.4-0
(is-premium-rate? phone-number)(is-premium-rate? phone-number region-specification)
Returns true when type is :phone-number.type/premium-rate, false otherwise.
is-shared-cost?
added in 8.12.4-0
(is-shared-cost? phone-number)(is-shared-cost? phone-number region-specification)
Returns true when type is :phone-number.type/shared-cost, false otherwise.
is-short?
added in 8.12.4-0
is-toll-free?
added in 8.12.4-0
(is-toll-free? phone-number)(is-toll-free? phone-number region-specification)
Returns true when type is :phone-number.type/toll-free, false otherwise.
is-uan?
added in 8.12.4-0
(is-uan? phone-number)(is-uan? phone-number region-specification)
Returns true when type is :phone-number.type/uan, false otherwise.
is-uncertain-fixed-line-or-mobile?
added in 8.12.4-0
(is-uncertain-fixed-line-or-mobile? phone-number)(is-uncertain-fixed-line-or-mobile? phone-number region-code)
Returns true if the given number belongs to a class of numbers that cannot be certainly decided as being mobile or fixed-line, false otherwise. Please note that it will return false for mobile or fixed-line numbers that are certainly classified as such.
is-unknown?
added in 8.12.4-0
(is-unknown? phone-number)(is-unknown? phone-number region-specification)
Returns true when type is :phone-number.type/unknown, false otherwise.
is-voicemail?
added in 8.12.4-0
(is-voicemail? phone-number)(is-voicemail? phone-number region-specification)
Returns true when type is :phone-number.type/voicemail, false otherwise.
is-voip?
added in 8.12.4-0
(is-voip? phone-number)(is-voip? phone-number region-specification)
Returns true when type is :phone-number.type/voip, false otherwise.
leniencies
added in 8.12.4-3
A set of all possible phone number leniencies as a set of keywords.
locales
added in 8.12.4-3
A set of all possible phone number locales as a set of keywords.
location
added in 8.12.4-0
(location phone-number)(location phone-number region-code)(location phone-number locale-specification-FQ)(location phone-number region-code locale-specification)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns its possible geographic location as a string or nil if the location happens to be empty.
If the second argument is present then it may be a valid region code (a keyword) to be used when the given phone number does not contain region information. It is acceptable to pass nil as a value to tell the function that there is no explicit region information and it should extract it from a number.
If the third argument is present then it should be a string specifying locale information or a java.util.Locale object. It will be used during rendering strings describing geographic location and carrier data. When nil is passed then the default locale settings will be used.
-
If there are 2 arguments and the second argument is a keyword but IS NOT a fully-qualified, valid locale specification (locale-specification-FQ having namespace set to phone-number.locale) then it will be treated as a region code. Using namespaced keyword for a locale (or using object other than keyword) is required to avoid ambiguity since simple region codes and locale specs can be expressed using the very same keyword names. Optionally (but a bad habit) you may use simple keyword with locale and variant (e.g. :pl_PL) that will not match any region but match locale object.
match
added in 8.12.4-0
(match phone-number-a region-code-a phone-number-b region-code-b)(match phone-number-a region-code-a phone-number-b)(match phone-number-a phone-number-b)
Returns matching level of two numbers or nil if there is no match. Optionally each second argument can be a region code (if the given phone number is not a kind of PhoneNumber and is not prefixed by any calling code ).
match-types
added in 8.12.4-0
A set of all possible phone number match types as a set of keywords.
match?
added in 8.12.4-0
(match? phone-number-a region-code-a phone-number-b region-code-b)(match? phone-number-a region-code-a phone-number-b)(match? phone-number-a phone-number-b)
Returns true if two numbers match, false otherwise. Optionally each second argument can be a region code (if the given phone number is not a kind of PhoneNumber and is not prefixed by any calling code).
native?
added in 8.12.4-0
(native? phone-number _)(native? phone-number)
Returns true if the given argument is an instance of PhoneNumber class.
net-codes
added in 8.12.4-0
A set of all possible global network calling codes.
none
added in 8.12.4-0
A set containing values considered to be none, unknown or empty in the domain of processing phone numbers and codes.
numeric
added in 8.12.4-1
(numeric phone-number)(numeric phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns its regional part as an integer, positive number of type Long.
-
If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
Phoneable
protocol
added in 8.12.4-0
This protocol is used to utilize class-based single dispatch on a phone number abstract.
members
number
added in 8.12.4-0
(number phone-number)(number phone-number region-code)
Takes a phone number represented as a string, a number, a map or a PhoneNumber object and returns parsed PhoneNumber object. Second, optional argument should be a keyword with region code which is helpful if a local number (without region code) was given. If the region code argument is passed and the first argument is already a kind of PhoneNumber then it will be ignored.
+
If there are 2 arguments and the second argument is a keyword but IS NOT a fully-qualified, valid locale specification (locale-specification-FQ having namespace set to phone-number.locale) then it will be treated as a region code. Using namespaced keyword for a locale (or using object other than keyword) is required to avoid ambiguity since simple region codes and locale specs can be expressed using the very same keyword names. Optionally (but a bad habit) you may use simple keyword with locale and variant (e.g. :pl_PL) that will not match any region but match locale object.
match
added in 8.12.4-0
(match phone-number-a region-code-a phone-number-b region-code-b)(match phone-number-a region-code-a phone-number-b)(match phone-number-a phone-number-b)
Returns matching level of two numbers or nil if there is no match. Optionally each second argument can be a region code (if the given phone number is not a kind of PhoneNumber and is not prefixed by any calling code ).
match-types
added in 8.12.4-0
A set of all possible phone number match types as a set of keywords.
match?
added in 8.12.4-0
(match? phone-number-a region-code-a phone-number-b region-code-b)(match? phone-number-a region-code-a phone-number-b)(match? phone-number-a phone-number-b)
Returns true if two numbers match, false otherwise. Optionally each second argument can be a region code (if the given phone number is not a kind of PhoneNumber and is not prefixed by any calling code).
native?
added in 8.12.4-0
(native? phone-number _)(native? phone-number)
Returns true if the given argument is an instance of PhoneNumber class.
net-codes
added in 8.12.4-0
A set of all possible global network calling codes.
none
added in 8.12.4-0
A set containing values considered to be none, unknown or empty in the domain of processing phone numbers and codes.
numeric
added in 8.12.4-1
(numeric phone-number)(numeric phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns its regional part as an integer, positive number of type Long.
+
If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
Phoneable
protocol
added in 8.12.4-0
This protocol is used to utilize class-based single dispatch on a phone number abstract.
members
number
added in 8.12.4-0
(number phone-number)(number phone-number region-code)
Takes a phone number represented as a string, a number, a map or a PhoneNumber object and returns parsed PhoneNumber object. Second, optional argument should be a keyword with region code which is helpful if a local number (without region code) was given. If the region code argument is passed and the first argument is already a kind of PhoneNumber then it will be ignored.
It is important to realize that certain properties of so called short numbers (like an emergency numbers) can only be successfully calculated by other functions if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are in use.
number-noraw
added in 8.12.4-0
(number-noraw phone-number)(number-noraw phone-number region-code)
Like number but does not preserve raw input.
valid?
added in 8.12.4-0
(valid? phone-number)(valid? phone-number region-code)(valid? phone-number region-code dialing-region)
Takes a phone number represented as a string, a number, a map or a PhoneNumber object and validates it. Returns true or false.
When 3 arguments are given the last one should be a source region code for which the test is performed. It only makes sense to use it when the calling code for a number is not the same as the dialing code for the region. If that argument is nil then a value stored in the dynamic variable *default-dialing-region* will be used. If this value is also nil then the function will fall back to checking a number without any dialing region.
One special case is when validating an info map (the result of calling info function). When there will not be dialing region given (or its value will be nil) then this function will try to obtain the source region information from an entry stored under the key :phone-number/dialing-region (or possibly :dialing-region when namespace inference is enabled). It will fetch it only when the key :phone-number.dialing-region/derived? is not holding a truthy value. When this fail then it will default to *default-dialing-region*.
-
This function will NOT make use of *info-dialing-region-derived*, hence the prefix info- (this variable is to control only the info function). If you need a dialing region code to be derived from the region code of a number, please parse a number and supply the result of the region function to valid? as its last argument.
possible?
added in 8.12.4-0
(possible? phone-number)(possible? phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns true if it is a possible number as defined by Libphonenumber. Otherwise it returns false.
-
If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
region
added in 8.12.4-0
(region phone-number)(region phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns its region code as a string or nil if the number is not regional or not given.
-
If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
region-for-calling-code
added in 8.12.16-1
(region-for-calling-code calling-code)
Returns a primary region code (keyword) assigned to the given calling code (integer number). Please be aware that for non-geographical calling codes (like global network calling codes) it will return a set containing :phone-number.region/:world which cannot be later used as a valid region argument in most of the functions.
regions
added in 8.12.4-0
A set of all possible phone number region codes.
regions-for-calling-code
added in 8.12.16-1
(regions-for-calling-code calling-code)
Returns a set of region codes (keywords) assigned to the given calling code (integer number). Please be aware that for non-geographical calling codes (like global network calling codes) it will return a set containing :phone-number.region/:world which cannot be later used as a valid region argument in most of the functions.
short-carrier-specific?
added in 8.12.4-0
(short-carrier-specific? phone-number)(short-carrier-specific? phone-number region-code)(short-carrier-specific? phone-number region-code dialing-region)
Takes a short phone number (expressed as a string, a number, a map or a PhoneNumber object), optional region code (or nil) and optional dialing region code. Returns true if it is a carrier-specific number.
+
This function will NOT make use of *info-dialing-region-derived*, hence the prefix info- (this variable is to control only the info function). If you need a dialing region code to be derived from the region code of a number, please parse a number and supply the result of the region function to valid? as its last argument.
possible?
added in 8.12.4-0
(possible? phone-number)(possible? phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns true if it is a possible number as defined by Libphonenumber. Otherwise it returns false.
+
If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
region
added in 8.12.4-0
(region phone-number)(region phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns its region code as a string or nil if the number is not regional or not given.
+
If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
region-for-calling-code
added in 8.12.16-1
(region-for-calling-code calling-code)
Returns a primary region code (keyword) assigned to the given calling code (integer number). Please be aware that for non-geographical calling codes (like global network calling codes) it will return a set containing :phone-number.region/:world which cannot be later used as a valid region argument in most of the functions.
regions
added in 8.12.4-0
A set of all possible phone number region codes.
regions-for-calling-code
added in 8.12.16-1
(regions-for-calling-code calling-code)
Returns a set of region codes (keywords) assigned to the given calling code (integer number). Please be aware that for non-geographical calling codes (like global network calling codes) it will return a set containing :phone-number.region/:world which cannot be later used as a valid region argument in most of the functions.
short-carrier-specific?
added in 8.12.4-0
(short-carrier-specific? phone-number)(short-carrier-specific? phone-number region-code)(short-carrier-specific? phone-number region-code dialing-region)
Takes a short phone number (expressed as a string, a number, a map or a PhoneNumber object), optional region code (or nil) and optional dialing region code. Returns true if it is a carrier-specific number.
If the default-dialing-region* dynamic variable is set then it will be used as a default dialing region if it is not passed as an argument.
-
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested.
short-cost
added in 8.12.4-0
(short-cost phone-number)(short-cost phone-number region-code)(short-cost phone-number region-code dialing-region)
Takes a short (like an emergency) phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns the expected cost class of that number as a keyword.
+
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested.
short-cost
added in 8.12.4-0
(short-cost phone-number)(short-cost phone-number region-code)(short-cost phone-number region-code dialing-region)
Takes a short (like an emergency) phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns the expected cost class of that number as a keyword.
The second, optional argument should be a valid region code (a keyword) to be used when the given phone number does not contain region information. It is acceptable to pass nil as a value to tell the function that there is no explicit region information and it should extract it from a number.
If the default-dialing-region* dynamic variable is set then it will be used as a default dialing region if it is not passed as an argument.
If the third argument is present then it should be a valid region code for the origination of a possible call. That hint will be used to restrict the check according to rules. For example 112 may be valid in multiple regions but if one calls it from some particular region it might not be reachable. When this argument is missing or its value is nil and the dynamic variable *default-dialing-region* is not nil then its value will be used to set the dialing region. If this argument is missing or is nil and there is no default the binary variant of this function is called (without a source region).
-
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested. It is also advised to submit a dialing region code when more precise checking should be performed.
short-emergency?
added in 8.12.4-0
(short-emergency? phone-number)(short-emergency? phone-number region-code)
Takes a short (like an emergency) phone number (expressed as a string!) and returns true if it is exactly the emergency number. The second argument should be a valid region code (a keyword).
-
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested.
short-info
added in 8.12.4-0
(short-info phone-number)(short-info phone-number region-code)(short-info phone-number region-code dialing-region)
Takes a short (like an emergency) phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns a map containing all possible information about the number with keywords as keys.
+
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested. It is also advised to submit a dialing region code when more precise checking should be performed.
short-emergency?
added in 8.12.4-0
(short-emergency? phone-number)(short-emergency? phone-number region-code)
Takes a short (like an emergency) phone number (expressed as a string!) and returns true if it is exactly the emergency number. The second argument should be a valid region code (a keyword).
+
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested.
short-info
added in 8.12.4-0
(short-info phone-number)(short-info phone-number region-code)(short-info phone-number region-code dialing-region)
Takes a short (like an emergency) phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns a map containing all possible information about the number with keywords as keys.
Required keys:
:phone-number.short/valid?
:phone-number.short/possible?
@@ -133,18 +133,18 @@
If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information. It is acceptable to pass nil as a value to tell the function that there is no explicit region information and it should extract it from a number.
If the third argument is present then it should be a valid region code for the origination of a possible call. That hint will be used to restrict the check according to rules. For example 112 may be valid in multiple regions but if one calls it from some particular region it might not be reachable. When this argument is missing or its value is nil and the dynamic variable *default-dialing-region* is not nil then its value will be used to set the dialing region. If the dynamic variable is also nil (which is the default) then the dynamic variable *info-dialing-region-derived* is checked to be set to truthy value (not nil and not false). If that is true then the dialing region will be derived from a region code of the number.
-
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested. It is also advised to submit a dialing region code when more precise checking is required.
short-invalid?
added in 8.12.4-0
Logical negation of short-valid?
short-possible?
added in 8.12.4-0
(short-possible? phone-number)(short-possible? phone-number region-code)(short-possible? phone-number region-code dialing-region)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns true if it is a possible short number (like emergency etc.) as defined by Libphonenumber. Otherwise it returns false. If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
+
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested. It is also advised to submit a dialing region code when more precise checking is required.
short-invalid?
added in 8.12.4-0
Logical negation of short-valid?
short-possible?
added in 8.12.4-0
(short-possible? phone-number)(short-possible? phone-number region-code)(short-possible? phone-number region-code dialing-region)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns true if it is a possible short number (like emergency etc.) as defined by Libphonenumber. Otherwise it returns false. If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
If the default-dialing-region* dynamic variable is set then it will be used as a default dialing region if it is not passed as an argument.
-
In its ternary form this function takes an additional argument (dialing-region) that should be a valid region code for the origination of a possible call. That hint will be used to restrict the check according to rules. For example 112 may be valid in multiple regions but if one calls it from some particular region it might not be reachable. When this argument is missing or its value is nil and the dynamic variable *default-dialing-region* is not nil then its value will be used to set the dialing region. If this argument is missing or is nil and there is no default the binary variant of this function is called (without a source region).
short-sms-service?
added in 8.12.4-0
(short-sms-service? phone-number)(short-sms-service? phone-number region-code)(short-sms-service? phone-number region-code dialing-region)
Takes a short phone number (expressed as a string, a number, a map or a PhoneNumber object), optional region code (or nil) and a dialing region code (uses *default-dialing-region* if not given). Returns true if SMS is supported, false otherwise.
+
In its ternary form this function takes an additional argument (dialing-region) that should be a valid region code for the origination of a possible call. That hint will be used to restrict the check according to rules. For example 112 may be valid in multiple regions but if one calls it from some particular region it might not be reachable. When this argument is missing or its value is nil and the dynamic variable *default-dialing-region* is not nil then its value will be used to set the dialing region. If this argument is missing or is nil and there is no default the binary variant of this function is called (without a source region).
short-sms-service?
added in 8.12.4-0
(short-sms-service? phone-number)(short-sms-service? phone-number region-code)(short-sms-service? phone-number region-code dialing-region)
Takes a short phone number (expressed as a string, a number, a map or a PhoneNumber object), optional region code (or nil) and a dialing region code (uses *default-dialing-region* if not given). Returns true if SMS is supported, false otherwise.
If the default-dialing-region* dynamic variable is set then it will be used as a default dialing region if it is not passed as an argument.
-
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested.
short-to-emergency?
added in 8.12.4-0
(short-to-emergency? phone-number)(short-to-emergency? phone-number region-code)
Takes a short (like an emergency) phone number (expressed as a string!) and returns true if it can be used to connect to emergency services. The second argument should be a valid region code (a keyword).
-
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested.
short-valid?
added in 8.12.4-0
(short-valid? phone-number)(short-valid? phone-number region-code)(short-valid? phone-number region-code dialing-region)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns true if it is a valid short number (like emergency etc.) as defined by Libphonenumber. Otherwise it returns false. If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
+
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested.
short-to-emergency?
added in 8.12.4-0
(short-to-emergency? phone-number)(short-to-emergency? phone-number region-code)
Takes a short (like an emergency) phone number (expressed as a string!) and returns true if it can be used to connect to emergency services. The second argument should be a valid region code (a keyword).
+
It is important to realize that certain properties of short numbers can only be successfully calculated if the unprocessed form of a number (a string or a natural number) does not contain country code and so it is delivered as it would be dialed. It is advised to pass a region code as the second argument when short numbers are tested.
short-valid?
added in 8.12.4-0
(short-valid? phone-number)(short-valid? phone-number region-code)(short-valid? phone-number region-code dialing-region)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns true if it is a valid short number (like emergency etc.) as defined by Libphonenumber. Otherwise it returns false. If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
If the default-dialing-region* dynamic variable is set then it will be used as a default dialing region if it is not passed as an argument.
-
In its ternary form this function takes an additional argument (dialing-region) that should be a valid region code for the origination of a possible call. That hint will be used to restrict the check according to rules. For example 112 may be valid in multiple regions but if one calls it from some particular region it might not be reachable. When this argument is missing or its value is nil and the dynamic variable *default-dialing-region* is not nil then its value will be used to set the dialing region. If this argument is missing or is nil and there is no default the binary variant of this function is called (without a source region).
time-zones
added in 8.12.4-0
(time-zones phone-number)(time-zones phone-number region-code)(time-zones phone-number format-specification)(time-zones phone-number region-code format-specification)(time-zones phone-number region-code locale-specification)(time-zones phone-number region-code locale-specification format-specification)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns all possible time zones which relate to its geographical location as a lazy sequence of strings (representing zone identifiers in English). Returns nil if the list would be empty.
+
In its ternary form this function takes an additional argument (dialing-region) that should be a valid region code for the origination of a possible call. That hint will be used to restrict the check according to rules. For example 112 may be valid in multiple regions but if one calls it from some particular region it might not be reachable. When this argument is missing or its value is nil and the dynamic variable *default-dialing-region* is not nil then its value will be used to set the dialing region. If this argument is missing or is nil and there is no default the binary variant of this function is called (without a source region).
time-zones
added in 8.12.4-0
(time-zones phone-number)(time-zones phone-number region-code)(time-zones phone-number format-specification)(time-zones phone-number region-code format-specification)(time-zones phone-number region-code locale-specification)(time-zones phone-number region-code locale-specification format-specification)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns all possible time zones which relate to its geographical location as a lazy sequence of strings (representing zone identifiers in English). Returns nil if the list would be empty.
If the second argument is present then it may be a valid region code (a keyword) to be used when the given phone number does not contain region information. It is acceptable to pass nil as a value to tell the function that there is no explicit region information and it should extract it from a number. It may also be a format specifier (also a keyword).
The third argument may be a format specification or a locale specification (both as keywords).
-
If there are 4 arguments then the format specification should be the last and locale specification should be last but one.
type
added in 8.12.4-0
(type phone-number)(type phone-number region-code)
Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns its type as a keyword. For unknown types and number without types it returns :phone-number.type/unknown.
-
If the second argument is present then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.
types
added in 8.12.4-0
A set of all possible phone number types as a set of keywords.
valid-for-region?
added in 8.12.4-0
deprecated in 8.12.4-1
(valid-for-region? phone-number region-code dialing-region)
DEPRECATED: Please use ternary version of the valid? function.
The third argument should be a Locale object or a string describing locale settings to be used when rendering locale-dependent time zone information. When there is no third argument or it is nil then default locale settings will be used.
