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 = buf_.make_space(len * elemsize);
1055  return EndVector(len);
1056  }
1057 
1058  /// @brief Specialized version of `CreateVector` for non-copying use cases.
1059  /// Write the data any time later to the returned buffer pointer `buf`.
1060  /// @tparam T The data type of the data that will be stored in the buffer
1061  /// as a `vector`.
1062  /// @param[in] len The number of elements to store in the `vector`.
1063  /// @param[out] buf A pointer to a pointer of type `T` that can be
1064  /// written to at a later time to serialize the data into a `vector`
1065  /// in the buffer.
1066  template<typename T> Offset<Vector<T>> CreateUninitializedVector(
1067  size_t len, T **buf) {
1068  return CreateUninitializedVector(len, sizeof(T),
1069  reinterpret_cast<uint8_t **>(buf));
1070  }
1071 
1072  /// @brief The length of a FlatBuffer file header.
1073  static const size_t kFileIdentifierLength = 4;
1074 
1075  /// @brief Finish serializing a buffer by writing the root offset.
1076  /// @param[in] file_identifier If a `file_identifier` is given, the buffer
1077  /// will be prefixed with a standard FlatBuffers file header.
1078  template<typename T> void Finish(Offset<T> root,
1079  const char *file_identifier = nullptr) {
1080  NotNested();
1081  // This will cause the whole buffer to be aligned.
1082  PreAlign(sizeof(uoffset_t) + (file_identifier ? kFileIdentifierLength : 0),
1083  minalign_);
1084  if (file_identifier) {
1085  assert(strlen(file_identifier) == kFileIdentifierLength);
1086  buf_.push(reinterpret_cast<const uint8_t *>(file_identifier),
1087  kFileIdentifierLength);
1088  }
1089  PushElement(ReferTo(root.o)); // Location of root.
1090  finished = true;
1091  }
1092 
1093  private:
1094  // You shouldn't really be copying instances of this class.
1096  FlatBufferBuilder &operator=(const FlatBufferBuilder &);
1097 
1098  struct FieldLoc {
1099  uoffset_t off;
1100  voffset_t id;
1101  };
1102 
1103  simple_allocator default_allocator;
1104 
1105  vector_downward buf_;
1106 
1107  // Accumulating offsets of table members while it is being built.
1108  std::vector<FieldLoc> offsetbuf_;
1109 
1110  // Ensure objects are not nested.
1111  bool nested;
1112 
1113  // Ensure the buffer is finished before it is being accessed.
1114  bool finished;
1115 
1116  std::vector<uoffset_t> vtables_; // todo: Could make this into a map?
1117 
1118  size_t minalign_;
1119 
1120  bool force_defaults_; // Serialize values equal to their defaults anyway.
1121 
1122  struct StringOffsetCompare {
1123  StringOffsetCompare(const vector_downward &buf) : buf_(&buf) {}
1124  bool operator() (const Offset<String> &a, const Offset<String> &b) const {
1125  auto stra = reinterpret_cast<const String *>(buf_->data_at(a.o));
1126  auto strb = reinterpret_cast<const String *>(buf_->data_at(b.o));
1127  return strncmp(stra->c_str(), strb->c_str(),
1128  std::min(stra->size(), strb->size()) + 1) < 0;
1129  }
1130  const vector_downward *buf_;
1131  };
1132 
1133  // For use with CreateSharedString. Instantiated on first use only.
1134  typedef std::set<Offset<String>, StringOffsetCompare> StringOffsetMap;
1135  StringOffsetMap *string_pool;
1136 };
1137 /// @}
1138 
1139 /// @cond FLATBUFFERS_INTERNAL
1140 // Helpers to get a typed pointer to the root object contained in the buffer.
1141 template<typename T> T *GetMutableRoot(void *buf) {
1142  EndianCheck();
1143  return reinterpret_cast<T *>(reinterpret_cast<uint8_t *>(buf) +
1144  EndianScalar(*reinterpret_cast<uoffset_t *>(buf)));
1145 }
1146 
1147 template<typename T> const T *GetRoot(const void *buf) {
1148  return GetMutableRoot<T>(const_cast<void *>(buf));
1149 }
1150 
1151 // Helper to see if the identifier in a buffer has the expected value.
1152 inline bool BufferHasIdentifier(const void *buf, const char *identifier) {
1153  return strncmp(reinterpret_cast<const char *>(buf) + sizeof(uoffset_t),
1154  identifier, FlatBufferBuilder::kFileIdentifierLength) == 0;
1155 }
1156 
1157 // Helper class to verify the integrity of a FlatBuffer
1158 class Verifier FLATBUFFERS_FINAL_CLASS {
1159  public:
1160  Verifier(const uint8_t *buf, size_t buf_len, size_t _max_depth = 64,
1161  size_t _max_tables = 1000000)
1162  : buf_(buf), end_(buf + buf_len), depth_(0), max_depth_(_max_depth),
1163  num_tables_(0), max_tables_(_max_tables)
1164  {}
1165 
1166  // Central location where any verification failures register.
1167  bool Check(bool ok) const {
1168  #ifdef FLATBUFFERS_DEBUG_VERIFICATION_FAILURE
1169  assert(ok);
1170  #endif
1171  return ok;
1172  }
1173 
1174  // Verify any range within the buffer.
1175  bool Verify(const void *elem, size_t elem_len) const {
1176  return Check(elem_len <= (size_t) (end_ - buf_) &&
1177  elem >= buf_ &&
1178  elem <= end_ - elem_len);
1179  }
1180 
1181  // Verify a range indicated by sizeof(T).
1182  template<typename T> bool Verify(const void *elem) const {
1183  return Verify(elem, sizeof(T));
1184  }
1185 
1186  // Verify a pointer (may be NULL) of a table type.
1187  template<typename T> bool VerifyTable(const T *table) {
1188  return !table || table->Verify(*this);
1189  }
1190 
1191  // Verify a pointer (may be NULL) of any vector type.
1192  template<typename T> bool Verify(const Vector<T> *vec) const {
1193  const uint8_t *end;
1194  return !vec ||
1195  VerifyVector(reinterpret_cast<const uint8_t *>(vec), sizeof(T),
1196  &end);
1197  }
1198 
1199  // Verify a pointer (may be NULL) of a vector to struct.
1200  template<typename T> bool Verify(const Vector<const T *> *vec) const {
1201  return Verify(reinterpret_cast<const Vector<T> *>(vec));
1202  }
1203 
1204  // Verify a pointer (may be NULL) to string.
1205  bool Verify(const String *str) const {
1206  const uint8_t *end;
1207  return !str ||
1208  (VerifyVector(reinterpret_cast<const uint8_t *>(str), 1, &end) &&
1209  Verify(end, 1) && // Must have terminator
1210  Check(*end == '\0')); // Terminating byte must be 0.
1211  }
1212 
1213  // Common code between vectors and strings.
1214  bool VerifyVector(const uint8_t *vec, size_t elem_size,
1215  const uint8_t **end) const {
1216  // Check we can read the size field.
1217  if (!Verify<uoffset_t>(vec)) return false;
1218  // Check the whole array. If this is a string, the byte past the array
1219  // must be 0.
1220  auto size = ReadScalar<uoffset_t>(vec);
1221  auto max_elems = FLATBUFFERS_MAX_BUFFER_SIZE / elem_size;
1222  Check(size < max_elems); // Protect against byte_size overflowing.
1223  auto byte_size = sizeof(size) + elem_size * size;
1224  *end = vec + byte_size;
1225  return Verify(vec, byte_size);
1226  }
1227 
1228  // Special case for string contents, after the above has been called.
1229  bool VerifyVectorOfStrings(const Vector<Offset<String>> *vec) const {
1230  if (vec) {
1231  for (uoffset_t i = 0; i < vec->size(); i++) {
1232  if (!Verify(vec->Get(i))) return false;
1233  }
1234  }
1235  return true;
1236  }
1237 
1238  // Special case for table contents, after the above has been called.
1239  template<typename T> bool VerifyVectorOfTables(const Vector<Offset<T>> *vec) {
1240  if (vec) {
1241  for (uoffset_t i = 0; i < vec->size(); i++) {
1242  if (!vec->Get(i)->Verify(*this)) return false;
1243  }
1244  }
1245  return true;
1246  }
1247 
1248  // Verify this whole buffer, starting with root type T.
1249  template<typename T> bool VerifyBuffer() {
1250  // Call T::Verify, which must be in the generated code for this type.
1251  return Verify<uoffset_t>(buf_) &&
1252  reinterpret_cast<const T *>(buf_ + ReadScalar<uoffset_t>(buf_))->
1253  Verify(*this);
1254  }
1255 
1256  // Called at the start of a table to increase counters measuring data
1257  // structure depth and amount, and possibly bails out with false if
1258  // limits set by the constructor have been hit. Needs to be balanced
1259  // with EndTable().
1260  bool VerifyComplexity() {
1261  depth_++;
1262  num_tables_++;
1263  return Check(depth_ <= max_depth_ && num_tables_ <= max_tables_);
1264  }
1265 
1266  // Called at the end of a table to pop the depth count.
1267  bool EndTable() {
1268  depth_--;
1269  return true;
1270  }
1271 
1272  private:
1273  const uint8_t *buf_;
1274  const uint8_t *end_;
1275  size_t depth_;
1276  size_t max_depth_;
1277  size_t num_tables_;
1278  size_t max_tables_;
1279 };
1280 
1281 // "structs" are flat structures that do not have an offset table, thus
1282 // always have all members present and do not support forwards/backwards
1283 // compatible extensions.
1284 
1285 class Struct FLATBUFFERS_FINAL_CLASS {
1286  public:
1287  template<typename T> T GetField(uoffset_t o) const {
1288  return ReadScalar<T>(&data_[o]);
1289  }
1290 
1291  template<typename T> T GetPointer(uoffset_t o) const {
1292  auto p = &data_[o];
1293  return reinterpret_cast<T>(p + ReadScalar<uoffset_t>(p));
1294  }
1295 
1296  template<typename T> T GetStruct(uoffset_t o) const {
1297  return reinterpret_cast<T>(&data_[o]);
1298  }
1299 
1300  const uint8_t *GetAddressOf(uoffset_t o) const { return &data_[o]; }
1301  uint8_t *GetAddressOf(uoffset_t o) { return &data_[o]; }
1302 
1303  private:
1304  uint8_t data_[1];
1305 };
1306 
1307 // "tables" use an offset table (possibly shared) that allows fields to be
1308 // omitted and added at will, but uses an extra indirection to read.
1309 class Table {
1310  public:
1311  // This gets the field offset for any of the functions below it, or 0
1312  // if the field was not present.
1313  voffset_t GetOptionalFieldOffset(voffset_t field) const {
1314  // The vtable offset is always at the start.
1315  auto vtable = data_ - ReadScalar<soffset_t>(data_);
1316  // The first element is the size of the vtable (fields + type id + itself).
1317  auto vtsize = ReadScalar<voffset_t>(vtable);
1318  // If the field we're accessing is outside the vtable, we're reading older
1319  // data, so it's the same as if the offset was 0 (not present).
1320  return field < vtsize ? ReadScalar<voffset_t>(vtable + field) : 0;
1321  }
1322 
1323  template<typename T> T GetField(voffset_t field, T defaultval) const {
1324  auto field_offset = GetOptionalFieldOffset(field);
1325  return field_offset ? ReadScalar<T>(data_ + field_offset) : defaultval;
1326  }
1327 
1328  template<typename P> P GetPointer(voffset_t field) {
1329  auto field_offset = GetOptionalFieldOffset(field);
1330  auto p = data_ + field_offset;
1331  return field_offset
1332  ? reinterpret_cast<P>(p + ReadScalar<uoffset_t>(p))
1333  : nullptr;
1334  }
1335  template<typename P> P GetPointer(voffset_t field) const {
1336  return const_cast<Table *>(this)->GetPointer<P>(field);
1337  }
1338 
1339  template<typename P> P GetStruct(voffset_t field) const {
1340  auto field_offset = GetOptionalFieldOffset(field);
1341  auto p = const_cast<uint8_t *>(data_ + field_offset);
1342  return field_offset ? reinterpret_cast<P>(p) : nullptr;
1343  }
1344 
1345  template<typename T> bool SetField(voffset_t field, T val) {
1346  auto field_offset = GetOptionalFieldOffset(field);
1347  if (!field_offset) return false;
1348  WriteScalar(data_ + field_offset, val);
1349  return true;
1350  }
1351 
1352  bool SetPointer(voffset_t field, const uint8_t *val) {
1353  auto field_offset = GetOptionalFieldOffset(field);
1354  if (!field_offset) return false;
1355  WriteScalar(data_ + field_offset, val - (data_ + field_offset));
1356  return true;
1357  }
1358 
1359  uint8_t *GetAddressOf(voffset_t field) {
1360  auto field_offset = GetOptionalFieldOffset(field);
1361  return field_offset ? data_ + field_offset : nullptr;
1362  }
1363  const uint8_t *GetAddressOf(voffset_t field) const {
1364  return const_cast<Table *>(this)->GetAddressOf(field);
1365  }
1366 
1367  uint8_t *GetVTable() { return data_ - ReadScalar<soffset_t>(data_); }
1368 
1369  bool CheckField(voffset_t field) const {
1370  return GetOptionalFieldOffset(field) != 0;
1371  }
1372 
1373  // Verify the vtable of this table.
1374  // Call this once per table, followed by VerifyField once per field.
1375  bool VerifyTableStart(Verifier &verifier) const {
1376  // Check the vtable offset.
1377  if (!verifier.Verify<soffset_t>(data_)) return false;
1378  auto vtable = data_ - ReadScalar<soffset_t>(data_);
1379  // Check the vtable size field, then check vtable fits in its entirety.
1380  return verifier.VerifyComplexity() &&
1381  verifier.Verify<voffset_t>(vtable) &&
1382  verifier.Verify(vtable, ReadScalar<voffset_t>(vtable));
1383  }
1384 
1385  // Verify a particular field.
1386  template<typename T> bool VerifyField(const Verifier &verifier,
1387  voffset_t field) const {
1388  // Calling GetOptionalFieldOffset should be safe now thanks to
1389  // VerifyTable().
1390  auto field_offset = GetOptionalFieldOffset(field);
1391  // Check the actual field.
1392  return !field_offset || verifier.Verify<T>(data_ + field_offset);
1393  }
1394 
1395  // VerifyField for required fields.
1396  template<typename T> bool VerifyFieldRequired(const Verifier &verifier,
1397  voffset_t field) const {
1398  auto field_offset = GetOptionalFieldOffset(field);
1399  return verifier.Check(field_offset != 0) &&
1400  verifier.Verify<T>(data_ + field_offset);
1401  }
1402 
1403  private:
1404  // private constructor & copy constructor: you obtain instances of this
1405  // class by pointing to existing data only
1406  Table();
1407  Table(const Table &other);
1408 
1409  uint8_t data_[1];
1410 };
1411 
1412 // Helper function to test if a field is present, using any of the field
1413 // enums in the generated code.
1414 // `table` must be a generated table type. Since this is a template parameter,
1415 // this is not typechecked to be a subclass of Table, so beware!
1416 // Note: this function will return false for fields equal to the default
1417 // value, since they're not stored in the buffer (unless force_defaults was
1418 // used).
1419 template<typename T> bool IsFieldPresent(const T *table, voffset_t field) {
1420  // Cast, since Table is a private baseclass of any table types.
1421  return reinterpret_cast<const Table *>(table)->CheckField(field);
1422 }
1423 
1424 // Utility function for reverse lookups on the EnumNames*() functions
1425 // (in the generated C++ code)
1426 // names must be NULL terminated.
1427 inline int LookupEnum(const char **names, const char *name) {
1428  for (const char **p = names; *p; p++)
1429  if (!strcmp(*p, name))
1430  return static_cast<int>(p - names);
1431  return -1;
1432 }
1433 
1434 // These macros allow us to layout a struct with a guarantee that they'll end
1435 // up looking the same on different compilers and platforms.
1436 // It does this by disallowing the compiler to do any padding, and then
1437 // does padding itself by inserting extra padding fields that make every
1438 // element aligned to its own size.
1439 // Additionally, it manually sets the alignment of the struct as a whole,
1440 // which is typically its largest element, or a custom size set in the schema
1441 // by the force_align attribute.
1442 // These are used in the generated code only.
1443 
1444 #if defined(_MSC_VER)
1445  #define MANUALLY_ALIGNED_STRUCT(alignment) \
1446  __pragma(pack(1)); \
1447  struct __declspec(align(alignment))
1448  #define STRUCT_END(name, size) \
1449  __pragma(pack()); \
1450  static_assert(sizeof(name) == size, "compiler breaks packing rules")
1451 #elif defined(__GNUC__) || defined(__clang__)
1452  #define MANUALLY_ALIGNED_STRUCT(alignment) \
1453  _Pragma("pack(1)") \
1454  struct __attribute__((aligned(alignment)))
1455  #define STRUCT_END(name, size) \
1456  _Pragma("pack()") \
1457  static_assert(sizeof(name) == size, "compiler breaks packing rules")
1458 #else
1459  #error Unknown compiler, please define structure alignment macros
1460 #endif
1461 
1462 // String which identifies the current version of FlatBuffers.
1463 // flatbuffer_version_string is used by Google developers to identify which
1464 // applications uploaded to Google Play are using this library. This allows
1465 // the development team at Google to determine the popularity of the library.
1466 // How it works: Applications that are uploaded to the Google Play Store are
1467 // scanned for this version string. We track which applications are using it
1468 // to measure popularity. You are free to remove it (of course) but we would
1469 // appreciate if you left it in.
1470 
1471 // Weak linkage is culled by VS & doesn't work on cygwin.
1472 #if !defined(_WIN32) && !defined(__CYGWIN__)
1473 
1474 extern volatile __attribute__((weak)) const char *flatbuffer_version_string;
1475 volatile __attribute__((weak)) const char *flatbuffer_version_string =
1476  "FlatBuffers "
1477  FLATBUFFERS_STRING(FLATBUFFERS_VERSION_MAJOR) "."
1478  FLATBUFFERS_STRING(FLATBUFFERS_VERSION_MINOR) "."
1479  FLATBUFFERS_STRING(FLATBUFFERS_VERSION_REVISION);
1480 
1481 #endif // !defined(_WIN32) && !defined(__CYGWIN__)
1482 
1483 /// @endcond
1484 } // namespace flatbuffers
1485 
1486 #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:1073
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:1066
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:1078
uint8_t * GetBufferPointer() const
Get the serialized buffer (after you call Finish()).
Definition: flatbuffers.h:610