From 4eb3efc221d66ef02928d1b1860e097ab2e4ce16 Mon Sep 17 00:00:00 2001 From: Michael Seifert Date: Wed, 12 Jun 2019 12:35:39 +0200 Subject: [PATCH] [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 * [docs] Updated obsolete JSON data in example showing how to convert JSON to FlatBuffer binaries. Signed-off-by: Michael Seifert --- docs/source/Tutorial.md | 67 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 54 insertions(+), 13 deletions(-) diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md index 425fe74..62abe7f 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.* +#### 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 -- 2.7.4