From 6479eb9a6534bcc6d637b72ce6c04dadafb4bc34 Mon Sep 17 00:00:00 2001 From: Keghani Kouzoujian Date: Wed, 5 Jul 2017 11:31:02 +0200 Subject: [PATCH] Add FAQ for vanity numbers / parsing with non-digit characters (#1834) --- FAQ.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/FAQ.md b/FAQ.md index aa7b00827..a7dff6803 100644 --- a/FAQ.md +++ b/FAQ.md @@ -17,6 +17,40 @@ If you know that your numbers are always in the form <country calling code><national significant number>, it is safe to put a "+" in front to indicate this to the library. +### Why does the library treat some non-digit characters as digits? + +When parsing, the library does its best to extract a phone number out of the +given input string. It looks for the phone number in the provided text; it +doesn't aim to verify whether the string is *only* a phone number. + +If the input looks like a vanity number to the library, `parse()` assumes this +is intentional and converts alpha characters to digits. Please read the +documentation for `PhoneNumber parse(String, String)` in +[PhoneNumberUtil](http://github.com/googlei18n/libphonenumber/blob/master/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java) +for details. Also see `Iterable findNumbers(CharSequence, +String)`. + +Some examples: + +* `+1 412 535 abcd` is parsed the same as `+1 412 535 2223`. + +* If someone fat-fingers and adds an extra alpha character in the *middle*, + then the library assumes this was a mistake and fixes it. E.g. the extra `c` + in `+1 412 535 c0000` is ignored, and this is parsed the same as `+1 412 535 + 0000`. + +* If someone fat-fingers and *replaces* a digit in the middle with an alpha + character, and the remaining characters do not make up a valid number, this + alpha character is not converted and the resulting number is invalid, e.g. + with `+1 412 535 c000`. + +Other examples, in reports: + +* [#328](http://github.com/googlei18n/libphonenumber/issues/328) +* [#1001](http://github.com/googlei18n/libphonenumber/issues/1001) +* [#1199](http://github.com/googlei18n/libphonenumber/issues/1199) +* [#1813](http://github.com/googlei18n/libphonenumber/issues/1813) + ## Validation and types of numbers ### What is the difference between isPossibleNumber and isValidNumber?