BigfootDev/flatbuffers
1
0
Fork 1
mirror of https://github.com/google/flatbuffers.git synced 2026-06-13 00:04:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clean up whitespace and fix typo in tutorial.md (#8695)

Browse Source 
* docs: remove trailing whitespace

* docs: fix typo in tutorial.md
This commit is contained in:
Daniel Nguyen
2025-09-25 11:02:22 -05:00
committed by GitHub
parent 1872409707
commit 27325e002a
26 changed files with 108 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/source/annotation.md
View File

@@ -55,8 +55,8 @@ The columns are as follows:
The prefix `+` is added to make searching for the offset (compared to some
random value) a bit easier.
2. The raw binary data, expressed in hexadecimal format.
2. The raw binary data, expressed in hexadecimal format.
This is in the little endian format the buffer uses internally and what you
would see with a normal binary text viewer.
@@ -108,7 +108,7 @@ regions in the flatbuffer itself.
### Binary Regions
Binary regions are contiguous bytes regions that are grouped together to form
Binary regions are contiguous bytes regions that are grouped together to form
some sort of value, e.g. a `scalar` or an array of scalars. A binary region may
be split up over multiple text lines, if the size of the region is large.
@@ -122,7 +122,7 @@ vtable (AnnotatedBinary.Bar):
```
The first column (`+0x00A0`) is the offset to this region from the beginning of
the buffer.
the buffer.
The second column are the raw bytes (hexadecimal) that make up this region.
These are expressed in the little-endian format that flatbuffers uses for the
@@ -135,7 +135,7 @@ The fourth column shows the raw bytes as a compacted, big-endian value. The raw
bytes are duplicated in this fashion since it is more intuitive to read the data
in the big-endian format (e.g., `0x0008`). This value is followed by the decimal
representation of the value (e.g., `(8)`). For strings, the raw string value is
shown instead.
shown instead.
The fifth column is a textual comment on what the value is. As much metadata as
known is provided.
@@ -146,4 +146,4 @@ If the type in the 3rd column is of an absolute offset (`SOffet32` or
`Offset32`), the fourth column also shows an `Loc: +0x025A` value which shows
where in the binary this region is pointing to. These values are absolute from
the beginning of the file, their calculation from the raw value in the 4th
column depends on the context.
column depends on the context.

6
docs/source/building.md
View File

@@ -152,11 +152,11 @@ add_subdirectory(${FLATBUFFERS_SRC_DIR}
# The flatbuffers target carry header search path automatically if CMake > 2.8.11.
target_link_libraries(own_project_target PRIVATE flatbuffers)
```
When build your project the `flatbuffers` library will be compiled and linked
When build your project the `flatbuffers` library will be compiled and linked
to a target as part of your project.
#### Override default depth limit of nested objects
To override [the depth limit of recursion](languages/cpp.md),
To override [the depth limit of recursion](languages/cpp.md),
add this directive:
```cmake
set(FLATBUFFERS_MAX_PARSING_DEPTH 16)
@@ -174,4 +174,4 @@ We generate [SLSA3 signatures](http://slsa.dev) using the OpenSSF's [slsa-framew
```shell
$ slsa-verifier -artifact-path <downloaded.zip> -provenance attestation.intoto.jsonl -source github.com/google/flatbuffers -tag <version>
PASSED: Verified SLSA provenance
```
```

10
docs/source/contributing.md
View File

