FlatBuffers
An open source project by FPL.
 All Classes Namespaces Files Functions Variables Properties Groups Pages
flatbuffers.h
Go to the documentation of this file.
1 /*
2  * Copyright 2014 Google Inc. All rights reserved.
3  *
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
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
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.
15  */
16 
17 #ifndef FLATBUFFERS_H_
18 #define FLATBUFFERS_H_
19 
20 #include <assert.h>
21 
22 #include <cstdint>
23 #include <cstddef>
24 #include <cstdlib>
25 #include <cstring>
26 #include <string>
27 #include <type_traits>
28 #include <vector>
29 #include <set>
30 #include <algorithm>
31 #include <functional>
32 #include <memory>
33 
34 /// @cond FLATBUFFERS_INTERNAL
35 #if __cplusplus <= 199711L && \
36  (!defined(_MSC_VER) || _MSC_VER < 1600) && \
37  (!defined(__GNUC__) || \
38  (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__ < 40400))
39  #error A C++11 compatible compiler with support for the auto typing is required for FlatBuffers.
40  #error __cplusplus _MSC_VER __GNUC__ __GNUC_MINOR__ __GNUC_PATCHLEVEL__
41 #endif
42 
43 #if !defined(__clang__) && \
44  defined(__GNUC__) && \
45  (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__ < 40600)
46  // Backwards compatability for g++ 4.4, and 4.5 which don't have the nullptr and constexpr
47  // keywords. Note the __clang__ check is needed, because clang presents itself as an older GNUC
48  // compiler.
49  #ifndef nullptr_t
50  const class nullptr_t {
51  public:
52  template<class T> inline operator T*() const { return 0; }
53  private:
54  void operator&() const;
55  } nullptr = {};
56  #endif
57  #ifndef constexpr
58  #define constexpr const
59  #endif
60 #endif
61 
62 // The wire format uses a little endian encoding (since that's efficient for
63 // the common platforms).
64 #if !defined(FLATBUFFERS_LITTLEENDIAN)
65  #if defined(__GNUC__) || defined(__clang__)
66  #ifdef __BIG_ENDIAN__
67  #define FLATBUFFERS_LITTLEENDIAN 0
68  #else
69  #define FLATBUFFERS_LITTLEENDIAN 1
70  #endif // __BIG_ENDIAN__
71  #elif defined(_MSC_VER)
72  #if defined(_M_PPC)
73  #define FLATBUFFERS_LITTLEENDIAN 0
74  #else
75  #define FLATBUFFERS_LITTLEENDIAN 1
76  #endif
77  #else
78  #error Unable to determine endianness, define FLATBUFFERS_LITTLEENDIAN.
79  #endif
80 #endif // !defined(FLATBUFFERS_LITTLEENDIAN)
81 
82 #define FLATBUFFERS_VERSION_MAJOR 1
83 #define FLATBUFFERS_VERSION_MINOR 0
84 #define FLATBUFFERS_VERSION_REVISION 0
85 #define FLATBUFFERS_STRING_EXPAND(X) #X
86 #define FLATBUFFERS_STRING(X) FLATBUFFERS_STRING_EXPAND(X)
87 
88 #if (!defined(_MSC_VER) || _MSC_VER > 1600) && \
89  (!defined(__GNUC__) || (__GNUC__ * 100 + __GNUC_MINOR__ >= 407))
90  #define FLATBUFFERS_FINAL_CLASS final
91 #else
92  #define FLATBUFFERS_FINAL_CLASS
93 #endif
94 
95 #if (!defined(_MSC_VER) || _MSC_VER >= 1900) && \
96  (!defined(__GNUC__) || (__GNUC__ * 100 + __GNUC_MINOR__ >= 406))
97  #define FLATBUFFERS_CONSTEXPR constexpr
98 #else
99  #define FLATBUFFERS_CONSTEXPR
100 #endif
101 
102 /// @endcond
103 
104 /// @file
105 namespace flatbuffers {
106 
107 /// @cond FLATBUFFERS_INTERNAL
108 // Our default offset / size type, 32bit on purpose on 64bit systems.
109 // Also, using a consistent offset type maintains compatibility of serialized
110 // offset values between 32bit and 64bit systems.
111 typedef uint32_t uoffset_t;
112 
113 // Signed offsets for references that can go in both directions.
114 typedef int32_t soffset_t;
115 
116 // Offset/index used in v-tables, can be changed to uint8_t in
117 // format forks to save a bit of space if desired.
118 typedef uint16_t voffset_t;
119 
120 typedef uintmax_t largest_scalar_t;
121 
122 // In 32bits, this evaluates to 2GB - 1
123 #define FLATBUFFERS_MAX_BUFFER_SIZE ((1ULL << (sizeof(soffset_t) * 8 - 1)) - 1)
124 
125 // Pointer to relinquished memory.
126 typedef std::unique_ptr<uint8_t, std::function<void(uint8_t * /* unused */)>>
127  unique_ptr_t;
128 
129 // Wrapper for uoffset_t to allow safe template specialization.
130 template<typename T> struct Offset {
131  uoffset_t o;
132  Offset() : o(0) {}
133  Offset(uoffset_t _o) : o(_o) {}
134  Offset<void> Union() const { return Offset<void>(o); }
135 };
136 
137 inline void EndianCheck() {
138  int endiantest = 1;
139  // If this fails, see FLATBUFFERS_LITTLEENDIAN above.
140  assert(*reinterpret_cast<char *>(&endiantest) == FLATBUFFERS_LITTLEENDIAN);
141  (void)endiantest;
142 }
143 
144 template<typename T> T EndianScalar(T t) {
145  #if FLATBUFFERS_LITTLEENDIAN
146  return t;
147  #else
148  #if defined(_MSC_VER)
149  #pragma push_macro("__builtin_bswap16")
150  #pragma push_macro("__builtin_bswap32")
151  #pragma push_macro("__builtin_bswap64")
152  #define __builtin_bswap16 _byteswap_ushort
153  #define __builtin_bswap32 _byteswap_ulong
154  #define __builtin_bswap64 _byteswap_uint64
155  #endif
156  // If you're on the few remaining big endian platforms, we make the bold
157  // assumption you're also on gcc/clang, and thus have bswap intrinsics:
158  if (sizeof(T) == 1) { // Compile-time if-then's.
159  return t;
160  } else if (sizeof(T) == 2) {
161  auto r = __builtin_bswap16(*reinterpret_cast<uint16_t *>(&t));
162  return *reinterpret_cast<T *>(&r);
163  } else if (sizeof(T) == 4) {
164  auto r = __builtin_bswap32(*reinterpret_cast<uint32_t *>(&t));
165  return *reinterpret_cast<T *>(&r);
166  } else if (sizeof(T) == 8) {
167  auto r = __builtin_bswap64(*reinterpret_cast<uint64_t *>(&t));
168  return *reinterpret_cast<T *>(&r);
169  } else {
170  assert(0);
171  }
172  #if defined(_MSC_VER)
173  #pragma pop_macro("__builtin_bswap16")
174  #pragma pop_macro("__builtin_bswap32")
175  #pragma pop_macro("__builtin_bswap64")
176  #endif
177  #endif
178 }
179 
180 template<typename T> T ReadScalar(const void *p) {
181  return EndianScalar(*reinterpret_cast<const T *>(p));
182 }
183 
184 template<typename T> void WriteScalar(void *p, T t) {
185  *reinterpret_cast<T *>(p) = EndianScalar(t);
186 }
187 
188 template<typename T> size_t AlignOf() {
189  #ifdef _MSC_VER
190  return __alignof(T);
191  #else
192  #ifndef alignof
193  return __alignof__(T);
194  #else
195  return alignof(T);
196  #endif
197  #endif
198 }
199 
200 // When we read serialized data from memory, in the case of most scalars,
201 // we want to just read T, but in the case of Offset, we want to actually
202 // perform the indirection and return a pointer.
203 // The template specialization below does just that.
204 // It is wrapped in a struct since function templates can't overload on the
205 // return type like this.
206 // The typedef is for the convenience of callers of this function
207 // (avoiding the need for a trailing return decltype)
208 template<typename T> struct IndirectHelper {
209  typedef T return_type;
210  static const size_t element_stride = sizeof(T);
211  static return_type Read(const uint8_t *p, uoffset_t i) {
212  return EndianScalar((reinterpret_cast<const T *>(p))[i]);
213  }
214 };
215 template<typename T> struct IndirectHelper<Offset<T>> {
216  typedef const T *return_type;
217  static const size_t element_stride = sizeof(uoffset_t);
218  static return_type Read(const uint8_t *p, uoffset_t i) {
219  p += i * sizeof(uoffset_t);
220  return reinterpret_cast<return_type>(p + ReadScalar<uoffset_t>(p));
221  }
222 };
223 template<typename T> struct IndirectHelper<const T *> {
224  typedef const T *return_type;
225  static const size_t element_stride = sizeof(T);
226  static return_type Read(const uint8_t *p, uoffset_t i) {
227  return reinterpret_cast<const T *>(p + i * sizeof(T));
228  }
229 };
230 
231 // An STL compatible iterator implementation for Vector below, effectively
232 // calling Get() for every element.
233 template<typename T, bool bConst>
234 struct VectorIterator : public
235  std::iterator < std::input_iterator_tag,
236  typename std::conditional < bConst,
237  const typename IndirectHelper<T>::return_type,
238  typename IndirectHelper<T>::return_type > ::type, uoffset_t > {
239 
240  typedef std::iterator<std::input_iterator_tag,
241  typename std::conditional<bConst,
242  const typename IndirectHelper<T>::return_type,
243  typename IndirectHelper<T>::return_type>::type, uoffset_t> super_type;
244 
245 public:
246  VectorIterator(const uint8_t *data, uoffset_t i) :
247  data_(data + IndirectHelper<T>::element_stride * i) {};
248  VectorIterator(const VectorIterator &other) : data_(other.data_) {}
249  VectorIterator(VectorIterator &&other) : data_(std::move(other.data_)) {}
250 
251  VectorIterator &operator=(const VectorIterator &other) {
252  data_ = other.data_;
253  return *this;
254  }
255 
256  VectorIterator &operator=(VectorIterator &&other) {
257  data_ = other.data_;
258  return *this;
259  }
260 
261  bool operator==(const VectorIterator& other) const {
262  return data_ == other.data_;
263  }
264 
265  bool operator!=(const VectorIterator& other) const {
266  return data_ != other.data_;
267  }
268 
269  ptrdiff_t operator-(const VectorIterator& other) const {
270  return (data_ - other.data_) / IndirectHelper<T>::element_stride;
271  }
272 
273  typename super_type::value_type operator *() const {
274  return IndirectHelper<T>::Read(data_, 0);
275  }
276 
277  typename super_type::value_type operator->() const {
278  return IndirectHelper<T>::Read(data_, 0);
279  }
280 
281  VectorIterator &operator++() {
282  data_ += IndirectHelper<T>::element_stride;
283  return *this;
284  }
285 
286  VectorIterator operator++(int) {
287  VectorIterator temp(data_);
288  data_ += IndirectHelper<T>::element_stride;
289  return temp;
290  }
291 
292 private:
293  const uint8_t *data_;
294 };
295 
296 // This is used as a helper type for accessing vectors.
297 // Vector::data() assumes the vector elements start after the length field.
298 template<typename T> class Vector {
299 public:
300  typedef VectorIterator<T, false> iterator;
301  typedef VectorIterator<T, true> const_iterator;
302 
303  uoffset_t size() const { return EndianScalar(length_); }
304 
305  // Deprecated: use size(). Here for backwards compatibility.
306  uoffset_t Length() const { return size(); }
307 
308  typedef typename IndirectHelper<T>::return_type return_type;
309 
310  return_type Get(uoffset_t i) const {
311  assert(i < size());
312  return IndirectHelper<T>::Read(Data(), i);
313  }
314 
315  return_type operator[](uoffset_t i) const { return Get(i); }
316 
317  // If this is a Vector of enums, T will be its storage type, not the enum
318  // type. This function makes it convenient to retrieve value with enum
319  // type E.
320  template<typename E> E GetEnum(uoffset_t i) const {
321  return static_cast<E>(Get(i));
322  }
323 
324  const void *GetStructFromOffset(size_t o) const {
325  return reinterpret_cast<const void *>(Data() + o);
326  }
327 
328  iterator begin() { return iterator(Data(), 0); }
329  const_iterator begin() const { return const_iterator(Data(), 0); }
330 
331  iterator end() { return iterator(Data(), size()); }
332  const_iterator end() const { return const_iterator(Data(), size()); }
333 
334  // Change elements if you have a non-const pointer to this object.
335  // Scalars only. See reflection.h, and the documentation.
336  void Mutate(uoffset_t i, T val) {
337  assert(i < size());
338  WriteScalar(data() + i, val);
339  }
340 
341  // Change an element of a vector of tables (or strings).
342  // "val" points to the new table/string, as you can obtain from
343  // e.g. reflection::AddFlatBuffer().
344  void MutateOffset(uoffset_t i, const uint8_t *val) {
345  assert(i < size());
346  assert(sizeof(T) == sizeof(uoffset_t));
347  WriteScalar(data() + i, val - (Data() + i * sizeof(uoffset_t)));
348  }
349 
350  // The raw data in little endian format. Use with care.
351  const uint8_t *Data() const {
352  return reinterpret_cast<const uint8_t *>(&length_ + 1);
353  }
354 
355  uint8_t *Data() {
356  return reinterpret_cast<uint8_t *>(&length_ + 1);
357  }
358 
359  // Similarly, but typed, much like std::vector::data
360  const T *data() const { return reinterpret_cast<const T *>(Data()); }
361  T *data() { return reinterpret_cast<T *>(Data()); }
362 
363  template<typename K> return_type LookupByKey(K key) const {
364  void *search_result = std::bsearch(&key, Data(), size(),
365  IndirectHelper<T>::element_stride, KeyCompare<K>);
366 
367  if (!search_result) {
368  return nullptr; // Key not found.
369  }
370 
371  const uint8_t *element = reinterpret_cast<const uint8_t *>(search_result);
372 
373  return IndirectHelper<T>::Read(element, 0);
374  }
375 
376 protected:
377  // This class is only used to access pre-existing data. Don't ever
378  // try to construct these manually.
379  Vector();
380 
381  uoffset_t length_;
382 
383 private:
384  template<typename K> static int KeyCompare(const void *ap, const void *bp) {
385  const K *key = reinterpret_cast<const K *>(ap);
386  const uint8_t *data = reinterpret_cast<const uint8_t *>(bp);
387  auto table = IndirectHelper<T>::Read(data, 0);
388 
389  // std::bsearch compares with the operands transposed, so we negate the
390  // result here.
391  return -table->KeyCompareWithValue(*key);
392  }
393 };
394 
395 // Represent a vector much like the template above, but in this case we
396 // don't know what the element types are (used with reflection.h).
397 class VectorOfAny {
398 public:
399  uoffset_t size() const { return EndianScalar(length_); }
400 
401  const uint8_t *Data() const {
402  return reinterpret_cast<const uint8_t *>(&length_ + 1);
403  }
404  uint8_t *Data() {
405  return reinterpret_cast<uint8_t *>(&length_ + 1);
406  }
407 protected:
408  VectorOfAny();
409 
410  uoffset_t length_;
411 };
412 
413 // Convenient helper function to get the length of any vector, regardless
414 // of wether it is null or not (the field is not set).
415 template<typename T> static inline size_t VectorLength(const Vector<T> *v) {
416  return v ? v->Length() : 0;
417 }
418 
419 struct String : public Vector<char> {
420  const char *c_str() const { return reinterpret_cast<const char *>(Data()); }
421  std::string str() const { return std::string(c_str(), Length()); }
422 
423  bool operator <(const String &o) const {
424  return strcmp(c_str(), o.c_str()) < 0;
425  }
426 };
427 
428 // Simple indirection for buffer allocation, to allow this to be overridden
429 // with custom allocation (see the FlatBufferBuilder constructor).
430 class simple_allocator {
431  public:
432  virtual ~simple_allocator() {}
433  virtual uint8_t *allocate(size_t size) const { return new uint8_t[size]; }
434  virtual void deallocate(uint8_t *p) const { delete[] p; }
435 };
436 
437 // This is a minimal replication of std::vector<uint8_t> functionality,
438 // except growing from higher to lower addresses. i.e push_back() inserts data
439 // in the lowest address in the vector.
440 class vector_downward {
441  public:
442  explicit vector_downward(size_t initial_size,
443  const simple_allocator &allocator)
444  : reserved_(initial_size),
445  buf_(allocator.allocate(reserved_)),
446  cur_(buf_ + reserved_),
447  allocator_(allocator) {
448  assert((initial_size & (sizeof(largest_scalar_t) - 1)) == 0);
449  }
450 
451  ~vector_downward() {
452  if (buf_)
453  allocator_.deallocate(buf_);
454  }
455 
456  void clear() {
457  if (buf_ == nullptr)
458  buf_ = allocator_.allocate(reserved_);
459 
460  cur_ = buf_ + reserved_;
461  }
462 
463  // Relinquish the pointer to the caller.
464  unique_ptr_t release() {
465  // Actually deallocate from the start of the allocated memory.
466  std::function<void(uint8_t *)> deleter(
467  std::bind(&simple_allocator::deallocate, allocator_, buf_));
468 
469  // Point to the desired offset.
470  unique_ptr_t retval(data(), deleter);
471 
472  // Don't deallocate when this instance is destroyed.
473  buf_ = nullptr;
474  cur_ = nullptr;
475 
476  return retval;
477  }
478 
479  size_t growth_policy(size_t bytes) {
480  return (bytes / 2) & ~(sizeof(largest_scalar_t) - 1);
481  }
482 
483  uint8_t *make_space(size_t len) {
484  if (len > static_cast<size_t>(cur_ - buf_)) {
485  auto old_size = size();
486  auto largest_align = AlignOf<largest_scalar_t>();
487  reserved_ += (std::max)(len, growth_policy(reserved_));
488  // Round up to avoid undefined behavior from unaligned loads and stores.
489  reserved_ = (reserved_ + (largest_align - 1)) & ~(largest_align - 1);
490  auto new_buf = allocator_.allocate(reserved_);
491  auto new_cur = new_buf + reserved_ - old_size;
492  memcpy(new_cur, cur_, old_size);
493  cur_ = new_cur;
494  allocator_.deallocate(buf_);
495  buf_ = new_buf;
496  }
497  cur_ -= len;
498  // Beyond this, signed offsets may not have enough range:
499  // (FlatBuffers > 2GB not supported).
500  assert(size() < FLATBUFFERS_MAX_BUFFER_SIZE);
501  return cur_;
502  }
503 
504  uoffset_t size() const {
505  assert(cur_ != nullptr && buf_ != nullptr);
506  return static_cast<uoffset_t>(reserved_ - (cur_ - buf_));
507  }
508 
509  uint8_t *data() const {
510  assert(cur_ != nullptr);
511  return cur_;
512  }
513 
514  uint8_t *data_at(size_t offset) const { return buf_ + reserved_ - offset; }
515 
516  // push() & fill() are most frequently called with small byte counts (<= 4),
517  // which is why we're using loops rather than calling memcpy/memset.
518  void push(const uint8_t *bytes, size_t num) {
519  auto dest = make_space(num);
520  for (size_t i = 0; i < num; i++) dest[i] = bytes[i];
521  }
522 
523  void fill(size_t zero_pad_bytes) {
524  auto dest = make_space(zero_pad_bytes);
525  for (size_t i = 0; i < zero_pad_bytes; i++) dest[i] = 0;
526  }
527 
528  void pop(size_t bytes_to_remove) { cur_ += bytes_to_remove; }
529 
530  private:
531  // You shouldn't really be copying instances of this class.
532  vector_downward(const vector_downward &);
533  vector_downward &operator=(const vector_downward &);
534 
535  size_t reserved_;
536  uint8_t *buf_;
537  uint8_t *cur_; // Points at location between empty (below) and used (above).
538  const simple_allocator &allocator_;
539 };
540 
541 // Converts a Field ID to a virtual table offset.
542 inline voffset_t FieldIndexToOffset(voffset_t field_id) {
543  // Should correspond to what EndTable() below builds up.
544  const int fixed_fields = 2; // Vtable size and Object Size.
545  return static_cast<voffset_t>((field_id + fixed_fields) * sizeof(voffset_t));
546 }
547 
548 // Computes how many bytes you'd have to pad to be able to write an
549 // "scalar_size" scalar if the buffer had grown to "buf_size" (downwards in
550 // memory).
551 inline size_t PaddingBytes(size_t buf_size, size_t scalar_size) {
552  return ((~buf_size) + 1) & (scalar_size - 1);
553 }
554 /// @endcond
555 
556 /// @addtogroup flatbuffers_cpp_api
557 /// @{
558 /// @class FlatBufferBuilder
559 /// @brief Helper class to hold data needed in creation of a FlatBuffer.
560 /// To serialize data, you typically call one of the `Create*()` functions in
561 /// the generated code, which in turn call a sequence of `StartTable`/
562 /// `PushElement`/`AddElement`/`EndTable`, or the builtin `CreateString`/
563 /// `CreateVector` functions. Do this is depth-first order to build up a tree to
564 /// the root. `Finish()` wraps up the buffer ready for transport.
566 /// @cond FLATBUFFERS_INTERNAL
567 FLATBUFFERS_FINAL_CLASS
568 /// @endcond
569 {
570  public:
571  /// @brief Default constructor for FlatBufferBuilder.
572  /// @param[in] initial_size The initial size of the buffer, in bytes. Defaults
573  /// to`1024`.
574  /// @param[in] allocator A pointer to the `simple_allocator` that should be
575  /// used. Defaults to `nullptr`, which means the `default_allocator` will be
576  /// be used.
577  explicit FlatBufferBuilder(uoffset_t initial_size = 1024,
578  const simple_allocator *allocator = nullptr)
579  : buf_(initial_size, allocator ? *allocator : default_allocator),
580  nested(false), finished(false), minalign_(1), force_defaults_(false),
581  string_pool(nullptr) {
582  offsetbuf_.reserve(16); // Avoid first few reallocs.
583  vtables_.reserve(16);
584  EndianCheck();
585  }
586 
587  ~FlatBufferBuilder() {
588  if (string_pool) delete string_pool;
589  }
590 
591  /// @brief Reset all the state in this FlatBufferBuilder so it can be reused
592  /// to construct another buffer.
593  void Clear() {
594  buf_.clear();
595  offsetbuf_.clear();
596  nested = false;
597  finished = false;
598  vtables_.clear();
599  minalign_ = 1;
600  if (string_pool) string_pool->clear();
601  }
602 
603  /// @brief The current size of the serialized buffer, counting from the end.
604  /// @return Returns an `uoffset_t` with the current size of the buffer.
605  uoffset_t GetSize() const { return buf_.size(); }
606 
607  /// @brief Get the serialized buffer (after you call `Finish()`).
608  /// @return Returns an `uint8_t` pointer to the FlatBuffer data inside the
609  /// buffer.
610  uint8_t *GetBufferPointer() const {
611  Finished();
612  return buf_.data();
613  }
614 
615  /// @brief Get a pointer to an unfinished buffer.
616  /// @return Returns a `uint8_t` pointer to the unfinished buffer.
617  uint8_t *GetCurrentBufferPointer() const { return buf_.data(); }
618 
619  /// @brief Get the released pointer to the serialized buffer.
620  /// @warning Do NOT attempt to use this FlatBufferBuilder afterwards!
621  /// @return The `unique_ptr` returned has a special allocator that knows how
622  /// to deallocate this pointer (since it points to the middle of an
623  /// allocation). Thus, do not mix this pointer with other `unique_ptr`'s, or
624  /// call `release()`/`reset()` on it.
625  unique_ptr_t ReleaseBufferPointer() {
626  Finished();
627  return buf_.release();
628  }
629 
630  /// @cond FLATBUFFERS_INTERNAL
631  void Finished() const {
632  // If you get this assert, you're attempting to get access a buffer
633  // which hasn't been finished yet. Be sure to call
634  // FlatBufferBuilder::Finish with your root table.
635  // If you really need to access an unfinished buffer, call
636  // GetCurrentBufferPointer instead.
637  assert(finished);
638  }
639  /// @endcond
640 
641  /// @brief In order to save space, fields that are set to their default value
642  /// don't get serialized into the buffer.
643  /// @param[in] bool fd When set to `true`, always serializes default values.
644  void ForceDefaults(bool fd) { force_defaults_ = fd; }
645 
646  /// @cond FLATBUFFERS_INTERNAL
647  void Pad(size_t num_bytes) { buf_.fill(num_bytes); }
648 
649  void Align(size_t elem_size) {
650  if (elem_size > minalign_) minalign_ = elem_size;
651  buf_.fill(PaddingBytes(buf_.size(), elem_size));
652  }
653 
654  void PushFlatBuffer(const uint8_t *bytes, size_t size) {
655  PushBytes(bytes, size);
656  finished = true;
657  }
658 
659  void PushBytes(const uint8_t *bytes, size_t size) {
660  buf_.push(bytes, size);
661  }
662 
663  void PopBytes(size_t amount) { buf_.pop(amount); }
664 
665  template<typename T> void AssertScalarT() {
666  // The code assumes power of 2 sizes and endian-swap-ability.
667  static_assert(std::is_scalar<T>::value
668  // The Offset<T> type is essentially a scalar but fails is_scalar.
669  || sizeof(T) == sizeof(Offset<void>),
670  "T must be a scalar type");
671  }
672 
673  // Write a single aligned scalar to the buffer
674  template<typename T> uoffset_t PushElement(T element) {
675  AssertScalarT<T>();
676  T litle_endian_element = EndianScalar(element);
677  Align(sizeof(T));
678  PushBytes(reinterpret_cast<uint8_t *>(&litle_endian_element), sizeof(T));
679  return GetSize();
680  }
681 
682  template<typename T> uoffset_t PushElement(Offset<T> off) {
683  // Special case for offsets: see ReferTo below.
684  return PushElement(ReferTo(off.o));
685  }
686 
687  // When writing fields, we track where they are, so we can create correct
688  // vtables later.
689  void TrackField(voffset_t field, uoffset_t off) {
690  FieldLoc fl = { off, field };
691  offsetbuf_.push_back(fl);
692  }
693 
694  // Like PushElement, but additionally tracks the field this represents.
695  template<typename T> void AddElement(voffset_t field, T e, T def) {
696  // We don't serialize values equal to the default.
697  if (e == def && !force_defaults_) return;
698  auto off = PushElement(e);
699  TrackField(field, off);
700  }
701 
702  template<typename T> void AddOffset(voffset_t field, Offset<T> off) {
703  if (!off.o) return; // An offset of 0 means NULL, don't store.
704  AddElement(field, ReferTo(off.o), static_cast<uoffset_t>(0));
705  }
706 
707  template<typename T> void AddStruct(voffset_t field, const T *structptr) {
708  if (!structptr) return; // Default, don't store.
709  Align(AlignOf<T>());
710  PushBytes(reinterpret_cast<const uint8_t *>(structptr), sizeof(T));
711  TrackField(field, GetSize());
712  }
713 
714  void AddStructOffset(voffset_t field, uoffset_t off) {
715  TrackField(field, off);
716  }
717 
718  // Offsets initially are relative to the end of the buffer (downwards).
719  // This function converts them to be relative to the current location
720  // in the buffer (when stored here), pointing upwards.
721  uoffset_t ReferTo(uoffset_t off) {
722  // Align to ensure GetSize() below is correct.
723  Align(sizeof(uoffset_t));
724  // Offset must refer to something already in buffer.
725  assert(off && off <= GetSize());
726  return GetSize() - off + static_cast<uoffset_t>(sizeof(uoffset_t));
727  }
728 
729  void NotNested() {
730  // If you hit this, you're trying to construct a Table/Vector/String
731  // during the construction of its parent table (between the MyTableBuilder
732  // and table.Finish().
733  // Move the creation of these sub-objects to above the MyTableBuilder to
734  // not get this assert.
735  // Ignoring this assert may appear to work in simple cases, but the reason
736  // it is here is that storing objects in-line may cause vtable offsets
737  // to not fit anymore. It also leads to vtable duplication.
738  assert(!nested);
739  }
740 
741  // From generated code (or from the parser), we call StartTable/EndTable
742  // with a sequence of AddElement calls in between.
743  uoffset_t StartTable() {
744  NotNested();
745  nested = true;
746  return GetSize();
747  }
748 
749  // This finishes one serialized object by generating the vtable if it's a
750  // table, comparing it against existing vtables, and writing the
751  // resulting vtable offset.
752  uoffset_t EndTable(uoffset_t start, voffset_t numfields) {
753  // If you get this assert, a corresponding StartTable wasn't called.
754  assert(nested);
755  // Write the vtable offset, which is the start of any Table.
756  // We fill it's value later.
757  auto vtableoffsetloc = PushElement<soffset_t>(0);
758  // Write a vtable, which consists entirely of voffset_t elements.
759  // It starts with the number of offsets, followed by a type id, followed
760  // by the offsets themselves. In reverse:
761  buf_.fill(numfields * sizeof(voffset_t));
762  auto table_object_size = vtableoffsetloc - start;
763  assert(table_object_size < 0x10000); // Vtable use 16bit offsets.
764  PushElement<voffset_t>(static_cast<voffset_t>(table_object_size));
765  PushElement<voffset_t>(FieldIndexToOffset(numfields));
766  // Write the offsets into the table
767  for (auto field_location = offsetbuf_.begin();
768  field_location != offsetbuf_.end();
769  ++field_location) {
770  auto pos = static_cast<voffset_t>(vtableoffsetloc - field_location->off);
771  // If this asserts, it means you've set a field twice.
772  assert(!ReadScalar<voffset_t>(buf_.data() + field_location->id));
773  WriteScalar<voffset_t>(buf_.data() + field_location->id, pos);
774  }
775  offsetbuf_.clear();
776  auto vt1 = reinterpret_cast<voffset_t *>(buf_.data());
777  auto vt1_size = ReadScalar<voffset_t>(vt1);
778  auto vt_use = GetSize();
779  // See if we already have generated a vtable with this exact same
780  // layout before. If so, make it point to the old one, remove this one.
781  for (auto it = vtables_.begin(); it != vtables_.end(); ++it) {
782  auto vt2 = reinterpret_cast<voffset_t *>(buf_.data_at(*it));
783  auto vt2_size = *vt2;
784  if (vt1_size != vt2_size || memcmp(vt2, vt1, vt1_size)) continue;
785  vt_use = *it;
786  buf_.pop(GetSize() - vtableoffsetloc);
787  break;
788  }
789  // If this is a new vtable, remember it.
790  if (vt_use == GetSize()) {
791  vtables_.push_back(vt_use);
792  }
793  // Fill the vtable offset we created above.
794  // The offset points from the beginning of the object to where the
795  // vtable is stored.
796  // Offsets default direction is downward in memory for future format
797  // flexibility (storing all vtables at the start of the file).
798  WriteScalar(buf_.data_at(vtableoffsetloc),
799  static_cast<soffset_t>(vt_use) -
800  static_cast<soffset_t>(vtableoffsetloc));
801 
802  nested = false;
803  return vtableoffsetloc;
804  }
805 
806  // This checks a required field has been set in a given table that has
807  // just been constructed.
808  template<typename T> void Required(Offset<T> table, voffset_t field) {
809  auto table_ptr = buf_.data_at(table.o);
810  auto vtable_ptr = table_ptr - ReadScalar<soffset_t>(table_ptr);
811  bool ok = ReadScalar<voffset_t>(vtable_ptr + field) != 0;
812  // If this fails, the caller will show what field needs to be set.
813  assert(ok);
814  (void)ok;
815  }
816 
817  uoffset_t StartStruct(size_t alignment) {
818  Align(alignment);
819  return GetSize();
820  }
821 
822  uoffset_t EndStruct() { return GetSize(); }
823 
824  void ClearOffsets() { offsetbuf_.clear(); }
825 
826  // Aligns such that when "len" bytes are written, an object can be written
827  // after it with "alignment" without padding.
828  void PreAlign(size_t len, size_t alignment) {
829  buf_.fill(PaddingBytes(GetSize() + len, alignment));
830  }
831  template<typename T> void PreAlign(size_t len) {
832  AssertScalarT<T>();
833  PreAlign(len, sizeof(T));
834  }
835  /// @endcond
836 
837  /// @brief Store a string in the buffer, which can contain any binary data.
838  /// @param[in] str A const char pointer to the data to be stored as a string.
839  /// @param[in] len The number of bytes that should be stored from `str`.
840  /// @return Returns the offset in the buffer where the string starts.
841  Offset<String> CreateString(const char *str, size_t len) {
842  NotNested();
843  PreAlign<uoffset_t>(len + 1); // Always 0-terminated.
844  buf_.fill(1);
845  PushBytes(reinterpret_cast<const uint8_t *>(str), len);
846  PushElement(static_cast<uoffset_t>(len));
847  return Offset<String>(GetSize());
848  }
849 
850  /// @brief Store a string in the buffer, which is null-terminated.
851  /// @param[in] str A const char pointer to a C-string to add to the buffer.
852  /// @return Returns the offset in the buffer where the string starts.
853  Offset<String> CreateString(const char *str) {
854  return CreateString(str, strlen(str));
855  }
856 
857  /// @brief Store a string in the buffer, which can contain any binary data.
858  /// @param[in] str A const reference to a std::string to store in the buffer.
859  /// @return Returns the offset in the buffer where the string starts.
860  Offset<String> CreateString(const std::string &str) {
861  return CreateString(str.c_str(), str.length());
862  }
863 
864  /// @brief Store a string in the buffer, which can contain any binary data.
865  /// @param[in] str A const pointer to a `String` struct to add to the buffer.
866  /// @return Returns the offset in the buffer where the string starts
867  Offset<String> CreateString(const String *str) {
868  return CreateString(str->c_str(), str->Length());
869  }
870 
871  /// @brief Store a string in the buffer, which can contain any binary data.
872  /// If a string with this exact contents has already been serialized before,
873  /// instead simply returns the offset of the existing string.
874  /// @param[in] str A const char pointer to the data to be stored as a string.
875  /// @param[in] len The number of bytes that should be stored from `str`.
876  /// @return Returns the offset in the buffer where the string starts.
877  Offset<String> CreateSharedString(const char *str, size_t len) {
878  if (!string_pool)
879  string_pool = new StringOffsetMap(StringOffsetCompare(buf_));
880  auto size_before_string = buf_.size();
881  // Must first serialize the string, since the set is all offsets into
882  // buffer.
883  auto off = CreateString(str, len);
884  auto it = string_pool->find(off);
885  // If it exists we reuse existing serialized data!
886  if (it != string_pool->end()) {
887  // We can remove the string we serialized.
888  buf_.pop(buf_.size() - size_before_string);
889  return *it;
890  }
891  // Record this string for future use.
892  string_pool->insert(off);
893  return off;
894  }
895 
896  /// @brief Store a string in the buffer, which null-terminated.
897  /// If a string with this exact contents has already been serialized before,
898  /// instead simply returns the offset of the existing string.
899  /// @param[in] str A const char pointer to a C-string to add to the buffer.
900  /// @return Returns the offset in the buffer where the string starts.
901  Offset<String> CreateSharedString(const char *str) {
902  return CreateSharedString(str, strlen(str));
903  }
904 
905  /// @brief Store a string in the buffer, which can contain any binary data.
906  /// If a string with this exact contents has already been serialized before,
907  /// instead simply returns the offset of the existing string.
908  /// @param[in] str A const reference to a std::string to store in the buffer.
909  /// @return Returns the offset in the buffer where the string starts.
910  Offset<String> CreateSharedString(const std::string &str) {
911  return CreateSharedString(str.c_str(), str.length());
912  }
913 
914  /// @brief Store a string in the buffer, which can contain any binary data.
915  /// If a string with this exact contents has already been serialized before,
916  /// instead simply returns the offset of the existing string.
917  /// @param[in] str A const pointer to a `String` struct to add to the buffer.
918  /// @return Returns the offset in the buffer where the string starts
919  Offset<String> CreateSharedString(const String *str) {
920  return CreateSharedString(str->c_str(), str->Length());
921  }
922 
923  /// @cond FLATBUFFERS_INTERNAL
924  uoffset_t EndVector(size_t len) {
925  assert(nested); // Hit if no corresponding StartVector.
926  nested = false;
927  return PushElement(static_cast<uoffset_t>(len));
928  }
929 
930  void StartVector(size_t len, size_t elemsize) {
931  NotNested();
932  nested = true;
933  PreAlign<uoffset_t>(len * elemsize);
934  PreAlign(len * elemsize, elemsize); // Just in case elemsize > uoffset_t.
935  }
936 
937  // Call this right before StartVector/CreateVector if you want to force the
938  // alignment to be something different than what the element size would
939  // normally dictate.
940  // This is useful when storing a nested_flatbuffer in a vector of bytes,
941  // or when storing SIMD floats, etc.
942  void ForceVectorAlignment(size_t len, size_t elemsize, size_t alignment) {
943  PreAlign(len * elemsize, alignment);
944  }
945 
946  uint8_t *ReserveElements(size_t len, size_t elemsize) {
947  return buf_.make_space(len * elemsize);
948  }
949  /// @endcond
950 
951  /// @brief Serialize an array into a FlatBuffer `vector`.
952  /// @tparam T The data type of the array elements.
953  /// @param[in] v A pointer to the array of type `T` to serialize into the
954  /// buffer as a `vector`.
955  /// @param[in] len The number of elements to serialize.
956  /// @return Returns a typed `Offset` into the serialized data indicating
957  /// where the vector is stored.
958  template<typename T> Offset<Vector<T>> CreateVector(const T *v, size_t len) {
959  StartVector(len, sizeof(T));
960  for (auto i = len; i > 0; ) {
961  PushElement(v[--i]);
962  }
963  return Offset<Vector<T>>(EndVector(len));
964  }
965 
966  /// @brief Serialize a `std::vector` into a FlatBuffer `vector`.
967  /// @tparam T The data type of the `std::vector` elements.
968  /// @param v A const reference to the `std::vector` to serialize into the
969  /// buffer as a `vector`.
970  /// @return Returns a typed `Offset` into the serialized data indicating
971  /// where the vector is stored.
972  template<typename T> Offset<Vector<T>> CreateVector(const std::vector<T> &v) {
973  return CreateVector(v.data(), v.size());
974  }
975 
976  /// @brief Serialize an array of structs into a FlatBuffer `vector`.
977  /// @tparam T The data type of the struct array elements.
978  /// @param[in] v A pointer to the array of type `T` to serialize into the
979  /// buffer as a `vector`.
980  /// @param[in] len The number of elements to serialize.
981  /// @return Returns a typed `Offset` into the serialized data indicating
982  /// where the vector is stored.
983  template<typename T> Offset<Vector<const T *>> CreateVectorOfStructs(
984  const T *v, size_t len) {
985  StartVector(len * sizeof(T) / AlignOf<T>(), AlignOf<T>());
986  PushBytes(reinterpret_cast<const uint8_t *>(v), sizeof(T) * len);
987  return Offset<Vector<const T *>>(EndVector(len));
988  }
989 
990  /// @brief Serialize a `std::vector` of structs into a FlatBuffer `vector`.
991  /// @tparam T The data type of the `std::vector` struct elements.
992  /// @param[in]] v A const reference to the `std::vector` of structs to
993  /// serialize into the buffer as a `vector`.
994  /// @return Returns a typed `Offset` into the serialized data indicating
995  /// where the vector is stored.
996  template<typename T> Offset<Vector<const T *>> CreateVectorOfStructs(
997  const std::vector<T> &v) {
998  return CreateVectorOfStructs(v.data(), v.size());
999  }
1000 
1001  /// @cond FLATBUFFERS_INTERNAL
1002  template<typename T>
1003  struct TableKeyComparator {
1004  TableKeyComparator(vector_downward& buf) : buf_(buf) {}
1005  bool operator()(const Offset<T> &a, const Offset<T> &b) const {
1006  auto table_a = reinterpret_cast<T *>(buf_.data_at(a.o));
1007  auto table_b = reinterpret_cast<T *>(buf_.data_at(b.o));
1008  return table_a->KeyCompareLessThan(table_b);
1009  }
1010  vector_downward& buf_;
1011 
1012  private:
1013  TableKeyComparator& operator= (const TableKeyComparator&);
1014  };
1015  /// @endcond
1016 
1017  /// @brief Serialize an array of `table` offsets as a `vector` in the buffer
1018  /// in sorted order.
1019  /// @tparam T The data type that the offset refers to.
1020  /// @param[in] v An array of type `Offset<T>` that contains the `table`
1021  /// offsets to store in the buffer in sorted order.
1022  /// @param[in] len The number of elements to store in the `vector`.
1023  /// @return Returns a typed `Offset` into the serialized data indicating
1024  /// where the vector is stored.
1025  template<typename T> Offset<Vector<Offset<T>>> CreateVectorOfSortedTables(
1026  Offset<T> *v, size_t len) {
1027  std::sort(v, v + len, TableKeyComparator<T>(buf_));
1028  return CreateVector(v, len);
1029  }
1030 
1031  /// @brief Serialize an array of `table` offsets as a `vector` in the buffer
1032  /// in sorted order.
1033  /// @tparam T The data type that the offset refers to.
1034  /// @param[in] v An array of type `Offset<T>` that contains the `table`
1035  /// offsets to store in the buffer in sorted order.
1036  /// @return Returns a typed `Offset` into the serialized data indicating
1037  /// where the vector is stored.
1038  template<typename T> Offset<Vector<Offset<T>>> CreateVectorOfSortedTables(
1039  std::vector<Offset<T>> *v) {
1040  return CreateVectorOfSortedTables(v->data(), v->size());
1041  }
1042 
1043  /// @brief Specialized version of `CreateVector` for non-copying use cases.
1044  /// Write the data any time later to the returned buffer pointer `buf`.
1045  /// @param[in] len The number of elements to store in the `vector`.
1046  /// @param[in] elemsize The size of each element in the `vector`.
1047  /// @param[out] buf A pointer to a `uint8_t` pointer that can be
1048  /// written to at a later time to serialize the data into a `vector`
1049  /// in the buffer.
1050  uoffset_t CreateUninitializedVector(size_t len, size_t elemsize,
1051  uint8_t **buf) {
1052  NotNested();
1053  StartVector(len, elemsize);
1054  buf_.make_space(len * elemsize);
1055  auto vec_start = GetSize();
1056  auto vec_end = EndVector(len);
1057  *buf = buf_.data_at(vec_start);
1058  return vec_end;
1059  }
1060 
1061  /// @brief Specialized version of `CreateVector` for non-copying use cases.
1062  /// Write the data any time later to the returned buffer pointer `buf`.
1063  /// @tparam T The data type of the data that will be stored in the buffer
1064  /// as a `vector`.
1065  /// @param[in] len The number of elements to store in the `vector`.
1066  /// @param[out] buf A pointer to a pointer of type `T` that can be
1067  /// written to at a later time to serialize the data into a `vector`
1068  /// in the buffer.
1069  template<typename T> Offset<Vector<T>> CreateUninitializedVector(
1070  size_t len, T **buf) {
1071  return CreateUninitializedVector(len, sizeof(T),
1072  reinterpret_cast<uint8_t **>(buf));
1073  }
1074 
1075  /// @brief The length of a FlatBuffer file header.
1076  static const size_t kFileIdentifierLength = 4;
1077 
1078  /// @brief Finish serializing a buffer by writing the root offset.
1079  /// @param[in] file_identifier If a `file_identifier` is given, the buffer
1080  /// will be prefixed with a standard FlatBuffers file header.
1081  template<typename T> void Finish(Offset<T> root,
1082  const char *file_identifier = nullptr) {
1083  NotNested();
1084  // This will cause the whole buffer to be aligned.
1085  PreAlign(sizeof(uoffset_t) + (file_identifier ? kFileIdentifierLength : 0),
1086  minalign_);
1087  if (file_identifier) {
1088  assert(strlen(file_identifier) == kFileIdentifierLength);
1089  buf_.push(reinterpret_cast<const uint8_t *>(file_identifier),
1090  kFileIdentifierLength);
1091  }
1092  PushElement(ReferTo(root.o)); // Location of root.
1093  finished = true;
1094  }
1095 
1096  private:
1097  // You shouldn't really be copying instances of this class.
1099  FlatBufferBuilder &operator=(const FlatBufferBuilder &);
1100 
1101  struct FieldLoc {
1102  uoffset_t off;
1103  voffset_t id;
1104  };
1105 
1106  simple_allocator default_allocator;
1107 
1108  vector_downward buf_;
1109 
1110  // Accumulating offsets of table members while it is being built.
1111  std::vector<FieldLoc> offsetbuf_;
1112 
1113  // Ensure objects are not nested.
1114  bool nested;
1115 
1116  // Ensure the buffer is finished before it is being accessed.
1117  bool finished;
1118 
1119  std::vector<uoffset_t> vtables_; // todo: Could make this into a map?
1120 
1121  size_t minalign_;
1122 
1123  bool force_defaults_; // Serialize values equal to their defaults anyway.
1124 
1125  struct StringOffsetCompare {
1126  StringOffsetCompare(const vector_downward &buf) : buf_(&buf) {}
1127  bool operator() (const Offset<String> &a, const Offset<String> &b) const {
1128  auto stra = reinterpret_cast<const String *>(buf_->data_at(a.o));
1129  auto strb = reinterpret_cast<const String *>(buf_->data_at(b.o));
1130  return strncmp(stra->c_str(), strb->c_str(),
1131  std::min(stra->size(), strb->size()) + 1) < 0;
1132  }
1133  const vector_downward *buf_;
1134  };
1135 
1136  // For use with CreateSharedString. Instantiated on first use only.
1137  typedef std::set<Offset<String>, StringOffsetCompare> StringOffsetMap;
1138  StringOffsetMap *string_pool;
1139 };
1140 /// @}
1141 
1142 /// @cond FLATBUFFERS_INTERNAL
1143 // Helpers to get a typed pointer to the root object contained in the buffer.
1144 template<typename T> T *GetMutableRoot(void *buf) {
1145  EndianCheck();
1146  return reinterpret_cast<T *>(reinterpret_cast<uint8_t *>(buf) +
1147  EndianScalar(*reinterpret_cast<uoffset_t *>(buf)));
1148 }
1149 
1150 template<typename T> const T *GetRoot(const void *buf) {
1151  return GetMutableRoot<T>(const_cast<void *>(buf));
1152 }
1153 
1154 // Helper to see if the identifier in a buffer has the expected value.
1155 inline bool BufferHasIdentifier(const void *buf, const char *identifier) {
1156  return strncmp(reinterpret_cast<const char *>(buf) + sizeof(uoffset_t),
1157  identifier, FlatBufferBuilder::kFileIdentifierLength) == 0;
1158 }
1159 
1160 // Helper class to verify the integrity of a FlatBuffer
1161 class Verifier FLATBUFFERS_FINAL_CLASS {
1162  public:
1163  Verifier(const uint8_t *buf, size_t buf_len, size_t _max_depth = 64,
1164  size_t _max_tables = 1000000)
1165  : buf_(buf), end_(buf + buf_len), depth_(0), max_depth_(_max_depth),
1166  num_tables_(0), max_tables_(_max_tables)
1167  {}
1168 
1169  // Central location where any verification failures register.
1170  bool Check(bool ok) const {
1171  #ifdef FLATBUFFERS_DEBUG_VERIFICATION_FAILURE
1172  assert(ok);
1173  #endif
1174  return ok;
1175  }
1176 
1177  // Verify any range within the buffer.
1178  bool Verify(const void *elem, size_t elem_len) const {
1179  return Check(elem_len <= (size_t) (end_ - buf_) &&
1180  elem >= buf_ &&
1181  elem <= end_ - elem_len);
1182  }
1183 
1184  // Verify a range indicated by sizeof(T).
1185  template<typename T> bool Verify(const void *elem) const {
1186  return Verify(elem, sizeof(T));
1187  }
1188 
1189  // Verify a pointer (may be NULL) of a table type.
1190  template<typename T> bool VerifyTable(const T *table) {
1191  return !table || table->Verify(*this);
1192  }
1193 
1194  // Verify a pointer (may be NULL) of any vector type.
1195  template<typename T> bool Verify(const Vector<T> *vec) const {
1196  const uint8_t *end;
1197  return !vec ||
1198  VerifyVector(reinterpret_cast<const uint8_t *>(vec), sizeof(T),
1199  &end);
1200  }
1201 
1202  // Verify a pointer (may be NULL) of a vector to struct.
1203  template<typename T> bool Verify(const Vector<const T *> *vec) const {
1204  return Verify(reinterpret_cast<const Vector<T> *>(vec));
1205  }
1206 
1207  // Verify a pointer (may be NULL) to string.
1208  bool Verify(const String *str) const {
1209  const uint8_t *end;
1210  return !str ||
1211  (VerifyVector(reinterpret_cast<const uint8_t *>(str), 1, &end) &&
1212  Verify(end, 1) && // Must have terminator
1213  Check(*end == '\0')); // Terminating byte must be 0.
1214  }
1215 
1216  // Common code between vectors and strings.
1217  bool VerifyVector(const uint8_t *vec, size_t elem_size,
1218  const uint8_t **end) const {
1219  // Check we can read the size field.
1220  if (!Verify<uoffset_t>(vec)) return false;
1221  // Check the whole array. If this is a string, the byte past the array
1222  // must be 0.
1223  auto size = ReadScalar<uoffset_t>(vec);
1224  auto max_elems = FLATBUFFERS_MAX_BUFFER_SIZE / elem_size;
1225  if (!Check(size < max_elems))
1226  return false; // Protect against byte_size overflowing.
1227  auto byte_size = sizeof(size) + elem_size * size;
1228  *end = vec + byte_size;
1229  return Verify(vec, byte_size);
1230  }
1231 
1232  // Special case for string contents, after the above has been called.
1233  bool VerifyVectorOfStrings(const Vector<Offset<String>> *vec) const {
1234  if (vec) {
1235  for (uoffset_t i = 0; i < vec->size(); i++) {
1236  if (!Verify(vec->Get(i))) return false;
1237  }
1238  }
1239  return true;
1240  }
1241 
1242  // Special case for table contents, after the above has been called.
1243  template<typename T> bool VerifyVectorOfTables(const Vector<Offset<T>> *vec) {
1244  if (vec) {
1245  for (uoffset_t i = 0; i < vec->size(); i++) {
1246  if (!vec->Get(i)->Verify(*this)) return false;
1247  }
1248  }
1249  return true;
1250  }
1251 
1252  // Verify this whole buffer, starting with root type T.
1253  template<typename T> bool VerifyBuffer() {
1254  // Call T::Verify, which must be in the generated code for this type.
1255  return Verify<uoffset_t>(buf_) &&
1256  reinterpret_cast<const T *>(buf_ + ReadScalar<uoffset_t>(buf_))->
1257  Verify(*this);
1258  }
1259 
1260  // Called at the start of a table to increase counters measuring data
1261  // structure depth and amount, and possibly bails out with false if
1262  // limits set by the constructor have been hit. Needs to be balanced
1263  // with EndTable().
1264  bool VerifyComplexity() {
1265  depth_++;
1266  num_tables_++;
1267  return Check(depth_ <= max_depth_ && num_tables_ <= max_tables_);
1268  }
1269 
1270  // Called at the end of a table to pop the depth count.
1271  bool EndTable() {
1272  depth_--;
1273  return true;
1274  }
1275 
1276  private:
1277  const uint8_t *buf_;
1278  const uint8_t *end_;
1279  size_t depth_;
1280  size_t max_depth_;
1281  size_t num_tables_;
1282  size_t max_tables_;
1283 };
1284 
1285 // "structs" are flat structures that do not have an offset table, thus
1286 // always have all members present and do not support forwards/backwards
1287 // compatible extensions.
1288 
1289 class Struct FLATBUFFERS_FINAL_CLASS {
1290  public:
1291  template<typename T> T GetField(uoffset_t o) const {
1292  return ReadScalar<T>(&data_[o]);
1293  }
1294 
1295  template<typename T> T GetPointer(uoffset_t o) const {
1296  auto p = &data_[o];
1297  return reinterpret_cast<T>(p + ReadScalar<uoffset_t>(p));
1298  }
1299 
1300  template<typename T> T GetStruct(uoffset_t o) const {
1301  return reinterpret_cast<T>(&data_[o]);
1302  }
1303 
1304  const uint8_t *GetAddressOf(uoffset_t o) const { return &data_[o]; }
1305  uint8_t *GetAddressOf(uoffset_t o) { return &data_[o]; }
1306 
1307  private:
1308  uint8_t data_[1];
1309 };
1310 
1311 // "tables" use an offset table (possibly shared) that allows fields to be
1312 // omitted and added at will, but uses an extra indirection to read.
1313 class Table {
1314  public:
1315  // This gets the field offset for any of the functions below it, or 0
1316  // if the field was not present.
1317  voffset_t GetOptionalFieldOffset(voffset_t field) const {
1318  // The vtable offset is always at the start.
1319  auto vtable = data_ - ReadScalar<soffset_t>(data_);
1320  // The first element is the size of the vtable (fields + type id + itself).
1321  auto vtsize = ReadScalar<voffset_t>(vtable);
1322  // If the field we're accessing is outside the vtable, we're reading older
1323  // data, so it's the same as if the offset was 0 (not present).
1324  return field < vtsize ? ReadScalar<voffset_t>(vtable + field) : 0;
1325  }
1326 
1327  template<typename T> T GetField(voffset_t field, T defaultval) const {
1328  auto field_offset = GetOptionalFieldOffset(field);
1329  return field_offset ? ReadScalar<T>(data_ + field_offset) : defaultval;
1330  }
1331 
1332  template<typename P> P GetPointer(voffset_t field) {
1333  auto field_offset = GetOptionalFieldOffset(field);
1334  auto p = data_ + field_offset;
1335  return field_offset
1336  ? reinterpret_cast<P>(p + ReadScalar<uoffset_t>(p))
1337  : nullptr;
1338  }
1339  template<typename P> P GetPointer(voffset_t field) const {
1340  return const_cast<Table *>(this)->GetPointer<P>(field);
1341  }
1342 
1343  template<typename P> P GetStruct(voffset_t field) const {
1344  auto field_offset = GetOptionalFieldOffset(field);
1345  auto p = const_cast<uint8_t *>(data_ + field_offset);
1346  return field_offset ? reinterpret_cast<P>(p) : nullptr;
1347  }
1348 
1349  template<typename T> bool SetField(voffset_t field, T val) {
1350  auto field_offset = GetOptionalFieldOffset(field);
1351  if (!field_offset) return false;
1352  WriteScalar(data_ + field_offset, val);
1353  return true;
1354  }
1355 
1356  bool SetPointer(voffset_t field, const uint8_t *val) {
1357  auto field_offset = GetOptionalFieldOffset(field);
1358  if (!field_offset) return false;
1359  WriteScalar(data_ + field_offset, val - (data_ + field_offset));
1360  return true;
1361  }
1362 
1363  uint8_t *GetAddressOf(voffset_t field) {
1364  auto field_offset = GetOptionalFieldOffset(field);
1365  return field_offset ? data_ + field_offset : nullptr;
1366  }
1367  const uint8_t *GetAddressOf(voffset_t field) const {
1368  return const_cast<Table *>(this)->GetAddressOf(field);
1369  }
1370 
1371  uint8_t *GetVTable() { return data_ - ReadScalar<soffset_t>(data_); }
1372 
1373  bool CheckField(voffset_t field) const {
1374  return GetOptionalFieldOffset(field) != 0;
1375  }
1376 
1377  // Verify the vtable of this table.
1378  // Call this once per table, followed by VerifyField once per field.
1379  bool VerifyTableStart(Verifier &verifier) const {
1380  // Check the vtable offset.
1381  if (!verifier.Verify<soffset_t>(data_)) return false;
1382  auto vtable = data_ - ReadScalar<soffset_t>(data_);
1383  // Check the vtable size field, then check vtable fits in its entirety.
1384  return verifier.VerifyComplexity() &&
1385  verifier.Verify<voffset_t>(vtable) &&
1386  (ReadScalar<voffset_t>(vtable) & (sizeof(voffset_t) - 1)) == 0 &&
1387  verifier.Verify(vtable, ReadScalar<voffset_t>(vtable));
1388  }
1389 
1390  // Verify a particular field.
1391  template<typename T> bool VerifyField(const Verifier &verifier,
1392  voffset_t field) const {
1393  // Calling GetOptionalFieldOffset should be safe now thanks to
1394  // VerifyTable().
1395  auto field_offset = GetOptionalFieldOffset(field);
1396  // Check the actual field.
1397  return !field_offset || verifier.Verify<T>(data_ + field_offset);
1398  }
1399 
1400  // VerifyField for required fields.
1401  template<typename T> bool VerifyFieldRequired(const Verifier &verifier,
1402  voffset_t field) const {
1403  auto field_offset = GetOptionalFieldOffset(field);
1404  return verifier.Check(field_offset != 0) &&
1405  verifier.Verify<T>(data_ + field_offset);
1406  }
1407 
1408  private:
1409  // private constructor & copy constructor: you obtain instances of this
1410  // class by pointing to existing data only
1411  Table();
1412  Table(const Table &other);
1413 
1414  uint8_t data_[1];
1415 };
1416 
1417 // Helper function to test if a field is present, using any of the field
1418 // enums in the generated code.
1419 // `table` must be a generated table type. Since this is a template parameter,
1420 // this is not typechecked to be a subclass of Table, so beware!
1421 // Note: this function will return false for fields equal to the default
1422 // value, since they're not stored in the buffer (unless force_defaults was
1423 // used).
1424 template<typename T> bool IsFieldPresent(const T *table, voffset_t field) {
1425  // Cast, since Table is a private baseclass of any table types.
1426  return reinterpret_cast<const Table *>(table)->CheckField(field);
1427 }
1428 
1429 // Utility function for reverse lookups on the EnumNames*() functions
1430 // (in the generated C++ code)
1431 // names must be NULL terminated.
1432 inline int LookupEnum(const char **names, const char *name) {
1433  for (const char **p = names; *p; p++)
1434  if (!strcmp(*p, name))
1435  return static_cast<int>(p - names);
1436  return -1;
1437 }
1438 
1439 // These macros allow us to layout a struct with a guarantee that they'll end
1440 // up looking the same on different compilers and platforms.
1441 // It does this by disallowing the compiler to do any padding, and then
1442 // does padding itself by inserting extra padding fields that make every
1443 // element aligned to its own size.
1444 // Additionally, it manually sets the alignment of the struct as a whole,
1445 // which is typically its largest element, or a custom size set in the schema
1446 // by the force_align attribute.
1447 // These are used in the generated code only.
1448 
1449 #if defined(_MSC_VER)
1450  #define MANUALLY_ALIGNED_STRUCT(alignment) \
1451  __pragma(pack(1)); \
1452  struct __declspec(align(alignment))
1453  #define STRUCT_END(name, size) \
1454  __pragma(pack()); \
1455  static_assert(sizeof(name) == size, "compiler breaks packing rules")
1456 #elif defined(__GNUC__) || defined(__clang__)
1457  #define MANUALLY_ALIGNED_STRUCT(alignment) \
1458  _Pragma("pack(1)") \
1459  struct __attribute__((aligned(alignment)))
1460  #define STRUCT_END(name, size) \
1461  _Pragma("pack()") \
1462  static_assert(sizeof(name) == size, "compiler breaks packing rules")
1463 #else
1464  #error Unknown compiler, please define structure alignment macros
1465 #endif
1466 
1467 // String which identifies the current version of FlatBuffers.
1468 // flatbuffer_version_string is used by Google developers to identify which
1469 // applications uploaded to Google Play are using this library. This allows
1470 // the development team at Google to determine the popularity of the library.
1471 // How it works: Applications that are uploaded to the Google Play Store are
1472 // scanned for this version string. We track which applications are using it
1473 // to measure popularity. You are free to remove it (of course) but we would
1474 // appreciate if you left it in.
1475 
1476 // Weak linkage is culled by VS & doesn't work on cygwin.
1477 #if !defined(_WIN32) && !defined(__CYGWIN__)
1478 
1479 extern volatile __attribute__((weak)) const char *flatbuffer_version_string;
1480 volatile __attribute__((weak)) const char *flatbuffer_version_string =
1481  "FlatBuffers "
1482  FLATBUFFERS_STRING(FLATBUFFERS_VERSION_MAJOR) "."
1483  FLATBUFFERS_STRING(FLATBUFFERS_VERSION_MINOR) "."
1484  FLATBUFFERS_STRING(FLATBUFFERS_VERSION_REVISION);
1485 
1486 #endif // !defined(_WIN32) && !defined(__CYGWIN__)
1487 
1488 /// @endcond
1489 } // namespace flatbuffers
1490 
1491 #endif // FLATBUFFERS_H_
uoffset_t CreateUninitializedVector(size_t len, size_t elemsize, uint8_t **buf)
Specialized version of CreateVector for non-copying use cases.
Definition: flatbuffers.h:1050
Offset< Vector< Offset< T > > > CreateVectorOfSortedTables(std::vector< Offset< T >> *v)
Serialize an array of table offsets as a vector in the buffer in sorted order.
Definition: flatbuffers.h:1038
Helper class to hold data needed in creation of a FlatBuffer.
Definition: flatbuffers.h:565
uoffset_t GetSize() const
The current size of the serialized buffer, counting from the end.
Definition: flatbuffers.h:605
FlatBufferBuilder(uoffset_t initial_size=1024, const simple_allocator *allocator=nullptr)
Default constructor for FlatBufferBuilder.
Definition: flatbuffers.h:577
void Clear()
Reset all the state in this FlatBufferBuilder so it can be reused to construct another buffer...
Definition: flatbuffers.h:593
unique_ptr_t ReleaseBufferPointer()
Get the released pointer to the serialized buffer.
Definition: flatbuffers.h:625
Offset< String > CreateSharedString(const char *str)
Store a string in the buffer, which null-terminated.
Definition: flatbuffers.h:901
Offset< String > CreateString(const char *str, size_t len)
Store a string in the buffer, which can contain any binary data.
Definition: flatbuffers.h:841
void ForceDefaults(bool fd)
In order to save space, fields that are set to their default value don't get serialized into the buff...
Definition: flatbuffers.h:644
static const size_t kFileIdentifierLength
The length of a FlatBuffer file header.
Definition: flatbuffers.h:1076
Offset< String > CreateString(const String *str)
Store a string in the buffer, which can contain any binary data.
Definition: flatbuffers.h:867
Offset< String > CreateSharedString(const String *str)
Store a string in the buffer, which can contain any binary data.
Definition: flatbuffers.h:919
Offset< Vector< const T * > > CreateVectorOfStructs(const T *v, size_t len)
Serialize an array of structs into a FlatBuffer vector.
Definition: flatbuffers.h:983
Offset< String > CreateString(const char *str)
Store a string in the buffer, which is null-terminated.
Definition: flatbuffers.h:853
Offset< String > CreateString(const std::string &str)
Store a string in the buffer, which can contain any binary data.
Definition: flatbuffers.h:860
Offset< Vector< T > > CreateVector(const std::vector< T > &v)
Serialize a std::vector into a FlatBuffer vector.
Definition: flatbuffers.h:972
Offset< Vector< T > > CreateUninitializedVector(size_t len, T **buf)
Specialized version of CreateVector for non-copying use cases.
Definition: flatbuffers.h:1069
uint8_t * GetCurrentBufferPointer() const
Get a pointer to an unfinished buffer.
Definition: flatbuffers.h:617
Offset< Vector< T > > CreateVector(const T *v, size_t len)
Serialize an array into a FlatBuffer vector.
Definition: flatbuffers.h:958
Offset< String > CreateSharedString(const std::string &str)
Store a string in the buffer, which can contain any binary data.
Definition: flatbuffers.h:910
Offset< Vector< Offset< T > > > CreateVectorOfSortedTables(Offset< T > *v, size_t len)
Serialize an array of table offsets as a vector in the buffer in sorted order.
Definition: flatbuffers.h:1025
Offset< String > CreateSharedString(const char *str, size_t len)
Store a string in the buffer, which can contain any binary data.
Definition: flatbuffers.h:877
Offset< Vector< const T * > > CreateVectorOfStructs(const std::vector< T > &v)
Serialize a std::vector of structs into a FlatBuffer vector.
Definition: flatbuffers.h:996
void Finish(Offset< T > root, const char *file_identifier=nullptr)
Finish serializing a buffer by writing the root offset.
Definition: flatbuffers.h:1081
uint8_t * GetBufferPointer() const
Get the serialized buffer (after you call Finish()).
Definition: flatbuffers.h:610