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

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>

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

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"`.