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_INLINED_STRING_FIELD_H__
32#define GOOGLE_PROTOBUF_INLINED_STRING_FIELD_H__
33
34#include <string>
35#include <utility>
36
37#include <google/protobuf/stubs/logging.h>
38#include <google/protobuf/stubs/common.h>
39#include <google/protobuf/port.h>
40#include <google/protobuf/stubs/strutil.h>
41#include <google/protobuf/arenastring.h>
42#include <google/protobuf/message_lite.h>
43
44// Must be included last.
45#include <google/protobuf/port_def.inc>
46
47#ifdef SWIG
48#error "You cannot SWIG proto headers"
49#endif
50
51namespace google {
52namespace protobuf {
53
54class Arena;
55
56namespace internal {
57
58// InlinedStringField wraps a std::string instance and exposes an API similar to
59// ArenaStringPtr's wrapping of a std::string* instance.
60//
61// default_value parameters are taken for consistency with ArenaStringPtr, but
62// are not used for most methods. With inlining, these should be removed from
63// the generated binary.
64//
65// InlinedStringField has a donating mechanism that allows string buffer
66// allocated on arena. A string is donated means both the string container and
67// the data buffer are on arena. The donating mechanism here is similar to the
68// one in ArenaStringPtr with some differences:
69//
70// When an InlinedStringField is constructed, the donating state is true. This
71// is because the string container is directly stored in the message on the
72// arena:
73//
74// Construction: donated=true
75// Arena:
76// +-----------------------+
77// |Message foo: |
78// | +-------------------+ |
79// | |InlinedStringField:| |
80// | | +-----+ | |
81// | | | | | | | |
82// | | +-----+ | |
83// | +-------------------+ |
84// +-----------------------+
85//
86// When lvalue Set is called, the donating state is still true. String data will
87// be allocated on the arena:
88//
89// Lvalue Set: donated=true
90// Arena:
91// +-----------------------+
92// |Message foo: |
93// | +-------------------+ |
94// | |InlinedStringField:| |
95// | | +-----+ | |
96// | | | | | | | |
97// | | +|----+ | |
98// | +--|----------------+ |
99// | V |
100// | +----------------+ |
101// | |'f','o','o',... | |
102// | +----------------+ |
103// +-----------------------+
104//
105// Some operations will undonate a donated string, including: Mutable,
106// SetAllocated, Rvalue Set, and Swap with a non-donated string.
107//
108// For more details of the donating states transitions, go/pd-inlined-string.
109class PROTOBUF_EXPORT InlinedStringField {
110 public:
111 InlinedStringField() { Init(); }
112 inline void Init() { new (get_mutable()) std::string(); }
113 // Add the dummy parameter just to make InlinedStringField(nullptr)
114 // unambiguous.
115 constexpr InlinedStringField(
116 const ExplicitlyConstructed<std::string>* /*default_value*/,
117 bool /*dummy*/)
118 : value_{} {}
119 explicit InlinedStringField(const std::string& default_value);
120 explicit InlinedStringField(Arena* arena);
121 ~InlinedStringField() { Destruct(); }
122
123 // Lvalue Set. To save space, we pack the donating states of multiple
124 // InlinedStringFields into an uint32_t `donating_states`. The `mask`
125 // indicates the position of the bit for this InlinedStringField. `donated` is
126 // whether this field is donated.
127 //
128 // The caller should guarantee that:
129 //
130 // `donated == ((donating_states & ~mask) != 0)`
131 //
132 // This method never changes the `donating_states`.
133 void Set(ConstStringParam value, Arena* arena, bool donated,
134 uint32_t* donating_states, uint32_t mask, MessageLite* msg);
135
136 // Rvalue Set. If this field is donated, this method will undonate this field
137 // by mutating the `donating_states` according to `mask`.
138 void Set(std::string&& value, Arena* arena, bool donated,
139 uint32_t* donating_states, uint32_t mask, MessageLite* msg);
140
141 void Set(const char* str, ::google::protobuf::Arena* arena, bool donated,
142 uint32_t* donating_states, uint32_t mask, MessageLite* msg);
143
144 void Set(const char* str, size_t size, ::google::protobuf::Arena* arena, bool donated,
145 uint32_t* donating_states, uint32_t mask, MessageLite* msg);
146
147 template <typename RefWrappedType>
148 void Set(std::reference_wrapper<RefWrappedType> const_string_ref,
149 ::google::protobuf::Arena* arena, bool donated, uint32_t* donating_states,
150 uint32_t mask, MessageLite* msg);
151
152 void SetBytes(ConstStringParam value, Arena* arena, bool donated,
153 uint32_t* donating_states, uint32_t mask, MessageLite* msg);
154
155 void SetBytes(std::string&& value, Arena* arena, bool donated,
156 uint32_t* donating_states, uint32_t mask, MessageLite* msg);
157
158 void SetBytes(const char* str, ::google::protobuf::Arena* arena, bool donated,
159 uint32_t* donating_states, uint32_t mask, MessageLite* msg);
160
161 void SetBytes(const void* p, size_t size, ::google::protobuf::Arena* arena,
162 bool donated, uint32_t* donating_states, uint32_t mask,
163 MessageLite* msg);
164
165 template <typename RefWrappedType>
166 void SetBytes(std::reference_wrapper<RefWrappedType> const_string_ref,
167 ::google::protobuf::Arena* arena, bool donated, uint32_t* donating_states,
168 uint32_t mask, MessageLite* msg);
169
170 PROTOBUF_NDEBUG_INLINE void SetNoArena(StringPiece value);
171 PROTOBUF_NDEBUG_INLINE void SetNoArena(std::string&& value);
172
173 // Basic accessors.
174 PROTOBUF_NDEBUG_INLINE const std::string& Get() const { return GetNoArena(); }
175 PROTOBUF_NDEBUG_INLINE const std::string& GetNoArena() const;
176
177 // Mutable returns a std::string* instance that is heap-allocated. If this
178 // field is donated, this method undonates this field by mutating the
179 // `donating_states` according to `mask`, and copies the content of the
180 // original string to the returning string.
181 std::string* Mutable(Arena* arena, bool donated, uint32_t* donating_states,
182 uint32_t mask, MessageLite* msg);
183 std::string* Mutable(const LazyString& default_value, Arena* arena,
184 bool donated, uint32_t* donating_states, uint32_t mask,
185 MessageLite* msg);
186
187 // Mutable(nullptr_t) is an overload to explicitly support Mutable(nullptr)
188 // calls used by the internal parser logic. This provides API equivalence with
189 // ArenaStringPtr, while still protecting against calls with arena pointers.
190 std::string* Mutable(std::nullptr_t);
191 std::string* MutableNoCopy(std::nullptr_t);
192
193 // Takes a std::string that is heap-allocated, and takes ownership. The
194 // std::string's destructor is registered with the arena. Used to implement
195 // set_allocated_<field> in generated classes.
196 //
197 // If this field is donated, this method undonates this field by mutating the
198 // `donating_states` according to `mask`.
199 void SetAllocated(const std::string* default_value, std::string* value,
200 Arena* arena, bool donated, uint32_t* donating_states,
201 uint32_t mask, MessageLite* msg);
202
203 void SetAllocatedNoArena(const std::string* default_value,
204 std::string* value);
205
206 // Release returns a std::string* instance that is heap-allocated and is not
207 // Own()'d by any arena. If the field is not set, this returns nullptr. The
208 // caller retains ownership. Clears this field back to nullptr state. Used to
209 // implement release_<field>() methods on generated classes.
210 PROTOBUF_NODISCARD std::string* Release(Arena* arena, bool donated);
211 PROTOBUF_NODISCARD std::string* Release();
212
213 // --------------------------------------------------------
214 // Below functions will be removed in subsequent code change
215 // --------------------------------------------------------
216#ifdef DEPRECATED_METHODS_TO_BE_DELETED
217 PROTOBUF_NODISCARD std::string* Release(const std::string*, Arena* arena,
218 bool donated) {
219 return Release(arena, donated);
220 }
221
222 PROTOBUF_NODISCARD std::string* ReleaseNonDefault(const std::string*,
223 Arena* arena) {
224 return Release();
225 }
226
227 std::string* ReleaseNonDefaultNoArena(const std::string* default_value) {
228 return Release();
229 }
230
231 void Set(const std::string*, ConstStringParam value, Arena* arena,
232 bool donated, uint32_t* donating_states, uint32_t mask,
233 MessageLite* msg) {
234 Set(value, arena, donated, donating_states, mask, msg);
235 }
236
237 void Set(const std::string*, std::string&& value, Arena* arena, bool donated,
238 uint32_t* donating_states, uint32_t mask, MessageLite* msg) {
239 Set(std::move(value), arena, donated, donating_states, mask, msg);
240 }
241
242
243 template <typename FirstParam>
244 void Set(FirstParam, const char* str, ::google::protobuf::Arena* arena, bool donated,
245 uint32_t* donating_states, uint32_t mask, MessageLite* msg) {
246 Set(str, arena, donated, donating_states, mask, msg);
247 }
248
249 template <typename FirstParam>
250 void Set(FirstParam p1, const char* str, size_t size, ::google::protobuf::Arena* arena,
251 bool donated, uint32_t* donating_states, uint32_t mask,
252 MessageLite* msg) {
253 Set(str, size, arena, donated, donating_states, mask, msg);
254 }
255
256 template <typename FirstParam, typename RefWrappedType>
257 void Set(FirstParam p1,
258 std::reference_wrapper<RefWrappedType> const_string_ref,
259 ::google::protobuf::Arena* arena, bool donated, uint32_t* donating_states,
260 uint32_t mask, MessageLite* msg) {
261 Set(const_string_ref, arena, donated, donating_states, mask, msg);
262 }
263
264 void SetBytes(const std::string*, ConstStringParam value, Arena* arena,
265 bool donated, uint32_t* donating_states, uint32_t mask,
266 MessageLite* msg) {
267 Set(value, arena, donated, donating_states, mask, msg);
268 }
269
270
271 void SetBytes(const std::string*, std::string&& value, Arena* arena,
272 bool donated, uint32_t* donating_states, uint32_t mask,
273 MessageLite* msg) {
274 Set(std::move(value), arena, donated, donating_states, mask, msg);
275 }
276
277 template <typename FirstParam>
278 void SetBytes(FirstParam p1, const char* str, ::google::protobuf::Arena* arena,
279 bool donated, uint32_t* donating_states, uint32_t mask,
280 MessageLite* msg) {
281 SetBytes(str, arena, donated, donating_states, mask, msg);
282 }
283
284 template <typename FirstParam>
285 void SetBytes(FirstParam p1, const void* p, size_t size,
286 ::google::protobuf::Arena* arena, bool donated, uint32_t* donating_states,
287 uint32_t mask, MessageLite* msg) {
288 SetBytes(p, size, arena, donated, donating_states, mask, msg);
289 }
290
291 template <typename FirstParam, typename RefWrappedType>
292 void SetBytes(FirstParam p1,
293 std::reference_wrapper<RefWrappedType> const_string_ref,
294 ::google::protobuf::Arena* arena, bool donated, uint32_t* donating_states,
295 uint32_t mask, MessageLite* msg) {
296 SetBytes(const_string_ref.get(), arena, donated, donating_states, mask,
297 msg);
298 }
299
300 void SetNoArena(const std::string*, StringPiece value) {
301 SetNoArena(value);
302 }
303 void SetNoArena(const std::string*, std::string&& value) {
304 SetNoArena(std::move(value));
305 }
306
307 std::string* Mutable(ArenaStringPtr::EmptyDefault, Arena* arena, bool donated,
308 uint32_t* donating_states, uint32_t mask,
309 MessageLite* msg) {
310 return Mutable(arena, donated, donating_states, mask, msg);
311 }
312
313 PROTOBUF_NDEBUG_INLINE std::string* MutableNoArenaNoDefault(
314 const std::string* /*default_value*/) {
315 return MutableNoCopy(nullptr);
316 }
317
318#endif // DEPRECATED_METHODS_TO_BE_DELETED
319
320 // Arena-safety semantics: this is guarded by the logic in
321 // Swap()/UnsafeArenaSwap() at the message level, so this method is
322 // 'unsafe' if called directly.
323 inline PROTOBUF_NDEBUG_INLINE static void InternalSwap(
324 InlinedStringField* lhs, Arena* lhs_arena, bool lhs_arena_dtor_registered,
325 MessageLite* lhs_msg, //
326 InlinedStringField* rhs, Arena* rhs_arena, bool rhs_arena_dtor_registered,
327 MessageLite* rhs_msg);
328
329 // Frees storage (if not on an arena).
330 PROTOBUF_NDEBUG_INLINE void Destroy(const std::string* default_value,
331 Arena* arena) {
332 if (arena == nullptr) {
333 DestroyNoArena(default_value);
334 }
335 }
336 PROTOBUF_NDEBUG_INLINE void DestroyNoArena(const std::string* default_value);
337
338 // Clears content, but keeps allocated std::string, to avoid the overhead of
339 // heap operations. After this returns, the content (as seen by the user) will
340 // always be the empty std::string.
341 PROTOBUF_NDEBUG_INLINE void ClearToEmpty() { ClearNonDefaultToEmpty(); }
342 PROTOBUF_NDEBUG_INLINE void ClearNonDefaultToEmpty() {
343 get_mutable()->clear();
344 }
345
346 // Clears content, but keeps allocated std::string if arena != nullptr, to
347 // avoid the overhead of heap operations. After this returns, the content (as
348 // seen by the user) will always be equal to |default_value|.
349 void ClearToDefault(const LazyString& default_value, Arena* arena,
350 bool donated);
351
352 // Generated code / reflection only! Returns a mutable pointer to the string.
353 PROTOBUF_NDEBUG_INLINE std::string* UnsafeMutablePointer();
354
355 // InlinedStringField doesn't have things like the `default_value` pointer in
356 // ArenaStringPtr.
357 static constexpr bool IsDefault() { return false; }
358 static constexpr bool IsDefault(const std::string*) { return false; }
359
360 private:
361 void Destruct() { get_mutable()->~basic_string(); }
362
363 PROTOBUF_NDEBUG_INLINE std::string* get_mutable();
364 PROTOBUF_NDEBUG_INLINE const std::string* get_const() const;
365
366 alignas(std::string) char value_[sizeof(std::string)];
367
368 std::string* MutableSlow(::google::protobuf::Arena* arena, bool donated,
369 uint32_t* donating_states, uint32_t mask,
370 MessageLite* msg);
371
372
373 // When constructed in an Arena, we want our destructor to be skipped.
374 friend class ::google::protobuf::Arena;
375 typedef void InternalArenaConstructable_;
376 typedef void DestructorSkippable_;
377};
378
379inline std::string* InlinedStringField::get_mutable() {
380 return reinterpret_cast<std::string*>(&value_);
381}
382
383inline const std::string* InlinedStringField::get_const() const {
384 return reinterpret_cast<const std::string*>(&value_);
385}
386
387inline InlinedStringField::InlinedStringField(
388 const std::string& default_value) {
389 new (get_mutable()) std::string(default_value);
390}
391
392
393inline InlinedStringField::InlinedStringField(Arena* /*arena*/) { Init(); }
394
395inline const std::string& InlinedStringField::GetNoArena() const {
396 return *get_const();
397}
398
399inline void InlinedStringField::SetAllocatedNoArena(
400 const std::string* /*default_value*/, std::string* value) {
401 if (value == nullptr) {
402 // Currently, inlined string field can't have non empty default.
403 get_mutable()->clear();
404 } else {
405 get_mutable()->assign(str: std::move(*value));
406 delete value;
407 }
408}
409
410inline void InlinedStringField::DestroyNoArena(const std::string*) {
411 // This is invoked from the generated message's ArenaDtor, which is used to
412 // clean up objects not allocated on the Arena.
413 this->~InlinedStringField();
414}
415
416inline void InlinedStringField::SetNoArena(StringPiece value) {
417 get_mutable()->assign(s: value.data(), n: value.length());
418}
419
420inline void InlinedStringField::SetNoArena(std::string&& value) {
421 get_mutable()->assign(str: std::move(value));
422}
423
424// Caller should make sure rhs_arena allocated rhs, and lhs_arena allocated lhs.
425inline PROTOBUF_NDEBUG_INLINE void InlinedStringField::InternalSwap(
426 InlinedStringField* lhs, Arena* lhs_arena, bool lhs_arena_dtor_registered,
427 MessageLite* lhs_msg, //
428 InlinedStringField* rhs, Arena* rhs_arena, bool rhs_arena_dtor_registered,
429 MessageLite* rhs_msg) {
430#if GOOGLE_PROTOBUF_INTERNAL_DONATE_STEAL_INLINE
431 lhs->get_mutable()->swap(*rhs->get_mutable());
432 if (!lhs_arena_dtor_registered && rhs_arena_dtor_registered) {
433 lhs_msg->OnDemandRegisterArenaDtor(lhs_arena);
434 } else if (lhs_arena_dtor_registered && !rhs_arena_dtor_registered) {
435 rhs_msg->OnDemandRegisterArenaDtor(rhs_arena);
436 }
437#else
438 (void)lhs_arena;
439 (void)rhs_arena;
440 (void)lhs_arena_dtor_registered;
441 (void)rhs_arena_dtor_registered;
442 (void)lhs_msg;
443 (void)rhs_msg;
444 lhs->get_mutable()->swap(s&: *rhs->get_mutable());
445#endif
446}
447
448inline void InlinedStringField::Set(ConstStringParam value, Arena* arena,
449 bool donated, uint32_t* /*donating_states*/,
450 uint32_t /*mask*/, MessageLite* /*msg*/) {
451 (void)arena;
452 (void)donated;
453 SetNoArena(value);
454}
455
456inline void InlinedStringField::Set(const char* str, ::google::protobuf::Arena* arena,
457 bool donated, uint32_t* donating_states,
458 uint32_t mask, MessageLite* msg) {
459 Set(value: ConstStringParam(str), arena, donated, donating_states, mask, msg);
460}
461
462inline void InlinedStringField::Set(const char* str, size_t size,
463 ::google::protobuf::Arena* arena, bool donated,
464 uint32_t* donating_states, uint32_t mask,
465 MessageLite* msg) {
466 Set(value: ConstStringParam{str, size}, arena, donated, donating_states, mask, msg);
467}
468
469inline void InlinedStringField::SetBytes(ConstStringParam value, Arena* arena,
470 bool donated,
471 uint32_t* donating_states,
472 uint32_t mask, MessageLite* msg) {
473 Set(value, arena, donated, donating_states, mask, msg);
474}
475
476inline void InlinedStringField::SetBytes(std::string&& value, Arena* arena,
477 bool donated,
478 uint32_t* donating_states,
479 uint32_t mask, MessageLite* msg) {
480 Set(value: std::move(value), arena, donated, donating_states, mask, msg);
481}
482
483inline void InlinedStringField::SetBytes(const char* str,
484 ::google::protobuf::Arena* arena, bool donated,
485 uint32_t* donating_states,
486 uint32_t mask, MessageLite* msg) {
487 Set(str, arena, donated, donating_states, mask, msg);
488}
489
490inline void InlinedStringField::SetBytes(const void* p, size_t size,
491 ::google::protobuf::Arena* arena, bool donated,
492 uint32_t* donating_states,
493 uint32_t mask, MessageLite* msg) {
494 Set(str: static_cast<const char*>(p), size, arena, donated, donating_states, mask,
495 msg);
496}
497
498template <typename RefWrappedType>
499inline void InlinedStringField::Set(
500 std::reference_wrapper<RefWrappedType> const_string_ref,
501 ::google::protobuf::Arena* arena, bool donated, uint32_t* donating_states,
502 uint32_t mask, MessageLite* msg) {
503 Set(const_string_ref.get(), arena, donated, donating_states, mask, msg);
504}
505
506template <typename RefWrappedType>
507inline void InlinedStringField::SetBytes(
508 std::reference_wrapper<RefWrappedType> const_string_ref,
509 ::google::protobuf::Arena* arena, bool donated, uint32_t* donating_states,
510 uint32_t mask, MessageLite* msg) {
511 Set(const_string_ref.get(), arena, donated, donating_states, mask, msg);
512}
513
514inline std::string* InlinedStringField::UnsafeMutablePointer() {
515 return get_mutable();
516}
517
518inline std::string* InlinedStringField::Mutable(std::nullptr_t) {
519 return get_mutable();
520}
521
522inline std::string* InlinedStringField::MutableNoCopy(std::nullptr_t) {
523 return get_mutable();
524}
525
526} // namespace internal
527} // namespace protobuf
528} // namespace google
529
530#include <google/protobuf/port_undef.inc>
531
532#endif // GOOGLE_PROTOBUF_INLINED_STRING_FIELD_H__
533