Note that vectors of structs are serialized differently from tables, since structs are stored in-line in the vector. For example, to create a vector for the path field above:

</div>
<div class="language-lua">
~~~{.lua}
    -- Create a FlatBuffer vector and prepend the path locations.
    -- Note: Since we prepend the data, prepend them in reverse order.
    monster.StartPathVector(builder, 2)
    vec3.CreateVec3(builder, 1.0, 2.0, 3.0)
    vec3.CreateVec3(builder, 4.0, 5.0, 6.0)
    local path = builder:EndVector(2)

</div>
<div class="language-swift">
~~~{.swift}
  //
  let points = fbb.createVector(ofStructs: [
    Vec3(x: 1, y: 2, z: 3),
    Vec3(x: 4, y: 5, z: 6)
  ])

  // OR
  var vec3 = [
    Vec3(x: 1, y: 2, z: 3),
    Vec3(x: 4, y: 5, z: 6)
  ]
  Monster.startVectorOfVec3(2, in: &fbb)
  for i in obj {
    _ = create(struct: i)
  }
  let points = fbb.endVector(len: size)

We have now serialized the non-scalar components of the orc, so we can serialize the monster itself:

</div>
<div class="language-java">
~~~{.java}
  // Create our monster using `startMonster()` and `endMonster()`.
  Monster.startMonster(builder);
  Monster.addPos(builder, Vec3.createVec3(builder, 1.0f, 2.0f, 3.0f));
  Monster.addName(builder, name);
  Monster.addColor(builder, Color.Red);
  Monster.addHp(builder, (short)300);
  Monster.addInventory(builder, inv);
  Monster.addWeapons(builder, weapons);
  Monster.addEquippedType(builder, Equipment.Weapon);
  Monster.addEquipped(builder, axe);
  Monster.addPath(builder, path);
  int orc = Monster.endMonster(builder);

</div>
<div class="language-dart">
~~~{.dart}
  // Using the Builder API:
  // Set his hit points to 300 and his mana to 150.
  final int hp = 300;
  final int mana = 150;

  final monster = new myGame.MonsterBuilder(builder)
    ..begin()
    ..addNameOffset(name)
    ..addInventoryOffset(inventory)
    ..addWeaponsOffset(weapons)
    ..addEquippedType(myGame.EquipmentTypeId.Weapon)
    ..addEquippedOffset(axe)
    ..addHp(hp)
    ..addMana(mana)
    ..addPos(vec3Builder.finish(1.0, 2.0, 3.0))
    ..addPathOffset(path)
    ..addColor(myGame.Color.Red);

  final int orc = monster.finish();

  // -Or- using the ObjectBuilder API:
  // Set his hit points to 300 and his mana to 150.
  final int hp = 300;
  final int mana = 150;

  // Note that these parameters are optional - it is not necessary to set
  // all of them.
  // Also note that it is not necessary to `finish` the builder helpers above
  // - the generated code will automatically reuse offsets if the same object
  // is used in more than one place (e.g. the axe appearing in `weapons` and
  // `equipped`).
  final myGame.MonsterBuilder orcBuilder = new myGame.MonsterBuilder(
    name: name,
    inventory: treasure,
    weapons: weaps,
    equippedType: myGame.EquipmentTypeId.Weapon,
    equipped: axe,
    path: path,
    hp: hp,
    mana: mana,
    pos: new myGame.Vec3Builder(x: 1.0, y: 2.0, z: 3.0),
    color: myGame.Color.Red,
    path: [
        new myGame.Vec3ObjectBuilder(x: 1.0, y: 2.0, z: 3.0),
        new myGame.Vec3ObjectBuilder(x: 4.0, y: 5.0, z: 6.0)
    ]);

  final int orc = orcBuilder.finish(builder);

Note how we create Vec3 struct in-line in the table. Unlike tables, structs are simple combinations of scalars that are always stored inline, just like scalars themselves.

Important: Unlike structs, you should not nest tables or other objects, which is why we created all the strings/vectors/tables that this monster refers to before start. If you try to create any of them between start and end, you will get an assert/exception/panic depending on your language.

Note: Since we are passing 150 as the mana field, which happens to be the default value, the field will not actually be written to the buffer, since the default value will be returned on query anyway. This is a nice space savings, especially if default values are common in your data. It also means that you do not need to be worried about adding a lot of fields that are only used in a small number of instances, as it will not bloat the buffer if unused.

</div>

