[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..4e6d9ad0f371d2a0b3f13e499c361f769d1d72a9
--- /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 LoadRulesObserver;
+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 : LoadRulesObserver {
+//     public:
+//      explicit MyClass()
+//          : validator_(new MyDownloader, new MyStorage) {
+//        validator_->PreloadRules("US", this);

[Evan Stade, 2013/12/10 23:59:43]

nit: this is out of date?

[please use gerrit instead, 2013/12/11 00:56:45]

Yes, I've updated the comment now.

+//      }
+//
+//      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 == AddressVerifier::SUCCESS) {
+//          Process(problems);
+//        }
+//      }
+//
+//     private:
+//      AddressValidator validator_;
+//    };
+struct AddressValidator {

[Evan Stade, 2013/12/10 23:59:43]

class

[please use gerrit instead, 2013/12/11 00:56:45]

Done.

+ public:
+  // The status of address validation.

[Evan Stade, 2013/12/10 23:59:43]

what would be the status if you haven't called LoadRules yet?

[please use gerrit instead, 2013/12/11 00:56:45]

We should assert(false) if we haven't called LoadRules() yet. That's a
programmer mistake.

[Evan Stade, 2013/12/11 01:21:49]

uhhhh, I suppose that's one solution. But there's also the case where you've
called LoadRules, just not for the correct country (i.e. the country in the
address in ValidateAddress). Client can be careful to avoid letting this happen,
but I can also half-imagine scenarios where it's extra work to make sure this
doesn't happen. Crashing seems like a harsh penalty. Can we return
RULES_UNAVAILABLE in that case? The distinction between "load failed" and "load
not tried" could be left up to the client to track based on LoadRulesObserver
calls.

+  enum Result {
+    // Address validation completed successfully. Check |problems| to see if any
+    // problems were found.
+    SUCCESS,
+
+    // Failed to load the validation rules. The user of the library may choose
+    // to reload the rules.
+    LOAD_RULES_FAIL,

[Evan Stade, 2013/12/10 23:59:43]

nit: RULES_UNAVAILABLE

[please use gerrit instead, 2013/12/11 00:56:45]

Done.

+
+    // The validation rules are being loaded. The user of the library should try
+    // again later.
+    LOADING_RULES

[Evan Stade, 2013/12/10 23:59:43]

nit: RULES_NOT_READY

[please use gerrit instead, 2013/12/11 00:56:45]

Done.

+  };
+
+  // Takes ownership of |downloader| and |storage|.
+  AddressValidator(const Downloader* downloader, Storage* storage);
+  ~AddressValidator();
+
+  // Downloads the generic validation rules for |country_code| and specific
+  // rules for the country's administrative areas, localities, and dependent
+  // localities.
+  //
+  // Notifies |observer| when finished. Does not take ownership of |observer|.
+  //
+  // If |force| is true, then reloads rules that are already loaded. Otherwise,
+  // loads the rules only once, even for multiple invocations of the method.
+  //
+  // A typical download size is 10KB. The largest is 250KB.
+  void LoadRules(const std::string& country_code,
+                 bool force,

[Evan Stade, 2013/12/10 23:59:43]

hmmm, I can't remember why this was necessary in our previous design discussion.
We don't need/want to reload rules if they successfully loaded already, right?
Only if they didn't successfully load. Leave this out for now IMO, we can add it
back if we decide we need it. Make LoadRules do nothing if you already have
rules for the country, and retry to download them if you don't have them or
loading previously failed.

[please use gerrit instead, 2013/12/11 00:56:45]

Done.

+                 LoadRulesObserver* observer);

[Evan Stade, 2013/12/10 23:59:43]

I would make the observer

a) a delegate (0-1 exist)
b) passed in the constructor
c) not required

[please use gerrit instead, 2013/12/11 00:56:45]

Done.

+
+  // Verifies 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.
+  Result ValidateAddress(const AddressData& address,
+                         const AddressProblemFilter& filter,
+                         AddressProblems* problems) const;
+ private:
+  scoped_ptr<RuleRetriever> rule_retriever_;
+
+  DISALLOW_COPY_AND_ASSIGN(AddressValidator);
+};
+
+}  // namespace addressinput
+}  // namespace i18n
+
+#endif  // I18N_ADDRESSINPUT_ADDRESS_VALIDATOR_H_