src/third_party/libaddressinput/src/cpp/src/rule.h

   1 // Copyright (C) 2013 Google Inc.
   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 // An object to store address metadata, describing the addressing rules for
  16 // regions and sub-regions. The address metadata format is documented here:
  17 //
  18 // https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata
  19
  20 #ifndef I18N_ADDRESSINPUT_RULE_H_
  21 #define I18N_ADDRESSINPUT_RULE_H_
  22
  23 #include <libaddressinput/address_field.h>
  24 #include <libaddressinput/util/basictypes.h>
  25 #include <libaddressinput/util/scoped_ptr.h>
  26
  27 #include <string>
  28 #include <vector>
  29
  30 namespace i18n {
  31 namespace addressinput {
  32
  33 class FormatElement;
  34 class Json;
  35 struct RE2ptr;
  36
  37 // Stores address metadata addressing rules, to be used for determining the
  38 // layout of an address input widget or for address validation. Sample usage:
  39 //    Rule rule;
  40 //    if (rule.ParseSerializedRule("{\"fmt\": \"%A%n%C%S %Z\"}")) {
  41 //      Process(rule.GetFormat());
  42 //    }
  43 class Rule {
  44  public:
  45   Rule();
  46   ~Rule();
  47
  48   // Returns the default rule at a country level. If a country does not specify
  49   // address format, for example, then the format from this rule should be used
  50   // instead.
  51   static const Rule& GetDefault();
  52
  53   // Copies all data from |rule|.
  54   void CopyFrom(const Rule& rule);
  55
  56   // Parses |serialized_rule|. Returns |true| if the |serialized_rule| has valid
  57   // format (JSON dictionary).
  58   bool ParseSerializedRule(const std::string& serialized_rule);
  59
  60   // Reads data from |json|, which must already have parsed a serialized rule.
  61   void ParseJsonRule(const Json& json);
  62
  63   // Returns the ID string for this rule.
  64   const std::string& GetId() const { return id_; }
  65
  66   // Returns the format elements for this rule. The format can include the
  67   // relevant address fields, but also strings used for formatting, or newline
  68   // information.
  69   const std::vector<FormatElement>& GetFormat() const { return format_; }
  70
  71   // Returns the approximate address format with the Latin order of fields. The
  72   // format can include the relevant address fields, but also strings used for
  73   // formatting, or newline information.
  74   const std::vector<FormatElement>& GetLatinFormat() const {
  75     return latin_format_;
  76   }
  77
  78   // Returns the required fields for this rule.
  79   const std::vector<AddressField>& GetRequired() const { return required_; }
  80
  81   // Returns the sub-keys for this rule, which are the administrative areas of a
  82   // country, the localities of an administrative area, or the dependent
  83   // localities of a locality. For example, the rules for "US" have sub-keys of
  84   // "CA", "NY", "TX", etc.
  85   const std::vector<std::string>& GetSubKeys() const { return sub_keys_; }
  86
  87   // Returns all of the language tags supported by this rule, for example ["de",
  88   // "fr", "it"].
  89   const std::vector<std::string>& GetLanguages() const { return languages_; }
  90
  91   // Returns a pointer to a RE2 regular expression object created from the
  92   // postal code format string, if specified, or NULL otherwise. The regular
  93   // expression is anchored to the beginning of the string so that it can be
  94   // used either with RE2::PartialMatch() to perform prefix matching or else
  95   // with RE2::FullMatch() to perform matching against the entire string.
  96   const RE2ptr* GetPostalCodeMatcher() const {
  97     return postal_code_matcher_.get();
  98   }
  99
 100   // Returns the sole postal code for this rule, if there is one.
 101   const std::string& GetSolePostalCode() const { return sole_postal_code_; }
 102
 103   // The message string identifier for admin area name. If not set, then
 104   // INVALID_MESSAGE_ID.
 105   int GetAdminAreaNameMessageId() const { return admin_area_name_message_id_; }
 106
 107   // The message string identifier for postal code name. If not set, then
 108   // INVALID_MESSAGE_ID.
 109   int GetPostalCodeNameMessageId() const {
 110     return postal_code_name_message_id_;
 111   }
 112
 113   // The message string identifier for locality name. If not set, then
 114   // INVALID_MESSAGE_ID.
 115   int GetLocalityNameMessageId() const {
 116     return locality_name_message_id_;
 117   }
 118
 119   // The message string identifier for sublocality name. If not set, then
 120   // INVALID_MESSAGE_ID.
 121   int GetSublocalityNameMessageId() const {
 122     return sublocality_name_message_id_;
 123   }
 124
 125   // Returns the name for the most specific place described by this rule, if
 126   // there is one. This is typically set when it differs from the key.
 127   const std::string& GetName() const { return name_; }
 128
 129   // Returns the Latin-script name for the most specific place described by this
 130   // rule, if there is one.
 131   const std::string& GetLatinName() const { return latin_name_; }
 132
 133   // Returns the postal code example string for this rule.
 134   const std::string& GetPostalCodeExample() const {
 135     return postal_code_example_;
 136   }
 137
 138   // Returns the post service URL string for this rule.
 139   const std::string& GetPostServiceUrl() const { return post_service_url_; }
 140
 141  private:
 142   std::string id_;
 143   std::vector<FormatElement> format_;
 144   std::vector<FormatElement> latin_format_;
 145   std::vector<AddressField> required_;
 146   std::vector<std::string> sub_keys_;
 147   std::vector<std::string> languages_;
 148   scoped_ptr<const RE2ptr> postal_code_matcher_;
 149   std::string sole_postal_code_;
 150   int admin_area_name_message_id_;
 151   int postal_code_name_message_id_;
 152   int locality_name_message_id_;
 153   int sublocality_name_message_id_;
 154   std::string name_;
 155   std::string latin_name_;
 156   std::string postal_code_example_;
 157   std::string post_service_url_;
 158
 159   DISALLOW_COPY_AND_ASSIGN(Rule);
 160 };
 161
 162 }  // namespace addressinput
 163 }  // namespace i18n
 164
 165 #endif  // I18N_ADDRESSINPUT_RULE_H_