third_party/protobuf: Update to HEAD (83d681ee2c)

third_party/protobuf/src/google/protobuf/util/field_mask_util.h

 // Protocol Buffers - Google's data interchange format
 // Copyright 2008 Google Inc.  All rights reserved.
 // https://developers.google.com/protocol-buffers/
 //
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are
 // met:
 //
 //     * Redistributions of source code must retain the above copyright
 // notice, this list of conditions and the following disclaimer.
@@ skipping 10 matching lines @@
 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+// Defines utilities for the FieldMask well known type.
+
 #ifndef GOOGLE_PROTOBUF_UTIL_FIELD_MASK_UTIL_H__
 #define GOOGLE_PROTOBUF_UTIL_FIELD_MASK_UTIL_H__
 
 #include <string>
 
 #include <google/protobuf/descriptor.h>
 #include <google/protobuf/field_mask.pb.h>
 #include <google/protobuf/stubs/stringpiece.h>
 
 namespace google {
@@ skipping 59 matching lines @@
 
   // Creates an intersection of two FieldMasks.
   static void Intersect(const FieldMask& mask1, const FieldMask& mask2,
                         FieldMask* out);
 
   // Returns true if path is covered by the given FieldMask. Note that path
   // "foo.bar" covers all paths like "foo.bar.baz", "foo.bar.quz.x", etc.
   static bool IsPathInFieldMask(StringPiece path, const FieldMask& mask);
 
   class MergeOptions;
-  // Merges fields specified in a FieldMask into another message.
+  // Merges fields specified in a FieldMask into another message. See the
+  // comments in MergeOptions regarding compatibility with
+  // google/protobuf/field_mask.proto
   static void MergeMessageTo(const Message& source, const FieldMask& mask,
                              const MergeOptions& options, Message* destination);
 
+  // Removes from 'message' any field that is not represented in the given
+  // FieldMask. If the FieldMask is empty, does nothing.
+  static void TrimMessage(const FieldMask& mask, Message* message);
+
  private:
   friend class SnakeCaseCamelCaseTest;
   // Converts a field name from snake_case to camelCase:
   //   1. Every character after "_" will be converted to uppercase.
   //   2. All "_"s are removed.
   // The conversion will fail if:
   //   1. The field name contains uppercase letters.
   //   2. Any character after a "_" is not a lowercase letter.
   // If the conversion succeeds, it's guaranteed that the resulted
   // camelCase name will yield the original snake_case name when
@@ skipping 17 matching lines @@
   // successfully.
   static bool CamelCaseToSnakeCase(StringPiece input, string* output);
 
   static bool InternalIsValidPath(const Descriptor* descriptor,
                                   StringPiece path);
 
   static void InternalGetFieldMaskForAllFields(const Descriptor* descriptor,
                                                FieldMask* out);
 };
 
+// Note that for compatibility with the defined behaviour for FieldMask in
+// google/protobuf/field_mask.proto, set replace_message_fields and
+// replace_repeated_fields to 'true'. The default options are not compatible
+// with google/protobuf/field_mask.proto.
 class LIBPROTOBUF_EXPORT FieldMaskUtil::MergeOptions {
  public:
   MergeOptions()
       : replace_message_fields_(false), replace_repeated_fields_(false) {}
   // When merging message fields, the default behavior is to merge the
   // content of two message fields together. If you instead want to use
   // the field from the source message to replace the corresponding field
   // in the destination message, set this flag to true. When this flag is set,
   // specified submessage fields that are missing in source will be cleared in
   // destination.
@@ skipping 13 matching lines @@
  private:
   bool replace_message_fields_;
   bool replace_repeated_fields_;
 };
 
 }  // namespace util
 }  // namespace protobuf
 
 }  // namespace google
 #endif  // GOOGLE_PROTOBUF_UTIL_FIELD_MASK_UTIL_H__