[rac] Add AddressValidator API.

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

Index: third_party/libaddressinput/chromium/cpp/include/libaddressinput/address_validator.h
diff --git a/third_party/libaddressinput/chromium/cpp/include/libaddressinput/address_validator.h b/third_party/libaddressinput/chromium/cpp/include/libaddressinput/address_validator.h
new file mode 100644
index 0000000000000000000000000000000000000000..d1c92c31bf6c22312ea804010149b6adcaa64a69
--- /dev/null
+++ b/third_party/libaddressinput/chromium/cpp/include/libaddressinput/address_validator.h
@@ -0,0 +1,124 @@
+// Copyright (C) 2013 Google Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef I18N_ADDRESSINPUT_ADDRESS_VALIDATOR_H_
+#define I18N_ADDRESSINPUT_ADDRESS_VALIDATOR_H_
+
+#include <libaddressinput/address_field.h>
+#include <libaddressinput/address_problem.h>
+#include <libaddressinput/util/basictypes.h>
+#include <libaddressinput/util/scoped_ptr.h>
+
+#include <map>
+#include <string>
+#include <vector>
+
+namespace i18n {
+namespace addressinput {
+
+class Downloader;
+class LoadRulesDelegate;
+class RuleRetriever;
+class Storage;
+struct AddressData;
+
+typedef std::vector<AddressProblem> AddressProblems;
+typedef std::multimap<AddressField, AddressProblem::Type> AddressProblemFilter;
+
+// Validates an AddressData structure. Sample usage:
+//    class MyClass : public LoadRulesDelegate {
+//     public:
+//      MyClass() : validator_(new MyDownloader, new MyStorage, this) {
+//        validator_.LoadRules("US");
+//      }
+//
+//      virtual ~MyClass() {}
+//
+//      virtual void OnAddressValidationRulesLoaded(
+//          const std::string& country_code,
+//          bool success) {
+//        ...
+//      }
+//
+//      void ValidateAddress() {
+//        AddressData address;
+//        address.country_code = "US";
+//        address.administrative_area = "CA";
+//        AddressProblems problems;
+//        AddressProblemFilter filter;
+//        AddressValidator::Result result =
+//            validator_.ValidateAddress(address, filter, &problems);
+//        if (result == AddressValidator::SUCCESS) {
+//          Process(problems);
+//        }
+//      }
+//
+//     private:
+//      AddressValidator validator_;
+//    };
+class AddressValidator {
+ public:
+  // The status of address validation.
+  enum Result {

[roubert, 2013/12/11 17:38:26]

Maybe a different name, eg. Status, might help highlight the fact that this
isn't actually the validation result; an invalid address would have
ValidateAddress() return SUCCESS if it was successful in determining that the
address was invalid.

+    // Address validation completed successfully. Check |problems| to see if any
+    // problems were found.
+    SUCCESS,
+
+    // The validation rules are not available, because LoadRules() was not
+    // called or failed. Reload the rules.
+    RULES_UNAVAILABLE,
+
+    // The validation rules are being loaded. Try again later.
+    RULES_NOT_READY
+  };
+
+  // Takes ownership of |downloader| and |storage|, which cannot be NULL. Does
+  // not take ownership of |load_rules_delegate|, which can be NULL.
+  AddressValidator(const Downloader* downloader,
+                   Storage* storage,
+                   LoadRulesDelegate* load_rules_delegate);
+  ~AddressValidator();
+
+  // Loads the generic validation rules for |country_code| and specific rules

[roubert, 2013/12/11 17:38:26]

Is this for pre-loading data for countries that are anticipated to be used? It
would be good if you here could comment on when and why anyone would want to
call this method.

+  // for the country's administrative areas, localities, and dependent
+  // localities. A typical data size is 10KB. The largest is 250KB. If a country

[lararennie, 2013/12/11 08:25:37]

The largest is "currently" 250KB....

Maybe point them at the data so they can always go and see themselves if they
are interested...

+  // has language-specific validation rules, then these are also loaded.
+  //
+  // If the rules were loaded successfully before, then does nothing. Notifies
+  // |load_rules_delegate| when the load finishes.

[roubert, 2013/12/11 17:38:26]

"the load" -> "the loading"?

+  void LoadRules(const std::string& country_code);
+
+  // Validates the |address| and populates |problems| with the validation
+  // problems, filtered according to the |filter| parameter.
+  //
+  // If the |filter| is empty, then all discovered validation problems are
+  // returned. If the |filter| contains problem elements, then only the problems
+  // in the |filter| may be returned.
+  //
+  // If the |problems| parameter is NULL, then checks whether the validation

[roubert, 2013/12/11 17:38:26]

This seems like a strange API to me. Would it not be more straightforward to
here require problems to be non-NULL and then provide a separate method to check
whether validation rules are available? (When do you envision that a user of
this library would want to check that?)

+  // rules are available, but does not validate the |address|.
+  Result ValidateAddress(const AddressData& address,
+                         const AddressProblemFilter& filter,
+                         AddressProblems* problems) const;
+ private:
+  scoped_ptr<RuleRetriever> rule_retriever_;
+  LoadRulesDelegate* load_rules_delegate_;
+
+  DISALLOW_COPY_AND_ASSIGN(AddressValidator);
+};
+
+}  // namespace addressinput
+}  // namespace i18n
+
+#endif  // I18N_ADDRESSINPUT_ADDRESS_VALIDATOR_H_