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

[C#] support Object API (#5710)

Browse Source 
* [C#] support Object API

* fix sign-compare

* fix indent

* add new line before for loop.

* using auto whenever possible

* reduce the amout of blank lines.

* wip: support vectors of union

* done: support unions of vectors

* set C# version to 4.0
* remove null propagation operator
* remove auto property initializer
* remove expression-bodied method
* remove pattern matching

* add Example2 to NetTest.sh

* separate JavaUsage.md and CsharpUsage.md from JavaCsharpUsage.md

* add C# Object based API notes.

* support vs2010.

* remove range based for loop.

* remove System.Linq

* fix indent

* CreateSharedString to CreateString

* check shared attribute

* snake case
This commit is contained in:
mugisoba
2020-01-31 03:18:28 +09:00
committed by GitHub
parent c580fa284c
commit 7418d85872
36 changed files with 2548 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
docs/source/JavaCsharpUsage.md → docs/source/CsharpUsage.md
View File

@@ -1,54 +1,30 @@
Use in Java/C# {#flatbuffers_guide_use_java_c-sharp}
Use in C# {#flatbuffers_guide_use_c-sharp}
==============
## Before you get started
Before diving into the FlatBuffers usage in Java or C#, it should be noted that
Before diving into the FlatBuffers usage in C#, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
general FlatBuffers usage in all of the supported languages (including both Java
and C#). This page is designed to cover the nuances of FlatBuffers usage,
specific to Java and C#.
general FlatBuffers usage in all of the supported languages (including C#).
This page is designed to cover the nuances of FlatBuffers usage,
specific to C#.
You should also have read the [Building](@ref flatbuffers_guide_building)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
## FlatBuffers Java and C-sharp code location
#### Java
The code for the FlatBuffers Java library can be found at
`flatbuffers/java/com/google/flatbuffers`. You can browse the library on the
[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/
java/com/google/flatbuffers).
#### C-sharp
## FlatBuffers C-sharp code location
The code for the FlatBuffers C# library can be found at
`flatbuffers/net/FlatBuffers`. You can browse the library on the
[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/net/
FlatBuffers).
## Testing the FlatBuffers Java and C-sharp libraries
## Testing the FlatBuffers C-sharp libraries
The code to test the libraries can be found at `flatbuffers/tests`.
#### Java
The test code for Java is located in [JavaTest.java](https://github.com/google
/flatbuffers/blob/master/tests/JavaTest.java).
To run the tests, use either [JavaTest.sh](https://github.com/google/
flatbuffers/blob/master/tests/JavaTest.sh) or [JavaTest.bat](https://github.com/
google/flatbuffers/blob/master/tests/JavaTest.bat), depending on your operating
system.
*Note: These scripts require that [Java](https://www.oracle.com/java/index.html)
is installed.*
#### C-sharp
The test code for C# is located in the [FlatBuffers.Test](https://github.com/
google/flatbuffers/tree/master/tests/FlatBuffers.Test) subfolder. To run the
tests, open `FlatBuffers.Test.csproj` in [Visual Studio](
@@ -63,62 +39,44 @@ by running the following commands from inside the `FlatBuffers.Test` folder:
mono Assert.exe
~~~
## Using the FlatBuffers Java (and C#) library
## Using the FlatBuffers C# library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
example of how to use FlatBuffers in Java or C#.*
example of how to use FlatBuffers in C#.*
FlatBuffers supports reading and writing binary FlatBuffers in Java and C#.
FlatBuffers supports reading and writing binary FlatBuffers in C#.
To use FlatBuffers in your own code, first generate Java classes from your
schema with the `--java` option to `flatc`. (Or for C# with `--csharp`).
To use FlatBuffers in your own code, first generate C# classes from your
schema with the `--csharp` option to `flatc`.
Then you can include both FlatBuffers and the generated code to read
or write a FlatBuffer.
For example, here is how you would read a FlatBuffer binary file in Java:
For example, here is how you would read a FlatBuffer binary file in C#:
First, import the library and generated code. Then, you read a FlatBuffer binary
file into a `byte[]`. You then turn the `byte[]` into a `ByteBuffer`, which you
pass to the `getRootAsMyRootType` function:
pass to the `GetRootAsMyRootType` function:
*Note: The code here is written from the perspective of Java. Code for both
languages is both generated and used in nearly the exact same way, with only
minor differences. These differences are
[explained in a section below](#differences_in_c-sharp).*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
import MyGame.Example.*;
import com.google.flatbuffers.FlatBufferBuilder;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cs}
using MyGame.Example;
using FlatBuffers;
// This snippet ignores exceptions for brevity.
File file = new File("monsterdata_test.mon");
RandomAccessFile f = new RandomAccessFile(file, "r");
byte[] data = new byte[(int)f.length()];
f.readFully(data);
f.close();
byte[] data = File.ReadAllBytes("monsterdata_test.mon");
ByteBuffer bb = ByteBuffer.wrap(data);
Monster monster = Monster.getRootAsMonster(bb);
ByteBuffer bb = new ByteBuffer(data);
Monster monster = Monster.GetRootAsMonster(bb);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now you can access the data from the `Monster monster`:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
short hp = monster.hp();
Vec3 pos = monster.pos();
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cs}
short hp = monster.Hp;
Vec3 pos = monster.Pos;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<a name="differences_in_c-sharp">
#### Differences in C-sharp
</a>
C# code works almost identically to Java, with only a few minor differences.
You can see an example of C# code in
`tests/FlatBuffers.Test/FlatBuffersExampleTests.cs` or
`samples/SampleBinary.cs`.
First of all, naming follows standard C# style with `PascalCasing` identifiers,
C# code naming follows standard C# style with `PascalCasing` identifiers,
e.g. `GetRootAsMyRootType`. Also, values (except vectors and unions) are
available as properties instead of parameterless accessor methods as in Java.
available as properties instead of parameterless accessor methods.
The performance-enhancing methods to which you can pass an already created
object are prefixed with `Get`, e.g.:
@@ -147,13 +105,11 @@ To use it:
array.
- Instead of calling standard generated method,
e.g.: `Monster.createTestarrayoftablesVector`,
call `CreateSortedVectorOfMonster` in C# or
`createSortedVectorOfTables` (from the `FlatBufferBuilder` object) in Java,
call `CreateSortedVectorOfMonster` in C#
which will first sort all offsets such that the tables they refer to
are sorted by the key field, then serialize it.
- Now when you're accessing the FlatBuffer, you can use
the `ByKey` accessor to access elements of the vector, e.g.:
`monster.testarrayoftablesByKey("Frodo")` in Java or
`monster.TestarrayoftablesByKey("Frodo")` in C#,
which returns an object of the corresponding table type,
or `null` if not found.
@@ -165,8 +121,34 @@ To use it:
## Text parsing
There currently is no support for parsing text (Schema's and JSON) directly
from Java or C#, though you could use the C++ parser through native call
from C#, though you could use the C++ parser through native call
interfaces available to each language. Please see the
C++ documentation for more on text parsing.
## Object based API
FlatBuffers is all about memory efficiency, which is why its base API is written
around using as little as possible of it. This does make the API clumsier
(requiring pre-order construction of all data, and making mutation harder).
For times when efficiency is less important a more convenient object based API
can be used (through `--gen-object-api`) that is able to unpack & pack a
FlatBuffer into objects and standard System.Collections.Generic containers, allowing for convenient
construction, access and mutation.
To use:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cs}
// Deserialize from buffer into object.
MonsterT monsterobj = GetMonster(flatbuffer).UnPack();
// Update object directly like a C# class instance.
Console.WriteLine(monsterobj.Name);
monsterobj.Name = "Bob"; // Change the name.
// Serialize into new flatbuffer.
FlatBufferBuilder fbb = new FlatBufferBuilder(1);
fbb.Finish(Monster.Pack(fbb, monsterobj).Value);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<br>

4
docs/source/FlatBuffers.md
View File

@@ -130,7 +130,9 @@ sections provide a more in-depth usage guide.
- How to [write a schema](@ref flatbuffers_guide_writing_schema).
- How to [use the generated C++ code](@ref flatbuffers_guide_use_cpp) in your
own programs.
- How to [use the generated Java/C# code](@ref flatbuffers_guide_use_java_c-sharp)
- How to [use the generated Java code](@ref flatbuffers_guide_use_java)
in your own programs.
- How to [use the generated C# code](@ref flatbuffers_guide_use_c-sharp)
in your own programs.
- How to [use the generated Kotlin code](@ref flatbuffers_guide_use_kotlin)
in your own programs.

114
docs/source/JavaUsage.md Normal file
View File

@@ -0,0 +1,114 @@
Use in Java {#flatbuffers_guide_use_java}
==============
## Before you get started
Before diving into the FlatBuffers usage in Java, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
general FlatBuffers usage in all of the supported languages (including Java).
This page is designed to cover the nuances of FlatBuffers usage,
specific to Java.
You should also have read the [Building](@ref flatbuffers_guide_building)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
## FlatBuffers Java code location
The code for the FlatBuffers Java library can be found at
`flatbuffers/java/com/google/flatbuffers`. You can browse the library on the
[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/
java/com/google/flatbuffers).
## Testing the FlatBuffers Java libraries
The code to test the libraries can be found at `flatbuffers/tests`.
The test code for Java is located in [JavaTest.java](https://github.com/google
/flatbuffers/blob/master/tests/JavaTest.java).
To run the tests, use either [JavaTest.sh](https://github.com/google/
flatbuffers/blob/master/tests/JavaTest.sh) or [JavaTest.bat](https://github.com/
google/flatbuffers/blob/master/tests/JavaTest.bat), depending on your operating
system.
*Note: These scripts require that [Java](https://www.oracle.com/java/index.html)
is installed.*
## Using the FlatBuffers Java library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
example of how to use FlatBuffers in Java.*
FlatBuffers supports reading and writing binary FlatBuffers in Java.
To use FlatBuffers in your own code, first generate Java classes from your
schema with the `--java` option to `flatc`.
Then you can include both FlatBuffers and the generated code to read
or write a FlatBuffer.
For example, here is how you would read a FlatBuffer binary file in Java:
First, import the library and generated code. Then, you read a FlatBuffer binary
file into a `byte[]`. You then turn the `byte[]` into a `ByteBuffer`, which you
pass to the `getRootAsMyRootType` function:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
import MyGame.Example.*;
import com.google.flatbuffers.FlatBufferBuilder;
// This snippet ignores exceptions for brevity.
File file = new File("monsterdata_test.mon");
RandomAccessFile f = new RandomAccessFile(file, "r");
byte[] data = new byte[(int)f.length()];
f.readFully(data);
f.close();
ByteBuffer bb = ByteBuffer.wrap(data);
Monster monster = Monster.getRootAsMonster(bb);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now you can access the data from the `Monster monster`:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
short hp = monster.hp();
Vec3 pos = monster.pos();
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## Storing dictionaries in a FlatBuffer
FlatBuffers doesn't support dictionaries natively, but there is support to
emulate their behavior with vectors and binary search, which means you
can have fast lookups directly from a FlatBuffer without having to unpack
your data into a `Dictionary` or similar.
To use it:
- Designate one of the fields in a table as the "key" field. You do this
by setting the `key` attribute on this field, e.g.
`name:string (key)`.
You may only have one key field, and it must be of string or scalar type.
- Write out tables of this type as usual, collect their offsets in an
array.
- Instead of calling standard generated method,
e.g.: `Monster.createTestarrayoftablesVector`,
call `createSortedVectorOfTables` (from the `FlatBufferBuilder` object).
which will first sort all offsets such that the tables they refer to
are sorted by the key field, then serialize it.
- Now when you're accessing the FlatBuffer, you can use
the `ByKey` accessor to access elements of the vector, e.g.:
`monster.testarrayoftablesByKey("Frodo")`.
which returns an object of the corresponding table type,
or `null` if not found.
`ByKey` performs a binary search, so should have a similar
speed to `Dictionary`, though may be faster because of better caching.
`ByKey` only works if the vector has been sorted, it will
likely not find elements if it hasn't been sorted.
## Text parsing
There currently is no support for parsing text (Schema's and JSON) directly
from Java, though you could use the C++ parser through native call
interfaces available to each language. Please see the
C++ documentation for more on text parsing.
<br>

4
docs/source/Tutorial.md
View File

@@ -3374,13 +3374,13 @@ For your chosen language, see:
[Use in C++](@ref flatbuffers_guide_use_cpp)
</div>
<div class="language-java">
[Use in Java/C#](@ref flatbuffers_guide_use_java_c-sharp)
[Use in Java](@ref flatbuffers_guide_use_java)
</div>
<div class="language-kotlin">
[Use in Kotlin](@ref flatbuffers_guide_use_kotlin)
</div>
<div class="language-csharp">
[Use in Java/C#](@ref flatbuffers_guide_use_java_c-sharp)
[Use in C#](@ref flatbuffers_guide_use_c-sharp)
</div>
<div class="language-go">
[Use in Go](@ref flatbuffers_guide_use_go)

6
docs/source/doxygen_layout.xml
View File

@@ -29,8 +29,10 @@
title="Use in C"/>
<tab type="user" url="@ref flatbuffers_guide_use_go"
title="Use in Go"/>
<tab type="user" url="@ref flatbuffers_guide_use_java_c-sharp"
title="Use in Java/C#"/>
<tab type="user" url="@ref flatbuffers_guide_use_java"
title="Use in Java"/>
<tab type="user" url="@ref flatbuffers_guide_use_c-sharp"
title="Use in C#"/>
<tab type="user" url="@ref flatbuffers_guide_use_javascript"
title="Use in JavaScript"/>
<tab type="user" url="@ref flatbuffers_guide_use_typescript"