src/third_party/libaddressinput/src/cpp/include/libaddressinput/address_validator.h

   1 // Copyright (C) 2014 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 // The public interface to the address validation features of libaddressinput.
  16 // The AddressValidator will examine an AddressData struct and return a map of
  17 // the problems found with the different fields of this struct.
  18
  19 #ifndef I18N_ADDRESSINPUT_ADDRESS_VALIDATOR_H_
  20 #define I18N_ADDRESSINPUT_ADDRESS_VALIDATOR_H_
  21
  22 #include <libaddressinput/address_field.h>
  23 #include <libaddressinput/address_problem.h>
  24 #include <libaddressinput/callback.h>
  25 #include <libaddressinput/util/basictypes.h>
  26
  27 #include <map>
  28
  29 namespace i18n {
  30 namespace addressinput {
  31
  32 class Supplier;
  33 struct AddressData;
  34
  35 typedef std::multimap<AddressField, AddressProblem> FieldProblemMap;
  36
  37 // Validates an AddressData struct. Sample usage:
  38 //    class MyClass {
  39 //     public:
  40 //      MyClass()
  41 //          : supplier_(new MySupplier),
  42 //            validator_(new AddressValidator(supplier_.get())),
  43 //            validated_(BuildCallback(this, &MyClass::Validated)) {}
  44 //
  45 //      virtual ~MyClass() {}
  46 //
  47 //      void ValidateAddress() const {
  48 //        address_.region_code = "US";
  49 //        address_.administrative_area = "CA";
  50 //        validator_.Validate(address_, filter_, &problems_, *validated_);
  51 //      }
  52 //
  53 //      void Validated(bool success,
  54 //                     const AddressData& address,
  55 //                     const FieldProblemMap& problems) {
  56 //        if (success && problems.empty()) {
  57 //          ...
  58 //        }
  59 //      }
  60 //
  61 //     private:
  62 //      AddressData address_;
  63 //      FieldProblemMap filter_;
  64 //      FieldProblemMap problems_;
  65 //      const scoped_ptr<Supplier> supplier_;
  66 //      const scoped_ptr<AddressValidator> validator_;
  67 //      const scoped_ptr<const AddressValidator::Callback> validated_;
  68 //    };
  69 class AddressValidator {
  70  public:
  71   typedef i18n::addressinput::Callback<const AddressData&,
  72                                        const FieldProblemMap&> Callback;
  73
  74   // Does not take ownership of |supplier|.
  75   AddressValidator(Supplier* supplier);
  76
  77   ~AddressValidator();
  78
  79   // Validates the |address| and populates |problems| with the validation
  80   // problems, filtered according to the |filter| parameter.
  81   //
  82   // Set |allow_postal| to allow postal addresses, rather than only addresses
  83   // describing physical locations.
  84   //
  85   // Set |require_name| if recipient should be considered a required field.
  86   //
  87   // If the |filter| is NULL or empty, then all discovered validation problems
  88   // are returned. If the |filter| contains problem elements, then only those
  89   // field-problem pairs present in the |filter| will be returned.
  90   //
  91   // Calls the |validated| callback when validation is done. All objects passed
  92   // as parameters must be kept available until the callback has been called.
  93   //
  94   // The |success| parameter of the callback indicates whether it was possible
  95   // to perform validation. If |success| is true, then |problems| will contain
  96   // information about any problems found with the |address|.
  97   void Validate(const AddressData& address,
  98                 bool allow_postal,
  99                 bool require_name,
 100                 const FieldProblemMap* filter,
 101                 FieldProblemMap* problems,
 102                 const Callback& validated) const;
 103
 104  private:
 105   Supplier* const supplier_;
 106
 107   DISALLOW_COPY_AND_ASSIGN(AddressValidator);
 108 };
 109
 110 }  // namespace addressinput
 111 }  // namespace i18n
 112
 113 #endif  // I18N_ADDRESSINPUT_ADDRESS_VALIDATOR_H_