Add front methods to json_pointers (implements #4889) (#5152)

* Added front, pop_front, and push_front methods to json_pointers in order to facilitate root-to-leaf traversals of JSON object trees. (#4889)

Signed-off-by: trdesilva <5818730+trdesilva@users.noreply.github.com>

* undid VS autoformatting in irrelevant code

Signed-off-by: trdesilva <5818730+trdesilva@users.noreply.github.com>

* Ran make amalgamate, added navigation to json_pointer's new front methods in mkdocs, and fixed errors in documented complexity for those methods.

Signed-off-by: trdesilva <5818730+trdesilva@users.noreply.github.com>

* Fixed GCC 4.8 compile error caused by const iterators

Signed-off-by: trdesilva <5818730+trdesilva@users.noreply.github.com>

* Fixed another gcc-4.8 compile error

Signed-off-by: trdesilva <5818730+trdesilva@users.noreply.github.com>

* amalgamated

Signed-off-by: trdesilva <5818730+trdesilva@users.noreply.github.com>

---------

Signed-off-by: trdesilva <5818730+trdesilva@users.noreply.github.com>

docs/mkdocs/docs/api/json_pointer/front.md

@@ -0,0 +1,37 @@
+# <small>nlohmann::json_pointer::</small>front
+
+```cpp
+const string_t& front() const;
+```
+
+Return the first reference token.
+
+## Return value
+
+First reference token.
+
+## Exceptions
+
+Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if the JSON pointer has no parent.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example shows the usage of `front`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__front.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__front.output"
+    ```
+
+## Version history

docs/mkdocs/docs/api/json_pointer/index.md

@@ -37,6 +37,9 @@ are the base for JSON patches.
 - [**pop_back**](pop_back.md) - remove the last reference token
 - [**back**](back.md) - return last reference token
 - [**push_back**](push_back.md) - append an unescaped token at the end of the pointer
+- [**pop_front**](pop_front.md) - remove the first reference token
+- [**front**](front.md) - return first reference token
+- [**push_front**](push_front.md) - append an unescaped token at the start of the pointer
 - [**empty**](empty.md) - return whether the pointer points to the root document
 
 ## Literals

docs/mkdocs/docs/api/json_pointer/pop_front.md

@@ -0,0 +1,33 @@
+# <small>nlohmann::json_pointer::</small>pop_front
+
+```cpp
+void pop_front();
+```
+
+Remove the first reference token.
+
+## Exceptions
+
+Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if the JSON pointer has no parent.
+
+## Complexity
+
+Linear in the number of reference tokens in the `json_pointer`.
+
+## Examples
+
+??? example
+
+    The example shows the usage of `pop_front`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__pop_front.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__pop_front.output"
+    ```
+
+## Version history

docs/mkdocs/docs/api/json_pointer/push_front.md

@@ -0,0 +1,36 @@
+# <small>nlohmann::json_pointer::</small>push_front
+
+```cpp
+void push_front(const string_t& token);
+
+void push_front(string_t&& token);
+```
+
+Append an unescaped token at the start of the reference pointer.
+
+## Parameters
+
+`token` (in)
+:   token to add
+
+## Complexity
+
+Linear in the number of reference tokens in the `json_pointer`.
+
+## Examples
+
+??? example
+
+    The example shows the result of `push_front` for different JSON Pointers.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__push_front.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__push_front.output"
+    ```
+
+## Version history

docs/mkdocs/docs/examples/json_pointer__front.cpp

@@ -0,0 +1,15 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // different JSON Pointers
+    json::json_pointer ptr1("/foo");
+    json::json_pointer ptr2("/foo/0");
+
+    // call empty()
+    std::cout << "first reference token of \"" << ptr1 << "\" is \"" << ptr1.front() << "\"\n"
+              << "first reference token of \"" << ptr2 << "\" is \"" << ptr2.front() << "\"" << std::endl;
+}

docs/mkdocs/docs/examples/json_pointer__front.output

@@ -0,0 +1,2 @@
+first reference token of "/foo" is "foo"
+first reference token of "/foo/0" is "foo"

docs/mkdocs/docs/examples/json_pointer__pop_front.cpp

@@ -0,0 +1,21 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create empty JSON Pointer
+    json::json_pointer ptr("/foo/bar/baz");
+    std::cout << "\"" << ptr << "\"\n";
+
+    // call pop_front()
+    ptr.pop_front();
+    std::cout << "\"" << ptr << "\"\n";
+
+    ptr.pop_front();
+    std::cout << "\"" << ptr << "\"\n";
+
+    ptr.pop_front();
+    std::cout << "\"" << ptr << "\"\n";
+}

docs/mkdocs/docs/examples/json_pointer__pop_front.output

@@ -0,0 +1,4 @@
+"/foo/bar/baz"
+"/bar/baz"
+"/baz"
+""

docs/mkdocs/docs/examples/json_pointer__push_front.cpp

@@ -0,0 +1,21 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create empty JSON Pointer
+    json::json_pointer ptr;
+    std::cout << "\"" << ptr << "\"\n";
+
+    // call push_front()
+    ptr.push_front("foo");
+    std::cout << "\"" << ptr << "\"\n";
+
+    ptr.push_front("0");
+    std::cout << "\"" << ptr << "\"\n";
+
+    ptr.push_front("bar");
+    std::cout << "\"" << ptr << "\"\n";
+}

docs/mkdocs/docs/examples/json_pointer__push_front.output

@@ -0,0 +1,4 @@
+""
+"/foo"
+"/0/foo"
+"/bar/0/foo"

docs/mkdocs/mkdocs.yml

@@ -233,6 +233,7 @@ nav:
           - '(Constructor)': api/json_pointer/json_pointer.md
           - 'back': api/json_pointer/back.md
           - 'empty': api/json_pointer/empty.md
+          - 'front': api/json_pointer/front.md
           - 'operator string_t': api/json_pointer/operator_string_t.md
           - 'operator==': api/json_pointer/operator_eq.md
           - 'operator!=': api/json_pointer/operator_ne.md
@@ -240,7 +241,9 @@ nav:
           - 'operator/=': api/json_pointer/operator_slasheq.md
           - 'parent_pointer': api/json_pointer/parent_pointer.md
           - 'pop_back': api/json_pointer/pop_back.md
+          - 'pop_front': api/json_pointer/pop_front.md
           - 'push_back': api/json_pointer/push_back.md
+          - 'push_front': api/json_pointer/push_front.md
           - 'string_t': api/json_pointer/string_t.md
           - 'to_string': api/json_pointer/to_string.md
       - json_sax:

include/nlohmann/detail/json_pointer.hpp

@@ -154,6 +154,44 @@ class json_pointer
         return res;
     }
 
+    /// @brief remove first reference token
+    /// @sa https://json.nlohmann.me/api/json_pointer/pop_front/
+    void pop_front()
+    {
+        if (JSON_HEDLEY_UNLIKELY(empty()))
+        {
+            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent", nullptr));
+        }
+
+        reference_tokens.erase(reference_tokens.begin());
+    }
+
+    /// @brief return first reference token
+    /// @sa https://json.nlohmann.me/api/json_pointer/front/
+    const string_t& front() const
+    {
+        if (JSON_HEDLEY_UNLIKELY(empty()))
+        {
+            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent", nullptr));
+        }
+
+        return reference_tokens.front();
+    }
+
+    /// @brief append an unescaped token at the start of the reference pointer
+    /// @sa https://json.nlohmann.me/api/json_pointer/push_front/
+    void push_front(const string_t& token)
+    {
+        reference_tokens.insert(reference_tokens.begin(), token);
+    }
+
+    /// @brief append an unescaped token at the start of the reference pointer
+    /// @sa https://json.nlohmann.me/api/json_pointer/push_front/
+    void push_front(string_t&& token)
+    {
+        reference_tokens.insert(reference_tokens.begin(), std::move(token));
+    }
+
     /// @brief remove last reference token
     /// @sa https://json.nlohmann.me/api/json_pointer/pop_back/
     void pop_back()

single_include/nlohmann/json.hpp

@@ -14872,6 +14872,44 @@ class json_pointer
         return res;
     }
 
+    /// @brief remove first reference token
+    /// @sa https://json.nlohmann.me/api/json_pointer/pop_front/
+    void pop_front()
+    {
+        if (JSON_HEDLEY_UNLIKELY(empty()))
+        {
+            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent", nullptr));
+        }
+
+        reference_tokens.erase(reference_tokens.begin());
+    }
+
+    /// @brief return first reference token
+    /// @sa https://json.nlohmann.me/api/json_pointer/front/
+    const string_t& front() const
+    {
+        if (JSON_HEDLEY_UNLIKELY(empty()))
+        {
+            JSON_THROW(detail::out_of_range::create(405, "JSON pointer has no parent", nullptr));
+        }
+
+        return reference_tokens.front();
+    }
+
+    /// @brief append an unescaped token at the start of the reference pointer
+    /// @sa https://json.nlohmann.me/api/json_pointer/push_front/
+    void push_front(const string_t& token)
+    {
+        reference_tokens.insert(reference_tokens.begin(), token);
+    }
+
+    /// @brief append an unescaped token at the start of the reference pointer
+    /// @sa https://json.nlohmann.me/api/json_pointer/push_front/
+    void push_front(string_t&& token)
+    {
+        reference_tokens.insert(reference_tokens.begin(), std::move(token));
+    }
+
     /// @brief remove last reference token
     /// @sa https://json.nlohmann.me/api/json_pointer/pop_back/
     void pop_back()

tests/src/unit-json_pointer.cpp

@@ -564,6 +564,14 @@ TEST_CASE("JSON pointers")
         CHECK(!ptr.empty());
         CHECK(j[ptr] == j["answer"]["everything"]);
 
+        ptr.pop_front();
+        CHECK(ptr.front() == "everything");
+        ptr.pop_front();
+        CHECK(ptr.empty());
+        ptr.push_front("everything");
+        ptr.push_front(answer);
+        CHECK(j[ptr] == j["answer"]["everything"]);
+
         // check access via const pointer
         const auto cptr = ptr;
         CHECK(cptr.back() == "everything");
@@ -588,8 +596,17 @@ TEST_CASE("JSON pointers")
         CHECK(ptr.empty());
         CHECK(j[ptr] == j);
 
-        CHECK_THROWS_WITH(ptr.pop_back(),
-                          "[json.exception.out_of_range.405] JSON pointer has no parent");
+        CHECK_THROWS_WITH_AS(ptr.pop_back(),
+                             "[json.exception.out_of_range.405] JSON pointer has no parent", json::out_of_range&);
+
+        CHECK_THROWS_WITH_AS(ptr.back(),
+                             "[json.exception.out_of_range.405] JSON pointer has no parent", json::out_of_range&);
+
+        CHECK_THROWS_WITH_AS(ptr.pop_front(),
+                             "[json.exception.out_of_range.405] JSON pointer has no parent", json::out_of_range&);
+
+        CHECK_THROWS_WITH_AS(ptr.front(),
+                             "[json.exception.out_of_range.405] JSON pointer has no parent", json::out_of_range&);
     }
 
     SECTION("operators")