tyiu/damus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add swift flatbuffers

Browse Source
This commit is contained in:
William Casarin
2023-08-26 20:43:54 -07:00
parent 35b67dc08d
commit 4c0166bd31
47 changed files with 3955 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
flatbuffers/Documentation.docc/Tutorials/Tutorial_Table_of_Contents.tutorial Normal file
View File

@@ -0,0 +1,14 @@
@Tutorials(name: "Starting with FlatBuffers") {
@Intro(title: "Starting with FlatBuffers") {
FlatBuffers is an efficient cross platform serialization library for C++,
C#, C, Go, Java, Kotlin, JavaScript, Lobster, Lua, TypeScript, PHP, Python, Rust and Swift.
It was originally created at Google for game development and other performance-critical applications.
}
@Chapter(name: "Generating your code") {
Start by generating your first FlatBuffers objects.
@Image(source: tutorial_cover_image_1.png, alt: "A code structure for a base struct in flatbuffers")
@TutorialReference(tutorial: "doc:creating_flatbuffer_schema")
@TutorialReference(tutorial: "doc:create_your_first_buffer")
@TutorialReference(tutorial: "doc:reading_bytebuffer")
}
}

72
flatbuffers/Documentation.docc/Tutorials/create_your_first_buffer.tutorial Normal file
View File

@@ -0,0 +1,72 @@
@Tutorial(time: 5) {
@Intro(title: "After having our code generated") {
After generating the code from the previous section, we will know start creating our monster object.
We will create a monster object called orc.
}
@Section(title: "Building your first buffer") {
@ContentAndMedia {}
@Steps {
@Step {
Starting with a new file, we will create our very first Flatbuffer.
@Code(name: "ViewController.swift", file: "swift_code_1.swift")
}
@Step {
First, we need to import ``FlatBuffers``
@Code(name: "ViewController.swift", file: "swift_code_2.swift")
}
@Step {
We need to create an instance of the `FlatBufferBuilder`, which will contain the buffer as it grows.
You can pass an initial size of the buffer (here 1024 bytes), which will grow automatically if needed.
@Code(name: "ViewController.swift", file: "swift_code_3.swift")
}
@Step {
After creating the builder, we can start serializing our data. Before we make our orc Monster,
let's create some Weapons: a Sword and an Axe. However we will start by naming our weapons as `Sword` and `Axe`
@Code(name: "ViewController.swift", file: "swift_code_4.swift")
}
@Step {
After naming the weapons, we will create two weapon objects with the damage that the weapon is going to deal.
That's done by calling the `start` Method on each table you will be creating, in this case its called `startWeapon`
and finished by calling `end`.
@Code(name: "ViewController.swift", file: "swift_code_5.swift")
}
@Step {
We will take our (Sword and Axe) serialized data and serialize their offsets as a vector of tables into our `ByteBuffer`.
So we can reference them later on from our Monster Object
@Code(name: "ViewController.swift", file: "swift_code_6.swift")
}
@Step {
We will add our Monster name as a string value just like we did with the weapons.
@Code(name: "ViewController.swift", file: "swift_code_7.swift")
}
@Step {
We will create a path that our monster should be using while roaming in its den. To create a vector of paths we would us
`createVector(ofStructs: [])` which will take a Native `Swift` struct that has been padded to fit the `FlatBuffers` standards.
There are usually two ways of creating vectors in `FlatBuffers` which you can see in commented out code.
And thus there are multiple convenience methods that will cover all the bases
when trying to create a vector so that you dont have to create it with `start` and `end`
@Code(name: "ViewController.swift", file: "swift_code_8.swift")
}
@Step {
Now to serialize our data into our `Monster` object. Which again there are two ways of doing, by calling the `create` method or
by serializing the objects yourself. What we added to our Monster were the `Equipped Type` and the `Equipped` union itself, which
allows the Monster to have the `Axe` as his equipped weapon.
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`.
@Code(name: "ViewController.swift", file: "swift_code_9.swift")
}
@Step {
Finally you can just finalize the buffer by calling `builder.finish` and get the Byte array from the buffer.
@Code(name: "ViewController.swift", file: "swift_code_10.swift")
}
}
}
}

47
flatbuffers/Documentation.docc/Tutorials/creating_flatbuffer_schema.tutorial Normal file
View File

@@ -0,0 +1,47 @@
@Tutorial(time: 2) {
@Intro(title: "Creating a schema") {
You will need to have the FlatBuffer compiler to be installed on your device
}
@Section(title: "Creating a schema") {
@ContentAndMedia {}
@Steps {
@Step {
Start by creating a new empty folder called `monster.fbs`. We want to create a Monster table, that contains
position, color, and basic information about the monster.
@Code(name: "monster.fbs", file: "monster_step_1.fbs")
}
@Step {
We will start by adding our Color object. We will be using an enumerate, to represent this object
@Code(name: "monster.fbs", file: "monster_step_2.fbs")
}
@Step {
We will add a position object and will use a struct to represent that type of data. Where we will need the monsters
x and y positions.
@Code(name: "monster.fbs", file: "monster_step_3.fbs")
}
@Step {
Then we will be creating our Monster object of type table. This will contain the current position of our
monster and its color
@Code(name: "monster.fbs", file: "monster_step_4.fbs")
}
@Step {
Our Monster is missing a name, mana, hp, name, equipped Weapon, weapons, and path. We will be adding these
fields to our table with a proper data type for each. Example; weapons, and path would be a vector of data.
@Code(name: "monster.fbs", file: "monster_step_5.fbs")
}
@Step {
Now we are missing two data types here, `Weapon` and `Equipment`. And since Equipment can be a weapon, we will be using
a `Union` enumerate that can contain all the equipment that you would want your monster to have. And the weapon can simply
have a name and amount of damage
@Code(name: "monster.fbs", file: "monster_step_6.fbs")
}
@Step {
And to finalize our monster table, we can add a root type of type Monster.
Then run the command `flatc --swift monster.fbs`
Note: Make sure to import the file to your xcode project.
@Code(name: "monster.fbs", file: "monster_step_7.fbs")
}
}
}
}

27
flatbuffers/Documentation.docc/Tutorials/reading_bytebuffer.tutorial Normal file
View File

@@ -0,0 +1,27 @@
@Tutorial(time: 2) {
@Intro(title: "Reading ByteBuffers") {
After getting our ByteBuffer created, we can now read it.
}
@Section(title: "Reading your first buffer") {
@ContentAndMedia {}
@Steps {
@Step {
After fetching the data from disk or network you need to access that data, and that can be done.
By simply calling `getCheckedRoot`, which checks if the data is valid before enabling you to read from a corrupt buffer.
however, if you are sure that the data is 100% correct you can simply call `getRoot`
@Code(name: "ViewController.swift", file: "swift_code_11.swift")
}
@Step {
Now since we have a Monster object, all the fields can be accessed by simply fetching the data. Note, Deprecated fields will not
show up
@Code(name: "ViewController.swift", file: "swift_code_12.swift")
}
@Step {
And you can access union types as easy as this
@Code(name: "ViewController.swift", file: "swift_code_13.swift")
}
}
}
}