.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Number::Phone::Country 3pm" .TH Number::Phone::Country 3pm "2018-12-16" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Number::Phone::Country \- Lookup country of phone number .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Number::Phone::Country; \& \& #returns \*(AqCA\*(Aq for Canada \& my $iso_country_code = phone2country("1 (604) 111\-1111"); .Ve .PP or .PP .Vb 1 \& use Number::Phone::Country qw(noexport uk); \& \& my $iso_country_code = Number::Phone::Country::phone2country(...); .Ve .PP or .PP .Vb 1 \& my ($iso_country_code, $idd) = Number::Phone::Country::phone2country_and_idd(...); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module looks up up the country based on a telephone number. It uses the International Direct Dialing (\s-1IDD\s0) prefix, and lookups North American numbers using the Area Code, in accordance with the North America Numbering Plan (\s-1NANP\s0). It can also, given a country, tell you the country code, and the prefixes you need to dial when in that country to call outside your local area or to call another country. .PP Note that by default, phone2country is exported into your namespace. This is deprecated and may be removed in a future version. You can turn that off by passing the 'noexport' constant when you use the module. .PP Also be aware that the \s-1ISO\s0 code for the United Kingdom is \s-1GB,\s0 not \s-1UK.\s0 If you would prefer \s-1UK,\s0 pass the 'uk' constant. .PP I have put in number ranges for Kosovo, which does not yet have an \s-1ISO\s0 country code. I have used \s-1XK,\s0 as that is the de facto standard as used by numerous international bodies such as the European Commission and the \s-1IMF.\s0 I previously used \s-1KOS,\s0 as used by the \s-1UN\s0 Development Programme. This may change again in the future. .SH "FUNCTIONS" .IX Header "FUNCTIONS" The following functions are available: .IP "country_code($country)" 4 .IX Item "country_code($country)" Returns the international dialing prefix for this country \- eg, for the \s-1UK\s0 it returns 44, and for Canada it returns 1. .IP "idd_code($country)" 4 .IX Item "idd_code($country)" Returns one, of possibly multiple, International Direct Dialing prefixes for the given \s-1ISO\s0 Alpha\-2 country code. Returns nothing if the country code is not recognised or not supported. .Sp The \s-1IDD\s0 prefix is needed to make a call \fBfrom a country\fR to another country. For example, when calling the \s-1UK\s0 from the \s-1US,\s0 the caller must first dial the \&\s-1IDD\s0 prefix 011 to setup an international call, followed by the country calling code for the \s-1UK\s0 (44), followed by the \s-1UK\s0 national number. .Sp Many telephone systems allow the caller to dial a plus sign prefix (+) in place of the \s-1IDD,\s0 in which case the system replaces the plus sign with the correct \s-1IDD\s0 prefix for the caller's country. .Sp Some countries have more than one \s-1IDD\s0 code, allowing the caller to route their calls through specific networks. \f(CW\*(C`idd_code\*(C'\fR only returns one code. See \&\f(CW\*(C`idd_regex\*(C'\fR if you need to match a number against known \s-1IDD\s0 prefixes for a given country. .IP "idd_regex($country)" 4 .IX Item "idd_regex($country)" Returns a regular expression that matches against known International Direct Dialing prefixes for the given \s-1ISO\s0 Alpha\-2 country code. Returns nothing if the country code is not recognised or not supported. .Sp As an example, the regular expression for Australia (\s-1AU\s0) will match a number of \&\s-1IDD\s0 prefixes, including 0011, 0014, and 0015, making it possible to determine that 001516502530000 could be a \s-1US\s0 number being dialled from Australia. .Sp Be aware that some numbers will match against \s-1IDD\s0 prefixes from multiple countries. Other numbers will be valid national numbers for one country, and valid international numbers when called for other countries. For example, \&\f(CW01143662111\fR is a valid national number for Sheffield, England. It could also be a valid number in Austria: .Sp Calling from within the \s-1UK:\s0 .Sp .Vb 4 \& Area code: 0114 \& Subscriber: 366 2111 \& National: 0114 366 2111 \& International: +441143662111 .Ve .Sp Calling from a country that uses the \s-1NANP\s0 (North American Numbering Plan): .Sp .Vb 6 \& IDD: 011 \& Country code: 43 (Austria) \& Area code: 0662 (Salzburg) \& Subscriber: 111 \& National: 0662 111 \& International: +43662111 .Ve .IP "ndd_code($country)" 4 .IX Item "ndd_code($country)" Returns the National Direct Dialing prefix for the given country. This is the prefix used to make a call \fBwithin a country\fR from one city to another. This prefix may not be necessary when calling another city in the same vicinity. This is followed by the city or area code for the place you are calling. For example, in the \s-1US,\s0 the \s-1NDD\s0 prefix is \*(L"1\*(R", so you must dial 1 before the area code to place a long distance call within the country. .IP "phone2country($phone)" 4 .IX Item "phone2country($phone)" Returns the \s-1ISO\s0 country code (or \s-1XK\s0 for Kosovo) for a phone number. eg, for +441234567890 it returns '\s-1GB\s0' (or '\s-1UK\s0' if you've told it to). .IP "phone2country_and_idd($phone)" 4 .IX Item "phone2country_and_idd($phone)" Returns a list containing the \s-1ISO\s0 country code and \s-1IDD\s0 prefix for the given phone number. eg for +441234567890 it returns ('\s-1GB\s0', 44). .SH "SEE ALSO" .IX Header "SEE ALSO" Parse::PhoneNumber .SH "BUGS" .IX Header "BUGS" It has not been possible to maintain complete backwards compatibility with the original 0.01 release. To fix a bug, while still retaining the ability to look up plain un-adorned \s-1NANP\s0 numbers without the +1 prefix, all non-NANP numbers *must* have their leading + sign. .PP Another incompatibility \- it was previously assumed that any number not assigned to some other country was in the \s-1US.\s0 This was incorrect for (eg) 800 numbers. These are now identified as being generic \s-1NANP\s0 numbers. .PP Will go out of date every time the \s-1NANP\s0 has one of its code splits/overlays. So that's about once a month then. I'll do my best to keep it up to date. .SH "WARNING" .IX Header "WARNING" The Yugoslavs keep changing their minds about what country they want to be and what their \s-1ISO 3166\s0 code and \s-1IDD\s0 prefix should be. \s-1YU\s0? \s-1CS\s0? \s-1RS\s0? \s-1ME\s0? God knows. And then there's Kosovo ... .SH "AUTHOR" .IX Header "AUTHOR" now maintained by David Cantrell .PP originally by \s-1TJ\s0 Mather, .PP country/IDD/NDD contributions by Michael Schout, .PP Thanks to Shraga Bor-Sood for the updates in version 1.4. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2003 by MaxMind \s-1LLC\s0 .PP Copyright 2004 \- 2011 David Cantrell .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.