diff --git a/doc/Makefile b/doc/Makefile index ba9cb6c34..dc10f1dd1 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -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 diff --git a/doc/css/mylayout.css b/doc/css/mylayout.css index b4c849a32..fe20b82c5 100644 --- a/doc/css/mylayout.css +++ b/doc/css/mylayout.css @@ -15,4 +15,12 @@ pre.fragment { td.paramname { vertical-align: top; -} \ No newline at end of file +} + +.ok_green { + background-color: #89C35C; +} + +.nok_throws { + background-color: #ffa500; +} diff --git a/doc/css/mylayout_docset.css b/doc/css/mylayout_docset.css index f18f92073..1a67e99df 100644 --- a/doc/css/mylayout_docset.css +++ b/doc/css/mylayout_docset.css @@ -13,3 +13,15 @@ #top, .footer { display: none; } + +td.paramname { + vertical-align: top; +} + +.ok_green { + background-color: #89C35C; +} + +.nok_throws { + background-color: #ffa500; +} diff --git a/doc/index.md b/doc/index.md index 20c61a0cc..5373d4f34 100644 --- a/doc/index.md +++ b/doc/index.md @@ -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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
group + function + JSON value type
objectarraystringnumberbooleannull
iterators`begin`@link nlohmann::basic_json::begin `begin` @endlink@link nlohmann::basic_json::begin `begin` @endlink@link nlohmann::basic_json::begin `begin` @endlink@link nlohmann::basic_json::begin `begin` @endlink@link nlohmann::basic_json::begin `begin` @endlink@link nlohmann::basic_json::begin `begin` @endlink (returns `end()`)
`cbegin`@link nlohmann::basic_json::cbegin `cbegin` @endlink@link nlohmann::basic_json::cbegin `cbegin` @endlink@link nlohmann::basic_json::cbegin `cbegin` @endlink@link nlohmann::basic_json::cbegin `cbegin` @endlink@link nlohmann::basic_json::cbegin `cbegin` @endlink@link nlohmann::basic_json::cbegin `cbegin` @endlink (returns `cend()`)
`end`@link nlohmann::basic_json::end `end` @endlink@link nlohmann::basic_json::end `end` @endlink@link nlohmann::basic_json::end `end` @endlink@link nlohmann::basic_json::end `end` @endlink@link nlohmann::basic_json::end `end` @endlink@link nlohmann::basic_json::end `end` @endlink
`cend`@link nlohmann::basic_json::cend `cend` @endlink@link nlohmann::basic_json::cend `cend` @endlink@link nlohmann::basic_json::cend `cend` @endlink@link nlohmann::basic_json::cend `cend` @endlink@link nlohmann::basic_json::cend `cend` @endlink@link nlohmann::basic_json::cend `cend` @endlink
`rbegin`@link nlohmann::basic_json::rbegin `rbegin` @endlink@link nlohmann::basic_json::rbegin `rbegin` @endlink@link nlohmann::basic_json::rbegin `rbegin` @endlink@link nlohmann::basic_json::rbegin `rbegin` @endlink@link nlohmann::basic_json::rbegin `rbegin` @endlink@link nlohmann::basic_json::rbegin `rbegin` @endlink
`crbegin`@link nlohmann::basic_json::crbegin `crbegin` @endlink@link nlohmann::basic_json::crbegin `crbegin` @endlink@link nlohmann::basic_json::crbegin `crbegin` @endlink@link nlohmann::basic_json::crbegin `crbegin` @endlink@link nlohmann::basic_json::crbegin `crbegin` @endlink@link nlohmann::basic_json::crbegin `crbegin` @endlink
`rend`@link nlohmann::basic_json::rend `rend` @endlink@link nlohmann::basic_json::rend `rend` @endlink@link nlohmann::basic_json::rend `rend` @endlink@link nlohmann::basic_json::rend `rend` @endlink@link nlohmann::basic_json::rend `rend` @endlink@link nlohmann::basic_json::rend `rend` @endlink
`crend`@link nlohmann::basic_json::crend `crend` @endlink@link nlohmann::basic_json::crend `crend` @endlink@link nlohmann::basic_json::crend `crend` @endlink@link nlohmann::basic_json::crend `crend` @endlink@link nlohmann::basic_json::crend `crend` @endlink@link nlohmann::basic_json::crend `crend` @endlink
element
access		`at`@link nlohmann::basic_json::at(const typename object_t::key_type & key) `at` @endlink@link nlohmann::basic_json::at(size_type) `at` @endlinkthrows `std::domain_error`throws `std::domain_error`throws `std::domain_error`throws `std::domain_error`
`operator[]`@link nlohmann::basic_json::operator[](const typename object_t::key_type &key) `operator[]` @endlink@link nlohmann::basic_json::operator[](size_type) `operator[]` @endlinkthrows `std::domain_error`throws `std::domain_error`throws `std::domain_error`@link nlohmann::basic_json::operator[](const typename object_t::key_type & key) `operator[]` @endlink (creates object)
@link nlohmann::basic_json::operator[](size_type) `operator[]` @endlink (creates array)
`front`@link nlohmann::basic_json::front `front` @endlink@link nlohmann::basic_json::front `front` @endlink@link nlohmann::basic_json::front `front` @endlink@link nlohmann::basic_json::front `front` @endlink@link nlohmann::basic_json::front `front` @endlinkthrows `std::out_of_range`
`back`@link nlohmann::basic_json::back `back` @endlink@link nlohmann::basic_json::back `back` @endlink@link nlohmann::basic_json::back `back` @endlink@link nlohmann::basic_json::back `back` @endlink@link nlohmann::basic_json::back `back` @endlinkthrows `std::out_of_range`
capacity`empty`@link nlohmann::basic_json::empty `empty` @endlink@link nlohmann::basic_json::empty `empty` @endlink@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)@link nlohmann::basic_json::empty `empty` @endlink (returns `true`)
`size`@link nlohmann::basic_json::size `size` @endlink@link nlohmann::basic_json::size `size` @endlink@link nlohmann::basic_json::size `size` @endlink (returns `1`)@link nlohmann::basic_json::size `size` @endlink (returns `1`)@link nlohmann::basic_json::size `size` @endlink (returns `1`)@link nlohmann::basic_json::size `size` @endlink (returns `0`)
`max_size_`@link nlohmann::basic_json::max_size `max_size` @endlink@link nlohmann::basic_json::max_size `max_size` @endlink@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)@link nlohmann::basic_json::max_size `max_size` @endlink (returns `0`)
modifiers`clear`@link nlohmann::basic_json::clear `clear` @endlink@link nlohmann::basic_json::clear `clear` @endlink@link nlohmann::basic_json::clear `clear` @endlink@link nlohmann::basic_json::clear `clear` @endlink@link nlohmann::basic_json::clear `clear` @endlink@link nlohmann::basic_json::clear `clear` @endlink
`insert`throws `std::domain_error`@link nlohmann::basic_json::insert `insert` @endlinkthrows `std::domain_error`throws `std::domain_error`throws `std::domain_error`throws `std::domain_error`
`erase`@link nlohmann::basic_json::erase `erase` @endlink@link nlohmann::basic_json::erase `erase` @endlink@link nlohmann::basic_json::erase `erase` @endlink (converts to null)@link nlohmann::basic_json::erase `erase` @endlink (converts to null)@link nlohmann::basic_json::erase `erase` @endlink (converts to null)throws
`push_back`@link nlohmann::basic_json::push_back(const typename object_t::value_type & val) `push_back` @endlink@link nlohmann::basic_json::push_back(const nlohmann::basic_json &) `push_back` @endlinkthrows `std::domain_error`throws `std::domain_error`throws `std::domain_error`@link nlohmann::basic_json::push_back(const typename object_t::value_type & val) `push_back` @endlink (creates object)
@link nlohmann::basic_json::push_back(const nlohmann::basic_json &) `push_back` @endlink (creates array)
`swap`@link nlohmann::basic_json::swap `swap` @endlink@link nlohmann::basic_json::swap `swap` @endlink@link nlohmann::basic_json::swap `swap` @endlink@link nlohmann::basic_json::swap `swap` @endlink@link nlohmann::basic_json::swap `swap` @endlink@link nlohmann::basic_json::swap `swap` @endlink
lookup`find`@link nlohmann::basic_json::find `find` @endlink (returns `end()`)@link nlohmann::basic_json::find `find` @endlink@link nlohmann::basic_json::find `find` @endlink (returns `end()`)@link nlohmann::basic_json::find `find` @endlink (returns `end()`)@link nlohmann::basic_json::find `find` @endlink (returns `end()`)@link nlohmann::basic_json::find `find` @endlink (returns `end()`)
`count`@link nlohmann::basic_json::count `count` @endlink (returns `0`)@link nlohmann::basic_json::count `count` @endlink@link nlohmann::basic_json::count `count` @endlink (returns `0`)@link nlohmann::basic_json::count `count` @endlink (returns `0`)@link nlohmann::basic_json::count `count` @endlink (returns `0`)@link nlohmann::basic_json::count `count` @endlink (returns `0`)
+ @copyright Copyright © 2013-2016 Niels Lohmann. The code is licensed under the [MIT License](http://opensource.org/licenses/MIT). @author [Niels Lohmann](http://nlohmann.me) diff --git a/src/json.hpp b/src/json.hpp index 829ba7de5..df14283cd 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -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 diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c index 333b4ddf5..292e4587a 100644 --- a/src/json.hpp.re2c +++ b/src/json.hpp.re2c @@ -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