proposal for emplace/emplace_back (#349)

doc/examples/emplace.cpp

@@ -0,0 +1,23 @@
+#include <json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create JSON values
+    json object = {{"one", 1}, {"two", 2}};
+    json null;
+
+    // print values
+    std::cout << object << '\n';
+    std::cout << null << '\n';
+
+    // add values
+    object.emplace("three", 3);
+    null.emplace("A", "a");
+    null.emplace("B", "b");
+
+    // print values
+    std::cout << object << '\n';
+    std::cout << null << '\n';
+}

doc/examples/emplace.link

@@ -0,0 +1 @@
+<a target="_blank" href="http://melpon.org/wandbox/permlink/Qg5Ogrh8yFrwT2GY"><b>online</b></a>

doc/examples/emplace.output

@@ -0,0 +1,4 @@
+{"one":1,"two":2}
+null
+{"one":1,"three":3,"two":2}
+{"A":"a","B":"b"}

doc/examples/emplace_back.cpp

@@ -0,0 +1,23 @@
+#include <json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create JSON values
+    json array = {1, 2, 3, 4, 5};
+    json null;
+
+    // print values
+    std::cout << array << '\n';
+    std::cout << null << '\n';
+
+    // add values
+    array.emplace_back(6);
+    null.emplace_back("first");
+    null.emplace_back(3, "second");
+
+    // print values
+    std::cout << array << '\n';
+    std::cout << null << '\n';
+}

doc/examples/emplace_back.link

@@ -0,0 +1 @@
+<a target="_blank" href="http://melpon.org/wandbox/permlink/jdch45YEMX94DvlH"><b>online</b></a>

doc/examples/emplace_back.output

@@ -0,0 +1,4 @@
+[1,2,3,4,5]
+null
+[1,2,3,4,5,6]
+["first",["second","second","second"]]

doc/index.md

@@ -197,7 +197,7 @@ The container functions known from STL have been extended to support the differe
     <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `0`)</td>
   </tr>
   <tr>
-    <td rowspan="5">modifiers</td>
+    <td rowspan="6">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>
@@ -233,6 +233,15 @@ The container functions known from STL have been extended to support the differe
     <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>`emplace` / `emplace_back`</td>
+    <td class="ok_green">@link nlohmann::basic_json::emplace() `emplace` @endlink</td>
+    <td class="ok_green">@link nlohmann::basic_json::emplace_back() `emplace_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::emplace() `emplace` @endlink (creates object)<br>@link nlohmann::basic_json::emplace_back() `emplace_back` @endlink (creates array)</td>
+  </tr>
   <tr>
     <td>`swap`</td>
     <td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>