diff options
author | Michael Seifert <m.seifert@digitalernachschub.de> | 2019-06-12 12:35:39 +0200 |
---|---|---|
committer | Wouter van Oortmerssen <aardappel@gmail.com> | 2019-06-12 12:35:39 +0200 |
commit | 4eb3efc221d66ef02928d1b1860e097ab2e4ce16 (patch) | |
tree | 5bc3d02c077fb628f5469ddd008706ea23776049 /docs/source | |
parent | a807fa9567c7302b2c446efb3bc7ee79d1a462b4 (diff) | |
download | flatbuffers-4eb3efc221d66ef02928d1b1860e097ab2e4ce16.tar.gz |
[flatc][docs] Document rounding behavior of floats in JSON output (#5397)
* [docs] Added an example on how to convert a FlatBuffer binary to JSON
Slightly adjusted section on "Using flatc as a conversion tool".
Signed-off-by: Michael Seifert <m.seifert@digitalernachschub.de>
* [docs] Updated obsolete JSON data in example showing how to convert JSON to FlatBuffer binaries.
Signed-off-by: Michael Seifert <m.seifert@digitalernachschub.de>
Diffstat (limited to 'docs/source')
-rw-r--r-- | docs/source/Tutorial.md | 67 |
1 files changed, 54 insertions, 13 deletions
diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md index 425fe744..62abe7ff 100644 --- a/docs/source/Tutorial.md +++ b/docs/source/Tutorial.md @@ -2899,16 +2899,18 @@ If this is not sufficient, other ways of mutating FlatBuffers may be supported in your language through an object based API (`--gen-object-api`) or reflection. See the individual language documents for support. -## JSON with FlatBuffers - -#### Using `flatc` as a Conversion Tool - -This is often the preferred method to use JSON with FlatBuffers, as it doesn't -require you to add any new code to your program. It is also efficient, since you -can ship with the binary data. The drawback is that it requires an extra step -for your users/developers to perform (although it may be able to be automated +## Using `flatc` as a JSON Conversion Tool + +If you are working with C, C++, or Lobster, you can parse JSON at runtime. +If your language does not support JSON at the moment, `flatc` may provide an +alternative. Using `flatc` is often the preferred method, as it doesn't require you to +add any new code to your program. It is also efficient, since you can ship with +the binary data. The drawback is that it requires an extra step for your +users/developers to perform (although it may be able to be automated as part of your compilation). +#### JSON to binary representation + Lets say you have a JSON file that describes your monster. In this example, we will use the file `flatbuffers/samples/monsterdata.json`. @@ -2917,16 +2919,31 @@ Here are the contents of the file: ~~~{.json} { pos: { - x: 1, - y: 2, - z: 3 + x: 1.0, + y: 2.0, + z: 3.0 }, hp: 300, - name: "Orc" + name: "Orc", + weapons: [ + { + name: "axe", + damage: 100 + }, + { + name: "bow", + damage: 90 + } + ], + equipped_type: "Weapon", + equipped: { + name: "bow", + damage: 90 + } } ~~~ -You can run this file through the `flatc` compile with the `-b` flag and +You can run this file through the `flatc` compiler with the `-b` flag and our `monster.fbs` schema to produce a FlatBuffer binary file. ~~~{.sh} @@ -2955,6 +2972,30 @@ for `flatcc` to support this.* Guide for more information.* </div> +#### FlatBuffer binary to JSON + +Converting from a FlatBuffer binary representation to JSON is supported as well: +~~~{.sh} +./../flatc --json --raw-binary monster.fbs -- monsterdata.bin +~~~ +This will convert `monsterdata.bin` back to its original JSON representation. +You need to pass the corresponding FlatBuffers schema so that flatc knows how to +interpret the binary buffer. Since `monster.fbs` does not specify an explicit +`file_identifier` for binary buffers, `flatc` needs to be forced into reading +the `.bin` file using the `--raw-binary` option. + +The FlatBuffer binary representation does not explicitly encode default values, +therefore they are not present in the resulting JSON unless you specify +`--defaults-json`. + +If you intend to process the JSON with other tools, you may consider switching +on `--strict-json` so that identifiers are quoted properly. + +*Note: The resulting JSON file is not necessarily identical with the original JSON. +If the binary representation contains floating point numbers, floats and doubles +are rounded to 6 and 12 digits, respectively, in order to represent them as +decimals in the JSON document. * + ## Advanced Features for Each Language Each language has a dedicated `Use in XXX` page in the Programmer's Guide |