2 * Copyright 2014 Google Inc. All rights reserved.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef FLATBUFFERS_H_
18 #define FLATBUFFERS_H_
20 #include "flatbuffers/base.h"
22 #if defined(FLATBUFFERS_NAN_DEFAULTS)
26 namespace flatbuffers {
27 // Generic 'operator==' with conditional specialisations.
28 // T e - new value of a scalar field.
29 // T def - default of scalar (is known at compile-time).
30 template<typename T> inline bool IsTheSameAs(T e, T def) { return e == def; }
32 #if defined(FLATBUFFERS_NAN_DEFAULTS) && \
33 defined(FLATBUFFERS_HAS_NEW_STRTOD) && (FLATBUFFERS_HAS_NEW_STRTOD > 0)
34 // Like `operator==(e, def)` with weak NaN if T=(float|double).
35 template<typename T> inline bool IsFloatTheSameAs(T e, T def) {
36 return (e == def) || ((def != def) && (e != e));
38 template<> inline bool IsTheSameAs<float>(float e, float def) {
39 return IsFloatTheSameAs(e, def);
41 template<> inline bool IsTheSameAs<double>(double e, double def) {
42 return IsFloatTheSameAs(e, def);
46 // Wrapper for uoffset_t to allow safe template specialization.
47 // Value is allowed to be 0 to indicate a null object (see e.g. AddOffset).
48 template<typename T> struct Offset {
51 Offset(uoffset_t _o) : o(_o) {}
52 Offset<void> Union() const { return Offset<void>(o); }
53 bool IsNull() const { return !o; }
56 inline void EndianCheck() {
58 // If this fails, see FLATBUFFERS_LITTLEENDIAN above.
59 FLATBUFFERS_ASSERT(*reinterpret_cast<char *>(&endiantest) ==
60 FLATBUFFERS_LITTLEENDIAN);
64 template<typename T> FLATBUFFERS_CONSTEXPR size_t AlignOf() {
70 return __alignof__(T);
78 // When we read serialized data from memory, in the case of most scalars,
79 // we want to just read T, but in the case of Offset, we want to actually
80 // perform the indirection and return a pointer.
81 // The template specialization below does just that.
82 // It is wrapped in a struct since function templates can't overload on the
83 // return type like this.
84 // The typedef is for the convenience of callers of this function
85 // (avoiding the need for a trailing return decltype)
86 template<typename T> struct IndirectHelper {
87 typedef T return_type;
88 typedef T mutable_return_type;
89 static const size_t element_stride = sizeof(T);
90 static return_type Read(const uint8_t *p, uoffset_t i) {
91 return EndianScalar((reinterpret_cast<const T *>(p))[i]);
94 template<typename T> struct IndirectHelper<Offset<T>> {
95 typedef const T *return_type;
96 typedef T *mutable_return_type;
97 static const size_t element_stride = sizeof(uoffset_t);
98 static return_type Read(const uint8_t *p, uoffset_t i) {
99 p += i * sizeof(uoffset_t);
100 return reinterpret_cast<return_type>(p + ReadScalar<uoffset_t>(p));
103 template<typename T> struct IndirectHelper<const T *> {
104 typedef const T *return_type;
105 typedef T *mutable_return_type;
106 static const size_t element_stride = sizeof(T);
107 static return_type Read(const uint8_t *p, uoffset_t i) {
108 return reinterpret_cast<const T *>(p + i * sizeof(T));
112 // An STL compatible iterator implementation for Vector below, effectively
113 // calling Get() for every element.
114 template<typename T, typename IT> struct VectorIterator {
115 typedef std::random_access_iterator_tag iterator_category;
116 typedef IT value_type;
117 typedef ptrdiff_t difference_type;
119 typedef IT &reference;
121 VectorIterator(const uint8_t *data, uoffset_t i)
122 : data_(data + IndirectHelper<T>::element_stride * i) {}
123 VectorIterator(const VectorIterator &other) : data_(other.data_) {}
124 VectorIterator() : data_(nullptr) {}
126 VectorIterator &operator=(const VectorIterator &other) {
132 #if !defined(FLATBUFFERS_CPP98_STL)
133 VectorIterator &operator=(VectorIterator &&other) {
137 #endif // !defined(FLATBUFFERS_CPP98_STL)
140 bool operator==(const VectorIterator &other) const {
141 return data_ == other.data_;
144 bool operator<(const VectorIterator &other) const {
145 return data_ < other.data_;
148 bool operator!=(const VectorIterator &other) const {
149 return data_ != other.data_;
152 difference_type operator-(const VectorIterator &other) const {
153 return (data_ - other.data_) / IndirectHelper<T>::element_stride;
156 IT operator*() const { return IndirectHelper<T>::Read(data_, 0); }
158 IT operator->() const { return IndirectHelper<T>::Read(data_, 0); }
160 VectorIterator &operator++() {
161 data_ += IndirectHelper<T>::element_stride;
165 VectorIterator operator++(int) {
166 VectorIterator temp(data_, 0);
167 data_ += IndirectHelper<T>::element_stride;
171 VectorIterator operator+(const uoffset_t &offset) const {
172 return VectorIterator(data_ + offset * IndirectHelper<T>::element_stride,
176 VectorIterator &operator+=(const uoffset_t &offset) {
177 data_ += offset * IndirectHelper<T>::element_stride;
181 VectorIterator &operator--() {
182 data_ -= IndirectHelper<T>::element_stride;
186 VectorIterator operator--(int) {
187 VectorIterator temp(data_, 0);
188 data_ -= IndirectHelper<T>::element_stride;
192 VectorIterator operator-(const uoffset_t &offset) const {
193 return VectorIterator(data_ - offset * IndirectHelper<T>::element_stride,
197 VectorIterator &operator-=(const uoffset_t &offset) {
198 data_ -= offset * IndirectHelper<T>::element_stride;
203 const uint8_t *data_;
206 template<typename Iterator> struct VectorReverseIterator :
207 public std::reverse_iterator<Iterator> {
209 explicit VectorReverseIterator(Iterator iter) :
210 std::reverse_iterator<Iterator>(iter) {}
212 typename Iterator::value_type operator*() const {
213 return *(std::reverse_iterator<Iterator>::current);
216 typename Iterator::value_type operator->() const {
217 return *(std::reverse_iterator<Iterator>::current);
223 // This is used as a helper type for accessing vectors.
224 // Vector::data() assumes the vector elements start after the length field.
225 template<typename T> class Vector {
227 typedef VectorIterator<T, typename IndirectHelper<T>::mutable_return_type>
229 typedef VectorIterator<T, typename IndirectHelper<T>::return_type>
231 typedef VectorReverseIterator<iterator> reverse_iterator;
232 typedef VectorReverseIterator<const_iterator> const_reverse_iterator;
234 uoffset_t size() const { return EndianScalar(length_); }
236 // Deprecated: use size(). Here for backwards compatibility.
237 FLATBUFFERS_ATTRIBUTE(deprecated("use size() instead"))
238 uoffset_t Length() const { return size(); }
240 typedef typename IndirectHelper<T>::return_type return_type;
241 typedef typename IndirectHelper<T>::mutable_return_type mutable_return_type;
243 return_type Get(uoffset_t i) const {
244 FLATBUFFERS_ASSERT(i < size());
245 return IndirectHelper<T>::Read(Data(), i);
248 return_type operator[](uoffset_t i) const { return Get(i); }
250 // If this is a Vector of enums, T will be its storage type, not the enum
251 // type. This function makes it convenient to retrieve value with enum
253 template<typename E> E GetEnum(uoffset_t i) const {
254 return static_cast<E>(Get(i));
257 // If this a vector of unions, this does the cast for you. There's no check
258 // to make sure this is the right type!
259 template<typename U> const U *GetAs(uoffset_t i) const {
260 return reinterpret_cast<const U *>(Get(i));
263 // If this a vector of unions, this does the cast for you. There's no check
264 // to make sure this is actually a string!
265 const String *GetAsString(uoffset_t i) const {
266 return reinterpret_cast<const String *>(Get(i));
269 const void *GetStructFromOffset(size_t o) const {
270 return reinterpret_cast<const void *>(Data() + o);
273 iterator begin() { return iterator(Data(), 0); }
274 const_iterator begin() const { return const_iterator(Data(), 0); }
276 iterator end() { return iterator(Data(), size()); }
277 const_iterator end() const { return const_iterator(Data(), size()); }
279 reverse_iterator rbegin() { return reverse_iterator(end() - 1); }
280 const_reverse_iterator rbegin() const { return const_reverse_iterator(end() - 1); }
282 reverse_iterator rend() { return reverse_iterator(begin() - 1); }
283 const_reverse_iterator rend() const { return const_reverse_iterator(begin() - 1); }
285 const_iterator cbegin() const { return begin(); }
287 const_iterator cend() const { return end(); }
289 const_reverse_iterator crbegin() const { return rbegin(); }
291 const_reverse_iterator crend() const { return rend(); }
293 // Change elements if you have a non-const pointer to this object.
294 // Scalars only. See reflection.h, and the documentation.
295 void Mutate(uoffset_t i, const T &val) {
296 FLATBUFFERS_ASSERT(i < size());
297 WriteScalar(data() + i, val);
300 // Change an element of a vector of tables (or strings).
301 // "val" points to the new table/string, as you can obtain from
302 // e.g. reflection::AddFlatBuffer().
303 void MutateOffset(uoffset_t i, const uint8_t *val) {
304 FLATBUFFERS_ASSERT(i < size());
305 static_assert(sizeof(T) == sizeof(uoffset_t), "Unrelated types");
306 WriteScalar(data() + i,
307 static_cast<uoffset_t>(val - (Data() + i * sizeof(uoffset_t))));
310 // Get a mutable pointer to tables/strings inside this vector.
311 mutable_return_type GetMutableObject(uoffset_t i) const {
312 FLATBUFFERS_ASSERT(i < size());
313 return const_cast<mutable_return_type>(IndirectHelper<T>::Read(Data(), i));
316 // The raw data in little endian format. Use with care.
317 const uint8_t *Data() const {
318 return reinterpret_cast<const uint8_t *>(&length_ + 1);
321 uint8_t *Data() { return reinterpret_cast<uint8_t *>(&length_ + 1); }
323 // Similarly, but typed, much like std::vector::data
324 const T *data() const { return reinterpret_cast<const T *>(Data()); }
325 T *data() { return reinterpret_cast<T *>(Data()); }
327 template<typename K> return_type LookupByKey(K key) const {
328 void *search_result = std::bsearch(
329 &key, Data(), size(), IndirectHelper<T>::element_stride, KeyCompare<K>);
331 if (!search_result) {
332 return nullptr; // Key not found.
335 const uint8_t *element = reinterpret_cast<const uint8_t *>(search_result);
337 return IndirectHelper<T>::Read(element, 0);
341 // This class is only used to access pre-existing data. Don't ever
342 // try to construct these manually.
348 // This class is a pointer. Copying will therefore create an invalid object.
349 // Private and unimplemented copy constructor.
350 Vector(const Vector &);
352 template<typename K> static int KeyCompare(const void *ap, const void *bp) {
353 const K *key = reinterpret_cast<const K *>(ap);
354 const uint8_t *data = reinterpret_cast<const uint8_t *>(bp);
355 auto table = IndirectHelper<T>::Read(data, 0);
357 // std::bsearch compares with the operands transposed, so we negate the
359 return -table->KeyCompareWithValue(*key);
363 // Represent a vector much like the template above, but in this case we
364 // don't know what the element types are (used with reflection.h).
367 uoffset_t size() const { return EndianScalar(length_); }
369 const uint8_t *Data() const {
370 return reinterpret_cast<const uint8_t *>(&length_ + 1);
372 uint8_t *Data() { return reinterpret_cast<uint8_t *>(&length_ + 1); }
380 VectorOfAny(const VectorOfAny &);
383 #ifndef FLATBUFFERS_CPP98_STL
384 template<typename T, typename U>
385 Vector<Offset<T>> *VectorCast(Vector<Offset<U>> *ptr) {
386 static_assert(std::is_base_of<T, U>::value, "Unrelated types");
387 return reinterpret_cast<Vector<Offset<T>> *>(ptr);
390 template<typename T, typename U>
391 const Vector<Offset<T>> *VectorCast(const Vector<Offset<U>> *ptr) {
392 static_assert(std::is_base_of<T, U>::value, "Unrelated types");
393 return reinterpret_cast<const Vector<Offset<T>> *>(ptr);
397 // Convenient helper function to get the length of any vector, regardless
398 // of whether it is null or not (the field is not set).
399 template<typename T> static inline size_t VectorLength(const Vector<T> *v) {
400 return v ? v->size() : 0;
403 // This is used as a helper type for accessing arrays.
404 template<typename T, uint16_t length> class Array {
406 typename flatbuffers::integral_constant<bool, flatbuffers::is_scalar<T>::value>
409 typename flatbuffers::conditional<scalar_tag::value, T, const T *>::type
413 typedef typename IndirectHelper<IndirectHelperType>::return_type return_type;
414 typedef VectorIterator<T, return_type> const_iterator;
415 typedef VectorReverseIterator<const_iterator> const_reverse_iterator;
417 FLATBUFFERS_CONSTEXPR uint16_t size() const { return length; }
419 return_type Get(uoffset_t i) const {
420 FLATBUFFERS_ASSERT(i < size());
421 return IndirectHelper<IndirectHelperType>::Read(Data(), i);
424 return_type operator[](uoffset_t i) const { return Get(i); }
426 const_iterator begin() const { return const_iterator(Data(), 0); }
427 const_iterator end() const { return const_iterator(Data(), size()); }
429 const_reverse_iterator rbegin() const {
430 return const_reverse_iterator(end());
432 const_reverse_iterator rend() const { return const_reverse_iterator(end()); }
434 const_iterator cbegin() const { return begin(); }
435 const_iterator cend() const { return end(); }
437 const_reverse_iterator crbegin() const { return rbegin(); }
438 const_reverse_iterator crend() const { return rend(); }
440 // Get a mutable pointer to elements inside this array.
441 // This method used to mutate arrays of structs followed by a @p Mutate
442 // operation. For primitive types use @p Mutate directly.
443 // @warning Assignments and reads to/from the dereferenced pointer are not
444 // automatically converted to the correct endianness.
445 typename flatbuffers::conditional<scalar_tag::value, void, T *>::type
446 GetMutablePointer(uoffset_t i) const {
447 FLATBUFFERS_ASSERT(i < size());
448 return const_cast<T *>(&data()[i]);
451 // Change elements if you have a non-const pointer to this object.
452 void Mutate(uoffset_t i, const T &val) {
453 MutateImpl(scalar_tag(), i, val);
456 // The raw data in little endian format. Use with care.
457 const uint8_t *Data() const { return data_; }
459 uint8_t *Data() { return data_; }
461 // Similarly, but typed, much like std::vector::data
462 const T *data() const { return reinterpret_cast<const T *>(Data()); }
463 T *data() { return reinterpret_cast<T *>(Data()); }
466 void MutateImpl(flatbuffers::integral_constant<bool, true>, uoffset_t i,
468 FLATBUFFERS_ASSERT(i < size());
469 WriteScalar(data() + i, val);
472 void MutateImpl(flatbuffers::integral_constant<bool, false>, uoffset_t i,
474 *(GetMutablePointer(i)) = val;
477 // This class is only used to access pre-existing data. Don't ever
478 // try to construct these manually.
479 // 'constexpr' allows us to use 'size()' at compile time.
480 // @note Must not use 'FLATBUFFERS_CONSTEXPR' here, as const is not allowed on
482 #if defined(__cpp_constexpr)
488 uint8_t data_[length * sizeof(T)];
491 // This class is a pointer. Copying will therefore create an invalid object.
492 // Private and unimplemented copy constructor.
493 Array(const Array &);
494 Array &operator=(const Array &);
497 // Specialization for Array[struct] with access using Offset<void> pointer.
498 // This specialization used by idl_gen_text.cpp.
499 template<typename T, uint16_t length> class Array<Offset<T>, length> {
500 static_assert(flatbuffers::is_same<T, void>::value, "unexpected type T");
503 const uint8_t *Data() const { return data_; }
505 // Make idl_gen_text.cpp::PrintContainer happy.
506 const void *operator[](uoffset_t) const {
507 FLATBUFFERS_ASSERT(false);
512 // This class is only used to access pre-existing data.
514 Array(const Array &);
515 Array &operator=(const Array &);
520 // Lexicographically compare two strings (possibly containing nulls), and
521 // return true if the first is less than the second.
522 static inline bool StringLessThan(const char *a_data, uoffset_t a_size,
523 const char *b_data, uoffset_t b_size) {
524 const auto cmp = memcmp(a_data, b_data, (std::min)(a_size, b_size));
525 return cmp == 0 ? a_size < b_size : cmp < 0;
528 struct String : public Vector<char> {
529 const char *c_str() const { return reinterpret_cast<const char *>(Data()); }
530 std::string str() const { return std::string(c_str(), size()); }
533 #ifdef FLATBUFFERS_HAS_STRING_VIEW
534 flatbuffers::string_view string_view() const {
535 return flatbuffers::string_view(c_str(), size());
537 #endif // FLATBUFFERS_HAS_STRING_VIEW
540 bool operator<(const String &o) const {
541 return StringLessThan(this->data(), this->size(), o.data(), o.size());
545 // Convenience function to get std::string from a String returning an empty
546 // string on null pointer.
547 static inline std::string GetString(const String * str) {
548 return str ? str->str() : "";
551 // Convenience function to get char* from a String returning an empty string on
553 static inline const char * GetCstring(const String * str) {
554 return str ? str->c_str() : "";
557 // Allocator interface. This is flatbuffers-specific and meant only for
558 // `vector_downward` usage.
561 virtual ~Allocator() {}
563 // Allocate `size` bytes of memory.
564 virtual uint8_t *allocate(size_t size) = 0;
566 // Deallocate `size` bytes of memory at `p` allocated by this allocator.
567 virtual void deallocate(uint8_t *p, size_t size) = 0;
569 // Reallocate `new_size` bytes of memory, replacing the old region of size
570 // `old_size` at `p`. In contrast to a normal realloc, this grows downwards,
571 // and is intended specifcally for `vector_downward` use.
572 // `in_use_back` and `in_use_front` indicate how much of `old_size` is
573 // actually in use at each end, and needs to be copied.
574 virtual uint8_t *reallocate_downward(uint8_t *old_p, size_t old_size,
575 size_t new_size, size_t in_use_back,
576 size_t in_use_front) {
577 FLATBUFFERS_ASSERT(new_size > old_size); // vector_downward only grows
578 uint8_t *new_p = allocate(new_size);
579 memcpy_downward(old_p, old_size, new_p, new_size, in_use_back,
581 deallocate(old_p, old_size);
586 // Called by `reallocate_downward` to copy memory from `old_p` of `old_size`
587 // to `new_p` of `new_size`. Only memory of size `in_use_front` and
588 // `in_use_back` will be copied from the front and back of the old memory
590 void memcpy_downward(uint8_t *old_p, size_t old_size,
591 uint8_t *new_p, size_t new_size,
592 size_t in_use_back, size_t in_use_front) {
593 memcpy(new_p + new_size - in_use_back, old_p + old_size - in_use_back,
595 memcpy(new_p, old_p, in_use_front);
599 // DefaultAllocator uses new/delete to allocate memory regions
600 class DefaultAllocator : public Allocator {
602 uint8_t *allocate(size_t size) FLATBUFFERS_OVERRIDE {
603 return new uint8_t[size];
606 void deallocate(uint8_t *p, size_t) FLATBUFFERS_OVERRIDE {
610 static void dealloc(void *p, size_t) {
611 delete[] static_cast<uint8_t *>(p);
615 // These functions allow for a null allocator to mean use the default allocator,
616 // as used by DetachedBuffer and vector_downward below.
617 // This is to avoid having a statically or dynamically allocated default
618 // allocator, or having to move it between the classes that may own it.
619 inline uint8_t *Allocate(Allocator *allocator, size_t size) {
620 return allocator ? allocator->allocate(size)
621 : DefaultAllocator().allocate(size);
624 inline void Deallocate(Allocator *allocator, uint8_t *p, size_t size) {
625 if (allocator) allocator->deallocate(p, size);
626 else DefaultAllocator().deallocate(p, size);
629 inline uint8_t *ReallocateDownward(Allocator *allocator, uint8_t *old_p,
630 size_t old_size, size_t new_size,
631 size_t in_use_back, size_t in_use_front) {
633 ? allocator->reallocate_downward(old_p, old_size, new_size,
634 in_use_back, in_use_front)
635 : DefaultAllocator().reallocate_downward(old_p, old_size, new_size,
636 in_use_back, in_use_front);
639 // DetachedBuffer is a finished flatbuffer memory region, detached from its
640 // builder. The original memory region and allocator are also stored so that
641 // the DetachedBuffer can manage the memory lifetime.
642 class DetachedBuffer {
645 : allocator_(nullptr),
646 own_allocator_(false),
652 DetachedBuffer(Allocator *allocator, bool own_allocator, uint8_t *buf,
653 size_t reserved, uint8_t *cur, size_t sz)
654 : allocator_(allocator),
655 own_allocator_(own_allocator),
662 #if !defined(FLATBUFFERS_CPP98_STL)
664 DetachedBuffer(DetachedBuffer &&other)
665 : allocator_(other.allocator_),
666 own_allocator_(other.own_allocator_),
668 reserved_(other.reserved_),
674 #endif // !defined(FLATBUFFERS_CPP98_STL)
678 #if !defined(FLATBUFFERS_CPP98_STL)
680 DetachedBuffer &operator=(DetachedBuffer &&other) {
686 allocator_ = other.allocator_;
687 own_allocator_ = other.own_allocator_;
689 reserved_ = other.reserved_;
698 #endif // !defined(FLATBUFFERS_CPP98_STL)
701 ~DetachedBuffer() { destroy(); }
703 const uint8_t *data() const { return cur_; }
705 uint8_t *data() { return cur_; }
707 size_t size() const { return size_; }
710 #if 0 // disabled for now due to the ordering of classes in this header
712 bool Verify() const {
713 Verifier verifier(data(), size());
714 return verifier.Verify<T>(nullptr);
718 const T* GetRoot() const {
719 return flatbuffers::GetRoot<T>(data());
724 return flatbuffers::GetRoot<T>(data());
730 #if !defined(FLATBUFFERS_CPP98_STL)
732 // These may change access mode, leave these at end of public section
733 FLATBUFFERS_DELETE_FUNC(DetachedBuffer(const DetachedBuffer &other))
734 FLATBUFFERS_DELETE_FUNC(
735 DetachedBuffer &operator=(const DetachedBuffer &other))
737 #endif // !defined(FLATBUFFERS_CPP98_STL)
741 Allocator *allocator_;
748 inline void destroy() {
749 if (buf_) Deallocate(allocator_, buf_, reserved_);
750 if (own_allocator_ && allocator_) { delete allocator_; }
754 inline void reset() {
755 allocator_ = nullptr;
756 own_allocator_ = false;
764 // This is a minimal replication of std::vector<uint8_t> functionality,
765 // except growing from higher to lower addresses. i.e push_back() inserts data
766 // in the lowest address in the vector.
767 // Since this vector leaves the lower part unused, we support a "scratch-pad"
768 // that can be stored there for temporary data, to share the allocated space.
769 // Essentially, this supports 2 std::vectors in a single buffer.
770 class vector_downward {
772 explicit vector_downward(size_t initial_size,
773 Allocator *allocator,
775 size_t buffer_minalign)
776 : allocator_(allocator),
777 own_allocator_(own_allocator),
778 initial_size_(initial_size),
779 buffer_minalign_(buffer_minalign),
786 #if !defined(FLATBUFFERS_CPP98_STL)
787 vector_downward(vector_downward &&other)
789 vector_downward(vector_downward &other)
790 #endif // defined(FLATBUFFERS_CPP98_STL)
792 : allocator_(other.allocator_),
793 own_allocator_(other.own_allocator_),
794 initial_size_(other.initial_size_),
795 buffer_minalign_(other.buffer_minalign_),
796 reserved_(other.reserved_),
799 scratch_(other.scratch_) {
800 // No change in other.allocator_
801 // No change in other.initial_size_
802 // No change in other.buffer_minalign_
803 other.own_allocator_ = false;
805 other.buf_ = nullptr;
806 other.cur_ = nullptr;
807 other.scratch_ = nullptr;
811 #if !defined(FLATBUFFERS_CPP98_STL)
813 vector_downward &operator=(vector_downward &&other) {
814 // Move construct a temporary and swap idiom
815 vector_downward temp(std::move(other));
820 #endif // defined(FLATBUFFERS_CPP98_STL)
835 cur_ = buf_ + reserved_;
843 void clear_scratch() {
847 void clear_allocator() {
848 if (own_allocator_ && allocator_) { delete allocator_; }
849 allocator_ = nullptr;
850 own_allocator_ = false;
853 void clear_buffer() {
854 if (buf_) Deallocate(allocator_, buf_, reserved_);
858 // Relinquish the pointer to the caller.
859 uint8_t *release_raw(size_t &allocated_bytes, size_t &offset) {
861 allocated_bytes = reserved_;
862 offset = static_cast<size_t>(cur_ - buf_);
864 // release_raw only relinquishes the buffer ownership.
865 // Does not deallocate or reset the allocator. Destructor will do that.
871 // Relinquish the pointer to the caller.
872 DetachedBuffer release() {
873 // allocator ownership (if any) is transferred to DetachedBuffer.
874 DetachedBuffer fb(allocator_, own_allocator_, buf_, reserved_, cur_,
876 if (own_allocator_) {
877 allocator_ = nullptr;
878 own_allocator_ = false;
885 size_t ensure_space(size_t len) {
886 FLATBUFFERS_ASSERT(cur_ >= scratch_ && scratch_ >= buf_);
887 if (len > static_cast<size_t>(cur_ - scratch_)) { reallocate(len); }
888 // Beyond this, signed offsets may not have enough range:
889 // (FlatBuffers > 2GB not supported).
890 FLATBUFFERS_ASSERT(size() < FLATBUFFERS_MAX_BUFFER_SIZE);
894 inline uint8_t *make_space(size_t len) {
895 size_t space = ensure_space(len);
900 // Returns nullptr if using the DefaultAllocator.
901 Allocator *get_custom_allocator() { return allocator_; }
903 uoffset_t size() const {
904 return static_cast<uoffset_t>(reserved_ - (cur_ - buf_));
907 uoffset_t scratch_size() const {
908 return static_cast<uoffset_t>(scratch_ - buf_);
911 size_t capacity() const { return reserved_; }
913 uint8_t *data() const {
914 FLATBUFFERS_ASSERT(cur_);
918 uint8_t *scratch_data() const {
919 FLATBUFFERS_ASSERT(buf_);
923 uint8_t *scratch_end() const {
924 FLATBUFFERS_ASSERT(scratch_);
928 uint8_t *data_at(size_t offset) const { return buf_ + reserved_ - offset; }
930 void push(const uint8_t *bytes, size_t num) {
931 if (num > 0) { memcpy(make_space(num), bytes, num); }
934 // Specialized version of push() that avoids memcpy call for small data.
935 template<typename T> void push_small(const T &little_endian_t) {
936 make_space(sizeof(T));
937 *reinterpret_cast<T *>(cur_) = little_endian_t;
940 template<typename T> void scratch_push_small(const T &t) {
941 ensure_space(sizeof(T));
942 *reinterpret_cast<T *>(scratch_) = t;
943 scratch_ += sizeof(T);
946 // fill() is most frequently called with small byte counts (<= 4),
947 // which is why we're using loops rather than calling memset.
948 void fill(size_t zero_pad_bytes) {
949 make_space(zero_pad_bytes);
950 for (size_t i = 0; i < zero_pad_bytes; i++) cur_[i] = 0;
953 // Version for when we know the size is larger.
954 // Precondition: zero_pad_bytes > 0
955 void fill_big(size_t zero_pad_bytes) {
956 memset(make_space(zero_pad_bytes), 0, zero_pad_bytes);
959 void pop(size_t bytes_to_remove) { cur_ += bytes_to_remove; }
960 void scratch_pop(size_t bytes_to_remove) { scratch_ -= bytes_to_remove; }
962 void swap(vector_downward &other) {
964 swap(allocator_, other.allocator_);
965 swap(own_allocator_, other.own_allocator_);
966 swap(initial_size_, other.initial_size_);
967 swap(buffer_minalign_, other.buffer_minalign_);
968 swap(reserved_, other.reserved_);
969 swap(buf_, other.buf_);
970 swap(cur_, other.cur_);
971 swap(scratch_, other.scratch_);
974 void swap_allocator(vector_downward &other) {
976 swap(allocator_, other.allocator_);
977 swap(own_allocator_, other.own_allocator_);
981 // You shouldn't really be copying instances of this class.
982 FLATBUFFERS_DELETE_FUNC(vector_downward(const vector_downward &))
983 FLATBUFFERS_DELETE_FUNC(vector_downward &operator=(const vector_downward &))
985 Allocator *allocator_;
987 size_t initial_size_;
988 size_t buffer_minalign_;
991 uint8_t *cur_; // Points at location between empty (below) and used (above).
992 uint8_t *scratch_; // Points to the end of the scratchpad in use.
994 void reallocate(size_t len) {
995 auto old_reserved = reserved_;
996 auto old_size = size();
997 auto old_scratch_size = scratch_size();
998 reserved_ += (std::max)(len,
999 old_reserved ? old_reserved / 2 : initial_size_);
1000 reserved_ = (reserved_ + buffer_minalign_ - 1) & ~(buffer_minalign_ - 1);
1002 buf_ = ReallocateDownward(allocator_, buf_, old_reserved, reserved_,
1003 old_size, old_scratch_size);
1005 buf_ = Allocate(allocator_, reserved_);
1007 cur_ = buf_ + reserved_ - old_size;
1008 scratch_ = buf_ + old_scratch_size;
1012 // Converts a Field ID to a virtual table offset.
1013 inline voffset_t FieldIndexToOffset(voffset_t field_id) {
1014 // Should correspond to what EndTable() below builds up.
1015 const int fixed_fields = 2; // Vtable size and Object Size.
1016 return static_cast<voffset_t>((field_id + fixed_fields) * sizeof(voffset_t));
1019 template<typename T, typename Alloc>
1020 const T *data(const std::vector<T, Alloc> &v) {
1021 // Eventually the returned pointer gets passed down to memcpy, so
1022 // we need it to be non-null to avoid undefined behavior.
1024 return v.empty() ? reinterpret_cast<const T*>(&t) : &v.front();
1026 template<typename T, typename Alloc> T *data(std::vector<T, Alloc> &v) {
1027 // Eventually the returned pointer gets passed down to memcpy, so
1028 // we need it to be non-null to avoid undefined behavior.
1030 return v.empty() ? reinterpret_cast<T*>(&t) : &v.front();
1035 /// @addtogroup flatbuffers_cpp_api
1037 /// @class FlatBufferBuilder
1038 /// @brief Helper class to hold data needed in creation of a FlatBuffer.
1039 /// To serialize data, you typically call one of the `Create*()` functions in
1040 /// the generated code, which in turn call a sequence of `StartTable`/
1041 /// `PushElement`/`AddElement`/`EndTable`, or the builtin `CreateString`/
1042 /// `CreateVector` functions. Do this is depth-first order to build up a tree to
1043 /// the root. `Finish()` wraps up the buffer ready for transport.
1044 class FlatBufferBuilder {
1046 /// @brief Default constructor for FlatBufferBuilder.
1047 /// @param[in] initial_size The initial size of the buffer, in bytes. Defaults
1049 /// @param[in] allocator An `Allocator` to use. If null will use
1050 /// `DefaultAllocator`.
1051 /// @param[in] own_allocator Whether the builder/vector should own the
1052 /// allocator. Defaults to / `false`.
1053 /// @param[in] buffer_minalign Force the buffer to be aligned to the given
1054 /// minimum alignment upon reallocation. Only needed if you intend to store
1055 /// types with custom alignment AND you wish to read the buffer in-place
1056 /// directly after creation.
1057 explicit FlatBufferBuilder(size_t initial_size = 1024,
1058 Allocator *allocator = nullptr,
1059 bool own_allocator = false,
1060 size_t buffer_minalign =
1061 AlignOf<largest_scalar_t>())
1062 : buf_(initial_size, allocator, own_allocator, buffer_minalign),
1068 force_defaults_(false),
1069 dedup_vtables_(true),
1070 string_pool(nullptr) {
1075 /// @brief Move constructor for FlatBufferBuilder.
1076 #if !defined(FLATBUFFERS_CPP98_STL)
1077 FlatBufferBuilder(FlatBufferBuilder &&other)
1079 FlatBufferBuilder(FlatBufferBuilder &other)
1080 #endif // #if !defined(FLATBUFFERS_CPP98_STL)
1081 : buf_(1024, nullptr, false, AlignOf<largest_scalar_t>()),
1087 force_defaults_(false),
1088 dedup_vtables_(true),
1089 string_pool(nullptr) {
1091 // Default construct and swap idiom.
1092 // Lack of delegating constructors in vs2010 makes it more verbose than needed.
1098 #if !defined(FLATBUFFERS_CPP98_STL)
1100 /// @brief Move assignment operator for FlatBufferBuilder.
1101 FlatBufferBuilder &operator=(FlatBufferBuilder &&other) {
1102 // Move construct a temporary and swap idiom
1103 FlatBufferBuilder temp(std::move(other));
1108 #endif // defined(FLATBUFFERS_CPP98_STL)
1111 void Swap(FlatBufferBuilder &other) {
1113 buf_.swap(other.buf_);
1114 swap(num_field_loc, other.num_field_loc);
1115 swap(max_voffset_, other.max_voffset_);
1116 swap(nested, other.nested);
1117 swap(finished, other.finished);
1118 swap(minalign_, other.minalign_);
1119 swap(force_defaults_, other.force_defaults_);
1120 swap(dedup_vtables_, other.dedup_vtables_);
1121 swap(string_pool, other.string_pool);
1124 ~FlatBufferBuilder() {
1125 if (string_pool) delete string_pool;
1129 Clear(); // clear builder state
1130 buf_.reset(); // deallocate buffer
1133 /// @brief Reset all the state in this FlatBufferBuilder so it can be reused
1134 /// to construct another buffer.
1141 if (string_pool) string_pool->clear();
1144 /// @brief The current size of the serialized buffer, counting from the end.
1145 /// @return Returns an `uoffset_t` with the current size of the buffer.
1146 uoffset_t GetSize() const { return buf_.size(); }
1148 /// @brief Get the serialized buffer (after you call `Finish()`).
1149 /// @return Returns an `uint8_t` pointer to the FlatBuffer data inside the
1151 uint8_t *GetBufferPointer() const {
1156 /// @brief Get a pointer to an unfinished buffer.
1157 /// @return Returns a `uint8_t` pointer to the unfinished buffer.
1158 uint8_t *GetCurrentBufferPointer() const { return buf_.data(); }
1160 /// @brief Get the released pointer to the serialized buffer.
1161 /// @warning Do NOT attempt to use this FlatBufferBuilder afterwards!
1162 /// @return A `FlatBuffer` that owns the buffer and its allocator and
1163 /// behaves similar to a `unique_ptr` with a deleter.
1164 FLATBUFFERS_ATTRIBUTE(deprecated("use Release() instead")) DetachedBuffer
1165 ReleaseBufferPointer() {
1167 return buf_.release();
1170 /// @brief Get the released DetachedBuffer.
1171 /// @return A `DetachedBuffer` that owns the buffer and its allocator.
1172 DetachedBuffer Release() {
1174 return buf_.release();
1177 /// @brief Get the released pointer to the serialized buffer.
1178 /// @param size The size of the memory block containing
1179 /// the serialized `FlatBuffer`.
1180 /// @param offset The offset from the released pointer where the finished
1181 /// `FlatBuffer` starts.
1182 /// @return A raw pointer to the start of the memory block containing
1183 /// the serialized `FlatBuffer`.
1184 /// @remark If the allocator is owned, it gets deleted when the destructor is called..
1185 uint8_t *ReleaseRaw(size_t &size, size_t &offset) {
1187 return buf_.release_raw(size, offset);
1190 /// @brief get the minimum alignment this buffer needs to be accessed
1191 /// properly. This is only known once all elements have been written (after
1192 /// you call Finish()). You can use this information if you need to embed
1193 /// a FlatBuffer in some other buffer, such that you can later read it
1194 /// without first having to copy it into its own buffer.
1195 size_t GetBufferMinAlignment() {
1200 /// @cond FLATBUFFERS_INTERNAL
1201 void Finished() const {
1202 // If you get this assert, you're attempting to get access a buffer
1203 // which hasn't been finished yet. Be sure to call
1204 // FlatBufferBuilder::Finish with your root table.
1205 // If you really need to access an unfinished buffer, call
1206 // GetCurrentBufferPointer instead.
1207 FLATBUFFERS_ASSERT(finished);
1211 /// @brief In order to save space, fields that are set to their default value
1212 /// don't get serialized into the buffer.
1213 /// @param[in] fd When set to `true`, always serializes default values that are set.
1214 /// Optional fields which are not set explicitly, will still not be serialized.
1215 void ForceDefaults(bool fd) { force_defaults_ = fd; }
1217 /// @brief By default vtables are deduped in order to save space.
1218 /// @param[in] dedup When set to `true`, dedup vtables.
1219 void DedupVtables(bool dedup) { dedup_vtables_ = dedup; }
1221 /// @cond FLATBUFFERS_INTERNAL
1222 void Pad(size_t num_bytes) { buf_.fill(num_bytes); }
1224 void TrackMinAlign(size_t elem_size) {
1225 if (elem_size > minalign_) minalign_ = elem_size;
1228 void Align(size_t elem_size) {
1229 TrackMinAlign(elem_size);
1230 buf_.fill(PaddingBytes(buf_.size(), elem_size));
1233 void PushFlatBuffer(const uint8_t *bytes, size_t size) {
1234 PushBytes(bytes, size);
1238 void PushBytes(const uint8_t *bytes, size_t size) { buf_.push(bytes, size); }
1240 void PopBytes(size_t amount) { buf_.pop(amount); }
1242 template<typename T> void AssertScalarT() {
1243 // The code assumes power of 2 sizes and endian-swap-ability.
1244 static_assert(flatbuffers::is_scalar<T>::value, "T must be a scalar type");
1247 // Write a single aligned scalar to the buffer
1248 template<typename T> uoffset_t PushElement(T element) {
1250 T litle_endian_element = EndianScalar(element);
1252 buf_.push_small(litle_endian_element);
1256 template<typename T> uoffset_t PushElement(Offset<T> off) {
1257 // Special case for offsets: see ReferTo below.
1258 return PushElement(ReferTo(off.o));
1261 // When writing fields, we track where they are, so we can create correct
1263 void TrackField(voffset_t field, uoffset_t off) {
1264 FieldLoc fl = { off, field };
1265 buf_.scratch_push_small(fl);
1267 max_voffset_ = (std::max)(max_voffset_, field);
1270 // Like PushElement, but additionally tracks the field this represents.
1271 template<typename T> void AddElement(voffset_t field, T e, T def) {
1272 // We don't serialize values equal to the default.
1273 if (IsTheSameAs(e, def) && !force_defaults_) return;
1274 auto off = PushElement(e);
1275 TrackField(field, off);
1278 template<typename T> void AddOffset(voffset_t field, Offset<T> off) {
1279 if (off.IsNull()) return; // Don't store.
1280 AddElement(field, ReferTo(off.o), static_cast<uoffset_t>(0));
1283 template<typename T> void AddStruct(voffset_t field, const T *structptr) {
1284 if (!structptr) return; // Default, don't store.
1285 Align(AlignOf<T>());
1286 buf_.push_small(*structptr);
1287 TrackField(field, GetSize());
1290 void AddStructOffset(voffset_t field, uoffset_t off) {
1291 TrackField(field, off);
1294 // Offsets initially are relative to the end of the buffer (downwards).
1295 // This function converts them to be relative to the current location
1296 // in the buffer (when stored here), pointing upwards.
1297 uoffset_t ReferTo(uoffset_t off) {
1298 // Align to ensure GetSize() below is correct.
1299 Align(sizeof(uoffset_t));
1300 // Offset must refer to something already in buffer.
1301 FLATBUFFERS_ASSERT(off && off <= GetSize());
1302 return GetSize() - off + static_cast<uoffset_t>(sizeof(uoffset_t));
1306 // If you hit this, you're trying to construct a Table/Vector/String
1307 // during the construction of its parent table (between the MyTableBuilder
1308 // and table.Finish().
1309 // Move the creation of these sub-objects to above the MyTableBuilder to
1310 // not get this assert.
1311 // Ignoring this assert may appear to work in simple cases, but the reason
1312 // it is here is that storing objects in-line may cause vtable offsets
1313 // to not fit anymore. It also leads to vtable duplication.
1314 FLATBUFFERS_ASSERT(!nested);
1315 // If you hit this, fields were added outside the scope of a table.
1316 FLATBUFFERS_ASSERT(!num_field_loc);
1319 // From generated code (or from the parser), we call StartTable/EndTable
1320 // with a sequence of AddElement calls in between.
1321 uoffset_t StartTable() {
1327 // This finishes one serialized object by generating the vtable if it's a
1328 // table, comparing it against existing vtables, and writing the
1329 // resulting vtable offset.
1330 uoffset_t EndTable(uoffset_t start) {
1331 // If you get this assert, a corresponding StartTable wasn't called.
1332 FLATBUFFERS_ASSERT(nested);
1333 // Write the vtable offset, which is the start of any Table.
1334 // We fill it's value later.
1335 auto vtableoffsetloc = PushElement<soffset_t>(0);
1336 // Write a vtable, which consists entirely of voffset_t elements.
1337 // It starts with the number of offsets, followed by a type id, followed
1338 // by the offsets themselves. In reverse:
1339 // Include space for the last offset and ensure empty tables have a
1342 (std::max)(static_cast<voffset_t>(max_voffset_ + sizeof(voffset_t)),
1343 FieldIndexToOffset(0));
1344 buf_.fill_big(max_voffset_);
1345 auto table_object_size = vtableoffsetloc - start;
1346 // Vtable use 16bit offsets.
1347 FLATBUFFERS_ASSERT(table_object_size < 0x10000);
1348 WriteScalar<voffset_t>(buf_.data() + sizeof(voffset_t),
1349 static_cast<voffset_t>(table_object_size));
1350 WriteScalar<voffset_t>(buf_.data(), max_voffset_);
1351 // Write the offsets into the table
1352 for (auto it = buf_.scratch_end() - num_field_loc * sizeof(FieldLoc);
1353 it < buf_.scratch_end(); it += sizeof(FieldLoc)) {
1354 auto field_location = reinterpret_cast<FieldLoc *>(it);
1355 auto pos = static_cast<voffset_t>(vtableoffsetloc - field_location->off);
1356 // If this asserts, it means you've set a field twice.
1358 !ReadScalar<voffset_t>(buf_.data() + field_location->id));
1359 WriteScalar<voffset_t>(buf_.data() + field_location->id, pos);
1362 auto vt1 = reinterpret_cast<voffset_t *>(buf_.data());
1363 auto vt1_size = ReadScalar<voffset_t>(vt1);
1364 auto vt_use = GetSize();
1365 // See if we already have generated a vtable with this exact same
1366 // layout before. If so, make it point to the old one, remove this one.
1367 if (dedup_vtables_) {
1368 for (auto it = buf_.scratch_data(); it < buf_.scratch_end();
1369 it += sizeof(uoffset_t)) {
1370 auto vt_offset_ptr = reinterpret_cast<uoffset_t *>(it);
1371 auto vt2 = reinterpret_cast<voffset_t *>(buf_.data_at(*vt_offset_ptr));
1372 auto vt2_size = *vt2;
1373 if (vt1_size != vt2_size || 0 != memcmp(vt2, vt1, vt1_size)) continue;
1374 vt_use = *vt_offset_ptr;
1375 buf_.pop(GetSize() - vtableoffsetloc);
1379 // If this is a new vtable, remember it.
1380 if (vt_use == GetSize()) { buf_.scratch_push_small(vt_use); }
1381 // Fill the vtable offset we created above.
1382 // The offset points from the beginning of the object to where the
1383 // vtable is stored.
1384 // Offsets default direction is downward in memory for future format
1385 // flexibility (storing all vtables at the start of the file).
1386 WriteScalar(buf_.data_at(vtableoffsetloc),
1387 static_cast<soffset_t>(vt_use) -
1388 static_cast<soffset_t>(vtableoffsetloc));
1391 return vtableoffsetloc;
1394 FLATBUFFERS_ATTRIBUTE(deprecated("call the version above instead"))
1395 uoffset_t EndTable(uoffset_t start, voffset_t /*numfields*/) {
1396 return EndTable(start);
1399 // This checks a required field has been set in a given table that has
1400 // just been constructed.
1401 template<typename T> void Required(Offset<T> table, voffset_t field);
1403 uoffset_t StartStruct(size_t alignment) {
1408 uoffset_t EndStruct() { return GetSize(); }
1410 void ClearOffsets() {
1411 buf_.scratch_pop(num_field_loc * sizeof(FieldLoc));
1416 // Aligns such that when "len" bytes are written, an object can be written
1417 // after it with "alignment" without padding.
1418 void PreAlign(size_t len, size_t alignment) {
1419 TrackMinAlign(alignment);
1420 buf_.fill(PaddingBytes(GetSize() + len, alignment));
1422 template<typename T> void PreAlign(size_t len) {
1424 PreAlign(len, sizeof(T));
1428 /// @brief Store a string in the buffer, which can contain any binary data.
1429 /// @param[in] str A const char pointer to the data to be stored as a string.
1430 /// @param[in] len The number of bytes that should be stored from `str`.
1431 /// @return Returns the offset in the buffer where the string starts.
1432 Offset<String> CreateString(const char *str, size_t len) {
1434 PreAlign<uoffset_t>(len + 1); // Always 0-terminated.
1436 PushBytes(reinterpret_cast<const uint8_t *>(str), len);
1437 PushElement(static_cast<uoffset_t>(len));
1438 return Offset<String>(GetSize());
1441 /// @brief Store a string in the buffer, which is null-terminated.
1442 /// @param[in] str A const char pointer to a C-string to add to the buffer.
1443 /// @return Returns the offset in the buffer where the string starts.
1444 Offset<String> CreateString(const char *str) {
1445 return CreateString(str, strlen(str));
1448 /// @brief Store a string in the buffer, which is null-terminated.
1449 /// @param[in] str A char pointer to a C-string to add to the buffer.
1450 /// @return Returns the offset in the buffer where the string starts.
1451 Offset<String> CreateString(char *str) {
1452 return CreateString(str, strlen(str));
1455 /// @brief Store a string in the buffer, which can contain any binary data.
1456 /// @param[in] str A const reference to a std::string to store in the buffer.
1457 /// @return Returns the offset in the buffer where the string starts.
1458 Offset<String> CreateString(const std::string &str) {
1459 return CreateString(str.c_str(), str.length());
1463 #ifdef FLATBUFFERS_HAS_STRING_VIEW
1464 /// @brief Store a string in the buffer, which can contain any binary data.
1465 /// @param[in] str A const string_view to copy in to the buffer.
1466 /// @return Returns the offset in the buffer where the string starts.
1467 Offset<String> CreateString(flatbuffers::string_view str) {
1468 return CreateString(str.data(), str.size());
1470 #endif // FLATBUFFERS_HAS_STRING_VIEW
1473 /// @brief Store a string in the buffer, which can contain any binary data.
1474 /// @param[in] str A const pointer to a `String` struct to add to the buffer.
1475 /// @return Returns the offset in the buffer where the string starts
1476 Offset<String> CreateString(const String *str) {
1477 return str ? CreateString(str->c_str(), str->size()) : 0;
1480 /// @brief Store a string in the buffer, which can contain any binary data.
1481 /// @param[in] str A const reference to a std::string like type with support
1482 /// of T::c_str() and T::length() to store in the buffer.
1483 /// @return Returns the offset in the buffer where the string starts.
1484 template<typename T> Offset<String> CreateString(const T &str) {
1485 return CreateString(str.c_str(), str.length());
1488 /// @brief Store a string in the buffer, which can contain any binary data.
1489 /// If a string with this exact contents has already been serialized before,
1490 /// instead simply returns the offset of the existing string.
1491 /// @param[in] str A const char pointer to the data to be stored as a string.
1492 /// @param[in] len The number of bytes that should be stored from `str`.
1493 /// @return Returns the offset in the buffer where the string starts.
1494 Offset<String> CreateSharedString(const char *str, size_t len) {
1496 string_pool = new StringOffsetMap(StringOffsetCompare(buf_));
1497 auto size_before_string = buf_.size();
1498 // Must first serialize the string, since the set is all offsets into
1500 auto off = CreateString(str, len);
1501 auto it = string_pool->find(off);
1502 // If it exists we reuse existing serialized data!
1503 if (it != string_pool->end()) {
1504 // We can remove the string we serialized.
1505 buf_.pop(buf_.size() - size_before_string);
1508 // Record this string for future use.
1509 string_pool->insert(off);
1513 /// @brief Store a string in the buffer, which null-terminated.
1514 /// If a string with this exact contents has already been serialized before,
1515 /// instead simply returns the offset of the existing string.
1516 /// @param[in] str A const char pointer to a C-string to add to the buffer.
1517 /// @return Returns the offset in the buffer where the string starts.
1518 Offset<String> CreateSharedString(const char *str) {
1519 return CreateSharedString(str, strlen(str));
1522 /// @brief Store a string in the buffer, which can contain any binary data.
1523 /// If a string with this exact contents has already been serialized before,
1524 /// instead simply returns the offset of the existing string.
1525 /// @param[in] str A const reference to a std::string to store in the buffer.
1526 /// @return Returns the offset in the buffer where the string starts.
1527 Offset<String> CreateSharedString(const std::string &str) {
1528 return CreateSharedString(str.c_str(), str.length());
1531 /// @brief Store a string in the buffer, which can contain any binary data.
1532 /// If a string with this exact contents has already been serialized before,
1533 /// instead simply returns the offset of the existing string.
1534 /// @param[in] str A const pointer to a `String` struct to add to the buffer.
1535 /// @return Returns the offset in the buffer where the string starts
1536 Offset<String> CreateSharedString(const String *str) {
1537 return CreateSharedString(str->c_str(), str->size());
1540 /// @cond FLATBUFFERS_INTERNAL
1541 uoffset_t EndVector(size_t len) {
1542 FLATBUFFERS_ASSERT(nested); // Hit if no corresponding StartVector.
1544 return PushElement(static_cast<uoffset_t>(len));
1547 void StartVector(size_t len, size_t elemsize) {
1550 PreAlign<uoffset_t>(len * elemsize);
1551 PreAlign(len * elemsize, elemsize); // Just in case elemsize > uoffset_t.
1554 // Call this right before StartVector/CreateVector if you want to force the
1555 // alignment to be something different than what the element size would
1556 // normally dictate.
1557 // This is useful when storing a nested_flatbuffer in a vector of bytes,
1558 // or when storing SIMD floats, etc.
1559 void ForceVectorAlignment(size_t len, size_t elemsize, size_t alignment) {
1560 PreAlign(len * elemsize, alignment);
1563 // Similar to ForceVectorAlignment but for String fields.
1564 void ForceStringAlignment(size_t len, size_t alignment) {
1565 PreAlign((len + 1) * sizeof(char), alignment);
1570 /// @brief Serialize an array into a FlatBuffer `vector`.
1571 /// @tparam T The data type of the array elements.
1572 /// @param[in] v A pointer to the array of type `T` to serialize into the
1573 /// buffer as a `vector`.
1574 /// @param[in] len The number of elements to serialize.
1575 /// @return Returns a typed `Offset` into the serialized data indicating
1576 /// where the vector is stored.
1577 template<typename T> Offset<Vector<T>> CreateVector(const T *v, size_t len) {
1578 // If this assert hits, you're specifying a template argument that is
1579 // causing the wrong overload to be selected, remove it.
1581 StartVector(len, sizeof(T));
1583 #if FLATBUFFERS_LITTLEENDIAN
1584 PushBytes(reinterpret_cast<const uint8_t *>(v), len * sizeof(T));
1586 if (sizeof(T) == 1) {
1587 PushBytes(reinterpret_cast<const uint8_t *>(v), len);
1589 for (auto i = len; i > 0; ) {
1590 PushElement(v[--i]);
1595 return Offset<Vector<T>>(EndVector(len));
1598 template<typename T>
1599 Offset<Vector<Offset<T>>> CreateVector(const Offset<T> *v, size_t len) {
1600 StartVector(len, sizeof(Offset<T>));
1601 for (auto i = len; i > 0;) { PushElement(v[--i]); }
1602 return Offset<Vector<Offset<T>>>(EndVector(len));
1605 /// @brief Serialize a `std::vector` into a FlatBuffer `vector`.
1606 /// @tparam T The data type of the `std::vector` elements.
1607 /// @param v A const reference to the `std::vector` to serialize into the
1608 /// buffer as a `vector`.
1609 /// @return Returns a typed `Offset` into the serialized data indicating
1610 /// where the vector is stored.
1611 template<typename T> Offset<Vector<T>> CreateVector(const std::vector<T> &v) {
1612 return CreateVector(data(v), v.size());
1615 // vector<bool> may be implemented using a bit-set, so we can't access it as
1616 // an array. Instead, read elements manually.
1617 // Background: https://isocpp.org/blog/2012/11/on-vectorbool
1618 Offset<Vector<uint8_t>> CreateVector(const std::vector<bool> &v) {
1619 StartVector(v.size(), sizeof(uint8_t));
1620 for (auto i = v.size(); i > 0;) {
1621 PushElement(static_cast<uint8_t>(v[--i]));
1623 return Offset<Vector<uint8_t>>(EndVector(v.size()));
1627 #ifndef FLATBUFFERS_CPP98_STL
1628 /// @brief Serialize values returned by a function into a FlatBuffer `vector`.
1629 /// This is a convenience function that takes care of iteration for you.
1630 /// @tparam T The data type of the `std::vector` elements.
1631 /// @param f A function that takes the current iteration 0..vector_size-1 and
1632 /// returns any type that you can construct a FlatBuffers vector out of.
1633 /// @return Returns a typed `Offset` into the serialized data indicating
1634 /// where the vector is stored.
1635 template<typename T> Offset<Vector<T>> CreateVector(size_t vector_size,
1636 const std::function<T (size_t i)> &f) {
1637 std::vector<T> elems(vector_size);
1638 for (size_t i = 0; i < vector_size; i++) elems[i] = f(i);
1639 return CreateVector(elems);
1644 /// @brief Serialize values returned by a function into a FlatBuffer `vector`.
1645 /// This is a convenience function that takes care of iteration for you.
1646 /// @tparam T The data type of the `std::vector` elements.
1647 /// @param f A function that takes the current iteration 0..vector_size-1,
1648 /// and the state parameter returning any type that you can construct a
1649 /// FlatBuffers vector out of.
1650 /// @param state State passed to f.
1651 /// @return Returns a typed `Offset` into the serialized data indicating
1652 /// where the vector is stored.
1653 template<typename T, typename F, typename S>
1654 Offset<Vector<T>> CreateVector(size_t vector_size, F f, S *state) {
1655 std::vector<T> elems(vector_size);
1656 for (size_t i = 0; i < vector_size; i++) elems[i] = f(i, state);
1657 return CreateVector(elems);
1660 /// @brief Serialize a `std::vector<std::string>` into a FlatBuffer `vector`.
1661 /// This is a convenience function for a common case.
1662 /// @param v A const reference to the `std::vector` to serialize into the
1663 /// buffer as a `vector`.
1664 /// @return Returns a typed `Offset` into the serialized data indicating
1665 /// where the vector is stored.
1666 Offset<Vector<Offset<String>>> CreateVectorOfStrings(
1667 const std::vector<std::string> &v) {
1668 std::vector<Offset<String>> offsets(v.size());
1669 for (size_t i = 0; i < v.size(); i++) offsets[i] = CreateString(v[i]);
1670 return CreateVector(offsets);
1673 /// @brief Serialize an array of structs into a FlatBuffer `vector`.
1674 /// @tparam T The data type of the struct array elements.
1675 /// @param[in] v A pointer to the array of type `T` to serialize into the
1676 /// buffer as a `vector`.
1677 /// @param[in] len The number of elements to serialize.
1678 /// @return Returns a typed `Offset` into the serialized data indicating
1679 /// where the vector is stored.
1680 template<typename T>
1681 Offset<Vector<const T *>> CreateVectorOfStructs(const T *v, size_t len) {
1682 StartVector(len * sizeof(T) / AlignOf<T>(), AlignOf<T>());
1683 PushBytes(reinterpret_cast<const uint8_t *>(v), sizeof(T) * len);
1684 return Offset<Vector<const T *>>(EndVector(len));
1687 /// @brief Serialize an array of native structs into a FlatBuffer `vector`.
1688 /// @tparam T The data type of the struct array elements.
1689 /// @tparam S The data type of the native struct array elements.
1690 /// @param[in] v A pointer to the array of type `S` to serialize into the
1691 /// buffer as a `vector`.
1692 /// @param[in] len The number of elements to serialize.
1693 /// @return Returns a typed `Offset` into the serialized data indicating
1694 /// where the vector is stored.
1695 template<typename T, typename S>
1696 Offset<Vector<const T *>> CreateVectorOfNativeStructs(const S *v,
1698 extern T Pack(const S &);
1699 std::vector<T> vv(len);
1700 std::transform(v, v + len, vv.begin(), Pack);
1701 return CreateVectorOfStructs<T>(data(vv), vv.size());
1705 #ifndef FLATBUFFERS_CPP98_STL
1706 /// @brief Serialize an array of structs into a FlatBuffer `vector`.
1707 /// @tparam T The data type of the struct array elements.
1708 /// @param[in] filler A function that takes the current iteration 0..vector_size-1
1709 /// and a pointer to the struct that must be filled.
1710 /// @return Returns a typed `Offset` into the serialized data indicating
1711 /// where the vector is stored.
1712 /// This is mostly useful when flatbuffers are generated with mutation
1714 template<typename T> Offset<Vector<const T *>> CreateVectorOfStructs(
1715 size_t vector_size, const std::function<void(size_t i, T *)> &filler) {
1716 T* structs = StartVectorOfStructs<T>(vector_size);
1717 for (size_t i = 0; i < vector_size; i++) {
1721 return EndVectorOfStructs<T>(vector_size);
1726 /// @brief Serialize an array of structs into a FlatBuffer `vector`.
1727 /// @tparam T The data type of the struct array elements.
1728 /// @param[in] f A function that takes the current iteration 0..vector_size-1,
1729 /// a pointer to the struct that must be filled and the state argument.
1730 /// @param[in] state Arbitrary state to pass to f.
1731 /// @return Returns a typed `Offset` into the serialized data indicating
1732 /// where the vector is stored.
1733 /// This is mostly useful when flatbuffers are generated with mutation
1735 template<typename T, typename F, typename S>
1736 Offset<Vector<const T *>> CreateVectorOfStructs(size_t vector_size, F f,
1738 T *structs = StartVectorOfStructs<T>(vector_size);
1739 for (size_t i = 0; i < vector_size; i++) {
1740 f(i, structs, state);
1743 return EndVectorOfStructs<T>(vector_size);
1746 /// @brief Serialize a `std::vector` of structs into a FlatBuffer `vector`.
1747 /// @tparam T The data type of the `std::vector` struct elements.
1748 /// @param[in] v A const reference to the `std::vector` of structs to
1749 /// serialize into the buffer as a `vector`.
1750 /// @return Returns a typed `Offset` into the serialized data indicating
1751 /// where the vector is stored.
1752 template<typename T, typename Alloc>
1753 Offset<Vector<const T *>> CreateVectorOfStructs(
1754 const std::vector<T, Alloc> &v) {
1755 return CreateVectorOfStructs(data(v), v.size());
1758 /// @brief Serialize a `std::vector` of native structs into a FlatBuffer
1760 /// @tparam T The data type of the `std::vector` struct elements.
1761 /// @tparam S The data type of the `std::vector` native struct elements.
1762 /// @param[in] v A const reference to the `std::vector` of structs to
1763 /// serialize into the buffer as a `vector`.
1764 /// @return Returns a typed `Offset` into the serialized data indicating
1765 /// where the vector is stored.
1766 template<typename T, typename S>
1767 Offset<Vector<const T *>> CreateVectorOfNativeStructs(
1768 const std::vector<S> &v) {
1769 return CreateVectorOfNativeStructs<T, S>(data(v), v.size());
1772 /// @cond FLATBUFFERS_INTERNAL
1773 template<typename T> struct StructKeyComparator {
1774 bool operator()(const T &a, const T &b) const {
1775 return a.KeyCompareLessThan(&b);
1779 StructKeyComparator &operator=(const StructKeyComparator &);
1783 /// @brief Serialize a `std::vector` of structs into a FlatBuffer `vector`
1784 /// in sorted order.
1785 /// @tparam T The data type of the `std::vector` struct elements.
1786 /// @param[in] v A const reference to the `std::vector` of structs to
1787 /// serialize into the buffer as a `vector`.
1788 /// @return Returns a typed `Offset` into the serialized data indicating
1789 /// where the vector is stored.
1790 template<typename T>
1791 Offset<Vector<const T *>> CreateVectorOfSortedStructs(std::vector<T> *v) {
1792 return CreateVectorOfSortedStructs(data(*v), v->size());
1795 /// @brief Serialize a `std::vector` of native structs into a FlatBuffer
1796 /// `vector` in sorted order.
1797 /// @tparam T The data type of the `std::vector` struct elements.
1798 /// @tparam S The data type of the `std::vector` native struct elements.
1799 /// @param[in] v A const reference to the `std::vector` of structs to
1800 /// serialize into the buffer as a `vector`.
1801 /// @return Returns a typed `Offset` into the serialized data indicating
1802 /// where the vector is stored.
1803 template<typename T, typename S>
1804 Offset<Vector<const T *>> CreateVectorOfSortedNativeStructs(
1805 std::vector<S> *v) {
1806 return CreateVectorOfSortedNativeStructs<T, S>(data(*v), v->size());
1809 /// @brief Serialize an array of structs into a FlatBuffer `vector` in sorted
1811 /// @tparam T The data type of the struct array elements.
1812 /// @param[in] v A pointer to the array of type `T` to serialize into the
1813 /// buffer as a `vector`.
1814 /// @param[in] len The number of elements to serialize.
1815 /// @return Returns a typed `Offset` into the serialized data indicating
1816 /// where the vector is stored.
1817 template<typename T>
1818 Offset<Vector<const T *>> CreateVectorOfSortedStructs(T *v, size_t len) {
1819 std::sort(v, v + len, StructKeyComparator<T>());
1820 return CreateVectorOfStructs(v, len);
1823 /// @brief Serialize an array of native structs into a FlatBuffer `vector` in
1825 /// @tparam T The data type of the struct array elements.
1826 /// @tparam S The data type of the native struct array elements.
1827 /// @param[in] v A pointer to the array of type `S` to serialize into the
1828 /// buffer as a `vector`.
1829 /// @param[in] len The number of elements to serialize.
1830 /// @return Returns a typed `Offset` into the serialized data indicating
1831 /// where the vector is stored.
1832 template<typename T, typename S>
1833 Offset<Vector<const T *>> CreateVectorOfSortedNativeStructs(S *v,
1835 extern T Pack(const S &);
1836 typedef T (*Pack_t)(const S &);
1837 std::vector<T> vv(len);
1838 std::transform(v, v + len, vv.begin(), static_cast<Pack_t&>(Pack));
1839 return CreateVectorOfSortedStructs<T>(vv, len);
1842 /// @cond FLATBUFFERS_INTERNAL
1843 template<typename T> struct TableKeyComparator {
1844 TableKeyComparator(vector_downward &buf) : buf_(buf) {}
1845 bool operator()(const Offset<T> &a, const Offset<T> &b) const {
1846 auto table_a = reinterpret_cast<T *>(buf_.data_at(a.o));
1847 auto table_b = reinterpret_cast<T *>(buf_.data_at(b.o));
1848 return table_a->KeyCompareLessThan(table_b);
1850 vector_downward &buf_;
1853 TableKeyComparator &operator=(const TableKeyComparator &);
1857 /// @brief Serialize an array of `table` offsets as a `vector` in the buffer
1858 /// in sorted order.
1859 /// @tparam T The data type that the offset refers to.
1860 /// @param[in] v An array of type `Offset<T>` that contains the `table`
1861 /// offsets to store in the buffer in sorted order.
1862 /// @param[in] len The number of elements to store in the `vector`.
1863 /// @return Returns a typed `Offset` into the serialized data indicating
1864 /// where the vector is stored.
1865 template<typename T>
1866 Offset<Vector<Offset<T>>> CreateVectorOfSortedTables(Offset<T> *v,
1868 std::sort(v, v + len, TableKeyComparator<T>(buf_));
1869 return CreateVector(v, len);
1872 /// @brief Serialize an array of `table` offsets as a `vector` in the buffer
1873 /// in sorted order.
1874 /// @tparam T The data type that the offset refers to.
1875 /// @param[in] v An array of type `Offset<T>` that contains the `table`
1876 /// offsets to store in the buffer in sorted order.
1877 /// @return Returns a typed `Offset` into the serialized data indicating
1878 /// where the vector is stored.
1879 template<typename T>
1880 Offset<Vector<Offset<T>>> CreateVectorOfSortedTables(
1881 std::vector<Offset<T>> *v) {
1882 return CreateVectorOfSortedTables(data(*v), v->size());
1885 /// @brief Specialized version of `CreateVector` for non-copying use cases.
1886 /// Write the data any time later to the returned buffer pointer `buf`.
1887 /// @param[in] len The number of elements to store in the `vector`.
1888 /// @param[in] elemsize The size of each element in the `vector`.
1889 /// @param[out] buf A pointer to a `uint8_t` pointer that can be
1890 /// written to at a later time to serialize the data into a `vector`
1892 uoffset_t CreateUninitializedVector(size_t len, size_t elemsize,
1895 StartVector(len, elemsize);
1896 buf_.make_space(len * elemsize);
1897 auto vec_start = GetSize();
1898 auto vec_end = EndVector(len);
1899 *buf = buf_.data_at(vec_start);
1903 /// @brief Specialized version of `CreateVector` for non-copying use cases.
1904 /// Write the data any time later to the returned buffer pointer `buf`.
1905 /// @tparam T The data type of the data that will be stored in the buffer
1907 /// @param[in] len The number of elements to store in the `vector`.
1908 /// @param[out] buf A pointer to a pointer of type `T` that can be
1909 /// written to at a later time to serialize the data into a `vector`
1911 template<typename T>
1912 Offset<Vector<T>> CreateUninitializedVector(size_t len, T **buf) {
1914 return CreateUninitializedVector(len, sizeof(T),
1915 reinterpret_cast<uint8_t **>(buf));
1918 template<typename T>
1919 Offset<Vector<const T*>> CreateUninitializedVectorOfStructs(size_t len, T **buf) {
1920 return CreateUninitializedVector(len, sizeof(T),
1921 reinterpret_cast<uint8_t **>(buf));
1925 // @brief Create a vector of scalar type T given as input a vector of scalar
1926 // type U, useful with e.g. pre "enum class" enums, or any existing scalar
1927 // data of the wrong type.
1928 template<typename T, typename U>
1929 Offset<Vector<T>> CreateVectorScalarCast(const U *v, size_t len) {
1932 StartVector(len, sizeof(T));
1933 for (auto i = len; i > 0;) { PushElement(static_cast<T>(v[--i])); }
1934 return Offset<Vector<T>>(EndVector(len));
1937 /// @brief Write a struct by itself, typically to be part of a union.
1938 template<typename T> Offset<const T *> CreateStruct(const T &structobj) {
1940 Align(AlignOf<T>());
1941 buf_.push_small(structobj);
1942 return Offset<const T *>(GetSize());
1945 /// @brief The length of a FlatBuffer file header.
1946 static const size_t kFileIdentifierLength = 4;
1948 /// @brief Finish serializing a buffer by writing the root offset.
1949 /// @param[in] file_identifier If a `file_identifier` is given, the buffer
1950 /// will be prefixed with a standard FlatBuffers file header.
1951 template<typename T>
1952 void Finish(Offset<T> root, const char *file_identifier = nullptr) {
1953 Finish(root.o, file_identifier, false);
1956 /// @brief Finish a buffer with a 32 bit size field pre-fixed (size of the
1957 /// buffer following the size field). These buffers are NOT compatible
1958 /// with standard buffers created by Finish, i.e. you can't call GetRoot
1959 /// on them, you have to use GetSizePrefixedRoot instead.
1960 /// All >32 bit quantities in this buffer will be aligned when the whole
1961 /// size pre-fixed buffer is aligned.
1962 /// These kinds of buffers are useful for creating a stream of FlatBuffers.
1963 template<typename T>
1964 void FinishSizePrefixed(Offset<T> root,
1965 const char *file_identifier = nullptr) {
1966 Finish(root.o, file_identifier, true);
1969 void SwapBufAllocator(FlatBufferBuilder &other) {
1970 buf_.swap_allocator(other.buf_);
1975 // You shouldn't really be copying instances of this class.
1976 FlatBufferBuilder(const FlatBufferBuilder &);
1977 FlatBufferBuilder &operator=(const FlatBufferBuilder &);
1979 void Finish(uoffset_t root, const char *file_identifier, bool size_prefix) {
1981 buf_.clear_scratch();
1982 // This will cause the whole buffer to be aligned.
1983 PreAlign((size_prefix ? sizeof(uoffset_t) : 0) + sizeof(uoffset_t) +
1984 (file_identifier ? kFileIdentifierLength : 0),
1986 if (file_identifier) {
1987 FLATBUFFERS_ASSERT(strlen(file_identifier) == kFileIdentifierLength);
1988 PushBytes(reinterpret_cast<const uint8_t *>(file_identifier),
1989 kFileIdentifierLength);
1991 PushElement(ReferTo(root)); // Location of root.
1992 if (size_prefix) { PushElement(GetSize()); }
2001 vector_downward buf_;
2003 // Accumulating offsets of table members while it is being built.
2004 // We store these in the scratch pad of buf_, after the vtable offsets.
2005 uoffset_t num_field_loc;
2006 // Track how much of the vtable is in use, so we can output the most compact
2008 voffset_t max_voffset_;
2010 // Ensure objects are not nested.
2013 // Ensure the buffer is finished before it is being accessed.
2018 bool force_defaults_; // Serialize values equal to their defaults anyway.
2020 bool dedup_vtables_;
2022 struct StringOffsetCompare {
2023 StringOffsetCompare(const vector_downward &buf) : buf_(&buf) {}
2024 bool operator()(const Offset<String> &a, const Offset<String> &b) const {
2025 auto stra = reinterpret_cast<const String *>(buf_->data_at(a.o));
2026 auto strb = reinterpret_cast<const String *>(buf_->data_at(b.o));
2027 return StringLessThan(stra->data(), stra->size(),
2028 strb->data(), strb->size());
2030 const vector_downward *buf_;
2033 // For use with CreateSharedString. Instantiated on first use only.
2034 typedef std::set<Offset<String>, StringOffsetCompare> StringOffsetMap;
2035 StringOffsetMap *string_pool;
2038 // Allocates space for a vector of structures.
2039 // Must be completed with EndVectorOfStructs().
2040 template<typename T> T *StartVectorOfStructs(size_t vector_size) {
2041 StartVector(vector_size * sizeof(T) / AlignOf<T>(), AlignOf<T>());
2042 return reinterpret_cast<T *>(buf_.make_space(vector_size * sizeof(T)));
2045 // End the vector of structues in the flatbuffers.
2046 // Vector should have previously be started with StartVectorOfStructs().
2047 template<typename T>
2048 Offset<Vector<const T *>> EndVectorOfStructs(size_t vector_size) {
2049 return Offset<Vector<const T *>>(EndVector(vector_size));
2054 /// @cond FLATBUFFERS_INTERNAL
2055 // Helpers to get a typed pointer to the root object contained in the buffer.
2056 template<typename T> T *GetMutableRoot(void *buf) {
2058 return reinterpret_cast<T *>(
2059 reinterpret_cast<uint8_t *>(buf) +
2060 EndianScalar(*reinterpret_cast<uoffset_t *>(buf)));
2063 template<typename T> const T *GetRoot(const void *buf) {
2064 return GetMutableRoot<T>(const_cast<void *>(buf));
2067 template<typename T> const T *GetSizePrefixedRoot(const void *buf) {
2068 return GetRoot<T>(reinterpret_cast<const uint8_t *>(buf) + sizeof(uoffset_t));
2071 /// Helpers to get a typed pointer to objects that are currently being built.
2072 /// @warning Creating new objects will lead to reallocations and invalidates
2074 template<typename T>
2075 T *GetMutableTemporaryPointer(FlatBufferBuilder &fbb, Offset<T> offset) {
2076 return reinterpret_cast<T *>(fbb.GetCurrentBufferPointer() + fbb.GetSize() -
2080 template<typename T>
2081 const T *GetTemporaryPointer(FlatBufferBuilder &fbb, Offset<T> offset) {
2082 return GetMutableTemporaryPointer<T>(fbb, offset);
2085 /// @brief Get a pointer to the the file_identifier section of the buffer.
2086 /// @return Returns a const char pointer to the start of the file_identifier
2087 /// characters in the buffer. The returned char * has length
2088 /// 'flatbuffers::FlatBufferBuilder::kFileIdentifierLength'.
2089 /// This function is UNDEFINED for FlatBuffers whose schema does not include
2090 /// a file_identifier (likely points at padding or the start of a the root
2092 inline const char *GetBufferIdentifier(const void *buf, bool size_prefixed = false) {
2093 return reinterpret_cast<const char *>(buf) +
2094 ((size_prefixed) ? 2 * sizeof(uoffset_t) : sizeof(uoffset_t));
2097 // Helper to see if the identifier in a buffer has the expected value.
2098 inline bool BufferHasIdentifier(const void *buf, const char *identifier, bool size_prefixed = false) {
2099 return strncmp(GetBufferIdentifier(buf, size_prefixed), identifier,
2100 FlatBufferBuilder::kFileIdentifierLength) == 0;
2103 // Helper class to verify the integrity of a FlatBuffer
2104 class Verifier FLATBUFFERS_FINAL_CLASS {
2106 Verifier(const uint8_t *buf, size_t buf_len, uoffset_t _max_depth = 64,
2107 uoffset_t _max_tables = 1000000, bool _check_alignment = true)
2111 max_depth_(_max_depth),
2113 max_tables_(_max_tables),
2115 check_alignment_(_check_alignment)
2117 FLATBUFFERS_ASSERT(size_ < FLATBUFFERS_MAX_BUFFER_SIZE);
2120 // Central location where any verification failures register.
2121 bool Check(bool ok) const {
2123 #ifdef FLATBUFFERS_DEBUG_VERIFICATION_FAILURE
2124 FLATBUFFERS_ASSERT(ok);
2126 #ifdef FLATBUFFERS_TRACK_VERIFIER_BUFFER_SIZE
2134 // Verify any range within the buffer.
2135 bool Verify(size_t elem, size_t elem_len) const {
2137 #ifdef FLATBUFFERS_TRACK_VERIFIER_BUFFER_SIZE
2138 auto upper_bound = elem + elem_len;
2139 if (upper_bound_ < upper_bound)
2140 upper_bound_ = upper_bound;
2143 return Check(elem_len < size_ && elem <= size_ - elem_len);
2146 template<typename T> bool VerifyAlignment(size_t elem) const {
2147 return (elem & (sizeof(T) - 1)) == 0 || !check_alignment_;
2150 // Verify a range indicated by sizeof(T).
2151 template<typename T> bool Verify(size_t elem) const {
2152 return VerifyAlignment<T>(elem) && Verify(elem, sizeof(T));
2155 bool VerifyFromPointer(const uint8_t *p, size_t len) {
2156 auto o = static_cast<size_t>(p - buf_);
2157 return Verify(o, len);
2160 // Verify relative to a known-good base pointer.
2161 bool Verify(const uint8_t *base, voffset_t elem_off, size_t elem_len) const {
2162 return Verify(static_cast<size_t>(base - buf_) + elem_off, elem_len);
2165 template<typename T> bool Verify(const uint8_t *base, voffset_t elem_off)
2167 return Verify(static_cast<size_t>(base - buf_) + elem_off, sizeof(T));
2170 // Verify a pointer (may be NULL) of a table type.
2171 template<typename T> bool VerifyTable(const T *table) {
2172 return !table || table->Verify(*this);
2175 // Verify a pointer (may be NULL) of any vector type.
2176 template<typename T> bool VerifyVector(const Vector<T> *vec) const {
2177 return !vec || VerifyVectorOrString(reinterpret_cast<const uint8_t *>(vec),
2181 // Verify a pointer (may be NULL) of a vector to struct.
2182 template<typename T> bool VerifyVector(const Vector<const T *> *vec) const {
2183 return VerifyVector(reinterpret_cast<const Vector<T> *>(vec));
2186 // Verify a pointer (may be NULL) to string.
2187 bool VerifyString(const String *str) const {
2190 (VerifyVectorOrString(reinterpret_cast<const uint8_t *>(str),
2192 Verify(end, 1) && // Must have terminator
2193 Check(buf_[end] == '\0')); // Terminating byte must be 0.
2196 // Common code between vectors and strings.
2197 bool VerifyVectorOrString(const uint8_t *vec, size_t elem_size,
2198 size_t *end = nullptr) const {
2199 auto veco = static_cast<size_t>(vec - buf_);
2200 // Check we can read the size field.
2201 if (!Verify<uoffset_t>(veco)) return false;
2202 // Check the whole array. If this is a string, the byte past the array
2204 auto size = ReadScalar<uoffset_t>(vec);
2205 auto max_elems = FLATBUFFERS_MAX_BUFFER_SIZE / elem_size;
2206 if (!Check(size < max_elems))
2207 return false; // Protect against byte_size overflowing.
2208 auto byte_size = sizeof(size) + elem_size * size;
2209 if (end) *end = veco + byte_size;
2210 return Verify(veco, byte_size);
2213 // Special case for string contents, after the above has been called.
2214 bool VerifyVectorOfStrings(const Vector<Offset<String>> *vec) const {
2216 for (uoffset_t i = 0; i < vec->size(); i++) {
2217 if (!VerifyString(vec->Get(i))) return false;
2223 // Special case for table contents, after the above has been called.
2224 template<typename T> bool VerifyVectorOfTables(const Vector<Offset<T>> *vec) {
2226 for (uoffset_t i = 0; i < vec->size(); i++) {
2227 if (!vec->Get(i)->Verify(*this)) return false;
2233 __supress_ubsan__("unsigned-integer-overflow")
2234 bool VerifyTableStart(const uint8_t *table) {
2235 // Check the vtable offset.
2236 auto tableo = static_cast<size_t>(table - buf_);
2237 if (!Verify<soffset_t>(tableo)) return false;
2238 // This offset may be signed, but doing the subtraction unsigned always
2239 // gives the result we want.
2240 auto vtableo = tableo - static_cast<size_t>(ReadScalar<soffset_t>(table));
2241 // Check the vtable size field, then check vtable fits in its entirety.
2242 return VerifyComplexity() && Verify<voffset_t>(vtableo) &&
2243 VerifyAlignment<voffset_t>(ReadScalar<voffset_t>(buf_ + vtableo)) &&
2244 Verify(vtableo, ReadScalar<voffset_t>(buf_ + vtableo));
2247 template<typename T>
2248 bool VerifyBufferFromStart(const char *identifier, size_t start) {
2250 (size_ < 2 * sizeof(flatbuffers::uoffset_t) ||
2251 !BufferHasIdentifier(buf_ + start, identifier))) {
2255 // Call T::Verify, which must be in the generated code for this type.
2256 auto o = VerifyOffset(start);
2257 return o && reinterpret_cast<const T *>(buf_ + start + o)->Verify(*this)
2259 #ifdef FLATBUFFERS_TRACK_VERIFIER_BUFFER_SIZE
2260 && GetComputedSize()
2266 // Verify this whole buffer, starting with root type T.
2267 template<typename T> bool VerifyBuffer() { return VerifyBuffer<T>(nullptr); }
2269 template<typename T> bool VerifyBuffer(const char *identifier) {
2270 return VerifyBufferFromStart<T>(identifier, 0);
2273 template<typename T> bool VerifySizePrefixedBuffer(const char *identifier) {
2274 return Verify<uoffset_t>(0U) &&
2275 ReadScalar<uoffset_t>(buf_) == size_ - sizeof(uoffset_t) &&
2276 VerifyBufferFromStart<T>(identifier, sizeof(uoffset_t));
2279 uoffset_t VerifyOffset(size_t start) const {
2280 if (!Verify<uoffset_t>(start)) return 0;
2281 auto o = ReadScalar<uoffset_t>(buf_ + start);
2282 // May not point to itself.
2283 if (!Check(o != 0)) return 0;
2284 // Can't wrap around / buffers are max 2GB.
2285 if (!Check(static_cast<soffset_t>(o) >= 0)) return 0;
2286 // Must be inside the buffer to create a pointer from it (pointer outside
2288 if (!Verify(start + o, 1)) return 0;
2292 uoffset_t VerifyOffset(const uint8_t *base, voffset_t start) const {
2293 return VerifyOffset(static_cast<size_t>(base - buf_) + start);
2296 // Called at the start of a table to increase counters measuring data
2297 // structure depth and amount, and possibly bails out with false if
2298 // limits set by the constructor have been hit. Needs to be balanced
2300 bool VerifyComplexity() {
2303 return Check(depth_ <= max_depth_ && num_tables_ <= max_tables_);
2306 // Called at the end of a table to pop the depth count.
2312 // Returns the message size in bytes
2313 size_t GetComputedSize() const {
2315 #ifdef FLATBUFFERS_TRACK_VERIFIER_BUFFER_SIZE
2316 uintptr_t size = upper_bound_;
2317 // Align the size to uoffset_t
2318 size = (size - 1 + sizeof(uoffset_t)) & ~(sizeof(uoffset_t) - 1);
2319 return (size > size_) ? 0 : size;
2321 // Must turn on FLATBUFFERS_TRACK_VERIFIER_BUFFER_SIZE for this to work.
2323 FLATBUFFERS_ASSERT(false);
2330 const uint8_t *buf_;
2333 uoffset_t max_depth_;
2334 uoffset_t num_tables_;
2335 uoffset_t max_tables_;
2336 mutable size_t upper_bound_;
2337 bool check_alignment_;
2340 // Convenient way to bundle a buffer and its length, to pass it around
2341 // typed by its root.
2342 // A BufferRef does not own its buffer.
2343 struct BufferRefBase {}; // for std::is_base_of
2344 template<typename T> struct BufferRef : BufferRefBase {
2345 BufferRef() : buf(nullptr), len(0), must_free(false) {}
2346 BufferRef(uint8_t *_buf, uoffset_t _len)
2347 : buf(_buf), len(_len), must_free(false) {}
2350 if (must_free) free(buf);
2353 const T *GetRoot() const { return flatbuffers::GetRoot<T>(buf); }
2356 Verifier verifier(buf, len);
2357 return verifier.VerifyBuffer<T>(nullptr);
2365 // "structs" are flat structures that do not have an offset table, thus
2366 // always have all members present and do not support forwards/backwards
2367 // compatible extensions.
2369 class Struct FLATBUFFERS_FINAL_CLASS {
2371 template<typename T> T GetField(uoffset_t o) const {
2372 return ReadScalar<T>(&data_[o]);
2375 template<typename T> T GetStruct(uoffset_t o) const {
2376 return reinterpret_cast<T>(&data_[o]);
2379 const uint8_t *GetAddressOf(uoffset_t o) const { return &data_[o]; }
2380 uint8_t *GetAddressOf(uoffset_t o) { return &data_[o]; }
2386 // "tables" use an offset table (possibly shared) that allows fields to be
2387 // omitted and added at will, but uses an extra indirection to read.
2390 const uint8_t *GetVTable() const {
2391 return data_ - ReadScalar<soffset_t>(data_);
2394 // This gets the field offset for any of the functions below it, or 0
2395 // if the field was not present.
2396 voffset_t GetOptionalFieldOffset(voffset_t field) const {
2397 // The vtable offset is always at the start.
2398 auto vtable = GetVTable();
2399 // The first element is the size of the vtable (fields + type id + itself).
2400 auto vtsize = ReadScalar<voffset_t>(vtable);
2401 // If the field we're accessing is outside the vtable, we're reading older
2402 // data, so it's the same as if the offset was 0 (not present).
2403 return field < vtsize ? ReadScalar<voffset_t>(vtable + field) : 0;
2406 template<typename T> T GetField(voffset_t field, T defaultval) const {
2407 auto field_offset = GetOptionalFieldOffset(field);
2408 return field_offset ? ReadScalar<T>(data_ + field_offset) : defaultval;
2411 template<typename P> P GetPointer(voffset_t field) {
2412 auto field_offset = GetOptionalFieldOffset(field);
2413 auto p = data_ + field_offset;
2414 return field_offset ? reinterpret_cast<P>(p + ReadScalar<uoffset_t>(p))
2417 template<typename P> P GetPointer(voffset_t field) const {
2418 return const_cast<Table *>(this)->GetPointer<P>(field);
2421 template<typename P> P GetStruct(voffset_t field) const {
2422 auto field_offset = GetOptionalFieldOffset(field);
2423 auto p = const_cast<uint8_t *>(data_ + field_offset);
2424 return field_offset ? reinterpret_cast<P>(p) : nullptr;
2427 template<typename T> bool SetField(voffset_t field, T val, T def) {
2428 auto field_offset = GetOptionalFieldOffset(field);
2429 if (!field_offset) return IsTheSameAs(val, def);
2430 WriteScalar(data_ + field_offset, val);
2434 bool SetPointer(voffset_t field, const uint8_t *val) {
2435 auto field_offset = GetOptionalFieldOffset(field);
2436 if (!field_offset) return false;
2437 WriteScalar(data_ + field_offset,
2438 static_cast<uoffset_t>(val - (data_ + field_offset)));
2442 uint8_t *GetAddressOf(voffset_t field) {
2443 auto field_offset = GetOptionalFieldOffset(field);
2444 return field_offset ? data_ + field_offset : nullptr;
2446 const uint8_t *GetAddressOf(voffset_t field) const {
2447 return const_cast<Table *>(this)->GetAddressOf(field);
2450 bool CheckField(voffset_t field) const {
2451 return GetOptionalFieldOffset(field) != 0;
2454 // Verify the vtable of this table.
2455 // Call this once per table, followed by VerifyField once per field.
2456 bool VerifyTableStart(Verifier &verifier) const {
2457 return verifier.VerifyTableStart(data_);
2460 // Verify a particular field.
2461 template<typename T>
2462 bool VerifyField(const Verifier &verifier, voffset_t field) const {
2463 // Calling GetOptionalFieldOffset should be safe now thanks to
2465 auto field_offset = GetOptionalFieldOffset(field);
2466 // Check the actual field.
2467 return !field_offset || verifier.Verify<T>(data_, field_offset);
2470 // VerifyField for required fields.
2471 template<typename T>
2472 bool VerifyFieldRequired(const Verifier &verifier, voffset_t field) const {
2473 auto field_offset = GetOptionalFieldOffset(field);
2474 return verifier.Check(field_offset != 0) &&
2475 verifier.Verify<T>(data_, field_offset);
2478 // Versions for offsets.
2479 bool VerifyOffset(const Verifier &verifier, voffset_t field) const {
2480 auto field_offset = GetOptionalFieldOffset(field);
2481 return !field_offset || verifier.VerifyOffset(data_, field_offset);
2484 bool VerifyOffsetRequired(const Verifier &verifier, voffset_t field) const {
2485 auto field_offset = GetOptionalFieldOffset(field);
2486 return verifier.Check(field_offset != 0) &&
2487 verifier.VerifyOffset(data_, field_offset);
2491 // private constructor & copy constructor: you obtain instances of this
2492 // class by pointing to existing data only
2494 Table(const Table &other);
2499 template<typename T> void FlatBufferBuilder::Required(Offset<T> table,
2501 auto table_ptr = reinterpret_cast<const Table *>(buf_.data_at(table.o));
2502 bool ok = table_ptr->GetOptionalFieldOffset(field) != 0;
2503 // If this fails, the caller will show what field needs to be set.
2504 FLATBUFFERS_ASSERT(ok);
2508 /// @brief This can compute the start of a FlatBuffer from a root pointer, i.e.
2509 /// it is the opposite transformation of GetRoot().
2510 /// This may be useful if you want to pass on a root and have the recipient
2511 /// delete the buffer afterwards.
2512 inline const uint8_t *GetBufferStartFromRootPointer(const void *root) {
2513 auto table = reinterpret_cast<const Table *>(root);
2514 auto vtable = table->GetVTable();
2515 // Either the vtable is before the root or after the root.
2516 auto start = (std::min)(vtable, reinterpret_cast<const uint8_t *>(root));
2517 // Align to at least sizeof(uoffset_t).
2518 start = reinterpret_cast<const uint8_t *>(reinterpret_cast<uintptr_t>(start) &
2519 ~(sizeof(uoffset_t) - 1));
2520 // Additionally, there may be a file_identifier in the buffer, and the root
2521 // offset. The buffer may have been aligned to any size between
2522 // sizeof(uoffset_t) and FLATBUFFERS_MAX_ALIGNMENT (see "force_align").
2523 // Sadly, the exact alignment is only known when constructing the buffer,
2524 // since it depends on the presence of values with said alignment properties.
2525 // So instead, we simply look at the next uoffset_t values (root,
2526 // file_identifier, and alignment padding) to see which points to the root.
2527 // None of the other values can "impersonate" the root since they will either
2528 // be 0 or four ASCII characters.
2529 static_assert(FlatBufferBuilder::kFileIdentifierLength == sizeof(uoffset_t),
2530 "file_identifier is assumed to be the same size as uoffset_t");
2531 for (auto possible_roots = FLATBUFFERS_MAX_ALIGNMENT / sizeof(uoffset_t) + 1;
2532 possible_roots; possible_roots--) {
2533 start -= sizeof(uoffset_t);
2534 if (ReadScalar<uoffset_t>(start) + start ==
2535 reinterpret_cast<const uint8_t *>(root))
2538 // We didn't find the root, either the "root" passed isn't really a root,
2539 // or the buffer is corrupt.
2540 // Assert, because calling this function with bad data may cause reads
2541 // outside of buffer boundaries.
2542 FLATBUFFERS_ASSERT(false);
2546 /// @brief This return the prefixed size of a FlatBuffer.
2547 inline uoffset_t GetPrefixedSize(const uint8_t* buf){ return ReadScalar<uoffset_t>(buf); }
2549 // Base class for native objects (FlatBuffer data de-serialized into native
2550 // C++ data structures).
2551 // Contains no functionality, purely documentative.
2552 struct NativeTable {};
2554 /// @brief Function types to be used with resolving hashes into objects and
2555 /// back again. The resolver gets a pointer to a field inside an object API
2556 /// object that is of the type specified in the schema using the attribute
2557 /// `cpp_type` (it is thus important whatever you write to this address
2558 /// matches that type). The value of this field is initially null, so you
2559 /// may choose to implement a delayed binding lookup using this function
2560 /// if you wish. The resolver does the opposite lookup, for when the object
2561 /// is being serialized again.
2562 typedef uint64_t hash_value_t;
2564 #ifdef FLATBUFFERS_CPP98_STL
2565 typedef void (*resolver_function_t)(void **pointer_adr, hash_value_t hash);
2566 typedef hash_value_t (*rehasher_function_t)(void *pointer);
2568 typedef std::function<void (void **pointer_adr, hash_value_t hash)>
2569 resolver_function_t;
2570 typedef std::function<hash_value_t (void *pointer)> rehasher_function_t;
2574 // Helper function to test if a field is present, using any of the field
2575 // enums in the generated code.
2576 // `table` must be a generated table type. Since this is a template parameter,
2577 // this is not typechecked to be a subclass of Table, so beware!
2578 // Note: this function will return false for fields equal to the default
2579 // value, since they're not stored in the buffer (unless force_defaults was
2581 template<typename T>
2582 bool IsFieldPresent(const T *table, typename T::FlatBuffersVTableOffset field) {
2583 // Cast, since Table is a private baseclass of any table types.
2584 return reinterpret_cast<const Table *>(table)->CheckField(
2585 static_cast<voffset_t>(field));
2588 // Utility function for reverse lookups on the EnumNames*() functions
2589 // (in the generated C++ code)
2590 // names must be NULL terminated.
2591 inline int LookupEnum(const char **names, const char *name) {
2592 for (const char **p = names; *p; p++)
2593 if (!strcmp(*p, name)) return static_cast<int>(p - names);
2597 // These macros allow us to layout a struct with a guarantee that they'll end
2598 // up looking the same on different compilers and platforms.
2599 // It does this by disallowing the compiler to do any padding, and then
2600 // does padding itself by inserting extra padding fields that make every
2601 // element aligned to its own size.
2602 // Additionally, it manually sets the alignment of the struct as a whole,
2603 // which is typically its largest element, or a custom size set in the schema
2604 // by the force_align attribute.
2605 // These are used in the generated code only.
2608 #if defined(_MSC_VER)
2609 #define FLATBUFFERS_MANUALLY_ALIGNED_STRUCT(alignment) \
2611 struct __declspec(align(alignment))
2612 #define FLATBUFFERS_STRUCT_END(name, size) \
2614 static_assert(sizeof(name) == size, "compiler breaks packing rules")
2615 #elif defined(__GNUC__) || defined(__clang__) || defined(__ICCARM__)
2616 #define FLATBUFFERS_MANUALLY_ALIGNED_STRUCT(alignment) \
2617 _Pragma("pack(1)") \
2618 struct __attribute__((aligned(alignment)))
2619 #define FLATBUFFERS_STRUCT_END(name, size) \
2621 static_assert(sizeof(name) == size, "compiler breaks packing rules")
2623 #error Unknown compiler, please define structure alignment macros
2627 // Minimal reflection via code generation.
2628 // Besides full-fat reflection (see reflection.h) and parsing/printing by
2629 // loading schemas (see idl.h), we can also have code generation for mimimal
2630 // reflection data which allows pretty-printing and other uses without needing
2631 // a schema or a parser.
2632 // Generate code with --reflect-types (types only) or --reflect-names (names
2634 // See minireflect.h for utilities using this functionality.
2636 // These types are organized slightly differently as the ones in idl.h.
2637 enum SequenceType { ST_TABLE, ST_STRUCT, ST_UNION, ST_ENUM };
2639 // Scalars have the same order as in idl.h
2641 #define FLATBUFFERS_GEN_ELEMENTARY_TYPES(ET) \
2655 ET(ET_SEQUENCE) // See SequenceType.
2657 enum ElementaryType {
2658 #define FLATBUFFERS_ET(E) E,
2659 FLATBUFFERS_GEN_ELEMENTARY_TYPES(FLATBUFFERS_ET)
2660 #undef FLATBUFFERS_ET
2663 inline const char * const *ElementaryTypeNames() {
2664 static const char * const names[] = {
2665 #define FLATBUFFERS_ET(E) #E,
2666 FLATBUFFERS_GEN_ELEMENTARY_TYPES(FLATBUFFERS_ET)
2667 #undef FLATBUFFERS_ET
2673 // Basic type info cost just 16bits per field!
2675 uint16_t base_type : 4; // ElementaryType
2676 uint16_t is_vector : 1;
2677 int16_t sequence_ref : 11; // Index into type_refs below, or -1 for none.
2680 static_assert(sizeof(TypeCode) == 2, "TypeCode");
2684 // Signature of the static method present in each type.
2685 typedef const TypeTable *(*TypeFunction)();
2689 size_t num_elems; // of type_codes, values, names (but not type_refs).
2690 const TypeCode *type_codes; // num_elems count
2691 const TypeFunction *type_refs; // less than num_elems entries (see TypeCode).
2692 const int64_t *values; // Only set for non-consecutive enum/union or structs.
2693 const char * const *names; // Only set if compiled with --reflect-names.
2696 // String which identifies the current version of FlatBuffers.
2697 // flatbuffer_version_string is used by Google developers to identify which
2698 // applications uploaded to Google Play are using this library. This allows
2699 // the development team at Google to determine the popularity of the library.
2700 // How it works: Applications that are uploaded to the Google Play Store are
2701 // scanned for this version string. We track which applications are using it
2702 // to measure popularity. You are free to remove it (of course) but we would
2703 // appreciate if you left it in.
2705 // Weak linkage is culled by VS & doesn't work on cygwin.
2707 #if !defined(_WIN32) && !defined(__CYGWIN__)
2709 extern volatile __attribute__((weak)) const char *flatbuffer_version_string;
2710 volatile __attribute__((weak)) const char *flatbuffer_version_string =
2712 FLATBUFFERS_STRING(FLATBUFFERS_VERSION_MAJOR) "."
2713 FLATBUFFERS_STRING(FLATBUFFERS_VERSION_MINOR) "."
2714 FLATBUFFERS_STRING(FLATBUFFERS_VERSION_REVISION);
2716 #endif // !defined(_WIN32) && !defined(__CYGWIN__)
2718 #define FLATBUFFERS_DEFINE_BITMASK_OPERATORS(E, T)\
2719 inline E operator | (E lhs, E rhs){\
2720 return E(T(lhs) | T(rhs));\
2722 inline E operator & (E lhs, E rhs){\
2723 return E(T(lhs) & T(rhs));\
2725 inline E operator ^ (E lhs, E rhs){\
2726 return E(T(lhs) ^ T(rhs));\
2728 inline E operator ~ (E lhs){\
2731 inline E operator |= (E &lhs, E rhs){\
2735 inline E operator &= (E &lhs, E rhs){\
2739 inline E operator ^= (E &lhs, E rhs){\
2743 inline bool operator !(E rhs) \
2745 return !bool(T(rhs)); \
2748 } // namespace flatbuffers
2752 #endif // FLATBUFFERS_H_