Skip to content

J
json
Unverified Commit fe71e7df by Niels Lohmann
Options

📝 overworked documentation

Replacing references to std exceptions with user-defined exceptions. Also changed some examples to the new exceptions.
parent 9374eaa0
Showing with 331 additions and 134 deletions
doc/examples/at__object_t_key_type.cpp
...@@ -26,8 +26,8 @@ int main() ...@@ -26,8 +26,8 @@ int main()
{ {
object.at("the fast") = "il rapido"; object.at("the fast") = "il rapido";
} }
catch (std::out_of_range& e) catch (json::out_of_range& e)
{ {
std::cout << "out of range: " << e.what() << '\n'; std::cout << e.what() << '\n';
} }
} }
doc/examples/at__object_t_key_type.link
<a target="_blank" href="http://melpon.org/wandbox/permlink/tb5CaFfsMWpAvi7m"><b>online</b></a> <a target="_blank" href="http://melpon.org/wandbox/permlink/WtZ49NXtkzcLAx37"><b>online</b></a>
\ No newline at end of file \ No newline at end of file
doc/examples/at__object_t_key_type.output
"il brutto" "il brutto"
{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"} {"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
out of range: key 'the fast' not found [json.exception.out_of_range.403] key 'the fast' not found
doc/examples/at__object_t_key_type.test 0 → 100644
"il brutto"
{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
[json.exception.out_of_range.403] key 'the fast' not found
doc/examples/at__object_t_key_type_const.cpp
...@@ -20,7 +20,7 @@ int main() ...@@ -20,7 +20,7 @@ int main()
{ {
std::cout << object.at("the fast") << '\n'; std::cout << object.at("the fast") << '\n';
} }
catch (std::out_of_range) catch (json::out_of_range)
{ {
std::cout << "out of range" << '\n'; std::cout << "out of range" << '\n';
} }
......
doc/examples/at__object_t_key_type_const.link
<a target="_blank" href="http://melpon.org/wandbox/permlink/NFG86H5khRUePc1s"><b>online</b></a> <a target="_blank" href="http://melpon.org/wandbox/permlink/AsC3grSJ7UngjKwF"><b>online</b></a>
\ No newline at end of file \ No newline at end of file
doc/examples/at__size_type.cpp
...@@ -21,8 +21,8 @@ int main() ...@@ -21,8 +21,8 @@ int main()
{ {
array.at(5) = "sixth"; array.at(5) = "sixth";
} }
catch (std::out_of_range& e) catch (json::out_of_range& e)
{ {
std::cout << "out of range: " << e.what() << '\n'; std::cout << e.what() << '\n';
} }
} }
doc/examples/at__size_type.link
<a target="_blank" href="http://melpon.org/wandbox/permlink/R7z2SB2rMdFQ9XtR"><b>online</b></a> <a target="_blank" href="http://melpon.org/wandbox/permlink/EU0DspVPybW5cJDH"><b>online</b></a>
\ No newline at end of file \ No newline at end of file
doc/examples/at__size_type.output
"third" "third"
["first","second","third","fourth"] ["first","second","third","fourth"]
out of range: array index 5 is out of range [json.exception.out_of_range.401] array index 5 is out of range
doc/examples/at__size_type_const.cpp
...@@ -15,7 +15,7 @@ int main() ...@@ -15,7 +15,7 @@ int main()
{ {
std::cout << array.at(5) << '\n'; std::cout << array.at(5) << '\n';
} }
catch (std::out_of_range) catch (json::out_of_range)
{ {
std::cout << "out of range" << '\n'; std::cout << "out of range" << '\n';
} }
......
doc/examples/at__size_type_const.link
<a target="_blank" href="http://melpon.org/wandbox/permlink/L1bMeiN6nYm7JrvA"><b>online</b></a> <a target="_blank" href="http://melpon.org/wandbox/permlink/ZiPo8P49B2Cc8B85"><b>online</b></a>
\ No newline at end of file \ No newline at end of file
doc/examples/get_ref.cpp
...@@ -19,7 +19,7 @@ int main() ...@@ -19,7 +19,7 @@ int main()
{ {
auto r3 = value.get_ref<json::number_float_t&>(); auto r3 = value.get_ref<json::number_float_t&>();
} }
catch (std::domain_error& ex) catch (json::type_error& ex)
{ {
std::cout << ex.what() << '\n'; std::cout << ex.what() << '\n';
} }
......
doc/examples/get_ref.link
<a target="_blank" href="http://melpon.org/wandbox/permlink/WiO1oBWDvIs82OX1"><b>online</b></a> <a target="_blank" href="http://melpon.org/wandbox/permlink/lsl8Ex3d3SOYnKHu"><b>online</b></a>
\ No newline at end of file \ No newline at end of file
doc/examples/get_ref.output
17 17 17 17
incompatible ReferenceType for get_ref, actual type is number [json.exception.type_error.303] incompatible ReferenceType for get_ref, actual type is number
doc/examples/get_ref.test 0 → 100644
17 17
[json.exception.type_error.303] incompatible ReferenceType for get_ref, actual type is number
doc/examples/json_pointer.cpp
...@@ -19,9 +19,9 @@ int main() ...@@ -19,9 +19,9 @@ int main()
{ {
json::json_pointer p9("foo"); json::json_pointer p9("foo");
} }
catch (std::domain_error& e) catch (json::parse_error& e)
{ {
std::cout << "domain_error: " << e.what() << '\n'; std::cout << e.what() << '\n';
} }
// error: JSON pointer uses escape symbol ~ not followed by 0 or 1 // error: JSON pointer uses escape symbol ~ not followed by 0 or 1
...@@ -29,9 +29,9 @@ int main() ...@@ -29,9 +29,9 @@ int main()
{ {
json::json_pointer p10("/foo/~"); json::json_pointer p10("/foo/~");
} }
catch (std::domain_error& e) catch (json::parse_error& e)
{ {
std::cout << "domain_error: " << e.what() << '\n'; std::cout << e.what() << '\n';
} }
// error: JSON pointer uses escape symbol ~ not followed by 0 or 1 // error: JSON pointer uses escape symbol ~ not followed by 0 or 1
...@@ -39,8 +39,8 @@ int main() ...@@ -39,8 +39,8 @@ int main()
{ {
json::json_pointer p11("/foo/~3"); json::json_pointer p11("/foo/~3");
} }
catch (std::domain_error& e) catch (json::parse_error& e)
{ {
std::cout << "domain_error: " << e.what() << '\n'; std::cout << e.what() << '\n';
} }
} }
doc/examples/json_pointer.link
<a target="_blank" href="http://melpon.org/wandbox/permlink/WM2WWKnXdmdw17Wu"><b>online</b></a> <a target="_blank" href="http://melpon.org/wandbox/permlink/Wlvqfd3JpEXTv2iH"><b>online</b></a>
\ No newline at end of file \ No newline at end of file
doc/examples/json_pointer.output
domain_error: JSON pointer must be empty or begin with '/' [json.exception.parse_error.107] parse error at 1: JSON pointer must be empty or begin with '/' - was: 'foo'
domain_error: escape error: '~' must be followed with '0' or '1' [json.exception.parse_error.108] parse error: escape character '~' must be followed with '0' or '1'
domain_error: escape error: '~' must be followed with '0' or '1' [json.exception.parse_error.108] parse error: escape character '~' must be followed with '0' or '1'
doc/examples/json_pointer.test 0 → 100644
[json.exception.parse_error.107] parse error at 1: JSON pointer must be empty or begin with '/' - was: 'foo'
[json.exception.parse_error.108] parse error: escape character '~' must be followed with '0' or '1'
[json.exception.parse_error.108] parse error: escape character '~' must be followed with '0' or '1'
src/json.hpp
...@@ -301,7 +301,8 @@ Exceptions have ids 5xx. ...@@ -301,7 +301,8 @@ Exceptions have ids 5xx.
name / id | example massage | description name / id | example massage | description
------------------------------ | --------------- | ------------------------- ------------------------------ | --------------- | -------------------------
json.exception.[other_error](@ref other_error).501 | "unsuccessful" | A JSON Patch operation 'test' failed. json.exception.[other_error](@ref other_error).501 | "unsuccessful: {"op":"test","path":"/baz",
"value":"bar"}" | A JSON Patch operation 'test' failed.
@since version 3.0.0 @since version 3.0.0
*/ */
...@@ -3652,7 +3653,7 @@ class basic_json ...@@ -3652,7 +3653,7 @@ class basic_json
@return copy of the JSON value, converted to type @a ValueType @return copy of the JSON value, converted to type @a ValueType
@throw std::domain_error in case passed type @a ValueType is incompatible @throw type_error.302 in case passed type @a ValueType is incompatible
to JSON, thrown by @ref get() const to JSON, thrown by @ref get() const
@complexity Linear in the size of the JSON value. @complexity Linear in the size of the JSON value.
...@@ -4088,7 +4089,7 @@ class basic_json ...@@ -4088,7 +4089,7 @@ class basic_json
@return const reference to the element at key @a key @return const reference to the element at key @a key
@throw std::domain_error if JSON is not an object; example: `"cannot use @throw type_error.305 if JSON is not an object; example: `"cannot use
operator[] with null"` operator[] with null"`
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
...@@ -4365,7 +4366,7 @@ class basic_json ...@@ -4365,7 +4366,7 @@ class basic_json
assertions**). assertions**).
@post The JSON value remains unchanged. @post The JSON value remains unchanged.
@throw std::out_of_range when called on `null` value @throw invalid_iterator.214 when called on `null` value
@liveexample{The following code shows an example for `front()`.,front} @liveexample{The following code shows an example for `front()`.,front}
...@@ -4408,7 +4409,7 @@ class basic_json ...@@ -4408,7 +4409,7 @@ class basic_json
assertions**). assertions**).
@post The JSON value remains unchanged. @post The JSON value remains unchanged.
@throw std::out_of_range when called on `null` value. @throw invalid_iterator.214 when called on `null` value.
@liveexample{The following code shows an example for `back()`.,back} @liveexample{The following code shows an example for `back()`.,back}
...@@ -4698,7 +4699,7 @@ class basic_json ...@@ -4698,7 +4699,7 @@ class basic_json
@throw type_error.307 when called on a type other than JSON object; @throw type_error.307 when called on a type other than JSON object;
example: `"cannot use erase() with null"` example: `"cannot use erase() with null"`
@throw std::out_of_range when `idx >= size()`; example: `"array index 17 @throw out_of_range.401 when `idx >= size()`; example: `"array index 17
is out of range"` is out of range"`
@complexity Linear in distance between @a idx and the end of the container. @complexity Linear in distance between @a idx and the end of the container.
...@@ -7032,6 +7033,8 @@ class basic_json ...@@ -7032,6 +7033,8 @@ class basic_json
@throw parse_error.101 if a parse error occurs; example: `""unexpected end @throw parse_error.101 if a parse error occurs; example: `""unexpected end
of input; expected string literal""` of input; expected string literal""`
@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 @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function LL(1) parser. The complexity can be higher if the parser callback function
...@@ -7063,6 +7066,10 @@ class basic_json ...@@ -7063,6 +7066,10 @@ class basic_json
@return result of the deserialization @return result of the deserialization
@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 @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function LL(1) parser. The complexity can be higher if the parser callback function
@a cb has a super-linear complexity. @a cb has a super-linear complexity.
...@@ -7099,6 +7106,11 @@ class basic_json ...@@ -7099,6 +7106,11 @@ class basic_json
@return result of the deserialization @return result of the deserialization
@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
@throw parse_error.111 if input stream is in a bad state
@complexity Linear in the length of the input. The parser is a predictive @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function LL(1) parser. The complexity can be higher if the parser callback function
@a cb has a super-linear complexity. @a cb has a super-linear complexity.
...@@ -7158,6 +7170,10 @@ class basic_json ...@@ -7158,6 +7170,10 @@ class basic_json
@return result of the deserialization @return result of the deserialization
@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 @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function LL(1) parser. The complexity can be higher if the parser callback function
@a cb has a super-linear complexity. @a cb has a super-linear complexity.
...@@ -7228,6 +7244,10 @@ class basic_json ...@@ -7228,6 +7244,10 @@ class basic_json
@return result of the deserialization @return result of the deserialization
@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 @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function LL(1) parser. The complexity can be higher if the parser callback function
@a cb has a super-linear complexity. @a cb has a super-linear complexity.
...@@ -7260,7 +7280,10 @@ class basic_json ...@@ -7260,7 +7280,10 @@ class basic_json
@param[in,out] i input stream to read a serialized JSON value from @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 @param[in,out] j JSON value to write the deserialized input to
@throw std::invalid_argument in case of parse errors @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
@throw parse_error.111 if input stream is in a bad state
@complexity Linear in the length of the input. The parser is a predictive @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. LL(1) parser.
...@@ -7963,9 +7986,9 @@ class basic_json ...@@ -7963,9 +7986,9 @@ class basic_json
@return deserialized JSON value @return deserialized JSON value
@throw std::invalid_argument if unsupported features from MessagePack were @throw parse_error.110 if the given vector ends prematurely
@throw parse_error.112 if unsupported features from MessagePack were
used in the given vector @a v or if the input is not valid MessagePack used in the given vector @a v or if the input is not valid MessagePack
@throw std::out_of_range if the given vector ends prematurely
@sa https://github.com/msgpack/msgpack/blob/master/spec.md @sa https://github.com/msgpack/msgpack/blob/master/spec.md
*/ */
...@@ -8205,9 +8228,9 @@ class basic_json ...@@ -8205,9 +8228,9 @@ class basic_json
@return deserialized JSON value @return deserialized JSON value
@throw std::invalid_argument if unsupported features from CBOR were used in @throw parse_error.110 if the given vector ends prematurely
the given vector @a v or if the input is not valid CBOR @throw parse_error.112 if unsupported features from CBOR were
@throw std::out_of_range if the given vector ends prematurely used in the given vector @a v or if the input is not valid CBOR
@sa https://tools.ietf.org/html/rfc7049 @sa https://tools.ietf.org/html/rfc7049
*/ */
...@@ -8729,9 +8752,9 @@ class basic_json ...@@ -8729,9 +8752,9 @@ class basic_json
@param[in] start_index the index to start reading from @a v (0 by default) @param[in] start_index the index to start reading from @a v (0 by default)
@return deserialized JSON value @return deserialized JSON value
@throw std::invalid_argument if unsupported features from MessagePack were @throw parse_error.110 if the given vector ends prematurely
@throw parse_error.112 if unsupported features from MessagePack were
used in the given vector @a v or if the input is not valid MessagePack used in the given vector @a v or if the input is not valid MessagePack
@throw std::out_of_range if the given vector ends prematurely
@complexity Linear in the size of the byte vector @a v. @complexity Linear in the size of the byte vector @a v.
...@@ -8792,9 +8815,9 @@ class basic_json ...@@ -8792,9 +8815,9 @@ class basic_json
@param[in] start_index the index to start reading from @a v (0 by default) @param[in] start_index the index to start reading from @a v (0 by default)
@return deserialized JSON value @return deserialized JSON value
@throw std::invalid_argument if unsupported features from CBOR were used in @throw parse_error.110 if the given vector ends prematurely
the given vector @a v or if the input is not valid MessagePack @throw parse_error.112 if unsupported features from CBOR were
@throw std::out_of_range if the given vector ends prematurely used in the given vector @a v or if the input is not valid CBOR
@complexity Linear in the size of the byte vector @a v. @complexity Linear in the size of the byte vector @a v.
...@@ -9908,7 +9931,10 @@ class basic_json ...@@ -9908,7 +9931,10 @@ class basic_json
m_limit = m_content + len; m_limit = m_content + len;
} }
/// a lexer from an input stream /*!
@brief a lexer from an input stream
@throw parse_error.111 if input stream is in a bad state
*/
explicit lexer(std::istream& s) explicit lexer(std::istream& s)
: m_stream(&s), m_line_buffer() : m_stream(&s), m_line_buffer()
{ {
...@@ -11288,7 +11314,7 @@ basic_json_parser_74: ...@@ -11288,7 +11314,7 @@ basic_json_parser_74:
@return string value of current token without opening and closing @return string value of current token without opening and closing
quotes quotes
@throw parse_error.102 if to_unicode fails @throw parse_error.102 if to_unicode fails or surrogate error
@throw parse_error.103 if to_unicode fails @throw parse_error.103 if to_unicode fails
*/ */
string_t get_string() const string_t get_string() const
...@@ -11685,7 +11711,10 @@ basic_json_parser_74: ...@@ -11685,7 +11711,10 @@ basic_json_parser_74:
m_lexer(reinterpret_cast<const typename lexer::lexer_char_t*>(buff), std::strlen(buff)) m_lexer(reinterpret_cast<const typename lexer::lexer_char_t*>(buff), std::strlen(buff))
{} {}
/// a parser reading from an input stream /*!
@brief a parser reading from an input stream
@throw parse_error.111 if input stream is in a bad state
*/
parser(std::istream& is, const parser_callback_t cb = nullptr) parser(std::istream& is, const parser_callback_t cb = nullptr)
: callback(cb), m_lexer(is) : callback(cb), m_lexer(is)
{} {}
...@@ -11701,7 +11730,12 @@ basic_json_parser_74: ...@@ -11701,7 +11730,12 @@ basic_json_parser_74:
static_cast<size_t>(std::distance(first, last))) static_cast<size_t>(std::distance(first, last)))
{} {}
/// public parser interface /*!
@brief public parser interface
@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
*/
basic_json parse() basic_json parse()
{ {
// read first token // read first token
...@@ -11718,7 +11752,12 @@ basic_json_parser_74: ...@@ -11718,7 +11752,12 @@ basic_json_parser_74:
} }
private: private:
/// the actual parser /*!
@brief the actual parser
@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
*/
basic_json parse_internal(bool keep) basic_json parse_internal(bool keep)
{ {
auto result = basic_json(value_t::discarded); auto result = basic_json(value_t::discarded);
...@@ -11921,6 +11960,9 @@ basic_json_parser_74: ...@@ -11921,6 +11960,9 @@ basic_json_parser_74:
return last_token; return last_token;
} }
/*!
@throw parse_error.101 if expected token did not occur
*/
void expect(typename lexer::token_type t) const void expect(typename lexer::token_type t) const
{ {
if (t != last_token) if (t != last_token)
...@@ -11934,6 +11976,9 @@ basic_json_parser_74: ...@@ -11934,6 +11976,9 @@ basic_json_parser_74:
} }
} }
/*!
@throw parse_error.101 if unexpected token occurred
*/
void unexpect(typename lexer::token_type t) const void unexpect(typename lexer::token_type t) const
{ {
if (t == last_token) if (t == last_token)
...@@ -11985,12 +12030,12 @@ basic_json_parser_74: ...@@ -11985,12 +12030,12 @@ basic_json_parser_74:
empty string is assumed which references the whole JSON empty string is assumed which references the whole JSON
value value
@throw parse_error.107 if reference token is nonempty and does not @throw parse_error.107 if the given JSON pointer @a s is nonempty and
begin with a slash (`/`); example: `"JSON pointer must be empty or does not begin with a slash (`/`); see example below
begin with / - was: 'foo'"`
@throw parse_error.108 if a tilde (`~`) is not followed by `0` @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s
(representing `~`) or `1` (representing `/`); example: `"escape is not followed by `0` (representing `~`) or `1` (representing `/`);
character '~' must be followed with '0' or '1'"` see example below
@liveexample{The example shows the construction several valid JSON @liveexample{The example shows the construction several valid JSON
pointers as well as the exceptional behavior.,json_pointer} pointers as well as the exceptional behavior.,json_pointer}
...@@ -12033,7 +12078,10 @@ basic_json_parser_74: ...@@ -12033,7 +12078,10 @@ basic_json_parser_74:
} }
private: private:
/// remove and return last reference pointer /*!
@brief remove and return last reference pointer
@throw out_of_range.405 if JSON pointer has no parent
*/
std::string pop_back() std::string pop_back()
{ {
if (is_root()) if (is_root())
...@@ -12068,6 +12116,9 @@ basic_json_parser_74: ...@@ -12068,6 +12116,9 @@ basic_json_parser_74:
@brief create and return a reference to the pointed to value @brief create and return a reference to the pointed to value
@complexity Linear in the number of reference tokens. @complexity Linear in the number of reference tokens.
@throw parse_error.109 if array index is not a number
@throw type_error.313 if value cannot be unflattened
*/ */
reference get_and_create(reference j) const reference get_and_create(reference j) const
{ {
...@@ -12147,9 +12198,9 @@ basic_json_parser_74: ...@@ -12147,9 +12198,9 @@ basic_json_parser_74:
@complexity Linear in the length of the JSON pointer. @complexity Linear in the length of the JSON pointer.
@throw out_of_range.404 if the JSON pointer can not be resolved @throw parse_error.106 if an array index begins with '0'
@throw parse_error.106 if an array index begins with '0' @throw parse_error.109 if an array index was not a number
@throw std::invalid_argument if an array index was not a number @throw out_of_range.404 if the JSON pointer can not be resolved
*/ */
reference get_unchecked(pointer ptr) const reference get_unchecked(pointer ptr) const
{ {
...@@ -12225,6 +12276,12 @@ basic_json_parser_74: ...@@ -12225,6 +12276,12 @@ basic_json_parser_74:
return *ptr; return *ptr;
} }
/*!
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
*/
reference get_checked(pointer ptr) const reference get_checked(pointer ptr) const
{ {
for (const auto& reference_token : reference_tokens) for (const auto& reference_token : reference_tokens)
...@@ -12283,6 +12340,11 @@ basic_json_parser_74: ...@@ -12283,6 +12340,11 @@ basic_json_parser_74:
@return const reference to the JSON value pointed to by the JSON @return const reference to the JSON value pointed to by the JSON
pointer pointer
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
*/ */
const_reference get_unchecked(const_pointer ptr) const const_reference get_unchecked(const_pointer ptr) const
{ {
...@@ -12335,6 +12397,12 @@ basic_json_parser_74: ...@@ -12335,6 +12397,12 @@ basic_json_parser_74:
return *ptr; return *ptr;
} }
/*!
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
*/
const_reference get_checked(const_pointer ptr) const const_reference get_checked(const_pointer ptr) const
{ {
for (const auto& reference_token : reference_tokens) for (const auto& reference_token : reference_tokens)
...@@ -12386,7 +12454,15 @@ basic_json_parser_74: ...@@ -12386,7 +12454,15 @@ basic_json_parser_74:
return *ptr; return *ptr;
} }
/// split the string input to reference tokens /*!
@brief split the string input to reference tokens
@note This function is only called by the json_pointer constructor.
All exceptions below are documented there.
@throw parse_error.107 if the pointer is not empty or begins with '/'
@throw parse_error.108 if character '~' is not followed by '0' or '1'
*/
static std::vector<std::string> split(const std::string& reference_string) static std::vector<std::string> split(const std::string& reference_string)
{ {
std::vector<std::string> result; std::vector<std::string> result;
...@@ -12447,7 +12523,6 @@ basic_json_parser_74: ...@@ -12447,7 +12523,6 @@ basic_json_parser_74:
return result; return result;
} }
private:
/*! /*!
@brief replace all occurrences of a substring by another string @brief replace all occurrences of a substring by another string
...@@ -12456,7 +12531,8 @@ basic_json_parser_74: ...@@ -12456,7 +12531,8 @@ basic_json_parser_74:
@param[in] f the substring to replace with @a t @param[in] f the substring to replace with @a t
@param[in] t the string to replace @a f @param[in] t the string to replace @a f
@pre The search string @a f must not be empty. @pre The search string @a f must not be empty. **This precondition is
enforced with an assertion.**
@since version 2.0.0 @since version 2.0.0
*/ */
...@@ -12556,6 +12632,11 @@ basic_json_parser_74: ...@@ -12556,6 +12632,11 @@ basic_json_parser_74:
@param[in] value flattened JSON @param[in] value flattened JSON
@return unflattened JSON @return unflattened JSON
@throw parse_error.109 if array index is not a number
@throw type_error.314 if value is not an object
@throw type_error.315 if object values are not primitive
@throw type_error.313 if value cannot be unflattened
*/ */
static basic_json unflatten(const basic_json& value) static basic_json unflatten(const basic_json& value)
{ {
...@@ -12585,7 +12666,6 @@ basic_json_parser_74: ...@@ -12585,7 +12666,6 @@ basic_json_parser_74:
return result; return result;
} }
private:
friend bool operator==(json_pointer const& lhs, friend bool operator==(json_pointer const& lhs,
json_pointer const& rhs) noexcept json_pointer const& rhs) noexcept
{ {
...@@ -12634,9 +12714,9 @@ basic_json_parser_74: ...@@ -12634,9 +12714,9 @@ basic_json_parser_74:
@complexity Constant. @complexity Constant.
@throw std::out_of_range if the JSON pointer can not be resolved @throw parse_error.106 if an array index begins with '0'
@throw std::domain_error if an array index begins with '0' @throw parse_error.109 if an array index was not a number
@throw std::invalid_argument if an array index was not a number @throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,operatorjson_pointer} @liveexample{The behavior is shown in the example.,operatorjson_pointer}
...@@ -12661,9 +12741,10 @@ basic_json_parser_74: ...@@ -12661,9 +12741,10 @@ basic_json_parser_74:
@complexity Constant. @complexity Constant.
@throw std::out_of_range if the JSON pointer can not be resolved @throw parse_error.106 if an array index begins with '0'
@throw std::domain_error if an array index begins with '0' @throw parse_error.109 if an array index was not a number
@throw std::invalid_argument if an array index was not a number @throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,operatorjson_pointer_const} @liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
...@@ -12686,9 +12767,10 @@ basic_json_parser_74: ...@@ -12686,9 +12767,10 @@ basic_json_parser_74:
@complexity Constant. @complexity Constant.
@throw std::out_of_range if the JSON pointer can not be resolved @throw parse_error.106 if an array index begins with '0'
@throw std::domain_error if an array index begins with '0' @throw parse_error.109 if an array index was not a number
@throw std::invalid_argument if an array index was not a number @throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,at_json_pointer} @liveexample{The behavior is shown in the example.,at_json_pointer}
...@@ -12711,9 +12793,10 @@ basic_json_parser_74: ...@@ -12711,9 +12793,10 @@ basic_json_parser_74:
@complexity Constant. @complexity Constant.
@throw std::out_of_range if the JSON pointer can not be resolved @throw parse_error.106 if an array index begins with '0'
@throw std::domain_error if an array index begins with '0' @throw parse_error.109 if an array index was not a number
@throw std::invalid_argument if an array index was not a number @throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,at_json_pointer_const} @liveexample{The behavior is shown in the example.,at_json_pointer_const}
...@@ -12773,6 +12856,9 @@ basic_json_parser_74: ...@@ -12773,6 +12856,9 @@ basic_json_parser_74:
@complexity Linear in the size the JSON value. @complexity Linear in the size the JSON value.
@throw type_error.314 if value is not an object
@throw type_error.315 if object values are not primitve
@liveexample{The following code shows how a flattened JSON object is @liveexample{The following code shows how a flattened JSON object is
unflattened into the original nested JSON object.,unflatten} unflattened into the original nested JSON object.,unflatten}
...@@ -12810,13 +12896,22 @@ basic_json_parser_74: ...@@ -12810,13 +12896,22 @@ basic_json_parser_74:
any case, the original value is not changed: the patch is applied any case, the original value is not changed: the patch is applied
to a copy of the value. to a copy of the value.
@throw parse_error.104 if the JSON patch does not consist of an array of
objects
@throw parse_error.105 if the JSON patch is malformed (e.g., mandatory
attributes are missing); example: `"operation add must have member path"`
@throw out_of_range.401 if an array index is out of range.
@throw out_of_range.403 if a JSON pointer inside the patch could not be @throw out_of_range.403 if a JSON pointer inside the patch could not be
resolved successfully in the current JSON value; example: `"key baz not resolved successfully in the current JSON value; example: `"key baz not
found"` found"`
@throw invalid_argument if the JSON patch is malformed (e.g., mandatory
attributes are missing); example: `"operation add must have member path"` @throw out_of_range.405 if JSON pointer has no parent ("add", "remove",
@throw parse_error.104 if the JSON patch does not consist of an array of "move")
objects
@throw other_error.501 if "test" operation was unsuccessful
@complexity Linear in the size of the JSON value and the length of the @complexity Linear in the size of the JSON value and the length of the
JSON patch. As usually only a fraction of the JSON value is affected by JSON patch. As usually only a fraction of the JSON value is affected by
......
src/json.hpp.re2c
...@@ -3653,7 +3653,7 @@ class basic_json ...@@ -3653,7 +3653,7 @@ class basic_json
@return copy of the JSON value, converted to type @a ValueType @return copy of the JSON value, converted to type @a ValueType
@throw std::domain_error in case passed type @a ValueType is incompatible @throw type_error.302 in case passed type @a ValueType is incompatible
to JSON, thrown by @ref get() const to JSON, thrown by @ref get() const
@complexity Linear in the size of the JSON value. @complexity Linear in the size of the JSON value.
...@@ -4089,7 +4089,7 @@ class basic_json ...@@ -4089,7 +4089,7 @@ class basic_json
@return const reference to the element at key @a key @return const reference to the element at key @a key
@throw std::domain_error if JSON is not an object; example: `"cannot use @throw type_error.305 if JSON is not an object; example: `"cannot use
operator[] with null"` operator[] with null"`
@complexity Logarithmic in the size of the container. @complexity Logarithmic in the size of the container.
...@@ -4366,7 +4366,7 @@ class basic_json ...@@ -4366,7 +4366,7 @@ class basic_json
assertions**). assertions**).
@post The JSON value remains unchanged. @post The JSON value remains unchanged.
@throw std::out_of_range when called on `null` value @throw invalid_iterator.214 when called on `null` value
@liveexample{The following code shows an example for `front()`.,front} @liveexample{The following code shows an example for `front()`.,front}
...@@ -4409,7 +4409,7 @@ class basic_json ...@@ -4409,7 +4409,7 @@ class basic_json
assertions**). assertions**).
@post The JSON value remains unchanged. @post The JSON value remains unchanged.
@throw std::out_of_range when called on `null` value. @throw invalid_iterator.214 when called on `null` value.
@liveexample{The following code shows an example for `back()`.,back} @liveexample{The following code shows an example for `back()`.,back}
...@@ -4699,7 +4699,7 @@ class basic_json ...@@ -4699,7 +4699,7 @@ class basic_json
@throw type_error.307 when called on a type other than JSON object; @throw type_error.307 when called on a type other than JSON object;
example: `"cannot use erase() with null"` example: `"cannot use erase() with null"`
@throw std::out_of_range when `idx >= size()`; example: `"array index 17 @throw out_of_range.401 when `idx >= size()`; example: `"array index 17
is out of range"` is out of range"`
@complexity Linear in distance between @a idx and the end of the container. @complexity Linear in distance between @a idx and the end of the container.
...@@ -7033,6 +7033,8 @@ class basic_json ...@@ -7033,6 +7033,8 @@ class basic_json
@throw parse_error.101 if a parse error occurs; example: `""unexpected end @throw parse_error.101 if a parse error occurs; example: `""unexpected end
of input; expected string literal""` of input; expected string literal""`
@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 @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function LL(1) parser. The complexity can be higher if the parser callback function
...@@ -7064,6 +7066,10 @@ class basic_json ...@@ -7064,6 +7066,10 @@ class basic_json
@return result of the deserialization @return result of the deserialization
@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 @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function LL(1) parser. The complexity can be higher if the parser callback function
@a cb has a super-linear complexity. @a cb has a super-linear complexity.
...@@ -7100,6 +7106,11 @@ class basic_json ...@@ -7100,6 +7106,11 @@ class basic_json
@return result of the deserialization @return result of the deserialization
@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
@throw parse_error.111 if input stream is in a bad state
@complexity Linear in the length of the input. The parser is a predictive @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function LL(1) parser. The complexity can be higher if the parser callback function
@a cb has a super-linear complexity. @a cb has a super-linear complexity.
...@@ -7159,6 +7170,10 @@ class basic_json ...@@ -7159,6 +7170,10 @@ class basic_json
@return result of the deserialization @return result of the deserialization
@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 @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function LL(1) parser. The complexity can be higher if the parser callback function
@a cb has a super-linear complexity. @a cb has a super-linear complexity.
...@@ -7229,6 +7244,10 @@ class basic_json ...@@ -7229,6 +7244,10 @@ class basic_json
@return result of the deserialization @return result of the deserialization
@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 @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function LL(1) parser. The complexity can be higher if the parser callback function
@a cb has a super-linear complexity. @a cb has a super-linear complexity.
...@@ -7261,7 +7280,10 @@ class basic_json ...@@ -7261,7 +7280,10 @@ class basic_json
@param[in,out] i input stream to read a serialized JSON value from @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 @param[in,out] j JSON value to write the deserialized input to
@throw std::invalid_argument in case of parse errors @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
@throw parse_error.111 if input stream is in a bad state
@complexity Linear in the length of the input. The parser is a predictive @complexity Linear in the length of the input. The parser is a predictive
LL(1) parser. LL(1) parser.
...@@ -7964,9 +7986,9 @@ class basic_json ...@@ -7964,9 +7986,9 @@ class basic_json
@return deserialized JSON value @return deserialized JSON value
@throw std::invalid_argument if unsupported features from MessagePack were @throw parse_error.110 if the given vector ends prematurely
@throw parse_error.112 if unsupported features from MessagePack were
used in the given vector @a v or if the input is not valid MessagePack used in the given vector @a v or if the input is not valid MessagePack
@throw std::out_of_range if the given vector ends prematurely
@sa https://github.com/msgpack/msgpack/blob/master/spec.md @sa https://github.com/msgpack/msgpack/blob/master/spec.md
*/ */
...@@ -8206,9 +8228,9 @@ class basic_json ...@@ -8206,9 +8228,9 @@ class basic_json
@return deserialized JSON value @return deserialized JSON value
@throw std::invalid_argument if unsupported features from CBOR were used in @throw parse_error.110 if the given vector ends prematurely
the given vector @a v or if the input is not valid CBOR @throw parse_error.112 if unsupported features from CBOR were
@throw std::out_of_range if the given vector ends prematurely used in the given vector @a v or if the input is not valid CBOR
@sa https://tools.ietf.org/html/rfc7049 @sa https://tools.ietf.org/html/rfc7049
*/ */
...@@ -8730,9 +8752,9 @@ class basic_json ...@@ -8730,9 +8752,9 @@ class basic_json
@param[in] start_index the index to start reading from @a v (0 by default) @param[in] start_index the index to start reading from @a v (0 by default)
@return deserialized JSON value @return deserialized JSON value
@throw std::invalid_argument if unsupported features from MessagePack were @throw parse_error.110 if the given vector ends prematurely
@throw parse_error.112 if unsupported features from MessagePack were
used in the given vector @a v or if the input is not valid MessagePack used in the given vector @a v or if the input is not valid MessagePack
@throw std::out_of_range if the given vector ends prematurely
@complexity Linear in the size of the byte vector @a v. @complexity Linear in the size of the byte vector @a v.
...@@ -8793,9 +8815,9 @@ class basic_json ...@@ -8793,9 +8815,9 @@ class basic_json
@param[in] start_index the index to start reading from @a v (0 by default) @param[in] start_index the index to start reading from @a v (0 by default)
@return deserialized JSON value @return deserialized JSON value
@throw std::invalid_argument if unsupported features from CBOR were used in @throw parse_error.110 if the given vector ends prematurely
the given vector @a v or if the input is not valid MessagePack @throw parse_error.112 if unsupported features from CBOR were
@throw std::out_of_range if the given vector ends prematurely used in the given vector @a v or if the input is not valid CBOR
@complexity Linear in the size of the byte vector @a v. @complexity Linear in the size of the byte vector @a v.
...@@ -9909,7 +9931,10 @@ class basic_json ...@@ -9909,7 +9931,10 @@ class basic_json
m_limit = m_content + len; m_limit = m_content + len;
} }
/// a lexer from an input stream /*!
@brief a lexer from an input stream
@throw parse_error.111 if input stream is in a bad state
*/
explicit lexer(std::istream& s) explicit lexer(std::istream& s)
: m_stream(&s), m_line_buffer() : m_stream(&s), m_line_buffer()
{ {
...@@ -10322,7 +10347,7 @@ class basic_json ...@@ -10322,7 +10347,7 @@ class basic_json
@return string value of current token without opening and closing @return string value of current token without opening and closing
quotes quotes
@throw parse_error.102 if to_unicode fails @throw parse_error.102 if to_unicode fails or surrogate error
@throw parse_error.103 if to_unicode fails @throw parse_error.103 if to_unicode fails
*/ */
string_t get_string() const string_t get_string() const
...@@ -10719,7 +10744,10 @@ class basic_json ...@@ -10719,7 +10744,10 @@ class basic_json
m_lexer(reinterpret_cast<const typename lexer::lexer_char_t*>(buff), std::strlen(buff)) m_lexer(reinterpret_cast<const typename lexer::lexer_char_t*>(buff), std::strlen(buff))
{} {}
/// a parser reading from an input stream /*!
@brief a parser reading from an input stream
@throw parse_error.111 if input stream is in a bad state
*/
parser(std::istream& is, const parser_callback_t cb = nullptr) parser(std::istream& is, const parser_callback_t cb = nullptr)
: callback(cb), m_lexer(is) : callback(cb), m_lexer(is)
{} {}
...@@ -10735,7 +10763,12 @@ class basic_json ...@@ -10735,7 +10763,12 @@ class basic_json
static_cast<size_t>(std::distance(first, last))) static_cast<size_t>(std::distance(first, last)))
{} {}
/// public parser interface /*!
@brief public parser interface
@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
*/
basic_json parse() basic_json parse()
{ {
// read first token // read first token
...@@ -10752,7 +10785,12 @@ class basic_json ...@@ -10752,7 +10785,12 @@ class basic_json
} }
private: private:
/// the actual parser /*!
@brief the actual parser
@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
*/
basic_json parse_internal(bool keep) basic_json parse_internal(bool keep)
{ {
auto result = basic_json(value_t::discarded); auto result = basic_json(value_t::discarded);
...@@ -10955,6 +10993,9 @@ class basic_json ...@@ -10955,6 +10993,9 @@ class basic_json
return last_token; return last_token;
} }
/*!
@throw parse_error.101 if expected token did not occur
*/
void expect(typename lexer::token_type t) const void expect(typename lexer::token_type t) const
{ {
if (t != last_token) if (t != last_token)
...@@ -10968,6 +11009,9 @@ class basic_json ...@@ -10968,6 +11009,9 @@ class basic_json
} }
} }
/*!
@throw parse_error.101 if unexpected token occurred
*/
void unexpect(typename lexer::token_type t) const void unexpect(typename lexer::token_type t) const
{ {
if (t == last_token) if (t == last_token)
...@@ -11019,12 +11063,12 @@ class basic_json ...@@ -11019,12 +11063,12 @@ class basic_json
empty string is assumed which references the whole JSON empty string is assumed which references the whole JSON
value value
@throw parse_error.107 if reference token is nonempty and does not @throw parse_error.107 if the given JSON pointer @a s is nonempty and
begin with a slash (`/`); example: `"JSON pointer must be empty or does not begin with a slash (`/`); see example below
begin with / - was: 'foo'"`
@throw parse_error.108 if a tilde (`~`) is not followed by `0` @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s
(representing `~`) or `1` (representing `/`); example: `"escape is not followed by `0` (representing `~`) or `1` (representing `/`);
character '~' must be followed with '0' or '1'"` see example below
@liveexample{The example shows the construction several valid JSON @liveexample{The example shows the construction several valid JSON
pointers as well as the exceptional behavior.,json_pointer} pointers as well as the exceptional behavior.,json_pointer}
...@@ -11067,7 +11111,10 @@ class basic_json ...@@ -11067,7 +11111,10 @@ class basic_json
} }
private: private:
/// remove and return last reference pointer /*!
@brief remove and return last reference pointer
@throw out_of_range.405 if JSON pointer has no parent
*/
std::string pop_back() std::string pop_back()
{ {
if (is_root()) if (is_root())
...@@ -11102,6 +11149,9 @@ class basic_json ...@@ -11102,6 +11149,9 @@ class basic_json
@brief create and return a reference to the pointed to value @brief create and return a reference to the pointed to value
@complexity Linear in the number of reference tokens. @complexity Linear in the number of reference tokens.
@throw parse_error.109 if array index is not a number
@throw type_error.313 if value cannot be unflattened
*/ */
reference get_and_create(reference j) const reference get_and_create(reference j) const
{ {
...@@ -11181,9 +11231,9 @@ class basic_json ...@@ -11181,9 +11231,9 @@ class basic_json
@complexity Linear in the length of the JSON pointer. @complexity Linear in the length of the JSON pointer.
@throw out_of_range.404 if the JSON pointer can not be resolved @throw parse_error.106 if an array index begins with '0'
@throw parse_error.106 if an array index begins with '0' @throw parse_error.109 if an array index was not a number
@throw std::invalid_argument if an array index was not a number @throw out_of_range.404 if the JSON pointer can not be resolved
*/ */
reference get_unchecked(pointer ptr) const reference get_unchecked(pointer ptr) const
{ {
...@@ -11259,6 +11309,12 @@ class basic_json ...@@ -11259,6 +11309,12 @@ class basic_json
return *ptr; return *ptr;
} }
/*!
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
*/
reference get_checked(pointer ptr) const reference get_checked(pointer ptr) const
{ {
for (const auto& reference_token : reference_tokens) for (const auto& reference_token : reference_tokens)
...@@ -11317,6 +11373,11 @@ class basic_json ...@@ -11317,6 +11373,11 @@ class basic_json
@return const reference to the JSON value pointed to by the JSON @return const reference to the JSON value pointed to by the JSON
pointer pointer
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
*/ */
const_reference get_unchecked(const_pointer ptr) const const_reference get_unchecked(const_pointer ptr) const
{ {
...@@ -11369,6 +11430,12 @@ class basic_json ...@@ -11369,6 +11430,12 @@ class basic_json
return *ptr; return *ptr;
} }
/*!
@throw parse_error.106 if an array index begins with '0'
@throw parse_error.109 if an array index was not a number
@throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
*/
const_reference get_checked(const_pointer ptr) const const_reference get_checked(const_pointer ptr) const
{ {
for (const auto& reference_token : reference_tokens) for (const auto& reference_token : reference_tokens)
...@@ -11420,7 +11487,15 @@ class basic_json ...@@ -11420,7 +11487,15 @@ class basic_json
return *ptr; return *ptr;
} }
/// split the string input to reference tokens /*!
@brief split the string input to reference tokens
@note This function is only called by the json_pointer constructor.
All exceptions below are documented there.
@throw parse_error.107 if the pointer is not empty or begins with '/'
@throw parse_error.108 if character '~' is not followed by '0' or '1'
*/
static std::vector<std::string> split(const std::string& reference_string) static std::vector<std::string> split(const std::string& reference_string)
{ {
std::vector<std::string> result; std::vector<std::string> result;
...@@ -11481,7 +11556,6 @@ class basic_json ...@@ -11481,7 +11556,6 @@ class basic_json
return result; return result;
} }
private:
/*! /*!
@brief replace all occurrences of a substring by another string @brief replace all occurrences of a substring by another string
...@@ -11490,7 +11564,8 @@ class basic_json ...@@ -11490,7 +11564,8 @@ class basic_json
@param[in] f the substring to replace with @a t @param[in] f the substring to replace with @a t
@param[in] t the string to replace @a f @param[in] t the string to replace @a f
@pre The search string @a f must not be empty. @pre The search string @a f must not be empty. **This precondition is
enforced with an assertion.**
@since version 2.0.0 @since version 2.0.0
*/ */
...@@ -11590,6 +11665,11 @@ class basic_json ...@@ -11590,6 +11665,11 @@ class basic_json
@param[in] value flattened JSON @param[in] value flattened JSON
@return unflattened JSON @return unflattened JSON
@throw parse_error.109 if array index is not a number
@throw type_error.314 if value is not an object
@throw type_error.315 if object values are not primitive
@throw type_error.313 if value cannot be unflattened
*/ */
static basic_json unflatten(const basic_json& value) static basic_json unflatten(const basic_json& value)
{ {
...@@ -11619,7 +11699,6 @@ class basic_json ...@@ -11619,7 +11699,6 @@ class basic_json
return result; return result;
} }
private:
friend bool operator==(json_pointer const& lhs, friend bool operator==(json_pointer const& lhs,
json_pointer const& rhs) noexcept json_pointer const& rhs) noexcept
{ {
...@@ -11668,9 +11747,9 @@ class basic_json ...@@ -11668,9 +11747,9 @@ class basic_json
@complexity Constant. @complexity Constant.
@throw std::out_of_range if the JSON pointer can not be resolved @throw parse_error.106 if an array index begins with '0'
@throw std::domain_error if an array index begins with '0' @throw parse_error.109 if an array index was not a number
@throw std::invalid_argument if an array index was not a number @throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,operatorjson_pointer} @liveexample{The behavior is shown in the example.,operatorjson_pointer}
...@@ -11695,9 +11774,10 @@ class basic_json ...@@ -11695,9 +11774,10 @@ class basic_json
@complexity Constant. @complexity Constant.
@throw std::out_of_range if the JSON pointer can not be resolved @throw parse_error.106 if an array index begins with '0'
@throw std::domain_error if an array index begins with '0' @throw parse_error.109 if an array index was not a number
@throw std::invalid_argument if an array index was not a number @throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,operatorjson_pointer_const} @liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
...@@ -11720,9 +11800,10 @@ class basic_json ...@@ -11720,9 +11800,10 @@ class basic_json
@complexity Constant. @complexity Constant.
@throw std::out_of_range if the JSON pointer can not be resolved @throw parse_error.106 if an array index begins with '0'
@throw std::domain_error if an array index begins with '0' @throw parse_error.109 if an array index was not a number
@throw std::invalid_argument if an array index was not a number @throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,at_json_pointer} @liveexample{The behavior is shown in the example.,at_json_pointer}
...@@ -11745,9 +11826,10 @@ class basic_json ...@@ -11745,9 +11826,10 @@ class basic_json
@complexity Constant. @complexity Constant.
@throw std::out_of_range if the JSON pointer can not be resolved @throw parse_error.106 if an array index begins with '0'
@throw std::domain_error if an array index begins with '0' @throw parse_error.109 if an array index was not a number
@throw std::invalid_argument if an array index was not a number @throw out_of_range.402 if the array index '-' is used
@throw out_of_range.404 if the JSON pointer can not be resolved
@liveexample{The behavior is shown in the example.,at_json_pointer_const} @liveexample{The behavior is shown in the example.,at_json_pointer_const}
...@@ -11807,6 +11889,9 @@ class basic_json ...@@ -11807,6 +11889,9 @@ class basic_json
@complexity Linear in the size the JSON value. @complexity Linear in the size the JSON value.
@throw type_error.314 if value is not an object
@throw type_error.315 if object values are not primitve
@liveexample{The following code shows how a flattened JSON object is @liveexample{The following code shows how a flattened JSON object is
unflattened into the original nested JSON object.,unflatten} unflattened into the original nested JSON object.,unflatten}
...@@ -11844,13 +11929,22 @@ class basic_json ...@@ -11844,13 +11929,22 @@ class basic_json
any case, the original value is not changed: the patch is applied any case, the original value is not changed: the patch is applied
to a copy of the value. to a copy of the value.
@throw parse_error.104 if the JSON patch does not consist of an array of
objects
@throw parse_error.105 if the JSON patch is malformed (e.g., mandatory
attributes are missing); example: `"operation add must have member path"`
@throw out_of_range.401 if an array index is out of range.
@throw out_of_range.403 if a JSON pointer inside the patch could not be @throw out_of_range.403 if a JSON pointer inside the patch could not be
resolved successfully in the current JSON value; example: `"key baz not resolved successfully in the current JSON value; example: `"key baz not
found"` found"`
@throw invalid_argument if the JSON patch is malformed (e.g., mandatory
attributes are missing); example: `"operation add must have member path"` @throw out_of_range.405 if JSON pointer has no parent ("add", "remove",
@throw parse_error.104 if the JSON patch does not consist of an array of "move")
objects
@throw other_error.501 if "test" operation was unsuccessful
@complexity Linear in the size of the JSON value and the length of the @complexity Linear in the size of the JSON value and the length of the
JSON patch. As usually only a fraction of the JSON value is affected by JSON patch. As usually only a fraction of the JSON value is affected by
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment