phone-number.core — io.randomseed/phone-number 8.12.52-0

Clojure interface to Libphonenumber.

*default-dialing-region* clj

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* clj

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* clj

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* clj

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.

all-formats clj

(all-formats phone-number)

(all-formats phone-number region-code)

Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns a map which keys are all possible formats expressed as keywords and values are string representations of the number formatted accordingly.

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.

allowed-input-characters clj

A set of allowed characters in a phone number which is a string (applied to all characters except the first 3 on a string cleaned up from removable characters).

allowed-removable-characters clj

A set of removable (like punctuation) characters in a phone number which is a string. Used during input validation.

calling-code clj

(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 clj

(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 clj

A set of all possible country calling codes.

calling-codes-for-region clj

(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 clj

(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 clj

A set of all possible phone number cost classes as a set of keywords.

country-codes clj

A set of all possible country calling codes.

example clj

(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 clj

(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 clj

(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 substring
• :phone-number.match/raw-string - phone number substring
• :phone-number/number - phone number object
• :phone-number/info - optional info object (lazily evaluated)

Phone number object is suitable to be used with majority of functions from the core. It is a mutable Java object so be careful!

Optional but highly recommended region-code argument should be a region code to be used as a hint when looking for numbers without any calling code prefix.

The leniency argument sets the matching leniency level during searching. Possible levels are:

• :phone-number.leniency/exact – accepts valid phone numbers that are formatted in a standard way (or as a single block)

• :phone-number.leniency/possible – accepts possible phone numbers (including invalid ones)

• :phone-number.leniency/strict –accepts valid phone numbers that are possible for the locale (and its formatting rules)

• :phone-number.leniency/valid – accepts possible AND valid phone numbers (this is default)

If it's nil then it will be set to a default (:phone-number.leniency/valid).

The max-tries argument tells the searching engine to deliver only certain number of matches. If it's not given then the maximum value of type Long will be used.

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

format clj

(format phone-number)

(format phone-number region-code)

(format phone-number format-specification)

(format phone-number region-code format-specification)

Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns it as a formatted string. The last argument should be a format expressed as a keyword (use the all-formats function to list them) or a PhoneNumberType.

If the second argument is present (and there are 3 arguments) then it should be a valid region code (a keyword) to be used when the given phone number does not contain region information.

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.

formats clj

A set of all possible phone number formats as a set of keywords.

generate clj

(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)
• :phone-number.sample/hits - a number of valid hits encountered during sampling
• :phone-number.sample/digits - a vector with used calling code prefix, template part and random part
• :phone-number.sample/max-samples - a maximum number of samples declared
• :phone-number.sample/samples - a number of samples processed before the result was formed
• :phone-number.sample/random-seed – random seed used to initialize pseudo-random generator

It is important to note that the result may be valid or invalid phone number. To get only valid number pass the valid? predicate function as the third argument (described later).

Without any arguments it generates any geographical number of any possible region and type.

When the first argument is present it should be a valid region code and the result will be a number that belongs to that region. It is possible to pass nil as a value (in order to make use of other positional arguments). In such case the region will be picked up randomly.

When the second argument is present it should be a valid number type and the result will be a number that is of that type. It is possible to pass nil as a value (in order to make use of other positional arguments). In such case the type will be picked up randomly.

When the third argument is present it should be a predicate function used by samples generator to look for a number for which the function returns truthy value (not false and not nil). It is possible to pass nil as a value to disable this check.

When the fourth argument is present it should be a maximal number of attempts the internal sampler will perform to get the desired sample. By default it will try to get the sample that meets the criteria (country code, type and a custom predicate) in 1000 attempts but when the supplied predicate makes it too improbable to get the desired result the operation may fail and this number should be increased. It is possible to pass nil as a value. In such case the default will be used. It is also possible to pass false as a value. In such case the sampler will continue indefinitely which poses the risk of freezing the program for complicated or impossible conditions.

It is important to know that even relatively low retry counts will produce valid results in most cases. This is due to randomization strategy the internal sampler uses. It starts by taking an initial, template number returned by the example function. This number is valid but may not fulfill additional criteria. If it fulfills them it is memorized and the next, more fuzzed variant is tried with last digit replaced by a randomly generated one. If such number is also valid it is memorized and the randomization continues until all digits (except the country code plus the static part described later) are randomized. When that happens the result is returned if it fulfills all of the validation criteria or the number of retries reaches the given maximal value. If the final result (after all the trials) is not valid then the memorized number is returned.

The fifth argument, when present, should be a minimal number of digits in regional part of the number that are accepted as a result. If it is not given the default of 3 is assumed.

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? clj

(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? clj

(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? clj

(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? clj

(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-raw-input? clj

(has-raw-input? phone-number)

(has-raw-input? phone-number region-code)

Checks whether raw input string can be obtained from the given phone number.

has-region? clj

(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? clj

(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? clj

(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 clj

(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?
:phone-number/possible?
:phone-number/valid?
:phone-number/type
:phone-number.short/valid?
:phone-number.short/possible?

Optional keys:

:phone-number/region
:phone-number/location
:phone-number/carrier
:phone-number/dialing-region
:phone-number.dialing-region/derived?
:phone-number.dialing-region/defaulted?
:phone-number.dialing-region/valid-for?
:phone-number.format/e164
:phone-number.format/international
:phone-number.format/national
:phone-number.format/rfc3966
:phone-number.format/raw-input
:phone-number.tz-format/narrow-global
:phone-number.tz-format/full
:phone-number.tz-format/short
:phone-number.tz-format/narrow
:phone-number.tz-format/full-global
:phone-number.tz-format/short-global
:phone-number.tz-format/id
:phone-number.short/carrier-specific?
:phone-number.short/cost
:phone-number.short/emergency?
:phone-number.short/sms-service?
:phone-number.short/to-emergency?

Keys with nil values assigned will be removed from the map unless the dynamic variable *info-removed-nils* is bound to false.

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 second argument is a locale specification (locale-specification-FQ) then it should be a fully-qualified keyword using phone-number.locale namespace (or an object that is not a keyword) in order to distinguish it from a region code (which is favored as this argument). 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.

If the third argument is present then it may be a string specifying locale information or a Locale object. It will be used during rendering strings describing geographic location, carrier data and full time zone information. When nil is passed then default locale settings will be used.

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 clj

(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? clj

(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? clj

(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? clj

(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? clj

(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? clj

(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? clj

Same as short-possible?

is-mobile? clj

(is-mobile? phone-number)

(is-mobile? phone-number region-specification)

Returns true when type is :phone-number.type/mobile, false otherwise.

is-pager? clj

(is-pager? phone-number)

(is-pager? phone-number region-specification)

Returns true when type is :phone-number.type/pager, false otherwise.

is-personal? clj

(is-personal? phone-number)

(is-personal? phone-number region-specification)

Returns true when type is :phone-number.type/personal, false otherwise.

is-premium-rate? clj

(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? clj

(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? clj

Same as short-valid?

is-toll-free? clj

(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? clj

(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? clj

(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? clj

(is-unknown? phone-number)

(is-unknown? phone-number region-specification)

Returns true when type is :phone-number.type/unknown, false otherwise.

is-voicemail? clj

(is-voicemail? phone-number)

(is-voicemail? phone-number region-specification)

Returns true when type is :phone-number.type/voicemail, false otherwise.

is-voip? clj

(is-voip? phone-number)

(is-voip? phone-number region-specification)

Returns true when type is :phone-number.type/voip, false otherwise.

leniencies clj

A set of all possible phone number leniencies as a set of keywords.

locales clj

A set of all possible phone number locales as a set of keywords.

location clj

(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 clj

(match phone-number-a phone-number-b)

(match phone-number-a region-code-a phone-number-b)

(match phone-number-a region-code-a phone-number-b region-code-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 clj

A set of all possible phone number match types as a set of keywords.

match? clj

(match? phone-number-a phone-number-b)

(match? phone-number-a region-code-a phone-number-b)

(match? phone-number-a region-code-a phone-number-b region-code-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? clj

(native? phone-number)

(native? phone-number _)

Returns true if the given argument is an instance of PhoneNumber class.

net-codes clj

A set of all possible global network calling codes.

none clj

A set containing values considered to be none, unknown or empty in the domain of processing phone numbers and codes.

numeric clj

(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 clj protocol

This protocol is used to utilize class-based single dispatch on a phone number abstract.

number clj

(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 clj

(number-noraw phone-number)

(number-noraw phone-number region-code)

Like number but does not preserve raw input.

raw-input clj

(raw-input phone-number)

(raw-input phone-number region-code)

Returns a string used to initialize phone number object with the number function. For strings and numbers it short-circuits on the given argument and ignores any given region code. Returns a string representation. For nil values it returns nil.

valid-input? clj

(valid-input? phone-number)

Takes a phone number represented as a string, a number, a map or a PhoneNumber object and returns true if it is a valid input to be parsed (must be not empty and not nil and have some minimal number of digits). Otherwise it returns false.

valid? clj

(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? clj

(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 clj

(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 clj

(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 clj

A set of all possible phone number region codes.

regions-for-calling-code clj

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

required-first-input-characters clj

A set of required first characters in a phone number which is a string.

short-carrier-specific? clj

(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 clj

(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? clj

(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 clj

(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?

Optional keys:

 :phone-number.short/carrier-specific?
 :phone-number.short/cost
 :phone-number.short/emergency?
 :phone-number.short/sms-service?
 :phone-number.short/to-emergency?
 :phone-number/dialing-region
 :phone-number.dialing-region/derived?
 :phone-number.dialing-region/defaulted?

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? clj

Logical negation of short-valid?

short-possible? clj

(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? clj

(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? clj

(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? clj

(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 clj

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

time-zones-all-formats clj

(time-zones-all-formats phone-number)

(time-zones-all-formats phone-number region-code)

(time-zones-all-formats phone-number locale-specification-FQ)

(time-zones-all-formats phone-number region-code locale-specification)

Takes a phone number (expressed as a string, a number, a map or a PhoneNumber object) and returns a map which keys are all possible time zone formats expressed as keywords and values are sequences of the number's time zones formatted accordingly. If the given number is nil, invalid or time zone information is unavailable for it this function returns nil.

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 possible to pass a nil value as this argument to ignore extra processing when region can be inferred from the number.

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.

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.

type clj

(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 clj

A set of all possible phone number types as a set of keywords.

tz-formats clj

A set of all possible time zone formats as a set of keywords.

valid-for-region? clj deprecated

(valid-for-region? phone-number region-code dialing-region)

DEPRECATED: Please use ternary version of the valid? function.

when-some-input clj macro

(when-some-input phone-num & body)