From 0de7ba9b2c03d20c2afd4b6e352a848828617568 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 13 Oct 2021 22:03:34 +0200 Subject: [PATCH] :fire: consolidate documentation --- doc/mkdocs/docs/api/basic_json/insert.md | 20 ++-- include/nlohmann/json.hpp | 139 ++--------------------- single_include/nlohmann/json.hpp | 139 ++--------------------- 3 files changed, 34 insertions(+), 264 deletions(-) diff --git a/doc/mkdocs/docs/api/basic_json/insert.md b/doc/mkdocs/docs/api/basic_json/insert.md index fbd466852..5bd8ff1a3 100644 --- a/doc/mkdocs/docs/api/basic_json/insert.md +++ b/doc/mkdocs/docs/api/basic_json/insert.md @@ -18,11 +18,11 @@ iterator insert(const_iterator pos, initializer_list_t ilist); void insert(const_iterator first, const_iterator last); ``` -1. Inserts element `val` to array before iterator `pos`. -2. Inserts `cnt` copies of `val` to array before iterator `pos`. -3. Inserts elements from range `[first, last)` to array before iterator `pos`. -4. Inserts elements from initializer list `ilist` to array before iterator `pos`. -5. Inserts elements from range `[first, last)` to object. +1. Inserts element `val` into array before iterator `pos`. +2. Inserts `cnt` copies of `val` into array before iterator `pos`. +3. Inserts elements from range `[first, last)` into array before iterator `pos`. +4. Inserts elements from initializer list `ilist` into array before iterator `pos`. +5. Inserts elements from range `[first, last)` into object. ## Parameters @@ -100,7 +100,7 @@ Strong exception safety: if an exception occurs, the original value stays intact ## Example -??? example +??? example "Example (1): insert element into array" The example shows how `insert()` is used. @@ -114,7 +114,7 @@ Strong exception safety: if an exception occurs, the original value stays intact --8<-- "examples/insert.output" ``` -??? example +??? example "Example (2): insert copies of element into array" The example shows how `insert()` is used. @@ -128,7 +128,7 @@ Strong exception safety: if an exception occurs, the original value stays intact --8<-- "examples/insert__count.output" ``` -??? example +??? example "Example (3): insert range of elements into array" The example shows how `insert()` is used. @@ -142,7 +142,7 @@ Strong exception safety: if an exception occurs, the original value stays intact --8<-- "examples/insert__range.output" ``` -??? example +??? example "Example (4): insert elements from initializer list into array" The example shows how `insert()` is used. @@ -156,7 +156,7 @@ Strong exception safety: if an exception occurs, the original value stays intact --8<-- "examples/insert__ilist.output" ``` -??? example +??? example "Example (5): insert range of elements into object" The example shows how `insert()` is used. diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index bc91611d0..14817165a 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -3638,28 +3638,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return result; } - /*! - @brief inserts element - - Inserts element @a val before iterator @a pos. - - @param[in] pos iterator before which the content will be inserted; may be - the end() iterator - @param[in] val element to insert - @return iterator pointing to the inserted @a val. - - @throw type_error.309 if called on JSON values other than arrays; - example: `"cannot use insert() with string"` - @throw invalid_iterator.202 if @a pos is not an iterator of *this; - example: `"iterator does not fit current value"` - - @complexity Constant plus linear in the distance between @a pos and end of - the container. - - @liveexample{The example shows how `insert()` is used.,insert} - - @since version 1.0.0 - */ + /// @brief inserts element into array + /// @sa https://json.nlohmann.me/api/basic_json/insert/ iterator insert(const_iterator pos, const basic_json& val) { // insert only works for arrays @@ -3678,39 +3658,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec JSON_THROW(type_error::create(309, "cannot use insert() with " + std::string(type_name()), *this)); } - /*! - @brief inserts element - @copydoc insert(const_iterator, const basic_json&) - */ + /// @brief inserts element into array + /// @sa https://json.nlohmann.me/api/basic_json/insert/ iterator insert(const_iterator pos, basic_json&& val) { return insert(pos, val); } - /*! - @brief inserts elements - - Inserts @a cnt copies of @a val before iterator @a pos. - - @param[in] pos iterator before which the content will be inserted; may be - the end() iterator - @param[in] cnt number of copies of @a val to insert - @param[in] val element to insert - @return iterator pointing to the first element inserted, or @a pos if - `cnt==0` - - @throw type_error.309 if called on JSON values other than arrays; example: - `"cannot use insert() with string"` - @throw invalid_iterator.202 if @a pos is not an iterator of *this; - example: `"iterator does not fit current value"` - - @complexity Linear in @a cnt plus linear in the distance between @a pos - and end of the container. - - @liveexample{The example shows how `insert()` is used.,insert__count} - - @since version 1.0.0 - */ + /// @brief inserts copies of element into array + /// @sa https://json.nlohmann.me/api/basic_json/insert/ iterator insert(const_iterator pos, size_type cnt, const basic_json& val) { // insert only works for arrays @@ -3729,36 +3685,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec JSON_THROW(type_error::create(309, "cannot use insert() with " + std::string(type_name()), *this)); } - /*! - @brief inserts elements - - Inserts elements from range `[first, last)` before iterator @a pos. - - @param[in] pos iterator before which the content will be inserted; may be - the end() iterator - @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.309 if called on JSON values other than arrays; example: - `"cannot use insert() with string"` - @throw invalid_iterator.202 if @a pos is not an iterator of *this; - example: `"iterator does not fit current value"` - @throw invalid_iterator.210 if @a first and @a last do not belong to the - same JSON value; example: `"iterators do not fit"` - @throw invalid_iterator.211 if @a first or @a last are iterators into - container for which insert is called; example: `"passed iterators may not - belong to container"` - - @return iterator pointing to the first element inserted, or @a pos if - `first==last` - - @complexity Linear in `std::distance(first, last)` plus linear in the - distance between @a pos and end of the container. - - @liveexample{The example shows how `insert()` is used.,insert__range} - - @since version 1.0.0 - */ + /// @brief inserts range of elements into array + /// @sa https://json.nlohmann.me/api/basic_json/insert/ iterator insert(const_iterator pos, const_iterator first, const_iterator last) { // insert only works for arrays @@ -3788,30 +3716,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return insert_iterator(pos, first.m_it.array_iterator, last.m_it.array_iterator); } - /*! - @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 type_error.309 if called on JSON values other than arrays; example: - `"cannot use insert() with string"` - @throw invalid_iterator.202 if @a pos is not an iterator of *this; - example: `"iterator does not fit current value"` - - @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} - - @since version 1.0.0 - */ + /// @brief inserts elements from initializer list into array + /// @sa https://json.nlohmann.me/api/basic_json/insert/ iterator insert(const_iterator pos, initializer_list_t ilist) { // insert only works for arrays @@ -3830,29 +3736,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return insert_iterator(pos, ilist.begin(), ilist.end()); } - /*! - @brief inserts elements - - Inserts elements from range `[first, last)`. - - @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.309 if called on JSON values other than objects; example: - `"cannot use insert() 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 Logarithmic: `O(N*log(size() + N))`, where `N` is the number - of elements to insert. - - @liveexample{The example shows how `insert()` is used.,insert__range_object} - - @since version 3.0.0 - */ + /// @brief inserts range of elements into object + /// @sa https://json.nlohmann.me/api/basic_json/insert/ void insert(const_iterator first, const_iterator last) { // insert only works for objects diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 288260709..199f8e49e 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -21125,28 +21125,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return result; } - /*! - @brief inserts element - - Inserts element @a val before iterator @a pos. - - @param[in] pos iterator before which the content will be inserted; may be - the end() iterator - @param[in] val element to insert - @return iterator pointing to the inserted @a val. - - @throw type_error.309 if called on JSON values other than arrays; - example: `"cannot use insert() with string"` - @throw invalid_iterator.202 if @a pos is not an iterator of *this; - example: `"iterator does not fit current value"` - - @complexity Constant plus linear in the distance between @a pos and end of - the container. - - @liveexample{The example shows how `insert()` is used.,insert} - - @since version 1.0.0 - */ + /// @brief inserts element into array + /// @sa https://json.nlohmann.me/api/basic_json/insert/ iterator insert(const_iterator pos, const basic_json& val) { // insert only works for arrays @@ -21165,39 +21145,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec JSON_THROW(type_error::create(309, "cannot use insert() with " + std::string(type_name()), *this)); } - /*! - @brief inserts element - @copydoc insert(const_iterator, const basic_json&) - */ + /// @brief inserts element into array + /// @sa https://json.nlohmann.me/api/basic_json/insert/ iterator insert(const_iterator pos, basic_json&& val) { return insert(pos, val); } - /*! - @brief inserts elements - - Inserts @a cnt copies of @a val before iterator @a pos. - - @param[in] pos iterator before which the content will be inserted; may be - the end() iterator - @param[in] cnt number of copies of @a val to insert - @param[in] val element to insert - @return iterator pointing to the first element inserted, or @a pos if - `cnt==0` - - @throw type_error.309 if called on JSON values other than arrays; example: - `"cannot use insert() with string"` - @throw invalid_iterator.202 if @a pos is not an iterator of *this; - example: `"iterator does not fit current value"` - - @complexity Linear in @a cnt plus linear in the distance between @a pos - and end of the container. - - @liveexample{The example shows how `insert()` is used.,insert__count} - - @since version 1.0.0 - */ + /// @brief inserts copies of element into array + /// @sa https://json.nlohmann.me/api/basic_json/insert/ iterator insert(const_iterator pos, size_type cnt, const basic_json& val) { // insert only works for arrays @@ -21216,36 +21172,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec JSON_THROW(type_error::create(309, "cannot use insert() with " + std::string(type_name()), *this)); } - /*! - @brief inserts elements - - Inserts elements from range `[first, last)` before iterator @a pos. - - @param[in] pos iterator before which the content will be inserted; may be - the end() iterator - @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.309 if called on JSON values other than arrays; example: - `"cannot use insert() with string"` - @throw invalid_iterator.202 if @a pos is not an iterator of *this; - example: `"iterator does not fit current value"` - @throw invalid_iterator.210 if @a first and @a last do not belong to the - same JSON value; example: `"iterators do not fit"` - @throw invalid_iterator.211 if @a first or @a last are iterators into - container for which insert is called; example: `"passed iterators may not - belong to container"` - - @return iterator pointing to the first element inserted, or @a pos if - `first==last` - - @complexity Linear in `std::distance(first, last)` plus linear in the - distance between @a pos and end of the container. - - @liveexample{The example shows how `insert()` is used.,insert__range} - - @since version 1.0.0 - */ + /// @brief inserts range of elements into array + /// @sa https://json.nlohmann.me/api/basic_json/insert/ iterator insert(const_iterator pos, const_iterator first, const_iterator last) { // insert only works for arrays @@ -21275,30 +21203,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return insert_iterator(pos, first.m_it.array_iterator, last.m_it.array_iterator); } - /*! - @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 type_error.309 if called on JSON values other than arrays; example: - `"cannot use insert() with string"` - @throw invalid_iterator.202 if @a pos is not an iterator of *this; - example: `"iterator does not fit current value"` - - @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} - - @since version 1.0.0 - */ + /// @brief inserts elements from initializer list into array + /// @sa https://json.nlohmann.me/api/basic_json/insert/ iterator insert(const_iterator pos, initializer_list_t ilist) { // insert only works for arrays @@ -21317,29 +21223,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return insert_iterator(pos, ilist.begin(), ilist.end()); } - /*! - @brief inserts elements - - Inserts elements from range `[first, last)`. - - @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.309 if called on JSON values other than objects; example: - `"cannot use insert() 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 Logarithmic: `O(N*log(size() + N))`, where `N` is the number - of elements to insert. - - @liveexample{The example shows how `insert()` is used.,insert__range_object} - - @since version 3.0.0 - */ + /// @brief inserts range of elements into object + /// @sa https://json.nlohmann.me/api/basic_json/insert/ void insert(const_iterator first, const_iterator last) { // insert only works for objects