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>

Author: trdesilva

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"