Bigfoot

docs/source/languages/cpp.md

@@ -57,7 +57,7 @@ a `char *` array, which you pass to `GetMonster()`.
 
 ```cpp
     #include "flatbuffers/flatbuffers.h"
-    #include "monster_test_generated.h"
+    #include "monster_test_generate.h"
     #include <iostream> // C++ header file for printing
     #include <fstream> // C++ header file for file access
 
@@ -242,6 +242,42 @@ provide the following functions to aide in the serialization process:
     }
 ```
 
+-   `bigfoot_ref_wrapper("type")` (on a struct) together with `bigfoot_ref("type")`
+    (on a field of that struct type): Bigfoot-specific sugar for a
+    UUID-addressed reference to another native type. `bigfoot_ref_wrapper`
+    marks a struct as a reference-wrapper template (e.g. Bigfoot's
+    `HardReference`/`SoftReference`); `bigfoot_ref` on a field of that type
+    names the referenced native type, e.g. `bigfoot_ref: "::Bigfoot::AssetA"`
+    on a `HardReference`-typed field with `bigfoot_ref_wrapper:
+    "::Bigfoot::HardReference"` produces the field's native type
+    `::Bigfoot::HardReference<::Bigfoot::AssetA>` (auto-deriving a
+    `native_type_pack_name` of `HardReferenceAssetA`, same short-name
+    convention as `native_type_pack_name`). Unlike a hand-written
+    `native_type`, `bigfoot_ref` also emits, directly into the generated
+    header:
+    -   a forward declaration of the referenced type (so the referencing
+        schema's generated header never needs that type's real definition -
+        only the wrapper template's constructor and a `GetUUID()` accessor
+        are used, and those don't require the referenced type to be
+        complete), and
+    -   `inline` `Pack<Name>`/`UnPack<Name>` definitions for it (so no
+        hand-written implementation is required anywhere).
+
+```cpp
+    struct HardReference (bigfoot_ref_wrapper: "::Bigfoot::HardReference") {
+      uuid: UUID;
+    }
+
+    table AssetB {
+      ref_a: HardReference (bigfoot_ref: "::Bigfoot::AssetA");
+    }
+```
+
+    is enough on its own - no forward declaration of `::Bigfoot::AssetA` and
+    no `flatbuffers::Pack/UnPackHardReferenceAssetA` implementation need to
+    be written by hand. `bigfoot_ref` is only valid on fields whose type is a
+    struct (or vector of structs) that declares `bigfoot_ref_wrapper`.
+
 -   `native_type("type")` (on a table): Tables can also be represented with
 native types. For example, the following schema:
 
@@ -337,6 +373,27 @@ constructor in the following format: `custom_str_class(const char *, size_t)`.
 Please note that the character array is not guaranteed to be NULL terminated,
 you should always use the provided size to determine end of string.
 
+## Using different vector type
+
+By default the object tree's vector fields are built out of `std::vector`,
+but you can influence this either globally (using the `--cpp-vector-type`
+argument to `flatc`) or per field using the `cpp_vector_type` attribute, to
+use any other vector-like template type (e.g. `eastl::vector`).
+
+The type must be a template taking a single element type argument
+(`my_vector<T>`), and must support the following member functions:
+`resize()`, `reserve()`, `size()`, `data()`, `operator[]`, `emplace_back()`,
+and `begin()`/`end()`. This matches the subset of `std::vector`'s interface
+that generated code relies on.
+
+Note that unlike `std::vector<bool>`, the custom vector type must not use a
+bit-packed specialization for `bool` elements, since generated code accesses
+`data()` as a contiguous `bool` array.
+
+As with custom string types, the header defining the custom vector type is
+not automatically included; use `--cpp-include` to add the necessary
+`#include`.
+
 ## Reflection (& Resizing)
 
 There is experimental support for reflection in FlatBuffers, allowing you to