diff options
author | Vladimir Glavnyy <31897320+vglavnyy@users.noreply.github.com> | 2019-07-09 01:22:56 +0700 |
---|---|---|
committer | Wouter van Oortmerssen <aardappel@gmail.com> | 2019-07-08 11:22:56 -0700 |
commit | e304f8c115a79c26dfc8b4b164f7920bbddfd7af (patch) | |
tree | 40e668c496325dbac121caba0be73c9ec626be38 /docs/source | |
parent | 47c7aa0361fec7708fae95c19a5cf8063d1a5df4 (diff) | |
download | flatbuffers-e304f8c115a79c26dfc8b4b164f7920bbddfd7af.tar.gz |
Extend the test of MonsterExtra (#5428)
* Extend the test of MonsterExtra
- Extend C++ test of MonsterExtra
- Add conversion of fbs/json NaNs to unsigned quiet-NaN
- Update documentation (cross-platform interoperability)
* Fix declaration of infinity constants int the test
Diffstat (limited to 'docs/source')
-rw-r--r-- | docs/source/CppUsage.md | 56 | ||||
-rw-r--r-- | docs/source/Internals.md | 6 | ||||
-rw-r--r-- | docs/source/Schemas.md | 11 |
3 files changed, 63 insertions, 10 deletions
diff --git a/docs/source/CppUsage.md b/docs/source/CppUsage.md index 6cf36d1f..7867f4be 100644 --- a/docs/source/CppUsage.md +++ b/docs/source/CppUsage.md @@ -35,7 +35,7 @@ The test code itself is located in [test.cpp](https://github.com/google/flatbuffers/blob/master/tests/test.cpp). This test file is built alongside `flatc`. To review how to build the project, -please read the [Building](@ref flatbuffers_guide_building) documenation. +please read the [Building](@ref flatbuffers_guide_building) documentation. To run the tests, execute `flattests` from the root `flatbuffers/` directory. For example, on [Linux](https://en.wikipedia.org/wiki/Linux), you would simply @@ -546,21 +546,63 @@ locale-independent or locale-narrow functions `strtof_l`, `strtod_l`, These functions use specified locale rather than the global or per-thread locale instead. They are part of POSIX-2008 but not part of the C/C++ standard library, therefore, may be missing on some platforms. - The Flatbuffers library try to detect these functions at configuration and compile time: -- `_MSC_VER >= 1900`: check MSVC2012 or higher for MSVC buid -- `_XOPEN_SOURCE>=700`: check POSIX-2008 for GCC/Clang build -- `check_cxx_symbol_exists(strtof_l stdlib.h)`: CMake check of `strtod_f` +- CMake `"CMakeLists.txt"`: + - Check existence of `strtol_l` and `strtod_l` in the `<stdlib.h>`. +- Compile-time `"/include/base.h"`: + - `_MSC_VER >= 1900`: MSVC2012 or higher if build with MSVC. + - `_XOPEN_SOURCE>=700`: POSIX-2008 if build with GCC/Clang. After detection, the definition `FLATBUFFERS_LOCALE_INDEPENDENT` will be set to `0` or `1`. +To override or stop this detection use CMake `-DFLATBUFFERS_LOCALE_INDEPENDENT={0|1}` +or predefine `FLATBUFFERS_LOCALE_INDEPENDENT` symbol. -It is possible to test the compatibility of the Flatbuffers library with -a specific locale using the environment variable `FLATBUFFERS_TEST_LOCALE`: +To test the compatibility of the Flatbuffers library with +a specific locale use the environment variable `FLATBUFFERS_TEST_LOCALE`: ```sh >FLATBUFFERS_TEST_LOCALE="" ./flattests >FLATBUFFERS_TEST_LOCALE="ru_RU.CP1251" ./flattests ``` +## Support of floating-point numbers +The Flatbuffers library assumes that a C++ compiler and a CPU are +compatible with the `IEEE-754` floating-point standard. +The schema and json parser may fail if `fast-math` or `/fp:fast` mode is active. + +### Support of hexadecimal and special floating-point numbers +According to the [grammar](@ref flatbuffers_grammar) `fbs` and `json` files +may use hexadecimal and special (`NaN`, `Inf`) floating-point literals. +The Flatbuffers uses `strtof` and `strtod` functions to parse floating-point +literals. The Flatbuffers library has a code to detect a compiler compatibility +with the literals. If necessary conditions are met the preprocessor constant +`FLATBUFFERS_HAS_NEW_STRTOD` will be set to `1`. +The support of floating-point literals will be limited at compile time +if `FLATBUFFERS_HAS_NEW_STRTOD` constant is less than `1`. +In this case, schemas with hexadecimal or special literals cannot be used. + +### Comparison of floating-point NaN values +The floating-point `NaN` (`not a number`) is special value which +representing an undefined or unrepresentable value. +`NaN` may be explicitly assigned to variables, typically as a representation +for missing values or may be a result of a mathematical operation. +The `IEEE-754` defines two kind of `NaNs`: +- Quiet NaNs, or `qNaNs`. +- Signaling NaNs, or `sNaNs`. + +According to the `IEEE-754`, a comparison with `NaN` always returns +an unordered result even when compared with itself. As a result, a whole +Flatbuffers object will be not equal to itself if has one or more `NaN`. +Flatbuffers scalar fields that have the default value are not actually stored +in the serialized data but are generated in code (see [Writing a schema](@ref flatbuffers_guide_writing_schema)). +Scalar fields with `NaN` defaults break this behavior. +If a schema has a lot of `NaN` defaults the Flatbuffers can override +the unordered comparison by the ordered: `(NaN==NaN)->true`. +This ordered comparison is enabled when compiling a program with the symbol +`FLATBUFFERS_NAN_DEFAULTS` defined. +Additional computations added by `FLATBUFFERS_NAN_DEFAULTS` are very cheap +if GCC or Clang used. These compilers have a compile-time implementation +of `isnan` checking which MSVC does not. + <br> diff --git a/docs/source/Internals.md b/docs/source/Internals.md index e8f453a8..d2064ca6 100644 --- a/docs/source/Internals.md +++ b/docs/source/Internals.md @@ -15,6 +15,12 @@ all commonly used CPUs today. FlatBuffers will also work on big-endian machines, but will be slightly slower because of additional byte-swap intrinsics. +It is assumed that the following conditions are met, to ensure +cross-platform interoperability: +- The binary `IEEE-754` format is used for floating-point numbers. +- The `two's complemented` representation is used for signed integers. +- The endianness is the same for floating-point numbers as for integers. + On purpose, the format leaves a lot of details about where exactly things live in memory undefined, e.g. fields in a table can have any order, and objects to some extent can be stored in many orders. This is diff --git a/docs/source/Schemas.md b/docs/source/Schemas.md index 58bedae6..403aebbe 100644 --- a/docs/source/Schemas.md +++ b/docs/source/Schemas.md @@ -439,14 +439,19 @@ numerical literals: For example: `[0x123, +0x45, -0x67]` are equal to `[291, 69, -103]` decimals. - The format of float-point numbers is fully compatible with C/C++ format. If a modern C++ compiler is used the parser accepts hexadecimal and special - float-point literals as well: + floating-point literals as well: `[-1.0, 2., .3e0, 3.e4, 0x21.34p-5, -inf, nan]`. - The exponent suffix of hexadecimal float-point number is mandatory. - Extended float-point support was tested with: + The following conventions for floating-point numbers are used: + - The exponent suffix of hexadecimal floating-point number is mandatory. + - Parsed `NaN` converted to unsigned IEEE-754 `quiet-NaN` value. + + Extended floating-point support was tested with: - x64 Windows: `MSVC2015` and higher. - x64 Linux: `LLVM 6.0`, `GCC 4.9` and higher. + For details, see [Use in C++](@ref flatbuffers_guide_use_cpp) section. + - For compatibility with a JSON lint tool all numeric literals of scalar fields can be wrapped to quoted string: `"1", "2.0", "0x48A", "0x0C.0Ep-1", "-inf", "true"`. |