<div class="language-swift">
~~~{.swift}
  let start = Monster.startMonster(&builder)
  Monster.add(pos: Vec3(x: 1, y: 2, z: 3), &builder)
  Monster.add(hp: 300, &builder)
  Monster.add(name: name, &builder)
  Monster.addVectorOf(inventory: inventoryOffset, &builder)
  Monster.add(color: .red, &builder)
  Monster.addVectorOf(weapons: weaponsOffset, &builder)
  Monster.add(equippedType: .weapon, &builder)
  Monster.add(equipped: axe, &builder)
  var orc = Monster.endMonster(&builder, start: start)

Before finishing the serialization, let's take a quick look at FlatBuffer union Equipped. There are two parts to each FlatBuffer union. The first is a hidden field _type that is generated to hold the type of table referred to by the union. This allows you to know which type to cast to at runtime. Second is the union's data.

In our example, the last two things we added to our Monster were the Equipped Type and the Equipped union itself.

Here is a repetition of these lines, to help highlight them more clearly:

</div>
<div class="language-lua">
~~~{.lua}
    monster.AddEquippedType(builder, equipment.Weapon) -- Union type
    monster.AddEquipped(builder, axe) -- Union data

After you have created your buffer, you will have the offset to the root of the data in the orc variable, so you can finish the buffer by calling the appropriate finish method.

The buffer is now ready to be stored somewhere, sent over the network, be compressed, or whatever you'd like to do with it. You can access the buffer like so:

</div>
<div class="language-kotlin">
~~~{.kt}
  // This must be called after `finish()`.
  val buf = builder.dataBuffer()
  // The data in this ByteBuffer does NOT start at 0, but at buf.position().
  // The number of bytes is buf.remaining().

  // Alternatively this copies the above data out of the ByteBuffer for you:
  val buf = builder.sizedByteArray()

</div>
<div class="language-go">
~~~{.go}
  // This must be called after `Finish()`.
  buf := builder.FinishedBytes() // Of type `byte[]`.

</div>
<div class="language-dart">
~~~{.dart}
  final Uint8List buf = builder.finish(orc);

Now you can write the bytes to a file or send them over the network. Make sure your file mode (or transfer protocol) is set to BINARY, not text. If you transfer a FlatBuffer in text mode, the buffer will be corrupted, which will lead to hard to find problems when you read the buffer.

Reading Orc FlatBuffers

Now that we have successfully created an Orc FlatBuffer, the monster data can be saved, sent over a network, etc. Let's now adventure into the inverse, and access a FlatBuffer.

This section requires the same import/include, namespace, etc. requirements as before:

</div>
<div class="language-java">
~~~{.java}
  import MyGame.Sample.*; //The `flatc` generated files. (Monster, Vec3, etc.)

  import com.google.flatbuffers.FlatBufferBuilder;

</div>
<div class="language-csharp">
~~~{.cs}
  using Google.FlatBuffers;
  using MyGame.Sample; // The `flatc` generated files. (Monster, Vec3, etc.)

</div>
<div class="language-javascript">
~~~{.js}
  // The following code is an example - use your desired module flavor by transpiling from TS. 
  var flatbuffers = require('/js/flatbuffers').flatbuffers;
  var MyGame = require('./monster_generated').MyGame; // Generated by `flatc`.

  //--------------------------------------------------------------------------//

  // The following code an example for browser-based HTML/JavaScript. Use the above code
  // for JavaScript module loaders (e.g. Node.js).
  <script src="../js/flatbuffers.js"></script>
  <script src="monster_generated.js"></script> // Generated by `flatc`.

</div>
<div class="language-php">
~~~{.php}
  // It is recommended that your use PSR autoload when using FlatBuffers in PHP.
  // Here is an example from `SampleBinary.php`:
  function __autoload($class_name) {
    // The last segment of the class name matches the file name.
    $class = substr($class_name, strrpos($class_name, "\\") + 1);
    $root_dir = join(DIRECTORY_SEPARATOR, array(dirname(dirname(__FILE__)))); // `flatbuffers` root.

    // Contains the `*.php` files for the FlatBuffers library and the `flatc` generated files.
    $paths = array(join(DIRECTORY_SEPARATOR, array($root_dir, "php")),
                   join(DIRECTORY_SEPARATOR, array($root_dir, "samples", "MyGame", "Sample")));
    foreach ($paths as $path) {
      $file = join(DIRECTORY_SEPARATOR, array($path, $class . ".php"));
      if (file_exists($file)) {
        require($file);
        break;
      }
    }
  }

