deploy: cc917d7123

api/basic_json/parse/index.md

@@ -24,6 +24,8 @@ static basic_json parse(IteratorType first, SentinelType last,
 
    The `value_type` of the iterator must be an integral type with size of 1, 2, or 4 bytes, which will be interpreted respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to the iterator type with `operator!=`.
 
+   Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its low surrogate, and a code point above `U+10FFFF` all yield a [`parse_error.101`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error101).
+
 ## Template parameters
 
 `InputType` : A compatible input, for instance:
@@ -33,9 +35,12 @@ static basic_json parse(IteratorType first, SentinelType last,
 - a `FILE` pointer (throws if null)
 - a C-style array of characters
 - a pointer to a null-terminated string of single byte characters (throws if null)
-- a `std::string`
+- a `std::string` or a `std::string_view` (C++17)
 - a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
   (as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
+- wide characters (`wchar_t`, `char16_t`, `char32_t`), which are converted to UTF-8: a wide string object
+  (`std::wstring`, `std::u16string`, `std::u32string`) or an array (e.g. a wide string literal); a pointer to a
+  null-terminated wide string (e.g. `std::u16string::c_str()`) is not supported
 ```
 
 `IteratorType` : a compatible iterator type, for instance.
@@ -93,6 +98,10 @@ Invalid Unicode escapes and unpaired surrogates in the input are reported as [`p
 
 By default, a `'\0'` (NUL) byte anywhere in the input is treated as end of input, rather than as an ordinary (and, outside of a string, invalid) byte; see the [FAQ entry](https://json.nlohmann.me/home/faq/#nul-bytes-in-the-input) for details and the [`JSON_STRICT_NUL_HANDLING`](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md) macro to opt into rejecting it instead.
 
+Parsing into a document instead of a value
+
+[`basic_json_document::parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) accepts the same inputs and the same options, but keeps the result as a flat index of the parsed values instead of a tree of `basic_json` values. It is faster and uses less memory when only parts of the document are read, and it also accepts a pointer to a null-terminated wide string, which `parse()` does not. See [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md).
+
 Performance
 
 Contiguous inputs (strings, string views, vectors, arrays, pointer ranges) are the fastest to parse. A `std::istream` comes close: the parser scans the characters its stream buffer holds in bulk, without reading ahead, so the stream is left exactly where it would be after reading one character at a time. A `FILE*` is read one character at a time, but the file is locked only once, so other threads that use the same `FILE` object wait until parsing is done. See [input sources and performance](https://json.nlohmann.me/features/parsing/#input-sources-and-performance), [`JSON_DISABLE_STREAM_BULK_SCAN`](https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/index.md), and [`JSON_DISABLE_UNLOCKED_FILE_IO`](https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/index.md).
@@ -618,6 +627,51 @@ Output:
 }
 ```
 
+Example: parse from UTF-16, UTF-32, and wide strings
+
+The encoding is deduced from the character type of the input; `std::u16string` and `std::u32string` are interpreted as UTF-16 and UTF-32, and `std::wstring` uses the platform's `wchar_t` width. String literals like `u"..."`, `U"..."`, and `L"..."` work as well, as do iterators over wide characters.
+
+```
+#include <iostream>
+#include <string>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // the same JSON text, given in different encodings
+    const std::string utf8 = "{\"name\":\"\u00e9\"}";
+    const std::u16string utf16 = u"{\"name\":\"\u00e9\"}";
+    const std::u32string utf32 = U"{\"name\":\"\u00e9\"}";
+    const std::wstring wide = L"{\"name\":\"\u00e9\"}";
+
+    // the encoding is deduced from the character type of the input, and all
+    // of them yield the same value
+    std::cout << json::parse(utf8) << '\n'
+              << json::parse(utf16) << '\n'
+              << json::parse(utf32) << '\n'
+              << json::parse(wide) << '\n';
+
+    // a wide string literal works as well: u"..." is UTF-16, U"..." is UTF-32
+    std::cout << json::parse(u"[1, 2, 3]") << '\n';
+
+    // iterators over wide characters work as well
+    std::cout << json::parse(utf16.begin(), utf16.end()) << '\n';
+}
+```
+
+Output:
+
+```
+{"name":"é"}
+{"name":"é"}
+{"name":"é"}
+{"name":"é"}
+[1,2,3]
+{"name":"é"}
+```
+
 ## See also
 
 - [accept](https://json.nlohmann.me/api/basic_json/accept/index.md) - check if the input is valid JSON
@@ -640,6 +694,7 @@ Output:
 - Extended empty-input detection to also cover an `std::istream` without a stream buffer, and fixed a crash (`std::terminate`) when parsing from an `std::istream` with `eofbit` in its exception mask, in version 3.13.0 unreleased.
 - Parsing from an `std::istream` scans the characters in its stream buffer in bulk in version 3.13.0 unreleased ([`JSON_DISABLE_STREAM_BULK_SCAN`](https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/index.md) restores reading one character at a time).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0 unreleased ([`JSON_DISABLE_UNLOCKED_FILE_IO`](https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/index.md) restores `std::fgetc`).
+- Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or a code point above `U+10FFFF`) is rejected with `parse_error.101` in version 3.13.0 unreleased; before that, some such sequences were accepted or ended the input silently.
 
 Deprecation