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-10-13 21:54:41 +02:00
parent 0b02eb0dfb
commit 0eea6f241e
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
4 changed files with 38 additions and 176 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/mkdocs/docs/api/basic_json/operator+=.md
View File

@ -62,7 +62,7 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
## Examples ## Examples
??? example ??? example "Example: (1) add element to array"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
was silently converted to a JSON array. was silently converted to a JSON array.
@ -77,7 +77,7 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
--8<-- "examples/push_back.output" --8<-- "examples/push_back.output"
``` ```
??? example ??? example "Example: (2) add element to object"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
was silently converted to a JSON object. was silently converted to a JSON object.
@ -92,7 +92,7 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
--8<-- "examples/push_back__object_t__value.output" --8<-- "examples/push_back__object_t__value.output"
``` ```
??? example ??? example "Example: (3) add to object from initializer list"
The example shows how initializer lists are treated as objects when possible. The example shows how initializer lists are treated as objects when possible.

6
doc/mkdocs/docs/api/basic_json/push_back.md
View File

@ -58,7 +58,7 @@ void push_back(initializer_list_t init);
## Examples ## Examples
??? example ??? example "Example: (1) add element to array"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
was silently converted to a JSON array. was silently converted to a JSON array.
@ -73,7 +73,7 @@ void push_back(initializer_list_t init);
--8<-- "examples/push_back.output" --8<-- "examples/push_back.output"
``` ```
??? example ??? example "Example: (2) add element to object"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
was silently converted to a JSON object. was silently converted to a JSON object.
@ -88,7 +88,7 @@ void push_back(initializer_list_t init);
--8<-- "examples/push_back__object_t__value.output" --8<-- "examples/push_back__object_t__value.output"
``` ```
??? example ??? example "Example: (3) add to object from initializer list"
The example shows how initializer lists are treated as objects when possible. The example shows how initializer lists are treated as objects when possible.

101
include/nlohmann/json.hpp
View File