</div>
<div class="language-dart">
~~~{.dart}
import 'package:flat_buffers/flat_buffers.dart' as fb;
import './monster_my_game.sample_generated.dart' as myGame;

</div>
<div class="language-lobster">
~~~{.lobster}
  import from "../lobster/"  // Where to find flatbuffers.lobster
  import monster_generated

</div>

Then, assuming you have a buffer of bytes received from disk,
network, etc., you can start accessing the buffer like so:

**Again, make sure you read the bytes in BINARY mode, otherwise the code below
won't work.**

<div class="language-cpp">
~~~{.cpp}
  uint8_t *buffer_pointer = /* the data you just read */;

  // Get a pointer to the root object inside the buffer.
  auto monster = GetMonster(buffer_pointer);

  // `monster` is of type `Monster *`.
  // Note: root object pointers are NOT the same as `buffer_pointer`.
  // `GetMonster` is a convenience function that calls `GetRoot<Monster>`,
  // the latter is also available for non-root types.

</div>
<div class="language-kotlin">
~~~{.kt}
  val bytes = /* the data you just read */
  val buf = java.nio.ByteBuffer.wrap(bytes)

  // Get an accessor to the root object inside the buffer.
  Monster monster = Monster.getRootAsMonster(buf)

</div>
<div class="language-go">
~~~{.go}
  var buf []byte = /* the data you just read */

  // Get an accessor to the root object inside the buffer.
  monster := sample.GetRootAsMonster(buf, 0)

  // Note: We use `0` for the offset here, which is typical for most buffers
  // you would read. If you wanted to read from `builder.Bytes` directly, you
  // would need to pass in the offset of `builder.Head()`, as the builder
  // constructs the buffer backwards, so may not start at offset 0.

</div>
<div class="language-javascript">
~~~{.js}
  // the data you just read, as a `Uint8Array`
  // Note that the example here uses `readFileSync` from the built-in `fs` module,
  // but other methods for accessing the file contents will also work.
  var bytes = new Uint8Array(readFileSync('./monsterdata.bin'));

  var buf = new flatbuffers.ByteBuffer(bytes);

  // Get an accessor to the root object inside the buffer.
  var monster = MyGame.Sample.Monster.getRootAsMonster(buf);

</div>
<div class="language-php">
~~~{.php}
  $bytes = /* the data you just read, in a string */
  $buf = Google\FlatBuffers\ByteBuffer::wrap($bytes);

  // Get an accessor to the root object inside the buffer.
  $monster = \MyGame\Sample\Monster::GetRootAsMonster($buf);

</div>
<div class="language-dart">
~~~{.dart}
List<int> data = ... // the data, e.g. from file or network
// A generated factory constructor that will read the data.
myGame.Monster monster = new myGame.Monster(data);

-- Convert the string representation into binary array Lua structure
local buf = flatbuffers.binaryArray.New(bufAsString)

-- Get an accessor to the root object insert the buffer
local mon = monster.GetRootAsMonster(buf, 0)

</div>
<div class="language-lobster">
~~~{.lobster}
  buf = /* the data you just read, in a string */

  // Get an accessor to the root object inside the buffer.
  let monster = MyGame_Sample_GetRootAsMonster(buf)

</div>
<div class="language-swift">
~~~{.swift}
  // create a ByteBuffer(:) from an [UInt8] or Data()
  var buf = // Get your data
  // Get an accessor to the root object inside the buffer.
  let monster: Monster = try! getCheckedRoot(byteBuffer: &byteBuffer)
  // let monster: Monster = getRoot(byteBuffer: &byteBuffer)

If you look in the generated files from the schema compiler, you will see it generated accessors for all non-deprecated fields. For example:

These should hold 300, 150, and "Orc" respectively.

Note: The default value 150 wasn't stored in mana, but we are still able to retrieve it.

To access sub-objects, in the case of our pos, which is a Vec3:

</div>
<div class="language-python">
~~~{.py}
  pos = monster.Pos()
  x = pos.X()
  y = pos.Y()
  z = pos.Z()

x, y, and z will contain 1.0, 2.0, and 3.0, respectively.

Note: Had we not set pos during serialization, it would be a null-value.

Similarly, we can access elements of the inventory vector by indexing it. You can also iterate over the length of the array/vector representing the FlatBuffers vector.

</div>
<div class="language-swift">
~~~{.swift}
  // Get a the count of objects in the vector
  let count = monster.inventoryCount

  // get item at index 4
  let object = monster.inventory(at: 4)

  // or you can fetch the entire array
  let inv = monster.inventory
  // inv[4] should equal object

