Add operator<<(json_pointer) (#3601)

* Add operator<< for json_pointer

* Deprecate json_pointer::operator string_t()

* Update documentation

* Move operator<<(basic_json) example

* Add example

* Add mkdocs-redirects

* Move operator<< and operator>> doc pages out of basic_json/

* Rename JSON pointer operator_string to operator_string_t

* Add unit test

docs/mkdocs/docs/api/basic_json/accept.md

@@ -96,7 +96,7 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
 ## See also
 
 - [parse](parse.md) - deserialize from a compatible input
-- [operator>>](operator_gtgt.md) - deserialize from stream
+- [operator>>](../operator_gtgt.md) - deserialize from stream
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/index.md

@@ -283,8 +283,8 @@ Access to the JSON value
 
 ## Non-member functions
 
-- [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream
-- [**operator>>(std::istream&)**](operator_gtgt.md) - deserialize from stream
+- [**operator<<(std::ostream&)**](../operator_ltlt.md) - serialize to stream
+- [**operator>>(std::istream&)**](../operator_gtgt.md) - deserialize from stream
 - [**to_string**](to_string.md) - user-defined `to_string` function for JSON values
 
 ## Literals

docs/mkdocs/docs/api/basic_json/operator_ltlt.md

@@ -1,62 +0,0 @@
-# operator<<(basic_json)
-
-```cpp
-std::ostream& operator<<(std::ostream& o, const basic_json& j);
-```
-
-Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the
-[`dump`](dump.md) member function.
-
-- The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For
-  instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4` and the serialization result
-  is the same as calling `dump(4)`.
-- The indentation character can be controlled with the member variable `fill` of the output stream `o`. For instance,
-  the manipulator `std::setfill('\\t')` sets indentation to use a tab character rather than the default space character.
-
-## Parameters
-
-`o` (in, out)
-:   stream to serialize to
-
-`j` (in)
-:   JSON value to serialize
-
-## Return value
-
-the stream `o`
-
-## Exceptions
-
-Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
-is not UTF-8 encoded. Note that unlike the [`dump`](dump.md) member functions, no `error_handler` can be set.
-
-## Complexity
-
-Linear.
-
-## Examples
-
-??? example
-
-    The example below shows the serialization with different parameters to `width` to adjust the indentation level.
-        
-    ```cpp
-    --8<-- "examples/operator_serialize.cpp"
-    ```
-    
-    Output:
-    
-    ```json
-    --8<-- "examples/operator_serialize.output"
-    ```
-
-## Version history
-
-- Added in version 1.0.0
-- Support for indentation character added in version 3.0.0.
-
-!!! warning "Deprecation"
-
-    This function replaces function `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` which has
-    been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j >> o;`
-    with `#!cpp o << j;`.

docs/mkdocs/docs/api/basic_json/parse.md

@@ -196,7 +196,7 @@ super-linear complexity.
 ## See also
 
 - [accept](accept.md) - check if the input is valid JSON
-- [operator>>](operator_gtgt.md) - deserialize from stream
+- [operator>>](../operator_gtgt.md) - deserialize from stream
 
 ## Version history
 

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

@@ -28,7 +28,7 @@ are the base for JSON patches.
 
 - [(constructor)](json_pointer.md)
 - [**to_string**](to_string.md) - return a string representation of the JSON pointer
-- [**operator string_t**](operator_string.md) - return a string representation of the JSON pointer
+- [**operator string_t**](operator_string_t.md) - return a string representation of the JSON pointer
 - [**operator/=**](operator_slasheq.md) - append to the end of the JSON pointer
 - [**operator/**](operator_slash.md) - create JSON Pointer by appending
 - [**parent_pointer**](parent_pointer.md) - returns the parent of this JSON pointer

docs/mkdocs/docs/api/json_pointer/operator_string_t.md

@@ -19,6 +19,13 @@ operator string_t() const
 }
 ```
 
+## Notes
+
+!!! warning "Deprecation"
+
+    This function is deprecated in favor of [`to_string`](to_string.md) and will be removed in a future major version
+    release.
+
 ## Examples
 
 ??? example
@@ -26,16 +33,16 @@ operator string_t() const
     The example shows how JSON Pointers can be implicitly converted to strings.
      
     ```cpp
-    --8<-- "examples/json_pointer__operator_string.cpp"
+    --8<-- "examples/json_pointer__operator_string_t.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/json_pointer__operator_string.output"
+    --8<-- "examples/json_pointer__operator_string_t.output"
     ```
 
 ## Version history
 
 - Since version 2.0.0.
-- Changed type to `string_t` in version 3.11.0.
+- Changed type to `string_t` and deprecated in version 3.11.0.

docs/mkdocs/docs/api/operator_gtgt.md

@@ -1,4 +1,4 @@
-# operator>>(basic_json)
+# <small>nlohmann::</small>operator>>(basic_json)
 
 ```cpp
 std::istream& operator>>(std::istream& i, basic_json& j);
@@ -20,10 +20,10 @@ the stream `i`
 
 ## Exceptions
 
-- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
-- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate 
+- Throws [`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
+- Throws [`parse_error.102`](../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate 
   error.
-- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
+- Throws [`parse_error.103`](../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
 
 ## Complexity
 
@@ -33,6 +33,12 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
 
 A UTF-8 byte order mark is silently ignored.
 
+!!! warning "Deprecation"
+
+    This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has
+    been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;`
+    with `#!cpp i >> j;`.
+
 ## Examples
 
 ??? example
@@ -51,15 +57,9 @@ A UTF-8 byte order mark is silently ignored.
 
 ## See also
 
-- [accept](accept.md) - check if the input is valid JSON
-- [parse](parse.md) - deserialize from a compatible input
+- [accept](basic_json/accept.md) - check if the input is valid JSON
+- [parse](basic_json/parse.md) - deserialize from a compatible input
 
 ## Version history
 
-- Added in version 1.0.0
-
-!!! warning "Deprecation"
-
-    This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has
-    been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;`
-    with `#!cpp i >> j;`.
+- Added in version 1.0.0. Deprecated in version 3.0.0.

docs/mkdocs/docs/api/operator_ltlt.md

@@ -0,0 +1,86 @@
+# <small>nlohmann::</small>operator<<(basic_json), <small>nlohmann::</small>operator<<(json_pointer)
+
+```cpp
+std::ostream& operator<<(std::ostream& o, const basic_json& j);      // (1)
+
+std::ostream& operator<<(std::ostream& o, const json_pointer& ptr);  // (2)
+```
+
+1. Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the
+   [`dump`](basic_json/dump.md) member function.
+    - The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For
+      instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4` and the serialization
+      result is the same as calling `dump(4)`.
+    - The indentation character can be controlled with the member variable `fill` of the output stream `o`.
+      For instance, the manipulator `std::setfill('\\t')` sets indentation to use a tab character rather than the
+      default space character.
+2. Write a string representation of the given JSON pointer `ptr` to the output stream `o`. The string representation is
+   obtained using the [`to_string`](json_pointer/to_string.md) member function.
+
+## Parameters
+
+`o` (in, out)
+:   stream to write to
+
+`j` (in)
+:   JSON value to serialize
+
+`ptr` (in)
+:   JSON pointer to write
+
+## Return value
+
+the stream `o`
+
+## Exceptions
+
+1. Throws [`type_error.316`](../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON
+   value is not UTF-8 encoded. Note that unlike the [`dump`](basic_json/dump.md) member functions, no `error_handler` can be set.
+2. None.
+
+## Complexity
+
+Linear.
+
+## Notes
+
+!!! warning "Deprecation"
+
+    Function  `#!cpp std::ostream& operator<<(std::ostream& o, const basic_json& j)` replaces function
+    `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` which has been deprecated in version 3.0.0.
+    It will be removed in version 4.0.0. Please replace calls like `#!cpp j >> o;` with `#!cpp o << j;`.
+
+## Examples
+
+??? example "Example: (1) serialize JSON value to stream"
+
+    The example below shows the serialization with different parameters to `width` to adjust the indentation level.
+    
+    ```cpp
+    --8<-- "examples/operator_ltlt__basic_json.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_ltlt__basic_json.output"
+    ```
+
+??? example "Example: (2) write JSON pointer to stream"
+
+    The example below shows how to write a JSON pointer to a stream.
+    
+    ```cpp
+    --8<-- "examples/operator_ltlt__json_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_ltlt__json_pointer.output"
+    ```
+## Version history
+
+1. Added in version 1.0.0. Added support for indentation character and deprecated
+   `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` in version 3.0.0.
+3. Added in version 3.11.0.