Skip to content

Commit

Permalink
📝 updated documentation for update() function #661
Browse files Browse the repository at this point in the history
  • Loading branch information
nlohmann committed Aug 15, 2017
1 parent 039e2f0 commit 72afe53
Show file tree
Hide file tree
Showing 8 changed files with 86 additions and 6 deletions.
17 changes: 17 additions & 0 deletions doc/examples/update.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
#include <iostream>
#include "json.hpp"

using json = nlohmann::json;

int main()
{
// create two JSON objects
json o1 = R"( {"color": "red", "price": 17.99} )"_json;
json o2 = R"( {"color": "blue", "speed": 100} )"_json;

// add all keys from o2 to o1 (updating "color")
o1.update(o2);

// output updated object o1
std::cout << std::setw(2) << o1 << '\n';
}
1 change: 1 addition & 0 deletions doc/examples/update.link
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/ZmHD2plm6OAuY6uJ"><b>online</b></a>
5 changes: 5 additions & 0 deletions doc/examples/update.output
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"color": "blue",
"price": 17.99,
"speed": 100
}
17 changes: 17 additions & 0 deletions doc/examples/update__range.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
#include <iostream>
#include "json.hpp"

using json = nlohmann::json;

int main()
{
// create two JSON objects
json o1 = R"( {"color": "red", "price": 17.99} )"_json;
json o2 = R"( {"color": "blue", "speed": 100} )"_json;

// add all keys from o2 to o1 (updating "color")
o1.update(o2.begin(), o2.end());

// output updated object o1
std::cout << std::setw(2) << o1 << '\n';
}
1 change: 1 addition & 0 deletions doc/examples/update__range.link
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/Dg4mswDmYr4e0M4f"><b>online</b></a>
5 changes: 5 additions & 0 deletions doc/examples/update__range.output
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"color": "blue",
"price": 17.99,
"speed": 100
}
40 changes: 37 additions & 3 deletions src/json.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -323,6 +323,7 @@ json.exception.type_error.308 | cannot use push_back() with string | The @ref pu
json.exception.type_error.309 | cannot use insert() with | The @ref insert() member functions can only be executed for certain JSON types.
json.exception.type_error.310 | cannot use swap() with number | The @ref swap() member functions can only be executed for certain JSON types.
json.exception.type_error.311 | cannot use emplace_back() with string | The @ref emplace_back() member function can only be executed for certain JSON types.
json.exception.type_error.312 | cannot use update() with string | The @ref update() member functions can only be executed for certain JSON types.
json.exception.type_error.313 | invalid value to unflatten | The @ref unflatten function converts an object whose keys are JSON Pointers back into an arbitrary nested JSON value. The JSON Pointers must not overlap, because then the resulting value would not be well defined.
json.exception.type_error.314 | only objects can be unflattened | The @ref unflatten function only works for an object whose keys are JSON Pointers.
json.exception.type_error.315 | values in object must be primitive | The @ref unflatten function only works for an object whose keys are JSON Pointers and whose values are primitive.
Expand Down Expand Up @@ -11871,9 +11872,16 @@ class basic_json
@param[in] j JSON object to read values from
@throw type_error.312 if called on JSON values other than objects; example:
`"cannot use update() with string"`
@complexity O(N*log(size() + N)), where N is the number of elements to
insert.
@liveexample{The example shows how `update()` is used.,update}
@sa https://docs.python.org/3.6/library/stdtypes.html#dict.update
@since version 3.0.0
*/
void update(const_reference j)
Expand All @@ -11888,11 +11896,11 @@ class basic_json

if (JSON_UNLIKELY(not is_object()))
{
JSON_THROW(type_error::create(305, "cannot use merge() with " + std::string(type_name())));
JSON_THROW(type_error::create(312, "cannot use update() with " + std::string(type_name())));
}
if (JSON_UNLIKELY(not j.is_object()))
{
JSON_THROW(type_error::create(305, "cannot use merge() with " + std::string(j.type_name())));
JSON_THROW(type_error::create(312, "cannot use update() with " + std::string(j.type_name())));
}

for (auto it = j.begin(); it != j.end(); ++it)
Expand All @@ -11901,6 +11909,32 @@ class basic_json
}
}

/*!
@brief updates a JSON object from another object, overwriting existing keys
Inserts all values from from range `[first, last)` and overwrites existing
keys.
@param[in] first begin of the range of elements to insert
@param[in] last end of the range of elements to insert
@throw type_error.312 if called on JSON values other than objects; example:
`"cannot use update() with string"`
@throw invalid_iterator.202 if iterator @a first or @a last does does not
point to an object; example: `"iterators first and last must point to
objects"`
@throw invalid_iterator.210 if @a first and @a last do not belong to the
same JSON value; example: `"iterators do not fit"`
@complexity O(N*log(size() + N)), where N is the number of elements to
insert.
@liveexample{The example shows how `update()` is used__range.,update}
@sa https://docs.python.org/3.6/library/stdtypes.html#dict.update
@since version 3.0.0
*/
void update(const_iterator first, const_iterator last)
{
// implicitly convert null value to an empty object
Expand All @@ -11913,7 +11947,7 @@ class basic_json

if (JSON_UNLIKELY(not is_object()))
{
JSON_THROW(type_error::create(305, "cannot use merge() with " + std::string(type_name())));
JSON_THROW(type_error::create(312, "cannot use update() with " + std::string(type_name())));
}

// check if range iterators belong to the same JSON object
Expand Down
6 changes: 3 additions & 3 deletions test/src/unit-modifiers.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -761,10 +761,10 @@ TEST_CASE("modifiers")
SECTION("wrong types")
{
CHECK_THROWS_AS(j_array.update(j_object1), json::type_error&);
CHECK_THROWS_WITH(j_array.update(j_object1), "[json.exception.type_error.305] cannot use merge() with array");
CHECK_THROWS_WITH(j_array.update(j_object1), "[json.exception.type_error.312] cannot use update() with array");

CHECK_THROWS_AS(j_object1.update(j_array), json::type_error&);
CHECK_THROWS_WITH(j_object1.update(j_array), "[json.exception.type_error.305] cannot use merge() with array");
CHECK_THROWS_WITH(j_object1.update(j_array), "[json.exception.type_error.312] cannot use update() with array");
}
}

Expand Down Expand Up @@ -795,7 +795,7 @@ TEST_CASE("modifiers")
CHECK_THROWS_AS(j_object1.update(j_array.begin(), j_array.end()), json::invalid_iterator&);

CHECK_THROWS_WITH(j_array.update(j_object2.begin(), j_object2.end()),
"[json.exception.type_error.305] cannot use merge() with array");
"[json.exception.type_error.312] cannot use update() with array");
CHECK_THROWS_WITH(j_object1.update(j_object1.begin(), j_object2.end()),
"[json.exception.invalid_iterator.210] iterators do not fit");
CHECK_THROWS_WITH(j_object1.update(j_array.begin(), j_array.end()),
Expand Down

0 comments on commit 72afe53

Please sign in to comment.