1 Use in Dart {#flatbuffers_guide_use_dart} 2 =========== 3 4 ## Before you get started 5 6 Before diving into the FlatBuffers usage in Dart, it should be noted that 7 the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide 8 to general FlatBuffers usage in all of the supported languages (including Dart). 9 This page is designed to cover the nuances of FlatBuffers usage, specific to 10 Dart. 11 12 You should also have read the [Building](@ref flatbuffers_guide_building) 13 documentation 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 19 The code for the FlatBuffers Go library can be found at 20 `flatbuffers/dart`. You can browse the library code on the [FlatBuffers 21 GitHub page](https://github.com/google/flatbuffers/tree/master/dart). 22 23 ## Testing the FlatBuffers Dart library 24 25 The code to test the Dart library can be found at `flatbuffers/tests`. 26 The test code itself is located in [dart_test.dart](https://github.com/google/ 27 flatbuffers/blob/master/tests/dart_test.dart). 28 29 To run the tests, use the [DartTest.sh](https://github.com/google/flatbuffers/ 30 blob/master/tests/DartTest.sh) shell script. 31 32 *Note: The shell script requires the [Dart SDK](https://www.dartlang.org/tools/sdk) 33 to be installed.* 34 35 ## Using the FlatBuffers Dart library 36 37 *Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth 38 example of how to use FlatBuffers in Dart.* 39 40 FlatBuffers supports reading and writing binary FlatBuffers in Dart. 41 42 To use FlatBuffers in your own code, first generate Dart classes from your 43 schema with the `--dart` option to `flatc`. Then you can include both FlatBuffers 44 and the generated code to read or write a FlatBuffer. 45 46 For example, here is how you would read a FlatBuffer binary file in Dart: First, 47 include the library and generated code. Then read a FlatBuffer binary file into 48 a `List<int>`, which you pass to the factory constructor for `Monster`: 49 50 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.dart} 51 import 'dart:io' as io; 52 53 import 'package:flat_buffers/flat_buffers.dart' as fb; 54 import './monster_my_game.sample_generated.dart' as myGame; 55 56 List<int> data = await new io.File('monster.dat').readAsBytes(); 57 var monster = new myGame.Monster(data); 58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 59 60 Now you can access values like this: 61 62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.dart} 63 var hp = monster.hp; 64 var pos = monster.pos; 65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 66 67 ## Differences from the Dart SDK Front End flat_buffers 68 69 The work in this repository is signfiicantly based on the implementation used 70 internally by the Dart SDK in the front end/analyzer package. Several 71 significant changes have been made. 72 73 1. 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. 79 2. 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. 83 3. 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. 88 4. 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. 94 5. 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 102 There currently is no support for parsing text (Schema's and JSON) directly 103 from Dart, though you could use the C++ parser through Dart Native Extensions. 104 Please see the C++ documentation for more on text parsing (note that this is 105 not currently an option in Flutter - follow [this issue](https://github.com/flutter/flutter/issues/7053) 106 for the latest). 107 108 <br> 109
