diff --git a/docs/html/md__compiler.html b/docs/html/md__compiler.html index 03cae7935..e6ee2b060 100644 --- a/docs/html/md__compiler.html +++ b/docs/html/md__compiler.html @@ -70,6 +70,7 @@ $(document).ready(function(){initNavTree('md__compiler.html','');});
  • --strict-json : Require & generate strict JSON (field names are enclosed in quotes, no trailing commas in tables/vectors). By default, no quotes are required/generated, and trailing commas are allowed.
  • --no-prefix : Don't prefix enum values in generated C++ by their enum type.
  • --gen-includes : Generate include statements for included schemas the generated file depends on (C++).
  • +
  • --gen-mutable : Generate additional non-const accessors for mutating FlatBuffers in-place.
  • --proto: Expect input files to be .proto files (protocol buffers). Output the corresponding .fbs file. Currently supports: package, message, enum. Does not support, but will skip without error: import, option. Does not support, will generate error: service, extend, extensions, oneof, group, custom options, nested declarations.
  • diff --git a/docs/html/md__cpp_usage.html b/docs/html/md__cpp_usage.html index b21e09184..2217273de 100644 --- a/docs/html/md__cpp_usage.html +++ b/docs/html/md__cpp_usage.html @@ -102,7 +102,21 @@ $(document).ready(function(){initNavTree('md__cpp_usage.html','');});
    auto inv = monster->inventory();
    assert(inv);
    assert(inv->Get(9) == 9);
    -

    Storing maps / dictionaries in a FlatBuffer

    +

    Mutating FlatBuffers

    +

    As you saw above, typically once you have created a FlatBuffer, it is read-only from that moment on. There are however cases where you have just received a FlatBuffer, and you'd like to modify something about it before sending it on to another recipient. With the above functionality, you'd have to generate an entirely new FlatBuffer, while tracking what you modify in your own data structures. This is inconvenient.

    +

    For this reason FlatBuffers can also be mutated in-place. While this is great for making small fixes to an existing buffer, you generally want to create buffers from scratch whenever possible, since it is much more efficient and the API is much more general purpose.

    +

    To get non-const accessors, invoke flatc with --gen-mutable.

    +

    Similar to the reading API above, you now can:

    +
    auto monster = GetMutableMonster(buffer_pointer); // non-const
    +
    monster->mutate_hp(10); // Set table field.
    +
    monster->mutable_pos()->mutate_z(4); // Set struct field.
    +
    monster->mutable_inventory()->Mutate(0, 1); // Set vector element.
    +

    We use the somewhat verbose term mutate instead of set to indicate that this is a special use case, not to be confused with the default way of constructing FlatBuffer data.

    +

    After the above mutations, you can send on the FlatBuffer to a new recipient without any further work!

    +

    Note that any mutate_ functions on tables return a bool, which is false if the field we're trying to set isn't present in the buffer. Fields are not present if they weren't set, or even if they happen to be equal to the default value. For example, in the creation code above we set the mana field to 150, which is the default value, so it was never stored in the buffer. Trying to call mutate_mana() on such data will return false, and the value won't actually be modified!

    +

    There's two ways around this. First, you can call ForceDefaults() on a FlatBufferBuilder to force all fields you set to actually be written. This of course increases the size of the buffer somewhat, but this may be acceptable for a mutable buffer.

    +

    Alternatively, you can use mutation functions that are able to insert fields and change the size of things. These functions are expensive however, since they need to resize the buffer and create new data.

    +

    Storing maps / dictionaries in a FlatBuffer

    FlatBuffers doesn't support maps natively, but there is support to emulate their behavior with vectors and binary search, which means you can have fast lookups directly from a FlatBuffer without having to unpack your data into a std::map or similar.

    To use it: