1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2008 Google Inc. All rights reserved. 3 // https://developers.google.com/protocol-buffers/ 4 // 5 // Redistribution and use in source and binary forms, with or without 6 // modification, are permitted provided that the following conditions are 7 // met: 8 // 9 // * Redistributions of source code must retain the above copyright 10 // notice, this list of conditions and the following disclaimer. 11 // * Redistributions in binary form must reproduce the above 12 // copyright notice, this list of conditions and the following disclaimer 13 // in the documentation and/or other materials provided with the 14 // distribution. 15 // * Neither the name of Google Inc. nor the names of its 16 // contributors may be used to endorse or promote products derived from 17 // this software without specific prior written permission. 18 // 19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31 #ifndef GOOGLE_PROTOBUF_UTIL_FIELD_MASK_UTIL_H__ 32 #define GOOGLE_PROTOBUF_UTIL_FIELD_MASK_UTIL_H__ 33 34 #include <string> 35 36 #include <google/protobuf/descriptor.h> 37 #include <google/protobuf/field_mask.pb.h> 38 #include <google/protobuf/stubs/stringpiece.h> 39 40 namespace google { 41 namespace protobuf { 42 namespace util { 43 44 class LIBPROTOBUF_EXPORT FieldMaskUtil { 45 typedef google::protobuf::FieldMask FieldMask; 46 47 public: 48 // Converts FieldMask to/from string, formatted by separating each path 49 // with a comma (e.g., "foo_bar,baz.quz"). 50 static string ToString(const FieldMask& mask); 51 static void FromString(StringPiece str, FieldMask* out); 52 53 // Converts FieldMask to/from string, formatted according to proto3 JSON 54 // spec for FieldMask (e.g., "fooBar,baz.quz"). If the field name is not 55 // style conforming (i.e., not snake_case when converted to string, or not 56 // camelCase when converted from string), the conversion will fail. 57 static bool ToJsonString(const FieldMask& mask, string* out); 58 static bool FromJsonString(StringPiece str, FieldMask* out); 59 60 // Checks whether the given path is valid for type T. 61 template <typename T> IsValidPath(StringPiece path)62 static bool IsValidPath(StringPiece path) { 63 return InternalIsValidPath(T::descriptor(), path); 64 } 65 66 // Checks whether the given FieldMask is valid for type T. 67 template <typename T> IsValidFieldMask(const FieldMask & mask)68 static bool IsValidFieldMask(const FieldMask& mask) { 69 for (int i = 0; i < mask.paths_size(); ++i) { 70 if (!InternalIsValidPath(T::descriptor(), mask.paths(i))) return false; 71 } 72 return true; 73 } 74 75 // Adds a path to FieldMask after checking whether the given path is valid. 76 // This method check-fails if the path is not a valid path for type T. 77 template <typename T> AddPathToFieldMask(StringPiece path,FieldMask * mask)78 static void AddPathToFieldMask(StringPiece path, FieldMask* mask) { 79 GOOGLE_CHECK(IsValidPath<T>(path)); 80 mask->add_paths(path); 81 } 82 83 // Creates a FieldMask with all fields of type T. This FieldMask only 84 // contains fields of T but not any sub-message fields. 85 template <typename T> GetFieldMaskForAllFields(FieldMask * out)86 static void GetFieldMaskForAllFields(FieldMask* out) { 87 InternalGetFieldMaskForAllFields(T::descriptor(), out); 88 } 89 90 // Converts a FieldMask to the canonical form. It will: 91 // 1. Remove paths that are covered by another path. For example, 92 // "foo.bar" is covered by "foo" and will be removed if "foo" 93 // is also in the FieldMask. 94 // 2. Sort all paths in alphabetical order. 95 static void ToCanonicalForm(const FieldMask& mask, FieldMask* out); 96 97 // Creates an union of two FieldMasks. 98 static void Union(const FieldMask& mask1, const FieldMask& mask2, 99 FieldMask* out); 100 101 // Creates an intersection of two FieldMasks. 102 static void Intersect(const FieldMask& mask1, const FieldMask& mask2, 103 FieldMask* out); 104 105 // Returns true if path is covered by the given FieldMask. Note that path 106 // "foo.bar" covers all paths like "foo.bar.baz", "foo.bar.quz.x", etc. 107 static bool IsPathInFieldMask(StringPiece path, const FieldMask& mask); 108 109 class MergeOptions; 110 // Merges fields specified in a FieldMask into another message. See the 111 // comments in MergeOptions regarding compatibility with 112 // google/protobuf/field_mask.proto 113 static void MergeMessageTo(const Message& source, const FieldMask& mask, 114 const MergeOptions& options, Message* destination); 115 116 // Removes from 'message' any field that is not represented in the given 117 // FieldMask. If the FieldMask is empty, does nothing. 118 static void TrimMessage(const FieldMask& mask, Message* message); 119 120 private: 121 friend class SnakeCaseCamelCaseTest; 122 // Converts a field name from snake_case to camelCase: 123 // 1. Every character after "_" will be converted to uppercase. 124 // 2. All "_"s are removed. 125 // The conversion will fail if: 126 // 1. The field name contains uppercase letters. 127 // 2. Any character after a "_" is not a lowercase letter. 128 // If the conversion succeeds, it's guaranteed that the resulted 129 // camelCase name will yield the original snake_case name when 130 // converted using CamelCaseToSnakeCase(). 131 // 132 // Note that the input can contain characters not allowed in C identifiers. 133 // For example, "foo_bar,baz_quz" will be converted to "fooBar,bazQuz" 134 // successfully. 135 static bool SnakeCaseToCamelCase(StringPiece input, string* output); 136 // Converts a field name from camelCase to snake_case: 137 // 1. Every uppercase letter is converted to lowercase with a additional 138 // preceding "-". 139 // The conversion will fail if: 140 // 1. The field name contains "_"s. 141 // If the conversion succeeds, it's guaranteed that the resulted 142 // snake_case name will yield the original camelCase name when 143 // converted using SnakeCaseToCamelCase(). 144 // 145 // Note that the input can contain characters not allowed in C identifiers. 146 // For example, "fooBar,bazQuz" will be converted to "foo_bar,baz_quz" 147 // successfully. 148 static bool CamelCaseToSnakeCase(StringPiece input, string* output); 149 150 static bool InternalIsValidPath(const Descriptor* descriptor, 151 StringPiece path); 152 153 static void InternalGetFieldMaskForAllFields(const Descriptor* descriptor, 154 FieldMask* out); 155 }; 156 157 // Note that for compatibility with the defined behaviour for FieldMask in 158 // google/protobuf/field_mask.proto, set replace_message_fields and 159 // replace_repeated_fields to 'true'. The default options are not compatible 160 // with google/protobuf/field_mask.proto. 161 class LIBPROTOBUF_EXPORT FieldMaskUtil::MergeOptions { 162 public: MergeOptions()163 MergeOptions() 164 : replace_message_fields_(false), replace_repeated_fields_(false) {} 165 // When merging message fields, the default behavior is to merge the 166 // content of two message fields together. If you instead want to use 167 // the field from the source message to replace the corresponding field 168 // in the destination message, set this flag to true. When this flag is set, 169 // specified submessage fields that are missing in source will be cleared in 170 // destination. set_replace_message_fields(bool value)171 void set_replace_message_fields(bool value) { 172 replace_message_fields_ = value; 173 } replace_message_fields()174 bool replace_message_fields() const { return replace_message_fields_; } 175 // The default merging behavior will append entries from the source 176 // repeated field to the destination repeated field. If you only want 177 // to keep the entries from the source repeated field, set this flag 178 // to true. set_replace_repeated_fields(bool value)179 void set_replace_repeated_fields(bool value) { 180 replace_repeated_fields_ = value; 181 } replace_repeated_fields()182 bool replace_repeated_fields() const { return replace_repeated_fields_; } 183 184 private: 185 bool replace_message_fields_; 186 bool replace_repeated_fields_; 187 }; 188 189 } // namespace util 190 } // namespace protobuf 191 192 } // namespace google 193 #endif // GOOGLE_PROTOBUF_UTIL_FIELD_MASK_UTIL_H__ 194