cpp/src/phonenumbers/geocoding/phonenumber_offline_geocoder.h

   1 // Copyright (C) 2012 The Libphonenumber Authors
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 // http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14 //
  15 // Author: Patrick Mezard
  16
  17 #ifndef I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_
  18 #define I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_
  19
  20 #include <map>
  21 #include <string>
  22
  23 #include <unicode/locid.h>  // NOLINT(build/include_order)
  24
  25 #include "phonenumbers/base/basictypes.h"
  26 #include "phonenumbers/base/memory/scoped_ptr.h"
  27
  28 namespace i18n {
  29 namespace phonenumbers {
  30
  31 using std::map;
  32 using std::string;
  33
  34 class AreaCodeMap;
  35 class MappingFileProvider;
  36 class PhoneNumber;
  37 class PhoneNumberUtil;
  38 struct CountryLanguages;
  39 struct PrefixDescriptions;
  40 typedef icu::Locale Locale;
  41
  42 // An offline geocoder which provides geographical information related to a
  43 // phone number.
  44 class PhoneNumberOfflineGeocoder {
  45  private:
  46   typedef map<string, const AreaCodeMap*> AreaCodeMaps;
  47
  48  public:
  49   typedef const CountryLanguages* (*country_languages_getter)(int index);
  50   typedef const PrefixDescriptions* (*prefix_descriptions_getter)(int index);
  51
  52   PhoneNumberOfflineGeocoder();
  53
  54   // For tests
  55   PhoneNumberOfflineGeocoder(
  56       const int* country_calling_codes,
  57       int country_calling_codes_size,
  58       country_languages_getter get_country_languages,
  59       const char** prefix_language_code_pairs,
  60       int prefix_language_code_pairs_size,
  61       prefix_descriptions_getter get_prefix_descriptions);
  62
  63   virtual ~PhoneNumberOfflineGeocoder();
  64
  65   // Returns a text description for the given phone number, in the language
  66   // provided. The description might consist of the name of the country where
  67   // the phone number is from, or the name of the geographical area the phone
  68   // number is from if more detailed information is available.
  69   //
  70   // This method assumes the validity of the number passed in has already been
  71   // checked.
  72   string GetDescriptionForValidNumber(const PhoneNumber& number,
  73                                       const Locale& language) const;
  74
  75   // As per GetDescriptionForValidNumber(PhoneNumber, Locale) but also considers
  76   // the region of the user. If the phone number is from the same region as the
  77   // user, only a lower-level description will be returned, if one exists.
  78   // Otherwise, the phone number's region will be returned, with optionally some
  79   // more detailed information.
  80   //
  81   // For example, for a user from the region "US" (United States), we would show
  82   // "Mountain View, CA" for a particular number, omitting the United States
  83   // from the description. For a user from the United Kingdom (region "GB"), for
  84   // the same number we may show "Mountain View, CA, United States" or even just
  85   // "United States".
  86   //
  87   // This method assumes the validity of the number passed in has already been
  88   // checked.
  89   //
  90   // user_region is the region code for a given user. This region will be
  91   // omitted from the description if the phone number comes from this region. It
  92   // is a two-letter uppercase ISO country code as defined by ISO 3166-1.
  93   string GetDescriptionForValidNumber(const PhoneNumber& number,
  94       const Locale& language, const string& user_region) const;
  95
  96   // As per GetDescriptionForValidNumber(PhoneNumber, Locale) but explicitly
  97   // checks the validity of the number passed in.
  98   string GetDescriptionForNumber(const PhoneNumber& number,
  99                                  const Locale& locale) const;
 100
 101   // As per GetDescriptionForValidNumber(PhoneNumber, Locale, String) but
 102   // explicitly checks the validity of the number passed in.
 103   string GetDescriptionForNumber(const PhoneNumber& number,
 104       const Locale& language, const string& user_region) const;
 105
 106  private:
 107   void Init(const int* country_calling_codes,
 108             int country_calling_codes_size,
 109             country_languages_getter get_country_languages,
 110             const char** prefix_language_code_pairs,
 111             int prefix_language_code_pairs_size,
 112             prefix_descriptions_getter get_prefix_descriptions);
 113
 114   const AreaCodeMap* GetPhonePrefixDescriptions(int prefix,
 115       const string& language, const string& script, const string& region) const;
 116
 117   AreaCodeMaps::const_iterator LoadAreaCodeMapFromFile(
 118       const string& filename) const;
 119
 120   // Returns the customary display name in the given language for the given
 121   // region.
 122   string GetRegionDisplayName(const string* region_code,
 123                               const Locale& language) const;
 124
 125   // Returns the customary display name in the given language for the given
 126   // territory the phone number is from.
 127   string GetCountryNameForNumber(const PhoneNumber& number,
 128                                  const Locale& language) const;
 129
 130   // Returns an area-level text description in the given language for the given
 131   // phone number, or an empty string.
 132   // lang is a two-letter lowercase ISO language codes as defined by ISO 639-1.
 133   // script is a four-letter titlecase (the first letter is uppercase and the
 134   // rest of the letters are lowercase) ISO script codes as defined in ISO
 135   // 15924.
 136   // region is a two-letter uppercase ISO country codes as defined by ISO
 137   // 3166-1.
 138   const char* GetAreaDescription(const PhoneNumber& number, const string& lang,
 139                                  const string& script,
 140                                  const string& region) const;
 141
 142   bool MayFallBackToEnglish(const string& lang) const;
 143
 144  private:
 145   const PhoneNumberUtil* phone_util_;
 146   // The MappingFileProvider knows for which combination of country calling code
 147   // and language a phone prefix mapping file is available in the file system,
 148   // so that a file can be loaded when needed.
 149   scoped_ptr<const MappingFileProvider> provider_;
 150
 151   const char** prefix_language_code_pairs_;
 152   int prefix_language_code_pairs_size_;
 153   prefix_descriptions_getter get_prefix_descriptions_;
 154
 155   // A mapping from country calling codes languages pairs to the corresponding
 156   // phone prefix map that has been loaded.
 157   mutable AreaCodeMaps available_maps_;
 158
 159   DISALLOW_COPY_AND_ASSIGN(PhoneNumberOfflineGeocoder);
 160 };
 161
 162 }  // namespace phonenumbers
 163 }  // namespace i18n
 164
 165 #endif /* I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_ */