@@ -15,17 +15,17 @@ repository.
Before we can use your contributions, you __must__ sign one of the following license agreements. The agreements are self-served at the following links.
Our code review process will automatically check if you have signed the CLA, so
don't fret. Though it may be prudent to check before spending a lot of time on
don't fret. Though it may be prudent to check before spending a lot of time on
contribution.
### Individual Contributions
### Individual Contributions
For individuals, the [Google Individual
Contributor License Agreement
(CLA)](https://cla.developers.google.com/about/google-individual?csw=1) which is
self served at the link. The CLA is required since you own the copyright to your
changes, even after your contribution becomes part of our codebase, so we need
your permission to use and distribute your code.
your permission to use and distribute your code.
### Corporate Contributions
@@ -67,7 +67,7 @@ pip install mkdocs-material
pip install mkdocs-redirects
```
Then, in the `root` directory of flatbuffers, run
Then, in the `root` directory of flatbuffers, run
```
mkdocs serve -f docs/mkdocs.yml
@@ -77,4 +77,4 @@ This will continually watch the repo for changes to the documentation and serve
the rendered pages locally.
Submit your documentation changes with your code changes and they will
automatically get published when your code is submitted.
automatically get published when your code is submitted.

2
docs/source/evolution.md
View File

@@ -261,7 +261,7 @@ a [option](flatc.md#additional-options) to do just that:
```sh
--conform FILE
```
```
Where `FILE` is the base schema the rest of the input schemas must evolve from.
It returns `0` if they are properly evolved, otherwise returns a non-zero value

12
docs/source/flatc.md
View File

@@ -1,13 +1,13 @@
# FlatBuffers Compiler (`flatc`)
The main compiler for FlatBuffers is called `flatc` and is used to convert
schema definitions into generated code files for a variety of languages.
schema definitions into generated code files for a variety of languages.
After [building](building.md) `flatc`, it is used as follows:
```sh
flatc [ GENERATOR_OPTIONS ] [ -o PATH ] [- I PATH ]
FILES...
flatc [ GENERATOR_OPTIONS ] [ -o PATH ] [- I PATH ]
FILES...
[ -- BINARY_FILES... ]
```
@@ -65,17 +65,17 @@ list of `FILES...`.
=== "To Binary"
To serialize the JSON data in `mydata.json` using the schema `myschema.fbs`:
```sh
flatc --binary myschema.fbs mydata.json
```
This will generate a `mydata_wire.bin` file containing the serialized
This will generate a `mydata_wire.bin` file containing the serialized
flatbuffer data.
=== "To JSON"
To convert the serialized binary flatbuffer `mydata.bin` using the schema
To convert the serialized binary flatbuffer `mydata.bin` using the schema
`myschema.fbs` to JSON:
```sh

4
docs/source/intermediate_representation.md
View File

@@ -6,7 +6,7 @@ errors and stores the resulting data in this IR, outputting `.bfbs` files.
Since this IR is a Flatbuffer, you can load and use it at runtime for runtime
reflection purposes.
There are some quirks:
There are some quirks:
- Tables and Structs are serialized as `Object`s.
- Unions and Enums are serialized as `Enum`s.
- It is the responsibility of the code generator to check the `advanced_features`
@@ -18,7 +18,7 @@ There are some quirks:
inferred to be the directory containing the first provided schema file.
## Invocation
## Invocation
You can invoke it like so
```{.sh}
flatc -b --schema ${your_fbs_files}

2
docs/source/languages/dart.md
View File

@@ -93,7 +93,7 @@ significant changes have been made.
goal of this implementation. Support for 16 bit integers was also added.
5. The code generation in this offers an "ObjectBuilder", which generates code
very similar to the SDK classes that consume FlatBuffers, as well as Builder
classes, which produces code which more closely resembles the builders in
classes, which produces code which more closely resembles the builders in
other languages. The ObjectBuilder classes are easier to use, at the cost of
additional references allocated.

4
docs/source/languages/javascript.md
View File

@@ -16,7 +16,7 @@ documentation to build `flatc` and should be familiar with
## FlatBuffers JavaScript library code location
The generated code for the FlatBuffers JavaScript library can be found at
The generated code for the FlatBuffers JavaScript library can be found at
https://www.npmjs.com/package/flatbuffers. To use it from sources:
1. Run `npm run compile` from the main folder to generate JS files from TS.
@@ -36,7 +36,7 @@ transpile your sources to desired JS flavor. The minimal steps to get up and
running with JS are:
1. Generate TS files from `*.fbs` by using the `--ts` option.
1. Transpile resulting TS files to desired JS flavor using `tsc` (see
1. Transpile resulting TS files to desired JS flavor using `tsc` (see
https://www.typescriptlang.org/download for installation instructions).
~~~{.js}

2
docs/source/languages/kotlin.md
View File

@@ -81,4 +81,4 @@ Kotlin generated code was designed to be as close as possible to the java counte
The most obvious ones are:
* Fields as accessed as Kotlin [properties](https://kotlinlang.org/docs/reference/properties.html)
* Static methods are accessed in [companion object](https://kotlinlang.org/docs/reference/classes.html#companion-objects)
* Static methods are accessed in [companion object](https://kotlinlang.org/docs/reference/classes.html#companion-objects)

2
docs/source/languages/lua.md
View File

@@ -50,7 +50,7 @@ file into a `string`, which you pass to the `GetRootAsMonster` function:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.lua}
-- require the library
local flatbuffers = require("flatbuffers")
-- require the generated code
local monster = require("MyGame.Sample.Monster")

2
docs/source/languages/swift.md
View File

@@ -81,7 +81,7 @@ In some cases it's necessary to modify values in an existing FlatBuffer in place
fatalError("couldn't mutate")
}
// mutate a struct field using flatbuffers struct
// DONT use monster.pos to mutate since swift copy on write
// DONT use monster.pos to mutate since swift copy on write
// will not mutate the value in the buffer
let vec = monster.mutablePos.mutate(z: 4)

16
docs/source/quick_start.md
View File

@@ -44,11 +44,11 @@ See the [Tutorial](tutorial.md) for a more in depth guide.
#include "flatbuffers.h"
#include "monster_generated.h"
int main() {
int main() {
// Used to build the flatbuffer
FlatBufferBuilder builder;
// Auto-generated function emitted from `flatc` and the input
// Auto-generated function emitted from `flatc` and the input
// `monster.fbs` schema.
auto monster = CreateMonsterDirect(builder, "Abominable Snowman", 100);
@@ -60,7 +60,7 @@ See the [Tutorial](tutorial.md) for a more in depth guide.
See complete [C++ Example](https://github.com/google/flatbuffers/blob/master/samples/sample_binary.cpp#L24-L56).
5. **Transmit/Store the serialized FlatBuffer**
Use your serialized buffer however you want. Send it to someone, save if for
later, etc...
@@ -73,10 +73,10 @@ See the [Tutorial](tutorial.md) for a more in depth guide.
Use the generated accessors to read the data from the serialized buffer.
It doesn't need to be the same language, or even schema version (see
It doesn't need to be the same language, or even schema version (see
[Evolving](evolution.md)), FlatBuffers ensures the data is readable across
languages and schema versions.
languages and schema versions.
```c++ title="my_monster_factory.cc" linenums="15"
// Get a view of the root monster from the flatbuffer.
const Monster snowman = GetMonster(flatbuffer);
@@ -84,7 +84,7 @@ See the [Tutorial](tutorial.md) for a more in depth guide.
// Access the monster's fields directly.
ASSERT_EQ(snowman->name(), "Abominable Snowman");
ASSERT_EQ(snowman->health(), 100);
```
```
See [`Rust` examples](https://github.com/google/flatbuffers/blob/master/samples/sample_binary.rs#L92-L106)
for reading the data written by `C++`.

84
docs/source/tutorial.md
View File

@@ -165,11 +165,11 @@ serializing and deserializing the flatbuffer binary data.
=== "C"
!!! Note
!!! Note
If you're working in C, you need to use the separate project
[FlatCC](https://github.com/dvidelabs/flatcc) which contains a schema
compiler and runtime library in C for C. See
If you're working in C, you need to use the separate project
[FlatCC](https://github.com/dvidelabs/flatcc) which contains a schema
compiler and runtime library in C for C. See
[flatcc build instructions](https://github.com/dvidelabs/flatcc#building).
Please be aware of the difference between `flatc` and `flatcc` tools.
@@ -291,7 +291,7 @@ generally involves two things:
// Convenient namespace macro to manage long namespace prefix.
#undef ns
// Specified in the schema.
#define ns(x) FLATBUFFERS_WRAP_NAMESPACE(MyGame_Sample, x)
#define ns(x) FLATBUFFERS_WRAP_NAMESPACE(MyGame_Sample, x)
// A helper to simplify creating vectors from C-arrays.
#define c_vec_len(V) (sizeof(V)/sizeof((V)[0]))
@@ -333,14 +333,14 @@ generally involves two things:
=== "JavaScript"
```javascript
// The following code is an example - use your desired module flavor by
// transpiling from TS.
// 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 is for browser-based HTML/JavaScript. Use the above
// The following code is 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`.
@@ -384,12 +384,12 @@ generally involves two things:
// The last segment of the class name matches the file name.
$class = substr($class_name, strrpos($class_name, "\\") + 1);
// `flatbuffers` root.
$root_dir = join(DIRECTORY_SEPARATOR, array(dirname(dirname(__FILE__))));
$root_dir = join(DIRECTORY_SEPARATOR, array(dirname(dirname(__FILE__))));
// 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,
join(DIRECTORY_SEPARATOR,
array($root_dir, "samples", "MyGame", "Sample")));
foreach ($paths as $path) {
$file = join(DIRECTORY_SEPARATOR, array($path, $class . ".php"));
@@ -546,7 +546,7 @@ for it. The builder will automatically resize the backing buffer when necessary.
=== "Lobster"
```lobster
// Construct a Builder with 1024 byte backing array.
// Construct a Builder with 1024 byte backing array.
let builder = flatbuffers_builder {}
```
@@ -630,9 +630,9 @@ Let's serialize two weapon strings.
=== "C"
```c
flatbuffers_string_ref_t weapon_one_name
flatbuffers_string_ref_t weapon_one_name
= flatbuffers_string_create_str(B, "Sword");
flatbuffers_string_ref_t weapon_two_name
flatbuffers_string_ref_t weapon_two_name
= flatbuffers_string_create_str(B, "Axe");
```
@@ -722,7 +722,7 @@ Let's serialize two weapon strings.
=== "TypeScript"
```ts
```ts
let weaponOne = builder.createString('Sword');
let weaponTwo = builder.createString('Axe');
```
@@ -760,9 +760,9 @@ offset to the weapon's name and a numerical value for the damage field.
uint16_t weapon_one_damage = 3;
uint16_t weapon_two_damage = 5;
ns(Weapon_ref_t) sword
ns(Weapon_ref_t) sword
= ns(Weapon_create(B, weapon_one_name, weapon_one_damage));
ns(Weapon_ref_t) axe
ns(Weapon_ref_t) axe
= ns(Weapon_create(B, weapon_two_name, weapon_two_damage));
```
@@ -772,7 +772,7 @@ offset to the weapon's name and a numerical value for the damage field.
short weaponOneDamage = 3;
short weaponTwoDamage = 5;
// Use the `CreateWeapon()` helper function to create the weapons, since we
// Use the `CreateWeapon()` helper function to create the weapons, since we
// set every field.
Offset<Weapon> sword =
Weapon.CreateWeapon(builder, weaponOneName, weaponOneDamage);
@@ -1073,7 +1073,7 @@ The Builder provides multiple ways to create `vectors`.
=== "Java"
```java
// Place the two weapons into an array, and pass it to the
// Place the two weapons into an array, and pass it to the
// `createWeaponsVector()` method to create a FlatBuffer vector.
int[] weaps = new int[2];
weaps[0] = sword;
@@ -1096,7 +1096,7 @@ The Builder provides multiple ways to create `vectors`.
=== "Kotlin"
```kotlin
// Place the two weapons into an array, and pass it to the
// Place the two weapons into an array, and pass it to the
// `createWeaponsVector()` method to create a FlatBuffer vector.
val weaps = intArrayOf(sword, axe)
@@ -1537,7 +1537,7 @@ the necessary values and Offsets to make a `Monster`.
```java
// Serialize a name for our monster, called "Orc".
int name = builder.createString("Orc");
// Create our monster using `startMonster()` and `endMonster()`.
Monster.startMonster(builder);
Monster.addPos(builder, Vec3.createVec3(builder, 1.0f, 2.0f, 3.0f));
@@ -1567,7 +1567,7 @@ the necessary values and Offsets to make a `Monster`.
MyGame.Sample.Monster.addName(builder, name);
MyGame.Sample.Monster.addInventory(builder, inv);
MyGame.Sample.Monster.addWeapons(builder, weapons);
MyGame.Sample.Monster.addEquippedType(builder,
MyGame.Sample.Monster.addEquippedType(builder,
MyGame.Sample.Equipment.Weapon);
MyGame.Sample.Monster.addEquipped(builder, axe);
MyGame.Sample.Monster.addPath(builder, path);
@@ -1649,7 +1649,7 @@ the necessary values and Offsets to make a `Monster`.
\MyGame\Sample\Monster::AddInventory($builder, $inv);
\MyGame\Sample\Monster::AddColor($builder, \MyGame\Sample\Color::Red);
\MyGame\Sample\Monster::AddWeapons($builder, $weapons);
\MyGame\Sample\Monster::AddEquippedType($builder,
\MyGame\Sample\Monster::AddEquippedType($builder,
\MyGame\Sample\Equipment::Weapon);
\MyGame\Sample\Monster::AddEquipped($builder, $axe);
\MyGame\Sample\Monster::AddPath($builder, $path);
@@ -1782,7 +1782,7 @@ deserializing the buffer later.
```dart
// Call `finish()` to instruct the builder that this monster is complete.
// See the next code section, as in Dart `finish` will also return the byte
// See the next code section, as in Dart `finish` will also return the byte
// array.
```
@@ -1982,7 +1982,7 @@ like so:
```php
// This must be called after `finish()`.
$buf = $builder->dataBuffer(); // Of type `Google\FlatBuffers\ByteBuffer`
// The data in this ByteBuffer does NOT start at 0, but at
// The data in this ByteBuffer does NOT start at 0, but at
// buf->getPosition().
// The end of the data is marked by buf->capacity(), so the size is
// buf->capacity() - buf->getPosition().
@@ -2056,7 +2056,7 @@ functions to get the root object given the buffer.
```c++
uint8_t *buffer_pointer = /* the data you just read */;
// Get an view to the root object inside the buffer.
// Get a view to the root object inside the buffer.
Monster monster = GetMonster(buffer_pointer);
```
@@ -2076,7 +2076,7 @@ functions to get the root object given the buffer.
```c#
byte[] bytes = /* the data you just read */
// Get an view to the root object inside the buffer.
// Get a view to the root object inside the buffer.
Monster monster = Monster.GetRootAsMonster(new ByteBuffer(bytes));
```
@@ -2204,7 +2204,7 @@ functions to get the root object given the buffer.
```ts
// the data you just read, as a `Uint8Array`.
// Note that the example here uses `readFileSync` from the built-in `fs`
// Note that the example here uses `readFileSync` from the built-in `fs`
// module, but other methods for accessing the file contents will also work.
let bytes = new Uint8Array(readFileSync('./monsterdata.bin'));
@@ -2656,9 +2656,9 @@ you need to handle the result as a FlatBuffer table. Here we iterate over the
ns(Weapon_vec_t) weapons = ns(Monster_weapons(monster));
size_t weapons_len = ns(Weapon_vec_len(weapons));
// We can use `const char *` instead of `flatbuffers_string_t`.
const char *second_weapon_name =
const char *second_weapon_name =
ns(Weapon_name(ns(Weapon_vec_at(weapons, 1))));
uint16_t second_weapon_damage =
uint16_t second_weapon_damage =
ns(Weapon_damage(ns(Weapon_vec_at(weapons, 1))));
```
@@ -2791,11 +2791,11 @@ only stores a FlatBuffer `table`).
```c++
auto union_type = monster.equipped_type();
if (union_type == Equipment_Weapon) {
// Requires `static_cast` to type `const Weapon*`.
auto weapon = static_cast<const Weapon*>(monster->equipped());
auto weapon_name = weapon->name()->str(); // "Axe"
auto weapon_damage = weapon->damage(); // 5
}
@@ -2807,7 +2807,7 @@ only stores a FlatBuffer `table`).
// 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
// 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"
@@ -2819,10 +2819,10 @@ only stores a FlatBuffer `table`).
```c#
var unionType = monster.EquippedType;
if (unionType == Equipment.Weapon) {
var weapon = monster.Equipped<Weapon>().Value;
var weaponName = weapon.Name; // "Axe"
var weaponDamage = weapon.Damage; // 5
}
@@ -2852,7 +2852,7 @@ only stores a FlatBuffer `table`).
unionType := monster.EquippedType()
if unionType == sample.EquipmentWeapon {
// Create a `sample.Weapon` object that can be initialized with the
// 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)
@@ -2887,7 +2887,7 @@ only stores a FlatBuffer `table`).
// 'Axe'
var weaponName = monster.equipped(new MyGame.Sample.Weapon()).name();
// 5
var weaponDamage =
var weaponDamage =
monster.equipped(new MyGame.Sample.Weapon()).damage();
}
```
@@ -2912,8 +2912,8 @@ only stores a FlatBuffer `table`).
union_type = monster.equipped_type
if union_type == MyGame_Sample_Equipment_Weapon:
// `monster.equipped_as_Weapon` returns a FlatBuffer handle much like
// normal table fields, but this is only valid to call if we already
// `monster.equipped_as_Weapon` returns a FlatBuffer handle much like
// normal table fields, but this is only valid to call if we already
// know it is the correct type.
let union_weapon = monster.equipped_as_Weapon
@@ -2945,8 +2945,8 @@ only stores a FlatBuffer `table`).
$weapon_name =
$monster->getEquipped(new \MyGame\Sample\Weapon())->getName();
// 5
$weapon_damage =
$monster->getEquipped(new \MyGame\Sample\Weapon())->getDamage();
$weapon_damage =
$monster->getEquipped(new \MyGame\Sample\Weapon())->getDamage();
}
```
@@ -2996,8 +2996,8 @@ only stores a FlatBuffer `table`).
if (unionType == MyGame.Sample.Equipment.Weapon) {
// 'Axe'
let weaponName = monster.equipped(new MyGame.Sample.Weapon()).name();
// 5
let weaponName = monster.equipped(new MyGame.Sample.Weapon()).name();
// 5
let weaponDamage = monster.equipped(new MyGame.Sample.Weapon()).damage();
}
```