From 1ff248739ecf7595834808eb483d6e6ab9de3496 Mon Sep 17 00:00:00 2001 From: Derek Bailey Date: Sat, 11 Jan 2025 10:43:50 -0800 Subject: [PATCH] format the tutorial for all the languages --- docs/source/tutorial.md | 924 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 923 insertions(+), 1 deletion(-) diff --git a/docs/source/tutorial.md b/docs/source/tutorial.md index 86b4874ca..0f06d9a2d 100644 --- a/docs/source/tutorial.md +++ b/docs/source/tutorial.md @@ -488,7 +488,12 @@ for it. The builder will automatically resize the backing buffer when necessary. ```c++ // Construct a Builder with 1024 byte backing array. - flatbuffers::FlatBufferBuidler builder(1024); + flatbuffers::FlatBufferBuilder builder(1024); + ``` + +=== "C" + + ```c ``` === "C#" @@ -498,6 +503,66 @@ for it. The builder will automatically resize the backing buffer when necessary. FlatBufferBuilder builder = new FlatBufferBuilder(1024); ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + Once a Builder is available, data can be serialized to it via the Builder APIs and the generated code. @@ -527,6 +592,11 @@ Builder `CreateString` method: flatbuffers::Offset weapon_two_name = builder.CreateString("Axe"); ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -534,6 +604,67 @@ Builder `CreateString` method: Offset weaponTwoName = builder.CreateString("Axe"); ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + This performs the actual serialization (the string data is copied into the backing array) and returns an offset. Think of the offset as a handle to that reference. It's just a "typed" numerical offset to where that data resides in @@ -559,6 +690,11 @@ the weapon's name and a numerical value for the damage field. CreateWeapon(builder, weapon_two_name, weapon_two_damage); ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -572,6 +708,67 @@ the weapon's name and a numerical value for the damage field. Weapon.CreateWeapon(builder, weaponTwoName, weaponTwoDamage); ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + The generated functions from `flatc`, like `CreateWeapon`, are just composed of various Builder API methods. So its not required to use the generated code, but it does make things much simpler and compact. @@ -625,6 +822,11 @@ The Builder provides multiple ways to create `vectors`. auto weapons = builder.CreateVector(weapons_vector); ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -638,6 +840,67 @@ The Builder provides multiple ways to create `vectors`. var weapons = Monster.CreateWeaponsVector(builder, weaps); ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + While we are at it, let us serialize the other two vector fields: the `inventory` field is just a vector of scalars, and the `path` field is a vector of structs (which are scalar data as well). So these vectors can be serialized a @@ -661,6 +924,11 @@ bit more directly. ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -685,6 +953,67 @@ bit more directly. Offset> inventory = builder.EndVector(); ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + #### Unions The last non-scalar data for the `Monster` table is the `equipped` `union` @@ -724,6 +1053,11 @@ the necessary values and Offsets to make a `Monster`. ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -747,6 +1081,67 @@ the necessary values and Offsets to make a `Monster`. Offset orc = Monster.EndMonster(builder); ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + ### Finishing At this point, we have serialized a `Monster` we've named "orc" to the @@ -765,6 +1160,11 @@ deserializing the buffer later. builder.Finish(orc); ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -773,6 +1173,67 @@ deserializing the buffer later. builder.Finish(orc.Value); ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + Once you finish a Builder, you can no longer serialize more data to it. #### Buffer Access @@ -791,6 +1252,11 @@ like so: int size = builder.GetSize(); ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -805,6 +1271,67 @@ like so: byte[] buf = builder.SizedByteArray(); ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + Now you can write the bytes to a file or send them over the network. The buffer stays valid until the Builder is cleared or destroyed. @@ -842,6 +1369,11 @@ functions to get the root object given the buffer. Monster monster = GetMonster(buffer_pointer); ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -851,6 +1383,67 @@ functions to get the root object given the buffer. Monster monster = Monster.GetRootAsMonster(new ByteBuffer(bytes)); ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + Again, make sure you read the bytes in BINARY mode, otherwise the buffer may be corrupted. @@ -872,6 +1465,11 @@ some of the accessors of the `Monster` root table would look like: auto name = monster->name()->c_str(); ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -883,6 +1481,67 @@ some of the accessors of the `Monster` root table would look like: var name = monster.Name; ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + These accessors should hold the values `300`, `150`, and `"Orc"` respectively. The default value of `150` wasn't stored in the `mana` field, but we are still @@ -905,6 +1564,11 @@ For example, accessing the `pos` `struct`, which is type `Vec3` you would do: auto z = pos->z(); ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -914,6 +1578,67 @@ For example, accessing the `pos` `struct`, which is type `Vec3` you would do: var z = pos.Z; ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + Where `x`, `y`, and `z` will contain `1.0`, `2.0`, and `3.0` respectively. ### Vector Access @@ -929,6 +1654,11 @@ You can also iterate over the length of the vector. auto third_item = inv->Get(2); ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -936,6 +1666,67 @@ You can also iterate over the length of the vector. var thirdItem = monster.Inventory(2); ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + For vectors of tables, you can access the elements like any other vector, except you need to handle the result as a FlatBuffer table. Here we iterate over the `weapons` vector that is houses `Weapon` `tables`. @@ -949,6 +1740,11 @@ you need to handle the result as a FlatBuffer table. Here we iterate over the auto second_weapon_damage = weapons->Get(1)->damage() ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -957,6 +1753,67 @@ you need to handle the result as a FlatBuffer table. Here we iterate over the var secondWeaponDamage = monster.Weapons(1).Damage; ``` +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ``` + + ### Union Access Lastly , we can access our `equipped` `union` field. Just like when we created @@ -979,6 +1836,11 @@ only stores a FlatBuffer `table`). } ``` +=== "C" + + ```c + ``` + === "C#" ```c# @@ -991,3 +1853,63 @@ only stores a FlatBuffer `table`). var weaponDamage = weapon.Damage; // 5 } ``` + +=== "Dart" + + ```dart + ``` + +=== "Go" + + ```go + ``` + +=== "Java" + + ```java + ``` + +=== "JavaScript" + + ```javascript + ``` + +=== "Kotlin" + + ```kotlin + ``` + +=== "Lobster" + + ```lobster + ``` + +=== "Lua" + + ```lua + ``` + +=== "PHP" + + ```php + ``` + +=== "Python" + + ```py + ``` + +=== "Rust" + + ```rust + ``` + +=== "Swift" + + ```swift + ``` + +=== "TypeScript" + + ```ts + ```