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