For vectors of tables, you can access the elements like any other vector, except you need to handle the result as a FlatBuffer table:

</div>
<div class="language-swift">
~~~{.swift}
  // Get the count of weapon objects
  let wepsCount = monster.weaponsCount

  let weapon2 = monster.weapons(at: 1)
  let weaponName = weapon2.name
  let weaponDmg = weapon2.damage

Last, we can access our Equipped FlatBuffer union. Just like when we created the union, we need to get both parts of the union: the type and the data.

We can access the type to dynamically cast the data as needed (since the union only stores a FlatBuffer table).

auto weapon_name = weapon->name()->str(); // "Axe"
auto weapon_damage = weapon->damage();    // 5

</div>
<div class="language-java">
~~~{.java}
  int unionType = monster.EquippedType();

  if (unionType == Equipment.Weapon) {
    Weapon weapon = (Weapon)monster.equipped(new Weapon()); // Requires explicit cast
                                                            // to `Weapon`.

    String weaponName = weapon.name();    // "Axe"
    short weaponDamage = weapon.damage(); // 5
  }

val weaponName = weapon.name   // "Axe"
val weaponDamage = weapon.damage // 5

</div>
<div class="language-csharp">
~~~{.cs}
  var unionType = monster.EquippedType;

  if (unionType == Equipment.Weapon) {
    var weapon = monster.Equipped<Weapon>().Value;

    var weaponName = weapon.Name;     // "Axe"
    var weaponDamage = weapon.Damage; // 5
  }

      if unionType == sample.EquipmentWeapon {
              // Create a `sample.Weapon` object that can be initialized with the contents
              // of the `flatbuffers.Table` (`unionTable`), which was populated by
              // `monster.Equipped()`.
              unionWeapon = new(sample.Weapon)
              unionWeapon.Init(unionTable.Bytes, unionTable.Pos)

              weaponName = unionWeapon.Name()
              weaponDamage = unionWeapon.Damage()
      }

</div>
<div class="language-python">
~~~{.py}
  union_type = monster.EquippedType()

  if union_type == MyGame.Sample.Equipment.Equipment().Weapon:
    # `monster.Equipped()` returns a `flatbuffers.Table`, which can be used to
    # initialize a `MyGame.Sample.Weapon.Weapon()`.
    union_weapon = MyGame.Sample.Weapon.Weapon()
    union_weapon.Init(monster.Equipped().Bytes, monster.Equipped().Pos)

    weapon_name = union_weapon.Name()     // 'Axe'
    weapon_damage = union_weapon.Damage() // 5

</div>
<div class="language-typescript">
~~~{.ts}
  let unionType = monster.equippedType();

  if (unionType == MyGame.Sample.Equipment.Weapon) {
    let weaponName = monster.equipped(new MyGame.Sample.Weapon()).name();     // 'Axe'
    let weaponDamage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5
  }

</div>
<div class="language-c">
~~~{.c}
  // Access union type field.
  if (ns(Monster_equipped_type(monster)) == ns(Equipment_Weapon)) {
      // Cast to appropriate type:
      // C allows for silent void pointer assignment, so we need no explicit cast.
      ns(Weapon_table_t) weapon = ns(Monster_equipped(monster));
      const char *weapon_name = ns(Weapon_name(weapon)); // "Axe"
      uint16_t weapon_damage = ns(Weapon_damage(weapon)); // 5
  }

var weaponName = weapon.name;     // "Axe"
var weaponDamage = weapon.damage; // 5

</div>
<div class="language-lua">
~~~{.lua}
  local unionType = mon:EquippedType()

  if unionType == equipment.Weapon then
    local unionWeapon = weapon.New()
    unionWeapon:Init(mon:Equipped().bytes, mon:Equipped().pos)

    local weaponName = unionWeapon:Name()     -- 'Axe'
    local weaponDamage = unionWeapon:Damage() -- 5
  end

  let weapon_name = union_weapon.name     // "Axe"
  let weapon_damage = union_weapon.damage // 5

