ceph/src/jaegertracing/opentelemetry-cpp/third_party/nlohmann-json/doc/mkdocs/docs/home/faq.md

   1 # Frequently Asked Questions (FAQ)
   2
   3 ## Known bugs
   4
   5 ### Brace initialization yields arrays
   6
   7 !!! question
   8
   9     Why does
  10
  11     ```cpp
  12     json j{true};
  13     ```
  14
  15     and
  16
  17     ```cpp
  18     json j(true);
  19     ```
  20
  21     yield different results (`#!json [true]` vs. `#!json true`)?
  22
  23 This is a known issue, and -- even worse -- the behavior differs between GCC and Clang. The "culprit" for this is the library's constructor overloads for initializer lists to allow syntax like
  24
  25 ```cpp
  26 json array = {1, 2, 3, 4};
  27 ```
  28
  29 for arrays and
  30
  31 ```cpp
  32 json object = {{"one", 1}, {"two", 2}};
  33 ```
  34
  35 for objects.
  36
  37 !!! tip
  38
  39     To avoid any confusion and ensure portable code, **do not** use brace initialization with the types `basic_json`, `json`, or `ordered_json` unless you want to create an object or array as shown in the examples above.
  40
  41 ## Limitations
  42
  43 ### Relaxed parsing
  44
  45 !!! question
  46
  47         Can you add an option to ignore trailing commas?
  48
  49 This library does not support any feature which would jeopardize interoperability.
  50
  51
  52 ### Parse errors reading non-ASCII characters
  53
  54 !!! question "Questions"
  55
  56         - Why is the parser complaining about a Chinese character?
  57         - Does the library support Unicode?
  58         - I get an exception `[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"`
  59
  60 The library supports **Unicode input** as follows:
  61
  62 - Only **UTF-8** encoded input is supported which is the default encoding for JSON according to [RFC 8259](https://tools.ietf.org/html/rfc8259.html#section-8.1).
  63 - `std::u16string` and `std::u32string` can be parsed, assuming UTF-16 and UTF-32 encoding, respectively. These encodings are not supported when reading from files or other input containers.
  64 - Other encodings such as Latin-1 or ISO 8859-1 are **not** supported and will yield parse or serialization errors.
  65 - [Unicode noncharacters](http://www.unicode.org/faq/private_use.html#nonchar1) will not be replaced by the library.
  66 - Invalid surrogates (e.g., incomplete pairs such as `\uDEAD`) will yield parse errors.
  67 - The strings stored in the library are UTF-8 encoded. When using the default string type (`std::string`), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.
  68 - When you store strings with different encodings in the library, calling [`dump()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a50ec80b02d0f3f51130d4abb5d1cfdc5.html#a50ec80b02d0f3f51130d4abb5d1cfdc5) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
  69
  70 In most cases, the parser is right to complain, because the input is not UTF-8 encoded. This is especially true for Microsoft Windows where Latin-1 or ISO 8859-1 is often the standard encoding.
  71
  72
  73 ### Wide string handling
  74
  75 !!! question
  76
  77     Why are wide strings (e.g., `std::wstring`) dumped as arrays of numbers?
  78
  79 As described [above](#parse-errors-reading-non-ascii-characters), the library assumes UTF-8 as encoding.  To store a wide string, you need to change the encoding.
  80
  81 !!! example
  82
  83     ```cpp
  84     #include <codecvt> // codecvt_utf8
  85     #include <locale>  // wstring_convert
  86
  87     // encoding function
  88     std::string to_utf8(std::wstring& wide_string)
  89     {
  90         static std::wstring_convert<std::codecvt_utf8<wchar_t>> utf8_conv;
  91         return utf8_conv.to_bytes(wide_string);
  92     }
  93
  94     json j;
  95     std::wstring ws = L"車B1234 こんにちは";
  96
  97     j["original"] = ws;
  98     j["encoded"] = to_utf8(ws);
  99
 100     std::cout << j << std::endl;
 101     ```
 102
 103     The result is:
 104
 105     ```json
 106     {
 107       "encoded": "車B1234 こんにちは",
 108       "original": [36554, 66, 49, 50, 51, 52, 32, 12371, 12435, 12395, 12385, 12399]
 109     }
 110     ```
 111
 112 ## Exceptions
 113
 114 ### Parsing without exceptions
 115
 116 !!! question
 117
 118     Is it possible to indicate a parse error without throwing an exception?
 119
 120 Yes, see [Parsing and exceptions](../features/parsing/parse_exceptions.md).
 121
 122
 123 ### Key name in exceptions
 124
 125 !!! question
 126
 127         Can I get the key of the object item that caused an exception?
 128
 129 Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../features/macros.md#json_diagnostics) to get [extended diagnostics messages](exceptions.md#extended-diagnostic-messages).
 130
 131
 132 ## Serialization issues
 133
 134
 135 ### Number precision
 136
 137 !!! question
 138
 139         - It seems that precision is lost when serializing a double.
 140         - Can I change the precision for floating-point serialization?
 141
 142 The library uses `std::numeric_limits<number_float_t>::digits10` (15 for IEEE `double`s) digits for serialization. This value is sufficient to guarantee roundtripping. If one uses more than this number of digits of precision, then string -> value -> string is not guaranteed to round-trip.
 143
 144 !!! quote "[cppreference.com](https://en.cppreference.com/w/cpp/types/numeric_limits/digits10)"
 145
 146         The value of `std::numeric_limits<T>::digits10` is the number of base-10 digits that can be represented by the type T without change, that is, any number with this many significant decimal digits can be converted to a value of type T and back to decimal form, without change due to rounding or overflow.
 147
 148 !!! tip
 149
 150         The website https://float.exposed gives a good insight into the internal storage of floating-point numbers.
 151
 152 See [this section](../features/types/number_handling.md#number-serialization) on the library's number handling for more information.
 153
 154 ## Compilation issues
 155
 156 ### Android SDK
 157
 158 !!! question
 159
 160         Why does the code not compile with Android SDK?
 161
 162 Android defaults to using very old compilers and C++ libraries. To fix this, add the following to your `Application.mk`. This will switch to the LLVM C++ library, the Clang compiler, and enable C++11 and other features disabled by default.
 163
 164 ```ini
 165 APP_STL := c++_shared
 166 NDK_TOOLCHAIN_VERSION := clang3.6
 167 APP_CPPFLAGS += -frtti -fexceptions
 168 ```
 169
 170 The code compiles successfully with [Android NDK](https://developer.android.com/ndk/index.html?hl=ml), Revision 9 - 11 (and possibly later) and [CrystaX's Android NDK](https://www.crystax.net/en/android/ndk) version 10.
 171
 172
 173 ### Missing STL function
 174
 175 !!! question "Questions"
 176
 177         - Why do I get a compilation error `'to_string' is not a member of 'std'` (or similarly, for `strtod` or `strtof`)?
 178         - Why does the code not compile with MinGW or Android SDK?
 179
 180 This is not an issue with the code,  but rather with the compiler itself. On Android, see above to build with a newer environment.  For MinGW, please refer to [this site](http://tehsausage.com/mingw-to-string) and [this discussion](https://github.com/nlohmann/json/issues/136) for information on how to fix this bug. For Android NDK using `APP_STL := gnustl_static`, please refer to [this discussion](https://github.com/nlohmann/json/issues/219).