view release on metacpan or  search on metacpan

lib/Number/Phone.pm  view on Meta::CPAN

above.

The superclass implementation returns undef, indicating that you don't
know whether the number has been ported.

=item type

Return a listref of all the is_... methods above which are true.  Note that
this method should only be implemented in the super-class.  eg, for the
number +44 20 87712924 this might return
C<[qw(valid allocated geographic)]>.

=item format

Return a sanely formatted E.123-compliant version of the number, complete with
IDD code, eg for the UK number (0208) 771-2924 it would return +44 20 8771
2924.

The superclass implementation returns undef, which is nonsense, so you
should always implement this.

=item format_using

If you want something different from E.123, then pass this the name of a
L<formatter|Number::Phone::Formatters> to use.

For example, if you want to get "just the digits, ma'am", use the
L<Raw|Number::Phone::Formatter::Raw> formatter thus:

  Number::Phone->new('+44 20 8771 2924')->format_using('Raw');

which will return:

  2087712924

It is a fatal error to specify a non-existent formatter.

=item format_for_country

Given a country code (either two-letter ISO or numeric prefix), return the
number formatted either nationally-formatted, if the number is in the same
country, or as a nationally-preferred international number if not. Internally
this uses the National and NationallyPreferredIntl formatters. Beware of the
potential performance hit!

=item canonical_number

If this is a number which is a part of a national number plan which maps to
another country then this will return an object representing the number that it
is mapped to. Otherwise you just get your object back.

This is similar to, and more useful than, C<translates_to>, which will either
return an object for the canonical number or C<undef> if the number is already
canonical.

=item country

The two letter ISO country code for the country in which the call will
terminate.  This is implemented in the superclass and you will only have
to implement your own version for countries where part of the number
range is overlayed with another country.

Exception: for the UK, return 'uk', not 'gb'.

Specifically, the superclass implementation looks at the class name and
returns the last two-letter code it finds.  eg ...

  from Number::Phone::UK, it would return UK
  from Number::Phone::UK::IM, it would return IM
  from Number::Phone::NANP::US, it would return US
  from Number::Phone::FR::Full, it would return FR

=item raw_number

Returns all the digits of a number, except any leading country code or national
dialling prefix. Exactly equivalent to the area code (if such a thing exists)
and the subscriber number, concatenated together.

=item translates_to

B<DEPRECATED>

If the number forwards to another number (such as a special rate number
forwarding to a geographic number), or is part of a chunk of number-space
mapped onto another chunk of number-space (such as where a country has a
shortcut to (part of) another country's number-space, like how Northern Ireland
appears as an area code in the Irish republic's numbering plan as well as being
canonically an area code in the UK's numbering plan, then this method may
return an object representing the target number.  Otherwise it returns undef.

The superclass implementation returns undef, and it was never implemented for
any of the country-specific subclasses bundled with Number::Phone. You are
encouraged to not implement this in subclasses, and users should use
C<canonical_number> instead.

=back

=head2 DATA SOURCES

=over

=item data_source

Class method, return some hopefully useful text about the source of the data
(if any) that drives a country-specific module. The implementation in the base
class returns undef as the base class itself has no data source.

=item libphonenumber_tag

Class method which you should not over-ride, implemented in the base class.
Returns the version of libphonenumber whose metadata was used for this release
of Number::Phone. NB that this is derived from their most recent git tag, so
may occasionally be a little ahead of the most recent libphonenumber release as
the tag gets created before their release is built.

The current version of this is also documented in L<Number::Phone::Data>.

=back

=head2 HOW TO DIAL FROM ONE NUMBER TO ANOTHER