added another insert function

doc/examples/insert__ilist.cpp

+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create a JSON array
+    json v = {1, 2, 3, 4};
+
+    // insert range from v2 before the end of array v
+    auto new_pos = v.insert(v.end(), {7, 8, 9});
+
+    // output new array and result of insert call
+    std::cout << *new_pos << '\n';
+    std::cout << v << '\n';
+}

doc/examples/insert__ilist.link

+<a target="_blank" href="http://melpon.org/wandbox/permlink/ciOQKs1KoHMSAWN3"><b>online</b></a>
\ No newline at end of file

doc/examples/insert__ilist.output

+7
+[1,2,3,4,7,8,9]

src/json.hpp

@@ -3877,6 +3877,45 @@ class basic_json
     }
 
     /*!
+    @brief inserts elements
+
+    Inserts elements from initializer list @a ilist before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] ilist initializer list to insert the values from
+
+    @throw std::domain_error if called on JSON values other than arrays
+    @throw std::domain_error if @a pos is not an iterator of *this
+    @return iterator pointing to the first element inserted, or @a pos if
+    `ilist` is empty
+
+    @complexity Linear in `ilist.size()` plus linear in the distance between @a
+    pos and end of the container.
+
+    @liveexample{The example shows how insert is used.,insert__ilist}
+    */
+    iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
+    {
+        // insert only works for arrays
+        if (m_type != value_t::array)
+        {
+            throw std::domain_error("cannot use insert() with " + type_name());
+        }
+
+        // check if iterator pos fits to this JSON value
+        if (pos.m_object != this)
+        {
+            throw std::domain_error("iterator does not fit current value");
+        }
+
+        // insert to array and return iterator
+        iterator result(this);
+        result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
+        return result;
+    }
+
+    /*!
     @brief exchanges the values
 
     Exchanges the contents of the JSON value with those of @a other. Does not

src/json.hpp.re2c

@@ -3877,6 +3877,45 @@ class basic_json
     }
 
     /*!
+    @brief inserts elements
+
+    Inserts elements from initializer list @a ilist before iterator @a pos.
+
+    @param[in] pos iterator before which the content will be inserted; may be
+    the end() iterator
+    @param[in] ilist initializer list to insert the values from
+
+    @throw std::domain_error if called on JSON values other than arrays
+    @throw std::domain_error if @a pos is not an iterator of *this
+    @return iterator pointing to the first element inserted, or @a pos if
+    `ilist` is empty
+
+    @complexity Linear in `ilist.size()` plus linear in the distance between @a
+    pos and end of the container.
+
+    @liveexample{The example shows how insert is used.,insert__ilist}
+    */
+    iterator insert(const_iterator pos, std::initializer_list<basic_json> ilist)
+    {
+        // insert only works for arrays
+        if (m_type != value_t::array)
+        {
+            throw std::domain_error("cannot use insert() with " + type_name());
+        }
+
+        // check if iterator pos fits to this JSON value
+        if (pos.m_object != this)
+        {
+            throw std::domain_error("iterator does not fit current value");
+        }
+
+        // insert to array and return iterator
+        iterator result(this);
+        result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, ilist);
+        return result;
+    }
+
+    /*!
     @brief exchanges the values
 
     Exchanges the contents of the JSON value with those of @a other. Does not

test/unit.cpp

@@ -6743,6 +6743,36 @@ TEST_CASE("modifiers")
             }
         }
 
+        SECTION("initializer list at position")
+        {
+            SECTION("insert before begin()")
+            {
+                auto it = j_array.insert(j_array.begin(), {7, 8, 9});
+                CHECK(j_array.size() == 7);
+                CHECK(*it == json(7));
+                CHECK(j_array.begin() == it);
+                CHECK(j_array == json({7, 8, 9, 1, 2, 3, 4}));
+            }
+
+            SECTION("insert in the middle")
+            {
+                auto it = j_array.insert(j_array.begin() + 2, {7, 8, 9});
+                CHECK(j_array.size() == 7);
+                CHECK(*it == json(7));
+                CHECK((it - j_array.begin()) == 2);
+                CHECK(j_array == json({1, 2, 7, 8, 9, 3, 4}));
+            }
+
+            SECTION("insert before end()")
+            {
+                auto it = j_array.insert(j_array.end(), {7, 8, 9});
+                CHECK(j_array.size() == 7);
+                CHECK(*it == json(7));
+                CHECK((j_array.end() - it) == 3);
+                CHECK(j_array == json({1, 2, 3, 4, 7, 8, 9}));
+            }
+        }
+
         SECTION("invalid iterator")
         {
             // pass iterator to a different array
@@ -6753,6 +6783,7 @@ TEST_CASE("modifiers")
             CHECK_THROWS_AS(j_array.insert(j_another_array.end(), 10, 11), std::domain_error);
             CHECK_THROWS_AS(j_array.insert(j_another_array.end(), j_yet_another_array.begin(),
                                            j_yet_another_array.end()), std::domain_error);
+            CHECK_THROWS_AS(j_array.insert(j_another_array.end(), {1, 2, 3, 4}), std::domain_error);
         }
 
         SECTION("non-array type")
@@ -6765,6 +6796,7 @@ TEST_CASE("modifiers")
             CHECK_THROWS_AS(j_nonarray.insert(j_nonarray.end(), 10, 11), std::domain_error);
             CHECK_THROWS_AS(j_nonarray.insert(j_nonarray.end(), j_yet_another_array.begin(),
                                               j_yet_another_array.end()), std::domain_error);
+            CHECK_THROWS_AS(j_nonarray.insert(j_nonarray.end(), {1, 2, 3, 4}), std::domain_error);
         }
     }