External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

🔥 consolidate documentation

Browse Source
This commit is contained in:
Niels Lohmann 2021-11-03 14:51:19 +01:00
parent cc218b7e80
commit ca5ecc2945
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
6 changed files with 99 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/mkdocs/docs/api/basic_json/index.md
View File

@ -280,7 +280,7 @@ Access to the JSON value
## Non-member functions
- [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream
- operator>>(std::istream&) - deserialize from stream
- [**operator>>(std::istream&)**](operator_gtgt.md) - deserialize from stream
## Literals

58
doc/mkdocs/docs/api/basic_json/operator_gtgt.md Normal file
View File

@ -0,0 +1,58 @@
# operator>>(basic_json)
```cpp
std::istream& operator>>(std::istream& i, basic_json& j)
```
Deserializes an input stream to a JSON value.
## Parameters
`i` (in, out)
: input stream to read a serialized JSON value from
`j` (in, out)
: JSON value to write the deserialized input to
## Return value
the stream `i`
## Exceptions
- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate
error.
- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
## Complexity
Linear in the length of the input. The parser is a predictive LL(1) parser.
## Note
A UTF-8 byte order mark is silently ignored.
## Example
??? example
The example below shows how a JSON value is constructed by reading a serialization from a stream.
```cpp
--8<-- "examples/operator_deserialize.cpp"
```
Output:
```json
--8<-- "examples/operator_deserialize.output"
```
## See also
- [parse](parse.md) for a variant with a parser callback function to filter values while parsing
## Version history
- Added in version 1.0.0

1
doc/mkdocs/docs/api/basic_json/operator_ltlt.md
View File

@ -3,6 +3,7 @@
```cpp
std::ostream& operator<<(std::ostream& o, const basic_json& j)
```
Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the
[`dump`](dump.md) member function.

1
doc/mkdocs/mkdocs.yml
View File

@ -151,6 +151,7 @@ nav:
- api/basic_json/operator_ltlt.md
- api/basic_json/operator_le.md
- api/basic_json/operator_gt.md
- api/basic_json/operator_gtgt.md
- api/basic_json/operator_ge.md
- api/basic_json/operator+=.md
- api/basic_json/operator_literal_json.md

60
include/nlohmann/json.hpp
View File

@ -3640,14 +3640,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return o;
}
/*!
@brief serialize to stream
@deprecated This stream operator is deprecated and will be removed in
future 4.0.0 of the library. Please use
@ref operator<<(std::ostream&, const basic_json&)
instead; that is, replace calls like `j >> o;` with `o << j;`.
@since version 1.0.0; deprecated since version 3.0.0
*/
/// @brief serialize to stream
/// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/
/// @deprecated This function is deprecated since 3.0.0 and will be removed in
/// version 4.0.0 of the library. Please use
/// operator<<(std::ostream&, const basic_json&) instead; that is,
/// replace calls like `j >> o;` with `o << j;`.
JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator<<(std::ostream&, const basic_json&))
friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
{
@ -3761,6 +3759,11 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
: detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
}
/// @brief generate SAX events
/// @sa https://json.nlohmann.me/api/basic_json/sax_parse/
/// @deprecated This function is deprecated since 3.8.0 and will be removed in
/// version 4.0.0 of the library. Please use
/// sax_parse(ptr, ptr + len) instead.
template <typename SAX>
JSON_HEDLEY_DEPRECATED_FOR(3.8.0, sax_parse(ptr, ptr + len, ...))
JSON_HEDLEY_NON_NULL(2)
@ -3777,45 +3780,20 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
: detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
}
#ifndef JSON_NO_IO
/*!
@brief deserialize from stream
@deprecated This stream operator is deprecated and will be removed in
version 4.0.0 of the library. Please use
@ref operator>>(std::istream&, basic_json&)
instead; that is, replace calls like `j << i;` with `i >> j;`.
@since version 1.0.0; deprecated since version 3.0.0
*/
/// @brief deserialize from stream
/// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
/// @deprecated This stream operator is deprecated since 3.0.0 and will be removed in
/// version 4.0.0 of the library. Please use
/// operator>>(std::istream&, basic_json&) instead; that is,
/// replace calls like `j << i;` with `i >> j;`.
JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator>>(std::istream&, basic_json&))
friend std::istream& operator<<(basic_json& j, std::istream& i)
{
return operator>>(i, j);
}
/*!
@brief deserialize from stream
Deserializes an input stream to a JSON value.
@param[in,out] i input stream to read a serialized JSON value from
@param[in,out] j JSON value to write the deserialized input to
@throw parse_error.101 in case of an unexpected token
@throw parse_error.102 if to_unicode fails or surrogate error
@throw parse_error.103 if to_unicode fails
@complexity Linear in the length of the input. The parser is a predictive
LL(1) parser.
@note A UTF-8 byte order mark is silently ignored.
@liveexample{The example below shows how a JSON value is constructed by
reading a serialization from a stream.,operator_deserialize}
@sa parse(std::istream&, const parser_callback_t) for a variant with a
parser callback function to filter values while parsing
@since version 1.0.0
*/
/// @brief deserialize from stream
/// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
friend std::istream& operator>>(std::istream& i, basic_json& j)
{
parser(detail::input_adapter(i)).parse(false, j);

60
single_include/nlohmann/json.hpp
View File

@ -21141,14 +21141,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return o;
}
/*!
@brief serialize to stream
@deprecated This stream operator is deprecated and will be removed in
future 4.0.0 of the library. Please use
@ref operator<<(std::ostream&, const basic_json&)
instead; that is, replace calls like `j >> o;` with `o << j;`.
@since version 1.0.0; deprecated since version 3.0.0
*/
/// @brief serialize to stream
/// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/
/// @deprecated This function is deprecated since 3.0.0 and will be removed in
/// version 4.0.0 of the library. Please use
/// operator<<(std::ostream&, const basic_json&) instead; that is,
/// replace calls like `j >> o;` with `o << j;`.
JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator<<(std::ostream&, const basic_json&))
friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
{
@ -21262,6 +21260,11 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
: detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
}
/// @brief generate SAX events
/// @sa https://json.nlohmann.me/api/basic_json/sax_parse/
/// @deprecated This function is deprecated since 3.8.0 and will be removed in
/// version 4.0.0 of the library. Please use
/// sax_parse(ptr, ptr + len) instead.
template <typename SAX>
JSON_HEDLEY_DEPRECATED_FOR(3.8.0, sax_parse(ptr, ptr + len, ...))
JSON_HEDLEY_NON_NULL(2)
@ -21278,45 +21281,20 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
: detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
}
#ifndef JSON_NO_IO
/*!
@brief deserialize from stream
@deprecated This stream operator is deprecated and will be removed in
version 4.0.0 of the library. Please use
@ref operator>>(std::istream&, basic_json&)
instead; that is, replace calls like `j << i;` with `i >> j;`.
@since version 1.0.0; deprecated since version 3.0.0
*/
/// @brief deserialize from stream
/// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
/// @deprecated This stream operator is deprecated since 3.0.0 and will be removed in
/// version 4.0.0 of the library. Please use
/// operator>>(std::istream&, basic_json&) instead; that is,
/// replace calls like `j << i;` with `i >> j;`.
JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator>>(std::istream&, basic_json&))
friend std::istream& operator<<(basic_json& j, std::istream& i)
{
return operator>>(i, j);
}
/*!
@brief deserialize from stream
Deserializes an input stream to a JSON value.
@param[in,out] i input stream to read a serialized JSON value from
@param[in,out] j JSON value to write the deserialized input to
@throw parse_error.101 in case of an unexpected token
@throw parse_error.102 if to_unicode fails or surrogate error
@throw parse_error.103 if to_unicode fails
@complexity Linear in the length of the input. The parser is a predictive
LL(1) parser.
@note A UTF-8 byte order mark is silently ignored.
@liveexample{The example below shows how a JSON value is constructed by
reading a serialization from a stream.,operator_deserialize}
@sa parse(std::istream&, const parser_callback_t) for a variant with a
parser callback function to filter values while parsing
@since version 1.0.0
*/
/// @brief deserialize from stream
/// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
friend std::istream& operator>>(std::istream& i, basic_json& j)
{
parser(detail::input_adapter(i)).parse(false, j);