1Use in Dart {#flatbuffers_guide_use_dart}
2===========
3
4## Before you get started
5
6Before diving into the FlatBuffers usage in Dart, it should be noted that
7the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide
8to general FlatBuffers usage in all of the supported languages (including Dart).
9This page is designed to cover the nuances of FlatBuffers usage, specific to
10Dart.
11
12You should also have read the [Building](@ref flatbuffers_guide_building)
13documentation to build `flatc` and should be familiar with
14[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
15[Writing a schema](@ref flatbuffers_guide_writing_schema).
16
17## FlatBuffers Dart library code location
18
19The code for the FlatBuffers Dart library can be found at
20`flatbuffers/dart`. You can browse the library code on the [FlatBuffers
21GitHub page](https://github.com/google/flatbuffers/tree/master/dart).
22
23## Testing the FlatBuffers Dart library
24
25The code to test the Dart library can be found at `flatbuffers/tests`.
26The test code itself is located in [dart_test.dart](https://github.com/google/
27flatbuffers/blob/master/tests/dart_test.dart).
28
29To run the tests, use the [DartTest.sh](https://github.com/google/flatbuffers/
30blob/master/tests/DartTest.sh) shell script.
31
32*Note: The shell script requires the [Dart SDK](https://www.dartlang.org/tools/sdk)
33to be installed.*
34
35## Using the FlatBuffers Dart library
36
37*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
38example of how to use FlatBuffers in Dart.*
39
40FlatBuffers supports reading and writing binary FlatBuffers in Dart.
41
42To use FlatBuffers in your own code, first generate Dart classes from your
43schema with the `--dart` option to `flatc`. Then you can include both FlatBuffers
44and the generated code to read or write a FlatBuffer.
45
46For example, here is how you would read a FlatBuffer binary file in Dart: First,
47include the library and generated code. Then read a FlatBuffer binary file into
48a `List<int>`, which you pass to the factory constructor for `Monster`:
49
50~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.dart}
51import 'dart:io' as io;
52
53import 'package:flat_buffers/flat_buffers.dart' as fb;
54import './monster_my_game.sample_generated.dart' as myGame;
55
56List<int> data = await new io.File('monster.dat').readAsBytes();
57var monster = new myGame.Monster(data);
58~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59
60Now you can access values like this:
61
62~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.dart}
63var hp = monster.hp;
64var pos = monster.pos;
65~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66
67## Differences from the Dart SDK Front End flat_buffers
68
69The work in this repository is signfiicantly based on the implementation used
70internally by the Dart SDK in the front end/analyzer package. Several
71significant changes have been made.
72
731. Support for packed boolean lists has been removed. This is not standard
74 in other implementations and is not compatible with them. Do note that,
75 like in the JavaScript implementation, __null values in boolean lists
76 will be treated as false__. It is also still entirely possible to pack data
77 in a single scalar field, but that would have to be done on the application
78 side.
792. The SDK implementation supports enums with regular Dart enums, which
80 works if enums are always indexed at 1; however, FlatBuffers does not
81 require that. This implementation uses specialized enum-like classes to
82 ensure proper mapping from FlatBuffers to Dart and other platforms.
833. The SDK implementation does not appear to support FlatBuffer structs or
84 vectors of structs - it treated everything as a built-in scalar or a table.
85 This implementation treats structs in a way that is compatible with other
86 non-Dart implementations, and properly handles vectors of structs. Many of
87 the methods prefixed with 'low' have been prepurposed to support this.
884. The SDK implementation treats int64 and uint64 as float64s. This
89 implementation does not. This may cause problems with JavaScript
90 compatibility - however, it should be possible to use the JavaScript
91 implementation, or to do a customized implementation that treats all 64 bit
92 numbers as floats. Supporting the Dart VM and Flutter was a more important
93 goal of this implementation. Support for 16 bit integers was also added.
945. The code generation in this offers an "ObjectBuilder", which generates code
95 very similar to the SDK classes that consume FlatBuffers, as well as Builder
96 classes, which produces code which more closely resembles the builders in
97 other languages. The ObjectBuilder classes are easier to use, at the cost of
98 additional references allocated.
99
100## Text Parsing
101
102There currently is no support for parsing text (Schema's and JSON) directly
103from Dart, though you could use the C++ parser through Dart Native Extensions.
104Please see the C++ documentation for more on text parsing (note that this is
105not currently an option in Flutter - follow [this issue](https://github.com/flutter/flutter/issues/7053)
106for the latest).
107
108## Object based API
109
110FlatBuffers is all about memory efficiency, which is why its base API is written
111around using as little as possible of it. This does make the API clumsier
112(requiring pre-order construction of all data, and making mutation harder).
113
114For times when efficiency is less important a more convenient object based API
115can be used (through `--gen-object-api`) that is able to unpack & pack a FlatBuffer
116into objects and lists, allowing for convenient construction, access and mutation.
117
118To use:
119
120~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.dart}
121 // Deserialize from buffer into object.
122 MonsterT monster = Monster(flatbuffer).unpack();
123
124 // Update object directly like a Dart class instance.
125 print(monster.Name);
126 monster.Name = "Bob"; // Change the name.
127
128 // Serialize into new flatbuffer.
129 final fbb = Builder();
130 fbb.Finish(monster.pack(fbb));
131~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
View as plain text