</div>
<div class="language-rust">
~~~{.rs}
  // Get and test the `Equipment` union (`equipped` field).
  // `equipped_as_weapon` returns a FlatBuffer handle much like normal table
  // fields, but this will return `None` if the union is not actually of that
  // type.
  if monster.equipped_type() == Equipment::Weapon {
    let equipped = monster.equipped_as_weapon().unwrap();
    let weapon_name = equipped.name();
    let weapon_damage = equipped.damage();

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 modified 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 how we read fields using the accessors above, we can now use the mutators like so:

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 a table will return a boolean, which is false if the field we're trying to set is not 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, the mana field is equal to 150, which is the default value, so it was never stored in the buffer. Trying to call the corresponding mutate method for mana on such data will return false, and the value won't actually be modified!

One way to solve this is to 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.

If this is not sufficient, other ways of mutating FlatBuffers may be supported in your language through an object based API (--gen-object-api) or reflection. See the individual language documents for support.

Using flatc as a JSON Conversion Tool

If you are working with C, C++, or Lobster, you can parse JSON at runtime. If your language does not support JSON at the moment, flatc may provide an alternative. Using flatc is often the preferred method, as it doesn't require you to add any new code to your program. It is also efficient, since you can ship with the binary data. The drawback is that it requires an extra step for your users/developers to perform (although it may be able to be automated as part of your compilation).

JSON to binary representation

Let's say you have a JSON file that describes your monster. In this example, we will use the file flatbuffers/samples/monsterdata.json.

Here are the contents of the file:

{
  "pos": {
    "x": 1.0,
    "y": 2.0,
    "z": 3.0
  },
  "hp": 300,
  "name": "Orc",
  "weapons": [
    {
      "name": "axe",
      "damage": 100
    },
    {
      "name": "bow",
      "damage": 90
    }
  ],
  "equipped_type": "Weapon",
  "equipped": {
    "name": "bow",
    "damage": 90
  }
}

You can run this file through the flatc compiler with the -b flag and our monster.fbs schema to produce a FlatBuffer binary file.

./../flatc --binary monster.fbs monsterdata.json

The output of this will be a file monsterdata.bin, which will contain the FlatBuffer binary representation of the contents from our .json file.

FlatBuffer binary to JSON

Converting from a FlatBuffer binary representation to JSON is supported as well:

./../flatc --json --raw-binary monster.fbs -- monsterdata.bin

This will convert monsterdata.bin back to its original JSON representation. You need to pass the corresponding FlatBuffers schema so that flatc knows how to interpret the binary buffer. Since monster.fbs does not specify an explicit file_identifier for binary buffers, flatc needs to be forced into reading the .bin file using the --raw-binary option.

The FlatBuffer binary representation does not explicitly encode default values, therefore they are not present in the resulting JSON unless you specify --defaults-json.

If you intend to process the JSON with other tools, you may consider switching on --strict-json so that identifiers are quoted properly.

Note: The resulting JSON file is not necessarily identical with the original JSON. If the binary representation contains floating point numbers, floats and doubles are rounded to 6 and 12 digits, respectively, in order to represent them as decimals in the JSON document.

Advanced Features for Each Language

Vector of Unions

Some languages support storing unions directly in a vector.

// File found in tests/union_vector/union_vector.fbs
namespace Example.VectorOfUnions;

// Demonstrates the ability to have vectors of unions, and also to
// store structs and strings in unions.

table Attacker {
  sword_attack_damage: int;
}

struct Rapunzel {
  hair_length: int;
}

struct BookReader {
  books_read: int;
}

union Character {
  MuLan: Attacker,  // Can have name be different from type.
  Rapunzel,         // Or just both the same, as before.
  Belle: BookReader,
  BookFan: BookReader,
  Other: string,
  Unused: string
}

table Movie {
  main_character: Character;
  characters: [Character];
}

Creating

Analagously to how a union adds two fields to a table a vector of unions creates two different vectors: one for the union data and one for the data types.

</div>
<div class="language-kotlin">
Kotlin supports vectors of unions, but it isn't currently documented.
</div>
<div class="language-swift">
Swift supports vectors of unions, but it isn't currently documented.
</div>

#### Reading
<div class="language-csharp">
~~~{.cs}
var movie = Movie.GetRootAsMovie(fbb.DataBuffer);

for (var i = 0; i <= movie.CharactersLength; i++)
{
  if (movie.CharactersType(i) == Character.MuLan)
  {
    var mulanSwordDamage = movie.Characters<Attacker>(i).Value.SwordAttackDamage;
  }
  else if (movie.CharactersType(i) == Character.Belle)
  {
    var belleBooksRead = movie.Characters<BookReader>(i).Value.BooksRead;
  }
  else if (movie.CharactersType(i) == Character.Other)
  {
    var otherStr = movie.CharactersAsString(i);
  }
}

Further Reading

Each language has a dedicated Use in XXX page in the Programmer's Guide to cover the nuances of FlatBuffers in that language.

For your chosen language, see: