There are project files for Visual Studio and Xcode that should allow you to build the compiler flatc, the samples and the tests out of the box.
-
Alternatively, the distribution comes with a cmake file that should allow you to build project/make files for any platform. For details on cmake, see http://www.cmake.org. In brief, depending on your platform, use one of e.g.:
-
cmake -G "Unix Makefiles"
+
Alternatively, the distribution comes with a cmake file that should allow you to build project/make files for any platform. For details on cmake, see http://www.cmake.org. In brief, depending on your platform, use one of e.g.:
Then, build as normal for your platform. This should result in a flatc executable, essential for the next steps. Note that to use clang instead of gcc, you may need to set up your environment variables, e.g. CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix Makefiles".
diff --git a/docs/html/md__compiler.html b/docs/html/md__compiler.html
index fab13cd7734..21bd4d476b8 100644
--- a/docs/html/md__compiler.html
+++ b/docs/html/md__compiler.html
@@ -3,7 +3,7 @@
-
+
FlatBuffers: Using the schema compiler
@@ -32,7 +32,7 @@
The files are read and parsed in order, and can contain either schemas or data (see below). Later files can make use of definitions in earlier files. Depending on the flags passed, additional files may be generated for each file processed:
-c : Generate a C++ header for all definitions in this file (as filename_generated.h). Skips data.
diff --git a/docs/html/md__cpp_usage.html b/docs/html/md__cpp_usage.html
index 4023544f6be..386fffc8678 100644
--- a/docs/html/md__cpp_usage.html
+++ b/docs/html/md__cpp_usage.html
@@ -3,7 +3,7 @@
-
+
FlatBuffers: Use in C++
@@ -32,7 +32,7 @@
-
+
@@ -55,49 +55,39 @@
Assuming you have written a schema using the above language in say mygame.fbs (FlatBuffer Schema, though the extension doesn't matter), you've generated a C++ header called mygame_generated.h using the compiler (e.g. flatc -c mygame.fbs), you can now start using this in your program by including the header. As noted, this header relies on flatbuffers/flatbuffers.h, which should be in your include path.
Writing in C++
-
To start creating a buffer, create an instance of FlatBufferBuilder which will contain the buffer as it grows:
-
FlatBufferBuilder fbb;
-
Before we serialize a Monster, we need to first serialize any objects that are contained there-in, i.e. we serialize the data tree using depth first, pre-order traversal. This is generally easy to do on any tree structures. For example:
-
auto name = fbb.CreateString("MyMonster");
+
To start creating a buffer, create an instance of FlatBufferBuilder which will contain the buffer as it grows:
FlatBufferBuilder fbb;
+
Before we serialize a Monster, we need to first serialize any objects that are contained there-in, i.e. we serialize the data tree using depth first, pre-order traversal. This is generally easy to do on any tree structures. For example:
auto name = fbb.CreateString("MyMonster");
unsigned char inv[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
auto inventory = fbb.CreateVector(inv, 10);
CreateString and CreateVector serialize these two built-in datatypes, and return offsets into the serialized data indicating where they are stored, such that Monster below can refer to them.
CreateString can also take an std::string, or a const char * with an explicit length, and is suitable for holding UTF-8 and binary data if needed.
-
CreateVector can also take an std::vector. The offset it returns is typed, i.e. can only be used to set fields of the correct type below. To create a vector of struct objects (which will be stored as contiguous memory in the buffer, use CreateVectorOfStructs instead.
-
Vec3 vec(1, 2, 3);
+
CreateVector can also take an std::vector. The offset it returns is typed, i.e. can only be used to set fields of the correct type below. To create a vector of struct objects (which will be stored as contiguous memory in the buffer, use CreateVectorOfStructs instead.
Vec3 vec(1, 2, 3);
Vec3 is the first example of code from our generated header. Structs (unlike tables) translate to simple structs in C++, so we can construct them in a familiar way.
-
We have now serialized the non-scalar components of of the monster example, so we could create the monster something like this:
Note that we're passing 150 for the mana field, which happens to be the default value: this means the field will not actually be written to the buffer, since we'll get that value anyway when we query it. This is a nice space savings, since it is very common for fields to be at their default. It means we also don't need to be scared to add fields only used in a minority of cases, since they won't bloat up the buffer sizes if they're not actually used.
We do something similarly for the union field test by specifying a 0 offset and the NONE enum value (part of every union) to indicate we don't actually want to write this field.
-
Tables (like Monster) give you full flexibility on what fields you write (unlike Vec3, which always has all fields set because it is a struct). If you want even more control over this (i.e. skip fields even when they are not default), instead of the convenient CreateMonster call we can also build the object field-by-field manually:
-
MonsterBuilder mb(fbb);
+
Tables (like Monster) give you full flexibility on what fields you write (unlike Vec3, which always has all fields set because it is a struct). If you want even more control over this (i.e. skip fields even when they are not default), instead of the convenient CreateMonster call we can also build the object field-by-field manually:
MonsterBuilder mb(fbb);
mb.add_pos(&vec);
mb.add_hp(80);
mb.add_name(name);
mb.add_inventory(inventory);
auto mloc = mb.Finish();
We start with a temporary helper class MonsterBuilder (which is defined in our generated code also), then call the various add_ methods to set fields, and Finish to complete the object. This is pretty much the same code as you find inside CreateMonster, except we're leaving out a few fields. Fields may also be added in any order, though orderings with fields of the same size adjacent to each other most efficient in size, due to alignment. You should not nest these Builder classes (serialize your data in pre-order).
-
Regardless of whether you used CreateMonster or MonsterBuilder, you now have an offset to the root of your data, and you can finish the buffer using:
-
fbb.Finish(mloc);
+
Regardless of whether you used CreateMonster or MonsterBuilder, you now have an offset to the root of your data, and you can finish the buffer using:
fbb.Finish(mloc);
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 start of the buffer with fbb.GetBufferPointer(), and it's size from fbb.GetSize().
samples/sample_binary.cpp is a complete code sample similar to the code above, that also includes the reading code below.
Reading in C++
-
If you've received a buffer from somewhere (disk, network, etc.) you can directly start traversing it using:
-
auto monster = GetMonster(buffer_pointer);
-
monster is of type Monster *, and points to somewhere inside your buffer. If you look in your generated header, you'll see it has convenient accessors for all fields, e.g.
-
assert(monster->hp() == 80);
+
If you've received a buffer from somewhere (disk, network, etc.) you can directly start traversing it using:
auto monster = GetMonster(buffer_pointer);
+
monster is of type Monster *, and points to somewhere inside your buffer. If you look in your generated header, you'll see it has convenient accessors for all fields, e.g.
These should all be true. Note that we never stored a mana value, so it will return the default.
-
To access sub-objects, in this case the Vec3:
-
auto pos = monster->pos();
+
To access sub-objects, in this case the Vec3:
auto pos = monster->pos();
assert(pos);
assert(pos->z() == 3);
If we had not set the pos field during serialization, it would be NULL.
-
Similarly, we can access elements of the inventory array:
-
auto inv = monster->inventory();
+
Similarly, we can access elements of the inventory array:
auto inv = monster->inventory();
assert(inv);
assert(inv->Get(9) == 9);
Direct memory access
@@ -110,17 +100,14 @@
Text & schema parsing
Another reason might be that you already have a lot of data in JSON format, or a tool that generates JSON, and if you can write a schema for it, this will provide you an easy way to use that data directly.
There are two ways to use text formats:
Using the compiler as a conversion tool
-
This is the preferred path, as it doesn't require you to add any new code to your program, and is maximally efficient since you can ship with binary data. The disadvantage is that it is an extra step for your users/developers to perform, though you might be able to automate it.
-
flatc -b myschema.fbs mydata.json
+
This is the preferred path, as it doesn't require you to add any new code to your program, and is maximally efficient since you can ship with binary data. The disadvantage is that it is an extra step for your users/developers to perform, though you might be able to automate it.
flatc -b myschema.fbs mydata.json
This will generate the binary file mydata_wire.bin which can be loaded as before.
Making your program capable of loading text directly
This gives you maximum flexibility. You could even opt to support both, i.e. check for both files, and regenerate the binary from text when required, otherwise just load the binary.
This option is currently only available for C++, or Java through JNI.
As mentioned in the section "Building" above, this technique requires you to link a few more files into your program, and you'll want to include flatbuffers/idl.h.
-
Load text (either a schema or json) into an in-memory buffer (there is a convenient LoadFile() utility function in flatbuffers/util.h if you wish). Construct a parser:
-
flatbuffers::Parser parser;
-
Now you can parse any number of text files in sequence:
-
parser.Parse(text_file.c_str());
+
Load text (either a schema or json) into an in-memory buffer (there is a convenient LoadFile() utility function in flatbuffers/util.h if you wish). Construct a parser:
flatbuffers::Parser parser;
+
Now you can parse any number of text files in sequence:
parser.Parse(text_file.c_str());
This works similarly to how the command-line compiler works: a sequence of files parsed by the same Parser object allow later files to reference definitions in earlier files. Typically this means you first load a schema file (which populates Parser with definitions), followed by one or more JSON files.
If there were any parsing errors, Parse will return false, and Parser::err contains a human readable error string with a line number etc, which you should present to the creator of that file.
After each JSON file, the Parser::fbb member variable is the FlatBufferBuilder that contains the binary buffer version of that file, that you can access as described above.
diff --git a/docs/html/md__grammar.html b/docs/html/md__grammar.html
index 96ffe576997..e5278c09b4f 100644
--- a/docs/html/md__grammar.html
+++ b/docs/html/md__grammar.html
@@ -3,7 +3,7 @@
-
+
FlatBuffers: Formal Grammar of the schema language
@@ -32,7 +32,7 @@
The current implementation constructs these buffers backwards, since that significantly reduces the amount of bookkeeping and simplifies the construction API.
Code example
-
Here's an example of the code that gets generated for the samples/monster.fbs. What follows is the entire file, broken up by comments:
-
// automatically generated, do not modify
+
Here's an example of the code that gets generated for the samples/monster.fbs. What follows is the entire file, broken up by comments:
// automatically generated, do not modify
#include "flatbuffers/flatbuffers.h"
namespace MyGame {
namespace Sample {
-
These ugly macros do a couple of things: they turn off any padding the compiler might normally do, since we add padding manually (though none in this example), and they enforce alignment chosen by FlatBuffers. This ensures the layout of this struct will look the same regardless of compiler and platform. Note that the fields are private: this is because these store little endian scalars regardless of platform (since this is part of the serialized data). EndianScalar then converts back and forth, which is a no-op on all current mobile and desktop platforms, and a single machine instruction on the few remaining big endian platforms.
-
struct Monster : private flatbuffers::Table {
+
These ugly macros do a couple of things: they turn off any padding the compiler might normally do, since we add padding manually (though none in this example), and they enforce alignment chosen by FlatBuffers. This ensures the layout of this struct will look the same regardless of compiler and platform. Note that the fields are private: this is because these store little endian scalars regardless of platform (since this is part of the serialized data). EndianScalar then converts back and forth, which is a no-op on all current mobile and desktop platforms, and a single machine instruction on the few remaining big endian platforms.
Tables are a bit more complicated. A table accessor struct is used to point at the serialized data for a table, which always starts with an offset to its vtable. It derives from Table, which contains the GetField helper functions. GetField takes a vtable offset, and a default value. It will look in the vtable at that offset. If the offset is out of bounds (data from an older version) or the vtable entry is 0, the field is not present and the default is returned. Otherwise, it uses the entry as an offset into the table to locate the field.
-
struct MonsterBuilder {
+
Tables are a bit more complicated. A table accessor struct is used to point at the serialized data for a table, which always starts with an offset to its vtable. It derives from Table, which contains the GetField helper functions. GetField takes a vtable offset, and a default value. It will look in the vtable at that offset. If the offset is out of bounds (data from an older version) or the vtable entry is 0, the field is not present and the default is returned. Otherwise, it uses the entry as an offset into the table to locate the field.
MonsterBuilder is the base helper struct to construct a table using a FlatBufferBuilder. You can add the fields in any order, and the Finish call will ensure the correct vtable gets generated.
MonsterBuilder is the base helper struct to construct a table using a FlatBufferBuilder. You can add the fields in any order, and the Finish call will ensure the correct vtable gets generated.
CreateMonster is a convenience function that calls all functions in MonsterBuilder above for you. Note that if you pass values which are defaults as arguments, it will not actually construct that field, so you can probably use this function instead of the builder class in almost all cases.
This function is only generated for the root table type, to be able to start traversing a FlatBuffer from a raw buffer pointer.
-
}; // namespace MyGame
+
CreateMonster is a convenience function that calls all functions in MonsterBuilder above for you. Note that if you pass values which are defaults as arguments, it will not actually construct that field, so you can probably use this function instead of the builder class in almost all cases.
This function is only generated for the root table type, to be able to start traversing a FlatBuffer from a raw buffer pointer.
}; // namespace MyGame
}; // namespace Sample
diff --git a/docs/html/md__java_usage.html b/docs/html/md__java_usage.html
index 7a90aeafdd7..27aae1b7e5d 100644
--- a/docs/html/md__java_usage.html
+++ b/docs/html/md__java_usage.html
@@ -3,7 +3,7 @@
-
+
FlatBuffers: Use in Java
@@ -32,7 +32,7 @@
-
+
@@ -54,23 +54,17 @@
There's experimental support for reading FlatBuffers in Java. Generate code for Java with the -j option to flatc.
-
See javaTest.java for an example. Essentially, you read a FlatBuffer binary file into a byte[], which you then turn into a ByteBuffer, which you pass to the getRootAsMonster function:
-
ByteBuffer bb = ByteBuffer.wrap(data);
+
See javaTest.java for an example. Essentially, you read a FlatBuffer binary file into a byte[], which you then turn into a ByteBuffer, which you pass to the getRootAsMonster function:
short hp = monster.hp();
Vec3 pos = monster.pos();
Note that whenever you access a new object like in the pos example above, a new temporary accessor object gets created. If your code is very performance sensitive (you iterate through a lot of objects), there's a second pos() method to which you can pass a Vec3 object you've already created. This allows you to reuse it across many calls and reduce the amount of object allocation (and thus garbage collection) your program does.
Sadly the string accessors currently always create a new string when accessed, since FlatBuffer's UTF-8 strings can't be read in-place by Java.
-
Vector access is also a bit different from C++: you pass an extra index to the vector field accessor. Then a second method with the same name suffixed by _length let's you know the number of elements you can access:
-
for (int i = 0; i < monster.inventory_length(); i++)
+
Vector access is also a bit different from C++: you pass an extra index to the vector field accessor. Then a second method with the same name suffixed by _length let's you know the number of elements you can access:
for (int i = 0; i < monster.inventory_length(); i++)
monster.inventory(i); // do something here
-
You can also construct these buffers in Java using the static methods found in the generated code, and the FlatBufferBuilder class:
-
FlatBufferBuilder fbb = new FlatBufferBuilder();
-
Create strings:
-
int str = fbb.createString("MyMonster");
-
Create a table with a struct contained therein:
-
Monster.startMonster(fbb);
+
You can also construct these buffers in Java using the static methods found in the generated code, and the FlatBufferBuilder class:
FlatBufferBuilder fbb = new FlatBufferBuilder();
+
As you can see, the Java code for tables does not use a convenient createMonster call like the C++ code. This is to create the buffer without using temporary object allocation (since the Vec3 is an inline component of Monster, it has to be created right where it is added, whereas the name and the inventory are not inline). Structs do have convenient methods that even have arguments for nested structs.
-
Vectors also use this start/end pattern to allow vectors of both scalar types and structs:
-
Monster.startInventoryVector(fbb, 5);
+
Vectors also use this start/end pattern to allow vectors of both scalar types and structs:
Monster.startInventoryVector(fbb, 5);
for (byte i = 4; i >=0; i--) fbb.addByte(i);
int inv = fbb.endVector();
You can use the generated method startInventoryVector to conveniently call startVector with the right element size. You pass the number of elements you want to write. You write the elements backwards since the buffer is being constructed back to front.
The syntax of the schema language (aka IDL, Interface Definition Language) should look quite familiar to users of any of the C family of languages, and also to users of other IDLs. Let's look at an example first:
-
// example IDL file
+
The syntax of the schema language (aka IDL, Interface Definition Language) should look quite familiar to users of any of the C family of languages, and also to users of other IDLs. Let's look at an example first:
// example IDL file
namespace MyGame;
diff --git a/docs/html/md__white_paper.html b/docs/html/md__white_paper.html
index b2ea6103509..b64f58180e6 100644
--- a/docs/html/md__white_paper.html
+++ b/docs/html/md__white_paper.html
@@ -3,7 +3,7 @@
-
+
FlatBuffers: FlatBuffers white paper
@@ -32,7 +32,7 @@
-
+
diff --git a/docs/html/navtree.js b/docs/html/navtree.js
index 30cc01d314f..abdc1d0a20b 100644
--- a/docs/html/navtree.js
+++ b/docs/html/navtree.js
@@ -18,8 +18,6 @@ var NAVTREEINDEX =
"index.html"
];
-var SYNCONMSG = 'click to disable panel synchronisation';
-var SYNCOFFMSG = 'click to enable panel synchronisation';
var SYNCONMSG = 'click to disable panel synchronisation';
var SYNCOFFMSG = 'click to enable panel synchronisation';
var navTreeSubIndices = new Array();
@@ -44,6 +42,21 @@ function stripPath2(uri)
return m ? uri.substring(i-6) : s;
}
+function hashValue()
+{
+ return $(location).attr('hash').substring(1).replace(/[^\w\-]/g,'');
+}
+
+function hashUrl()
+{
+ return '#'+hashValue();
+}
+
+function pathName()
+{
+ return $(location).attr('pathname').replace(/[^-A-Za-z0-9+&@#/%?=~_|!:,.;\(\)]/g, '');
+}
+
function localStorageSupported()
{
try {
@@ -66,7 +79,7 @@ function deleteLink()
{
if (localStorageSupported()) {
window.localStorage.setItem('navpath','');
- }
+ }
}
function cachedLink()
@@ -128,7 +141,7 @@ function createIndent(o,domNode,node,level)
span.style.display = 'inline-block';
span.style.width = 16*(level+1)+'px';
span.style.height = '22px';
- span.innerHTML = ' ';
+ span.innerHTML = ' ';
domNode.appendChild(span);
}
}
@@ -138,11 +151,13 @@ var animationInProgress = false;
function gotoAnchor(anchor,aname,updateLocation)
{
var pos, docContent = $('#doc-content');
- if (anchor.parent().attr('class')=='memItemLeft' ||
- anchor.parent().attr('class')=='fieldtype' ||
- anchor.parent().is(':header'))
+ var ancParent = $(anchor.parent());
+ if (ancParent.hasClass('memItemLeft') ||
+ ancParent.hasClass('fieldname') ||
+ ancParent.hasClass('fieldtype') ||
+ ancParent.is(':header'))
{
- pos = anchor.parent().position().top;
+ pos = ancParent.position().top;
} else if (anchor.position()) {
pos = anchor.position().top;
}
@@ -200,7 +215,7 @@ function newNode(o, po, text, link, childrenData, lastNode)
a.className = stripPath(link.replace('#',':'));
if (link.indexOf('#')!=-1) {
var aname = '#'+link.split('#')[1];
- var srcPage = stripPath($(location).attr('pathname'));
+ var srcPage = stripPath(pathName());
var targetPage = stripPath(link.split('#')[0]);
a.href = srcPage!=targetPage ? url : "javascript:void(0)";
a.onclick = function(){
@@ -294,14 +309,13 @@ function glowEffect(n,duration)
function highlightAnchor()
{
- var aname = $(location).attr('hash');
+ var aname = hashUrl();
var anchor = $(aname);
if (anchor.parent().attr('class')=='memItemLeft'){
- var rows = $('.memberdecls tr[class$="'+
- window.location.hash.substring(1)+'"]');
+ var rows = $('.memberdecls tr[class$="'+hashValue()+'"]');
glowEffect(rows.children(),300); // member without details
- } else if (anchor.parents().slice(2).prop('tagName')=='TR') {
- glowEffect(anchor.parents('div.memitem'),1000); // enum value
+ } else if (anchor.parent().attr('class')=='fieldname'){
+ glowEffect(anchor.parent().parent(),1000); // enum value
} else if (anchor.parent().attr('class')=='fieldtype'){
glowEffect(anchor.parent().parent(),1000); // struct field
} else if (anchor.parent().is(":header")) {
@@ -316,7 +330,7 @@ function selectAndHighlight(hash,n)
{
var a;
if (hash) {
- var link=stripPath($(location).attr('pathname'))+':'+hash.substring(1);
+ var link=stripPath(pathName())+':'+hash.substring(1);
a=$('.item a[class$="'+link+'"]');
}
if (a && a.length) {
@@ -427,14 +441,13 @@ function navTo(o,root,hash,relpath)
if (link) {
var parts = link.split('#');
root = parts[0];
- if (parts.length>1) hash = '#'+parts[1];
+ if (parts.length>1) hash = '#'+parts[1].replace(/[^\w\-]/g,'');
else hash='';
}
if (hash.match(/^#l\d+$/)) {
var anchor=$('a[name='+hash.substring(1)+']');
glowEffect(anchor.parent(),1000); // line number
hash=''; // strip line number anchors
- //root=root.replace(/_source\./,'.'); // source link to doc link
}
var url=root+hash;
var i=-1;
@@ -468,7 +481,7 @@ function toggleSyncButton(relpath)
if (navSync.hasClass('sync')) {
navSync.removeClass('sync');
showSyncOff(navSync,relpath);
- storeLink(stripPath2($(location).attr('pathname'))+$(location).attr('hash'));
+ storeLink(stripPath2(pathName())+hashUrl());
} else {
navSync.addClass('sync');
showSyncOn(navSync,relpath);
@@ -508,7 +521,7 @@ function initNavTree(toroot,relpath)
}
$(window).load(function(){
- navTo(o,toroot,window.location.hash,relpath);
+ navTo(o,toroot,hashUrl(),relpath);
showRoot();
});
@@ -516,21 +529,20 @@ function initNavTree(toroot,relpath)
if (window.location.hash && window.location.hash.length>1){
var a;
if ($(location).attr('hash')){
- var clslink=stripPath($(location).attr('pathname'))+':'+
- $(location).attr('hash').substring(1);
- a=$('.item a[class$="'+clslink+'"]');
+ var clslink=stripPath(pathName())+':'+hashValue();
+ a=$('.item a[class$="'+clslink.replace(/
-
+
FlatBuffers: Related Pages
@@ -32,7 +32,7 @@
-
+
@@ -55,15 +55,15 @@
Here is a list of all related documentation pages: