haraldwolff
/
json
mirror of https://github.com/nlohmann/json.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

improved documentation

pull/205/head
Niels 2016-02-07 14:55:29 +01:00
parent 3b776c08c7
commit fdfb39d949
6 changed files with 335 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/Makefile
View File

@ -54,6 +54,7 @@ doxygen: create_output create_links
gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType >@@g' html/*.html
gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType >@@g' html/*.html
gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType >@@g' html/*.html
gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType >@@g' html/*.html
upload: clean doxygen check_output
cd html ; ../scripts/git-update-ghpages nlohmann/json

10
doc/css/mylayout.css
View File

@ -15,4 +15,12 @@ pre.fragment {
td.paramname {
vertical-align: top;
}
}
.ok_green {
background-color: #89C35C;
}
.nok_throws {
background-color: #ffa500;
}

12
doc/css/mylayout_docset.css
View File

@ -13,3 +13,15 @@
#top, .footer {
display: none;
}
td.paramname {
vertical-align: top;
}
.ok_green {
background-color: #89C35C;
}
.nok_throws {
background-color: #ffa500;
}

248
doc/index.md
View File

@ -2,6 +2,8 @@
These pages contain the API documentation of JSON for Modern C++, a C++11 header-only JSON class.
# Contents
- @link nlohmann::basic_json `basic_json` class @endlink
- [Functions](functions_func.html)
- object inspection
@ -25,29 +27,6 @@ These pages contain the API documentation of JSON for Modern C++, a C++11 header
- @link nlohmann::basic_json::get_ptr get_ptr @endlink -- get a value pointer
- @link nlohmann::basic_json::get_ref get_ref @endlink -- get a value reference
- @link nlohmann::basic_json::operator ValueType() const operator ValueType @endlink -- get a value (implicit conversion)
- element access
- @link nlohmann::basic_json::at(size_type) at @endlink -- access array element with bounds checking
- @link nlohmann::basic_json::at(const typename object_t::key_type & key) at @endlink -- access object element with bounds checking
- @link nlohmann::basic_json::operator[](size_type) operator[] @endlink -- access array element
- @link nlohmann::basic_json::operator[](const typename object_t::key_type & key) operator[] @endlink -- access object element
- @link nlohmann::basic_json::value value @endlink -- access object element with default value
- @link nlohmann::basic_json::front front @endlink -- access the first element
- @link nlohmann::basic_json::back back @endlink -- access the last element
- iterators
- begin, cbegin
- end, cend
- rbegin, crbegin
- rend, crend
- capacity
- @link nlohmann::basic_json::empty empty @endlink -- checks whether the container is empty
- @link nlohmann::basic_json::size size @endlink -- returns the number of elements
- @link nlohmann::basic_json::max_size max_size @endlink -- returns the maximum possible number of elements
- modifiers
- @link nlohmann::basic_json::clear clear @endlink -- clears the contents
- @link nlohmann::basic_json::push_back(const nlohmann::basic_json &) push_back @endlink -- add an object to an array
- @link nlohmann::basic_json::operator+=(const nlohmann::basic_json &) operator+= @endlink -- add an object to an array
- @link nlohmann::basic_json::insert insert @endlink -- inserts elements
- @link nlohmann::basic_json::swap swap @endlink -- exchanges the values
- lexicographical comparison operators
- serialization
- deserialization
@ -61,6 +40,229 @@ These pages contain the API documentation of JSON for Modern C++, a C++11 header
- @link nlohmann::basic_json::number_unsigned_t unsigned integers @endlink
- @link nlohmann::basic_json::number_float_t floating-point @endlink
# Container function overview
The container functions known from STL have been extended to support the different value types from JSON. However, not all functions can be applied to all value types. Note that the signature of some functions differ between the types; for instance, `at` may be called with either a string to address a key in an object or with an integer to address a value in an array.
<table>
<tr>
<th rowspan="2">group</td>
<th rowspan="2">function</td>
<th colspan="6">JSON value type</th>
</tr>
<tr>
<th>object</th>
<th>array</th>
<th>string</th>
<th>number</th>
<th>boolean</th>
<th>null</th>
</tr>
<tr>
<td rowspan="8">iterators</td>
<td>`begin`</td>
<td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink (returns `end()`)</td>
</tr>
<tr>
<td>`cbegin`</td>
<td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink (returns `cend()`)</td>
</tr>
<tr>
<td>`end`</td>
<td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
</tr>
<tr>
<td>`cend`</td>
<td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
</tr>
<tr>
<td>`rbegin`</td>
<td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
</tr>
<tr>
<td>`crbegin`</td>
<td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
</tr>
<tr>
<td>`rend`</td>
<td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
</tr>
<tr>
<td>`crend`</td>
<td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
</tr>
<tr>
<td rowspan="4">element<br>access</td>
<td>`at`</td>
<td class="ok_green">@link nlohmann::basic_json::at(const typename object_t::key_type & key) `at` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::at(size_type) `at` @endlink</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="nok_throws">throws `std::domain_error`</td>
</tr>
<tr>
<td>`operator[]`</td>
<td class="ok_green">@link nlohmann::basic_json::operator[](const typename object_t::key_type &key) `operator[]` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::operator[](size_type) `operator[]` @endlink</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="ok_green">@link nlohmann::basic_json::operator[](const typename object_t::key_type & key) `operator[]` @endlink (creates object)<br>@link nlohmann::basic_json::operator[](size_type) `operator[]` @endlink (creates array)</td>
</tr>
<tr>
<td>`front`</td>
<td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td>
<td class="nok_throws">throws `std::out_of_range`</td>
</tr>
<tr>
<td>`back`</td>
<td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td>
<td class="nok_throws">throws `std::out_of_range`</td>
</tr>
<tr>
<td rowspan="3">capacity</td>
<td>`empty`</td>
<td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)</td>
<td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)</td>
<td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)</td>
<td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `true`)</td>
</tr>
<tr>
<td>`size`</td>
<td class="ok_green">@link nlohmann::basic_json::size `size` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::size `size` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `1`)</td>
<td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `1`)</td>
<td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `1`)</td>
<td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `0`)</td>
</tr>
<tr>
<td>`max_size_`</td>
<td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)</td>
<td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)</td>
<td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)</td>
<td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `0`)</td>
</tr>
<tr>
<td rowspan="5">modifiers</td>
<td>`clear`</td>
<td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
</tr>
<tr>
<td>`insert`</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="ok_green">@link nlohmann::basic_json::insert `insert` @endlink</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="nok_throws">throws `std::domain_error`</td>
</tr>
<tr>
<td>`erase`</td>
<td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink (converts to null)</td>
<td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink (converts to null)</td>
<td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink (converts to null)</td>
<td class="nok_throws">throws</td>
</tr>
<tr>
<td>`push_back`</td>
<td class="ok_green">@link nlohmann::basic_json::push_back(const typename object_t::value_type & val) `push_back` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::push_back(const nlohmann::basic_json &) `push_back` @endlink</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="nok_throws">throws `std::domain_error`</td>
<td class="ok_green">@link nlohmann::basic_json::push_back(const typename object_t::value_type & val) `push_back` @endlink (creates object)<br>@link nlohmann::basic_json::push_back(const nlohmann::basic_json &) `push_back` @endlink (creates array)</td>
</tr>
<tr>
<td>`swap`</td>
<td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
</tr>
<tr>
<td rowspan="2">lookup</td>
<td>`find`</td>
<td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td>
<td class="ok_green">@link nlohmann::basic_json::find `find` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td>
<td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td>
<td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td>
<td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td>
</tr>
<tr>
<td>`count`</td>
<td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td>
<td class="ok_green">@link nlohmann::basic_json::count `count` @endlink</td>
<td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td>
<td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td>
<td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td>
<td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td>
</tr>
</table>
@copyright Copyright &copy; 2013-2016 Niels Lohmann. The code is licensed under the [MIT License](http://opensource.org/licenses/MIT).
@author [Niels Lohmann](http://nlohmann.me)

68
src/json.hpp
View File

@ -3229,7 +3229,7 @@ class basic_json
@return reference to the element at key @a key
@throw std::domain_error if JSON is not an object or null; example:
`"cannot use operator[] with null"`
`"cannot use operator[] with string"`
@complexity Logarithmic in the size of the container.
@ -3319,7 +3319,7 @@ class basic_json
@return reference to the element at key @a key
@throw std::domain_error if JSON is not an object or null; example:
`"cannot use operator[] with null"`
`"cannot use operator[] with string"`
@complexity Logarithmic in the size of the container.
@ -3387,7 +3387,7 @@ class basic_json
@return reference to the element at key @a key
@throw std::domain_error if JSON is not an object or null; example:
`"cannot use operator[] with null"`
`"cannot use operator[] with string"`
@complexity Logarithmic in the size of the container.
@ -3589,8 +3589,12 @@ class basic_json
@brief access the last element
Returns a reference to the last element in the container. For a JSON
container `c`, the expression `c.back()` is equivalent to `{ auto tmp =
c.end(); --tmp; return *tmp; }`.
container `c`, the expression `c.back()` is equivalent to
@code {.cpp}
auto tmp = c.end();
--tmp;
return *tmp;
@endcode
@return In case of a structured type (array or object), a reference to the
last element is returned. In cast of number, string, or boolean values, a
@ -3602,7 +3606,7 @@ class basic_json
an empty array or object (undefined behavior, guarded by assertions).
@post The JSON value remains unchanged.
@throw std::out_of_range when called on null value.
@throw std::out_of_range when called on `null` value.
@liveexample{The following code shows an example for `back()`.,back}
@ -3630,28 +3634,29 @@ class basic_json
/*!
@brief remove element given an iterator
Removes the element specified by iterator @a pos. Invalidates iterators and
references at or after the point of the erase, including the end()
iterator. The iterator @a pos must be valid and dereferenceable. Thus the
end() iterator (which is valid, but is not dereferenceable) cannot be used
as a value for @a pos.
Removes the element specified by iterator @a pos. The iterator @a pos must
be valid and dereferenceable. Thus the `end()` iterator (which is valid,
but is not dereferenceable) cannot be used as a value for @a pos.
If called on a primitive type other than null, the resulting JSON value
If called on a primitive type other than `null`, the resulting JSON value
will be `null`.
@param[in] pos iterator to the element to remove
@return Iterator following the last removed element. If the iterator @a pos
refers to the last element, the end() iterator is returned.
refers to the last element, the `end()` iterator is returned.
@tparam InteratorType an @ref iterator or @ref const_iterator
@post Invalidates iterators and references at or after the point of the
erase, including the `end()` iterator.
@throw std::domain_error if called on a `null` value; example: `"cannot use
erase() with null"`
@throw std::domain_error if called on an iterator which does not belong to
the current JSON value; example: `"iterator does not fit current value"`
@throw std::out_of_range if called on a primitive type with invalid
iterator (i.e., any iterator which is not end()); example: `"iterator out
of range"`
iterator (i.e., any iterator which is not `begin()`); example: `"iterator
out of range"`
@complexity The complexity depends on the type:
- objects: amortized constant
@ -3736,21 +3741,23 @@ class basic_json
/*!
@brief remove elements given an iterator range
Removes the element specified by the range `[first; last)`. Invalidates
iterators and references at or after the point of the erase, including the
end() iterator. The iterator @a first does not need to be dereferenceable
if `first == last`: erasing an empty range is a no-op.
Removes the element specified by the range `[first; last)`. The iterator @a
first does not need to be dereferenceable if `first == last`: erasing an
empty range is a no-op.
If called on a primitive type other than null, the resulting JSON value
If called on a primitive type other than `null`, the resulting JSON value
will be `null`.
@param[in] first iterator to the beginning of the range to remove
@param[in] last iterator past the end of the range to remove
@return Iterator following the last removed element. If the iterator @a
second refers to the last element, the end() iterator is returned.
second refers to the last element, the `end()` iterator is returned.
@tparam InteratorType an @ref iterator or @ref const_iterator
@post Invalidates iterators and references at or after the point of the
erase, including the `end()` iterator.
@throw std::domain_error if called on a `null` value; example: `"cannot use
erase() with null"`
@throw std::domain_error if called on iterators which does not belong to
@ -3848,9 +3855,12 @@ class basic_json
@param[in] key value of the elements to remove
@return Number of elements removed. If ObjectType is the default `std::map`
type, the return value will always be `0` (@a key was not found) or `1` (@a
key was found).
@return Number of elements removed. If @a ObjectType is the default
`std::map` type, the return value will always be `0` (@a key was not found)
or `1` (@a key was found).
@post References and iterators to the erased elements are invalidated.
Other references and iterators are not affected.
@throw std::domain_error when called on a type other than JSON object;
example: `"cannot use erase() with null"`
@ -3924,6 +3934,16 @@ class basic_json
}
}
/// @}
////////////
// lookup //
////////////
/// @name lookup
/// @{
/*!
@brief find an element in a JSON object

68
src/json.hpp.re2c
View File

@ -3229,7 +3229,7 @@ class basic_json
@return reference to the element at key @a key
@throw std::domain_error if JSON is not an object or null; example:
`"cannot use operator[] with null"`
`"cannot use operator[] with string"`
@complexity Logarithmic in the size of the container.
@ -3319,7 +3319,7 @@ class basic_json
@return reference to the element at key @a key
@throw std::domain_error if JSON is not an object or null; example:
`"cannot use operator[] with null"`
`"cannot use operator[] with string"`
@complexity Logarithmic in the size of the container.
@ -3387,7 +3387,7 @@ class basic_json
@return reference to the element at key @a key
@throw std::domain_error if JSON is not an object or null; example:
`"cannot use operator[] with null"`
`"cannot use operator[] with string"`
@complexity Logarithmic in the size of the container.
@ -3589,8 +3589,12 @@ class basic_json
@brief access the last element
Returns a reference to the last element in the container. For a JSON
container `c`, the expression `c.back()` is equivalent to `{ auto tmp =
c.end(); --tmp; return *tmp; }`.
container `c`, the expression `c.back()` is equivalent to
@code {.cpp}
auto tmp = c.end();
--tmp;
return *tmp;
@endcode
@return In case of a structured type (array or object), a reference to the
last element is returned. In cast of number, string, or boolean values, a
@ -3602,7 +3606,7 @@ class basic_json
an empty array or object (undefined behavior, guarded by assertions).
@post The JSON value remains unchanged.
@throw std::out_of_range when called on null value.
@throw std::out_of_range when called on `null` value.
@liveexample{The following code shows an example for `back()`.,back}
@ -3630,28 +3634,29 @@ class basic_json
/*!
@brief remove element given an iterator
Removes the element specified by iterator @a pos. Invalidates iterators and
references at or after the point of the erase, including the end()
iterator. The iterator @a pos must be valid and dereferenceable. Thus the
end() iterator (which is valid, but is not dereferenceable) cannot be used
as a value for @a pos.
Removes the element specified by iterator @a pos. The iterator @a pos must
be valid and dereferenceable. Thus the `end()` iterator (which is valid,
but is not dereferenceable) cannot be used as a value for @a pos.
If called on a primitive type other than null, the resulting JSON value
If called on a primitive type other than `null`, the resulting JSON value
will be `null`.
@param[in] pos iterator to the element to remove
@return Iterator following the last removed element. If the iterator @a pos
refers to the last element, the end() iterator is returned.
refers to the last element, the `end()` iterator is returned.
@tparam InteratorType an @ref iterator or @ref const_iterator
@post Invalidates iterators and references at or after the point of the
erase, including the `end()` iterator.
@throw std::domain_error if called on a `null` value; example: `"cannot use
erase() with null"`
@throw std::domain_error if called on an iterator which does not belong to
the current JSON value; example: `"iterator does not fit current value"`
@throw std::out_of_range if called on a primitive type with invalid
iterator (i.e., any iterator which is not end()); example: `"iterator out
of range"`
iterator (i.e., any iterator which is not `begin()`); example: `"iterator
out of range"`
@complexity The complexity depends on the type:
- objects: amortized constant
@ -3736,21 +3741,23 @@ class basic_json
/*!
@brief remove elements given an iterator range
Removes the element specified by the range `[first; last)`. Invalidates
iterators and references at or after the point of the erase, including the
end() iterator. The iterator @a first does not need to be dereferenceable
if `first == last`: erasing an empty range is a no-op.
Removes the element specified by the range `[first; last)`. The iterator @a
first does not need to be dereferenceable if `first == last`: erasing an
empty range is a no-op.
If called on a primitive type other than null, the resulting JSON value
If called on a primitive type other than `null`, the resulting JSON value
will be `null`.
@param[in] first iterator to the beginning of the range to remove
@param[in] last iterator past the end of the range to remove
@return Iterator following the last removed element. If the iterator @a
second refers to the last element, the end() iterator is returned.
second refers to the last element, the `end()` iterator is returned.
@tparam InteratorType an @ref iterator or @ref const_iterator
@post Invalidates iterators and references at or after the point of the
erase, including the `end()` iterator.
@throw std::domain_error if called on a `null` value; example: `"cannot use
erase() with null"`
@throw std::domain_error if called on iterators which does not belong to
@ -3848,9 +3855,12 @@ class basic_json
@param[in] key value of the elements to remove
@return Number of elements removed. If ObjectType is the default `std::map`
type, the return value will always be `0` (@a key was not found) or `1` (@a
key was found).
@return Number of elements removed. If @a ObjectType is the default
`std::map` type, the return value will always be `0` (@a key was not found)
or `1` (@a key was found).
@post References and iterators to the erased elements are invalidated.
Other references and iterators are not affected.
@throw std::domain_error when called on a type other than JSON object;
example: `"cannot use erase() with null"`
@ -3924,6 +3934,16 @@ class basic_json
}
}
/// @}
////////////
// lookup //
////////////
/// @name lookup
/// @{
/*!
@brief find an element in a JSON object