flatbuffers_guide_use_dart.html - third_party/flatbuffers - Git at Google

 <!-- HTML header for doxygen 1.8.6-->
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
 <meta name="generator" content="Doxygen 1.9.1"/>
 <title>FlatBuffers: Use in Dart</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
 <link href="navtree.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="resize.js"></script>
 <script type="text/javascript" src="navtreedata.js"></script>
 <script type="text/javascript" src="navtree.js"></script>
 <link href="search/search.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="search/searchdata.js"></script>
 <script type="text/javascript" src="search/search.js"></script>
 <link href="doxygen.css" rel="stylesheet" type="text/css" />
 <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
 <link href="style.css" rel="stylesheet" type="text/css"/>
 </head>
 <body>
 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
 <div id="titlearea" style="height: 110px;">
 <table cellspacing="0" cellpadding="0">
  <tbody>
  <tr style="height: 56px;">
   <td id="commonprojectlogo">
     <img alt="Logo" src="fpl_logo_small.png"/>
   </td>
   <td style="padding-left: 0.5em;">
    <div id="projectname">FlatBuffers
    </div>
    <div style="font-size:12px;">
     An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
    </div>
   </td>
  </tr>
  </tbody>
 </table>
 </div>
 <!-- end header part -->
 <!-- Generated by Doxygen 1.9.1 -->
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
 /* @license-end */
 </script>
 <script type="text/javascript" src="menudata.js"></script>
 <script type="text/javascript" src="menu.js"></script>
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 $(function() {
   initMenu('',true,false,'search.php','Search');
   $(document).ready(function() { init_search(); });
 });
 /* @license-end */</script>
 <div id="main-nav"></div>
 </div><!-- top -->
 <div id="side-nav" class="ui-resizable side-nav-resizable">
   <div id="nav-tree">
     <div id="nav-tree-contents">
       <div id="nav-sync" class="sync"></div>
     </div>
   </div>
   <div id="splitbar" style="-moz-user-select:none;"
        class="ui-resizable-handle">
   </div>
 </div>
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 $(document).ready(function(){initNavTree('flatbuffers_guide_use_dart.html',''); initResizable(); });
 /* @license-end */
 </script>
 <div id="doc-content">
 <!-- window showing the filter options -->
 <div id="MSearchSelectWindow"
      onmouseover="return searchBox.OnSearchSelectShow()"
      onmouseout="return searchBox.OnSearchSelectHide()"
      onkeydown="return searchBox.OnSearchSelectKey(event)">
 </div>

 <!-- iframe showing the search results (closed by default) -->
 <div id="MSearchResultsWindow">
 <iframe src="javascript:void(0)" frameborder="0"
         name="MSearchResults" id="MSearchResults">
 </iframe>
 </div>

 <div class="PageDoc"><div class="header">
   <div class="headertitle">
 <div class="title">Use in Dart </div>  </div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p><a class="anchor" id="md_DartUsage"></a></p>
 <h1><a class="anchor" id="autotoc_md70"></a>
 Before you get started</h1>
 <p>Before diving into the FlatBuffers usage in Dart, it should be noted that the <a class="el" href="flatbuffers_guide_tutorial.html">Tutorial</a> page has a complete guide to general FlatBuffers usage in all of the supported languages (including Dart). This page is designed to cover the nuances of FlatBuffers usage, specific to Dart.</p>
 <p>You should also have read the <a class="el" href="flatbuffers_guide_building.html">Building</a> documentation to build <code>flatc</code> and should be familiar with <a class="el" href="flatbuffers_guide_using_schema_compiler.html">Using the schema compiler</a> and <a class="el" href="flatbuffers_guide_writing_schema.html">Writing a schema</a>.</p>
 <h1><a class="anchor" id="autotoc_md71"></a>
 FlatBuffers Dart library code location</h1>
 <p>The code for the FlatBuffers Dart library can be found at <code>flatbuffers/dart</code>. You can browse the library code on the <a href="https://github.com/google/flatbuffers/tree/master/dart">FlatBuffers GitHub page</a>.</p>
 <h1><a class="anchor" id="autotoc_md72"></a>
 Testing the FlatBuffers Dart library</h1>
 <p>The code to test the Dart library can be found at <code>flatbuffers/tests</code>. The test code itself is located in <a href="https://github.com/google/
 flatbuffers/blob/master/tests/dart_test.dart">dart_test.dart</a>.</p>
 <p>To run the tests, use the <a href="https://github.com/google/flatbuffers/
 blob/master/tests/DartTest.sh">DartTest.sh</a> shell script.</p>
 <p><em>Note: The shell script requires the <a href="https://www.dartlang.org/tools/sdk">Dart SDK</a> to be installed.</em></p>
 <h1><a class="anchor" id="autotoc_md73"></a>
 Using the FlatBuffers Dart library</h1>
 <p><em>Note: See <a class="el" href="flatbuffers_guide_tutorial.html">Tutorial</a> for a more in-depth example of how to use FlatBuffers in Dart.</em></p>
 <p>FlatBuffers supports reading and writing binary FlatBuffers in Dart.</p>
 <p>To use FlatBuffers in your own code, first generate Dart classes from your schema with the <code>--dart</code> option to <code>flatc</code>. Then you can include both FlatBuffers and the generated code to read or write a FlatBuffer.</p>
 <p>For example, here is how you would read a FlatBuffer binary file in Dart: First, include the library and generated code. Then read a FlatBuffer binary file into a <code>List&lt;int&gt;</code>, which you pass to the factory constructor for <code>Monster</code>:</p>
 <div class="fragment"><div class="line">import &#39;dart:io&#39; as io;</div>
 <div class="line"> </div>
 <div class="line">import &#39;package:flat_buffers/flat_buffers.dart&#39; as fb;</div>
 <div class="line">import &#39;./monster_my_game.sample_generated.dart&#39; as myGame;</div>
 <div class="line"> </div>
 <div class="line">List&lt;int&gt; data = await new io.File(&#39;monster.dat&#39;).readAsBytes();</div>
 <div class="line">var monster = new myGame.Monster(data);</div>
 </div><!-- fragment --><p>Now you can access values like this:</p>
 <div class="fragment"><div class="line">var hp = monster.hp;</div>
 <div class="line">var pos = monster.pos;</div>
 </div><!-- fragment --><h1><a class="anchor" id="autotoc_md74"></a>
 Differences from the Dart SDK Front End flat_buffers</h1>
 <p>The work in this repository is signfiicantly based on the implementation used internally by the Dart SDK in the front end/analyzer package. Several significant changes have been made.</p>
 <ol type="1">
 <li>Support for packed boolean lists has been removed. This is not standard in other implementations and is not compatible with them. Do note that, like in the JavaScript implementation, <b>null values in boolean lists will be treated as false</b>. It is also still entirely possible to pack data in a single scalar field, but that would have to be done on the application side.</li>
 <li>The SDK implementation supports enums with regular Dart enums, which works if enums are always indexed at 1; however, FlatBuffers does not require that. This implementation uses specialized enum-like classes to ensure proper mapping from FlatBuffers to Dart and other platforms.</li>
 <li>The SDK implementation does not appear to support FlatBuffer structs or vectors of structs - it treated everything as a built-in scalar or a table. This implementation treats structs in a way that is compatible with other non-Dart implementations, and properly handles vectors of structs. Many of the methods prefixed with 'low' have been prepurposed to support this.</li>
 <li>The SDK implementation treats int64 and uint64 as float64s. This implementation does not. This may cause problems with JavaScript compatibility - however, it should be possible to use the JavaScript implementation, or to do a customized implementation that treats all 64 bit numbers as floats. Supporting the Dart VM and Flutter was a more important goal of this implementation. Support for 16 bit integers was also added.</li>
 <li>The code generation in this offers an "ObjectBuilder", which generates code very similar to the SDK classes that consume FlatBuffers, as well as Builder classes, which produces code which more closely resembles the builders in other languages. The ObjectBuilder classes are easier to use, at the cost of additional references allocated.</li>
 </ol>
 <h1><a class="anchor" id="autotoc_md75"></a>
 Text Parsing</h1>
 <p>There currently is no support for parsing text (Schema's and JSON) directly from Dart, though you could use the C++ parser through Dart Native Extensions. Please see the C++ documentation for more on text parsing (note that this is not currently an option in Flutter - follow <a href="https://github.com/flutter/flutter/issues/7053">this issue</a> for the latest).</p>
 <h1><a class="anchor" id="autotoc_md76"></a>
 Object based API</h1>
 <p>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).</p>
 <p>For times when efficiency is less important a more convenient object based API can be used (through <code>--gen-object-api</code>) that is able to unpack &amp; pack a FlatBuffer into objects and lists, allowing for convenient construction, access and mutation.</p>
 <p>To use:</p>
 <div class="fragment"><div class="line">// Deserialize from buffer into object.</div>
 <div class="line">MonsterT monster = Monster(flatbuffer).unpack();</div>
 <div class="line"> </div>
 <div class="line">// Update object directly like a Dart class instance.</div>
 <div class="line">print(monster.Name);</div>
 <div class="line">monster.Name = &quot;Bob&quot;;  // Change the name.</div>
 <div class="line"> </div>
 <div class="line">// Serialize into new flatbuffer.</div>
 <div class="line">final fbb = Builder();</div>
 <div class="line">fbb.Finish(monster.pack(fbb));</div>
 </div><!-- fragment --> </div></div><!-- contents -->
 </div><!-- PageDoc -->
 </div><!-- doc-content -->
 <!-- Google Analytics -->
 <script>
   (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
   (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
   m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
   })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
   ga('create', 'UA-49880327-7', 'auto');
   ga('send', 'pageview');
 </script>
 </body>
 </html>
	<!-- HTML header for doxygen 1.8.6-->
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
	<meta http-equiv="X-UA-Compatible" content="IE=9"/>
	<meta name="generator" content="Doxygen 1.9.1"/>
	<title>FlatBuffers: Use in Dart</title>
	<link href="tabs.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="jquery.js"></script>
	<script type="text/javascript" src="dynsections.js"></script>
	<link href="navtree.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="resize.js"></script>
	<script type="text/javascript" src="navtreedata.js"></script>
	<script type="text/javascript" src="navtree.js"></script>
	<link href="search/search.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="search/searchdata.js"></script>
	<script type="text/javascript" src="search/search.js"></script>
	<link href="doxygen.css" rel="stylesheet" type="text/css" />
	<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic\|Roboto+Mono:400,700" rel="stylesheet">
	<link href="style.css" rel="stylesheet" type="text/css"/>
	</head>
	<body>
	<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
	<div id="titlearea" style="height: 110px;">
	<table cellspacing="0" cellpadding="0">
	<tbody>
	<tr style="height: 56px;">
	<td id="commonprojectlogo">
	<img alt="Logo" src="fpl_logo_small.png"/>
	</td>
	<td style="padding-left: 0.5em;">
	<div id="projectname">FlatBuffers
	</div>
	<div style="font-size:12px;">
	An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
	</div>
	</td>
	</tr>
	</tbody>
	</table>
	</div>
	<!-- end header part -->
	<!-- Generated by Doxygen 1.9.1 -->
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
	/* @license-end */
	</script>
	<script type="text/javascript" src="menudata.js"></script>
	<script type="text/javascript" src="menu.js"></script>
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	$(function() {
	initMenu('',true,false,'search.php','Search');
	$(document).ready(function() { init_search(); });
	});
	/* @license-end */</script>
	<div id="main-nav"></div>
	</div><!-- top -->
	<div id="side-nav" class="ui-resizable side-nav-resizable">
	<div id="nav-tree">
	<div id="nav-tree-contents">
	<div id="nav-sync" class="sync"></div>
	</div>
	</div>
	<div id="splitbar" style="-moz-user-select:none;"
	class="ui-resizable-handle">
	</div>
	</div>
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	$(document).ready(function(){initNavTree('flatbuffers_guide_use_dart.html',''); initResizable(); });
	/* @license-end */
	</script>
	<div id="doc-content">
	<!-- window showing the filter options -->
	<div id="MSearchSelectWindow"
	onmouseover="return searchBox.OnSearchSelectShow()"
	onmouseout="return searchBox.OnSearchSelectHide()"
	onkeydown="return searchBox.OnSearchSelectKey(event)">
	</div>

	<!-- iframe showing the search results (closed by default) -->
	<div id="MSearchResultsWindow">
	<iframe src="javascript:void(0)" frameborder="0"
	name="MSearchResults" id="MSearchResults">
	</iframe>
	</div>

	<div class="PageDoc"><div class="header">
	<div class="headertitle">
	<div class="title">Use in Dart </div> </div>
	</div><!--header-->
	<div class="contents">
	<div class="textblock"><p><a class="anchor" id="md_DartUsage"></a></p>
	<h1><a class="anchor" id="autotoc_md70"></a>
	Before you get started</h1>
	<p>Before diving into the FlatBuffers usage in Dart, it should be noted that the <a class="el" href="flatbuffers_guide_tutorial.html">Tutorial</a> page has a complete guide to general FlatBuffers usage in all of the supported languages (including Dart). This page is designed to cover the nuances of FlatBuffers usage, specific to Dart.</p>
	<p>You should also have read the <a class="el" href="flatbuffers_guide_building.html">Building</a> documentation to build <code>flatc</code> and should be familiar with <a class="el" href="flatbuffers_guide_using_schema_compiler.html">Using the schema compiler</a> and <a class="el" href="flatbuffers_guide_writing_schema.html">Writing a schema</a>.</p>
	<h1><a class="anchor" id="autotoc_md71"></a>
	FlatBuffers Dart library code location</h1>
	<p>The code for the FlatBuffers Dart library can be found at <code>flatbuffers/dart</code>. You can browse the library code on the <a href="https://github.com/google/flatbuffers/tree/master/dart">FlatBuffers GitHub page</a>.</p>
	<h1><a class="anchor" id="autotoc_md72"></a>
	Testing the FlatBuffers Dart library</h1>
	<p>The code to test the Dart library can be found at <code>flatbuffers/tests</code>. The test code itself is located in <a href="https://github.com/google/
	flatbuffers/blob/master/tests/dart_test.dart">dart_test.dart</a>.</p>
	<p>To run the tests, use the <a href="https://github.com/google/flatbuffers/
	blob/master/tests/DartTest.sh">DartTest.sh</a> shell script.</p>
	<p><em>Note: The shell script requires the <a href="https://www.dartlang.org/tools/sdk">Dart SDK</a> to be installed.</em></p>
	<h1><a class="anchor" id="autotoc_md73"></a>
	Using the FlatBuffers Dart library</h1>
	<p><em>Note: See <a class="el" href="flatbuffers_guide_tutorial.html">Tutorial</a> for a more in-depth example of how to use FlatBuffers in Dart.</em></p>
	<p>FlatBuffers supports reading and writing binary FlatBuffers in Dart.</p>
	<p>To use FlatBuffers in your own code, first generate Dart classes from your schema with the <code>--dart</code> option to <code>flatc</code>. Then you can include both FlatBuffers and the generated code to read or write a FlatBuffer.</p>
	<p>For example, here is how you would read a FlatBuffer binary file in Dart: First, include the library and generated code. Then read a FlatBuffer binary file into a <code>List<int></code>, which you pass to the factory constructor for <code>Monster</code>:</p>
	<div class="fragment"><div class="line">import 'dart:io' as io;</div>
	<div class="line"> </div>
	<div class="line">import 'package:flat_buffers/flat_buffers.dart' as fb;</div>
	<div class="line">import './monster_my_game.sample_generated.dart' as myGame;</div>
	<div class="line"> </div>
	<div class="line">List<int> data = await new io.File('monster.dat').readAsBytes();</div>
	<div class="line">var monster = new myGame.Monster(data);</div>
	</div><!-- fragment --><p>Now you can access values like this:</p>
	<div class="fragment"><div class="line">var hp = monster.hp;</div>
	<div class="line">var pos = monster.pos;</div>
	</div><!-- fragment --><h1><a class="anchor" id="autotoc_md74"></a>
	Differences from the Dart SDK Front End flat_buffers</h1>
	<p>The work in this repository is signfiicantly based on the implementation used internally by the Dart SDK in the front end/analyzer package. Several significant changes have been made.</p>
	<ol type="1">
	<li>Support for packed boolean lists has been removed. This is not standard in other implementations and is not compatible with them. Do note that, like in the JavaScript implementation, <b>null values in boolean lists will be treated as false</b>. It is also still entirely possible to pack data in a single scalar field, but that would have to be done on the application side.</li>
	<li>The SDK implementation supports enums with regular Dart enums, which works if enums are always indexed at 1; however, FlatBuffers does not require that. This implementation uses specialized enum-like classes to ensure proper mapping from FlatBuffers to Dart and other platforms.</li>
	<li>The SDK implementation does not appear to support FlatBuffer structs or vectors of structs - it treated everything as a built-in scalar or a table. This implementation treats structs in a way that is compatible with other non-Dart implementations, and properly handles vectors of structs. Many of the methods prefixed with 'low' have been prepurposed to support this.</li>
	<li>The SDK implementation treats int64 and uint64 as float64s. This implementation does not. This may cause problems with JavaScript compatibility - however, it should be possible to use the JavaScript implementation, or to do a customized implementation that treats all 64 bit numbers as floats. Supporting the Dart VM and Flutter was a more important goal of this implementation. Support for 16 bit integers was also added.</li>
	<li>The code generation in this offers an "ObjectBuilder", which generates code very similar to the SDK classes that consume FlatBuffers, as well as Builder classes, which produces code which more closely resembles the builders in other languages. The ObjectBuilder classes are easier to use, at the cost of additional references allocated.</li>
	</ol>
	<h1><a class="anchor" id="autotoc_md75"></a>
	Text Parsing</h1>
	<p>There currently is no support for parsing text (Schema's and JSON) directly from Dart, though you could use the C++ parser through Dart Native Extensions. Please see the C++ documentation for more on text parsing (note that this is not currently an option in Flutter - follow <a href="https://github.com/flutter/flutter/issues/7053">this issue</a> for the latest).</p>
	<h1><a class="anchor" id="autotoc_md76"></a>
	Object based API</h1>
	<p>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).</p>
	<p>For times when efficiency is less important a more convenient object based API can be used (through <code>--gen-object-api</code>) that is able to unpack & pack a FlatBuffer into objects and lists, allowing for convenient construction, access and mutation.</p>
	<p>To use:</p>
	<div class="fragment"><div class="line">// Deserialize from buffer into object.</div>
	<div class="line">MonsterT monster = Monster(flatbuffer).unpack();</div>
	<div class="line"> </div>
	<div class="line">// Update object directly like a Dart class instance.</div>
	<div class="line">print(monster.Name);</div>
	<div class="line">monster.Name = "Bob"; // Change the name.</div>
	<div class="line"> </div>
	<div class="line">// Serialize into new flatbuffer.</div>
	<div class="line">final fbb = Builder();</div>
	<div class="line">fbb.Finish(monster.pack(fbb));</div>
	</div><!-- fragment --> </div></div><!-- contents -->
	</div><!-- PageDoc -->
	</div><!-- doc-content -->
	<!-- Google Analytics -->
	<script>
	(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]\|\|function(){
	(i[r].q=i[r].q\|\|[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
	m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
	})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
	ga('create', 'UA-49880327-7', 'auto');
	ga('send', 'pageview');
	</script>
	</body>
	</html>