@ -3441,26 +3441,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief add an object to an array
@brief add an object to an array /// @sa https://json.nlohmann.me/api/basic_json/push_back/
Appends the given element @a val to the end of the JSON value. If the
function is called on a JSON null value, an empty array is created before
appending @a val.
@param[in] val the value to add to the JSON array
@throw type_error.308 when called on a type other than JSON array or
null; example: `"cannot use push_back() with number"`
@complexity Amortized constant.
@liveexample{The example shows how `push_back()` and `+=` can be used to
add elements to a JSON array. Note how the `null` value was silently
converted to a JSON array.,push_back}
@since version 1.0.0
*/
void push_back(basic_json&& val) void push_back(basic_json&& val)
{ {
// push_back only works for null objects or arrays // push_back only works for null objects or arrays
@ -3484,20 +3466,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
// if val is moved from, basic_json move constructor marks it null so we do not call the destructor // if val is moved from, basic_json move constructor marks it null so we do not call the destructor
} }
/*! /// @brief add an object to an array
@brief add an object to an array /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
@copydoc push_back(basic_json&&)
*/
reference operator+=(basic_json&& val) reference operator+=(basic_json&& val)
{ {
push_back(std::move(val)); push_back(std::move(val));
return *this; return *this;
} }
/*! /// @brief add an object to an array
@brief add an object to an array /// @sa https://json.nlohmann.me/api/basic_json/push_back/
@copydoc push_back(basic_json&&)
*/
void push_back(const basic_json& val) void push_back(const basic_json& val)
{ {
// push_back only works for null objects or arrays // push_back only works for null objects or arrays
@ -3520,36 +3498,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
set_parent(m_value.array->back(), old_capacity); set_parent(m_value.array->back(), old_capacity);
} }
/*! /// @brief add an object to an array
@brief add an object to an array /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
@copydoc push_back(basic_json&&)
*/
reference operator+=(const basic_json& val) reference operator+=(const basic_json& val)
{ {
push_back(val); push_back(val);
return *this; return *this;
} }
/*! /// @brief add an object to an object
@brief add an object to an object /// @sa https://json.nlohmann.me/api/basic_json/push_back/
Inserts the given element @a val to the JSON object. If the function is
called on a JSON null value, an empty object is created before inserting
@a val.
@param[in] val the value to add to the JSON object
@throw type_error.308 when called on a type other than JSON object or
null; example: `"cannot use push_back() with number"`
@complexity Logarithmic in the size of the container, O(log(`size()`)).
@liveexample{The example shows how `push_back()` and `+=` can be used to
add elements to a JSON object. Note how the `null` value was silently
converted to a JSON object.,push_back__object_t__value}
@since version 1.0.0
*/
void push_back(const typename object_t::value_type& val) void push_back(const typename object_t::value_type& val)
{ {
// push_back only works for null objects or objects // push_back only works for null objects or objects
@ -3571,41 +3529,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
set_parent(res.first->second); set_parent(res.first->second);
} }
/*! /// @brief add an object to an object
@brief add an object to an object /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
@copydoc push_back(const typename object_t::value_type&)
*/
reference operator+=(const typename object_t::value_type& val) reference operator+=(const typename object_t::value_type& val)
{ {
push_back(val); push_back(val);
return *this; return *this;
} }
/*! /// @brief add an object to an object
@brief add an object to an object /// @sa https://json.nlohmann.me/api/basic_json/push_back/
This function allows to use `push_back` with an initializer list. In case
1. the current value is an object,
2. the initializer list @a init contains only two elements, and
3. the first element of @a init is a string,
@a init is converted into an object element and added using
@ref push_back(const typename object_t::value_type&). Otherwise, @a init
is converted to a JSON value and added using @ref push_back(basic_json&&).
@param[in] init an initializer list
@complexity Linear in the size of the initializer list @a init.
@note This function is required to resolve an ambiguous overload error,
because pairs like `{"key", "value"}` can be both interpreted as
`object_t::value_type` or `std::initializer_list<basic_json>`, see
https://github.com/nlohmann/json/issues/235 for more information.
@liveexample{The example shows how initializer lists are treated as
objects when possible.,push_back__initializer_list}
*/
void push_back(initializer_list_t init) void push_back(initializer_list_t init)
{ {
if (is_object() && init.size() == 2 && (*init.begin())->is_string()) if (is_object() && init.size() == 2 && (*init.begin())->is_string())
@ -3620,10 +3553,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief add an object to an object
@brief add an object to an object /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
@copydoc push_back(initializer_list_t)
*/
reference operator+=(initializer_list_t init) reference operator+=(initializer_list_t init)
{ {
push_back(init); push_back(init);

101
single_include/nlohmann/json.hpp
View File

@ -20928,26 +20928,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief add an object to an array
@brief add an object to an array /// @sa https://json.nlohmann.me/api/basic_json/push_back/
Appends the given element @a val to the end of the JSON value. If the
function is called on a JSON null value, an empty array is created before
appending @a val.
@param[in] val the value to add to the JSON array
@throw type_error.308 when called on a type other than JSON array or
null; example: `"cannot use push_back() with number"`
@complexity Amortized constant.
@liveexample{The example shows how `push_back()` and `+=` can be used to
add elements to a JSON array. Note how the `null` value was silently
converted to a JSON array.,push_back}
@since version 1.0.0
*/
void push_back(basic_json&& val) void push_back(basic_json&& val)
{ {
// push_back only works for null objects or arrays // push_back only works for null objects or arrays
@ -20971,20 +20953,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
// if val is moved from, basic_json move constructor marks it null so we do not call the destructor // if val is moved from, basic_json move constructor marks it null so we do not call the destructor
} }
/*! /// @brief add an object to an array
@brief add an object to an array /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
@copydoc push_back(basic_json&&)
*/
reference operator+=(basic_json&& val) reference operator+=(basic_json&& val)
{ {
push_back(std::move(val)); push_back(std::move(val));
return *this; return *this;
} }
/*! /// @brief add an object to an array
@brief add an object to an array /// @sa https://json.nlohmann.me/api/basic_json/push_back/
@copydoc push_back(basic_json&&)
*/
void push_back(const basic_json& val) void push_back(const basic_json& val)
{ {
// push_back only works for null objects or arrays // push_back only works for null objects or arrays
@ -21007,36 +20985,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
set_parent(m_value.array->back(), old_capacity); set_parent(m_value.array->back(), old_capacity);
} }
/*! /// @brief add an object to an array
@brief add an object to an array /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
@copydoc push_back(basic_json&&)
*/
reference operator+=(const basic_json& val) reference operator+=(const basic_json& val)
{ {
push_back(val); push_back(val);
return *this; return *this;
} }
/*! /// @brief add an object to an object
@brief add an object to an object /// @sa https://json.nlohmann.me/api/basic_json/push_back/
Inserts the given element @a val to the JSON object. If the function is
called on a JSON null value, an empty object is created before inserting
@a val.
@param[in] val the value to add to the JSON object
@throw type_error.308 when called on a type other than JSON object or
null; example: `"cannot use push_back() with number"`
@complexity Logarithmic in the size of the container, O(log(`size()`)).
@liveexample{The example shows how `push_back()` and `+=` can be used to
add elements to a JSON object. Note how the `null` value was silently
converted to a JSON object.,push_back__object_t__value}
@since version 1.0.0
*/
void push_back(const typename object_t::value_type& val) void push_back(const typename object_t::value_type& val)
{ {
// push_back only works for null objects or objects // push_back only works for null objects or objects
@ -21058,41 +21016,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
set_parent(res.first->second); set_parent(res.first->second);
} }
/*! /// @brief add an object to an object
@brief add an object to an object /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
@copydoc push_back(const typename object_t::value_type&)
*/
reference operator+=(const typename object_t::value_type& val) reference operator+=(const typename object_t::value_type& val)
{ {
push_back(val); push_back(val);
return *this; return *this;
} }
/*! /// @brief add an object to an object
@brief add an object to an object /// @sa https://json.nlohmann.me/api/basic_json/push_back/
This function allows to use `push_back` with an initializer list. In case
1. the current value is an object,
2. the initializer list @a init contains only two elements, and
3. the first element of @a init is a string,
@a init is converted into an object element and added using
@ref push_back(const typename object_t::value_type&). Otherwise, @a init
is converted to a JSON value and added using @ref push_back(basic_json&&).
@param[in] init an initializer list
@complexity Linear in the size of the initializer list @a init.
@note This function is required to resolve an ambiguous overload error,
because pairs like `{"key", "value"}` can be both interpreted as
`object_t::value_type` or `std::initializer_list<basic_json>`, see
https://github.com/nlohmann/json/issues/235 for more information.
@liveexample{The example shows how initializer lists are treated as
objects when possible.,push_back__initializer_list}
*/
void push_back(initializer_list_t init) void push_back(initializer_list_t init)
{ {
if (is_object() && init.size() == 2 && (*init.begin())->is_string()) if (is_object() && init.size() == 2 && (*init.begin())->is_string())
@ -21107,10 +21040,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
} }
} }
/*! /// @brief add an object to an object
@brief add an object to an object /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
@copydoc push_back(initializer_list_t)
*/
reference operator+=(initializer_list_t init) reference operator+=(initializer_list_t init)
{ {
push_back(init); push_back(init);