Re-template json_pointer on string type (#3415)

* Make exception context optional

Change exception context parameter to pointer and replace context with
nullptr where appropriate.

* Support escaping other string types

* Add string concatenation function

Add variadic concat() function for concatenating char *, char, and
string types.

* Replace string concatenations using + with concat()

* Template json_pointer on string type

Change json_pointer from being templated on basic_json to being
templated on string type.

* Add unit test for #3388

Closes #3388.

* Fix regression test for #2958

* Add backwards compatibility with json_pointer<basic_json>

* Update json_pointer docs

* Allow comparing different json_pointers

* Update version numbers

doc/mkdocs/docs/api/json_pointer/back.md

@@ -1,7 +1,7 @@
 # <small>nlohmann::json_pointer::</small>back
 
 ```cpp
-const std::string& back() const;
+const string_t& back() const;
 ```
 
 Return last reference token.
@@ -36,4 +36,5 @@ Constant.
 
 ## Version history
 
-Added in version 3.6.0.
+- Added in version 3.6.0.
+- Changed return type to `string_t` in version 3.11.0.

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

@@ -1,7 +1,7 @@
 # <small>nlohmann::</small>json_pointer
 
 ```cpp
-template<typename BasicJsonType>
+template<typename RefStringType>
 class json_pointer;
 ```
 
@@ -11,14 +11,18 @@ are the base for JSON patches.
 
 ## Template parameters
 
-`BasicJsonType`
-:   a specialization of [`basic_json`](../basic_json/index.md)
+`RefStringType`
+:   the string type used for the reference tokens making up the JSON pointer
+
+## Notes
+
+For backwards compatibility `RefStringType` may also be a specialization of [`basic_json`](../basic_json/index.md) in which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is deprecated and may be removed in a future major version.
 
 ## Member functions
 
 - [(constructor)](json_pointer.md)
 - [**to_string**](to_string.md) - return a string representation of the JSON pointer
-- [**operator std::string**](operator_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/=**](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
@@ -27,6 +31,10 @@ are the base for JSON patches.
 - [**push_back**](push_back.md) - append an unescaped token at the end of the pointer
 - [**empty**](empty.md) - return whether pointer points to the root document
 
+## Member types
+
+- [**string_t**](string_t.md) - the string type used for the reference tokens
+
 ## See also
 
 - [operator""_json_pointer](../basic_json/operator_literal_json_pointer.md) - user-defined string literal for JSON pointers
@@ -34,4 +42,5 @@ are the base for JSON patches.
 
 ## Version history
 
-Added in version 2.0.0.
+- Added in version 2.0.0.
+- Changed template parameter from `basic_json` to string type in version 3.11.0.

doc/mkdocs/docs/api/json_pointer/json_pointer.md

@@ -1,7 +1,7 @@
 # <small>nlohmann::json_pointer::</small>json_pointer
 
 ```cpp
-explicit json_pointer(const std::string& s = "");
+explicit json_pointer(const string_t& s = "");
 ```
 
 Create a JSON pointer according to the syntax described in
@@ -37,4 +37,5 @@ Create a JSON pointer according to the syntax described in
 
 ## Version history
 
-Added in version 2.0.0.
+- Added in version 2.0.0.
+- Changed type of `s` to `string_t` in version 3.11.0.

doc/mkdocs/docs/api/json_pointer/operator_slash.md

@@ -5,7 +5,7 @@
 json_pointer operator/(const json_pointer& lhs, const json_pointer& rhs);
 
 // (2)
-json_pointer operator/(const json_pointer& lhs, std::string token);
+json_pointer operator/(const json_pointer& lhs, string_t token);
 
 // (3)
 json_pointer operator/(const json_pointer& lhs, std::size_t array_idx);
@@ -60,5 +60,5 @@ json_pointer operator/(const json_pointer& lhs, std::size_t array_idx);
 ## Version history
 
 1. Added in version 3.6.0.
-2. Added in version 3.6.0.
+2. Added in version 3.6.0. Changed type of `token` to `string_t` in version 3.11.0.
 3. Added in version 3.6.0.

doc/mkdocs/docs/api/json_pointer/operator_slasheq.md

@@ -5,7 +5,7 @@
 json_pointer& operator/=(const json_pointer& ptr);
 
 // (2)
-json_pointer& operator/=(std::string token);
+json_pointer& operator/=(string_t token);
 
 // (3)
 json_pointer& operator/=(std::size_t array_idx)
@@ -57,5 +57,5 @@ json_pointer& operator/=(std::size_t array_idx)
 ## Version history
 
 1. Added in version 3.6.0.
-2. Added in version 3.6.0.
+2. Added in version 3.6.0. Changed type of `token` to `string_t` in version 3.11.0.
 3. Added in version 3.6.0.

doc/mkdocs/docs/api/json_pointer/operator_string.md

@@ -1,7 +1,7 @@
-# <small>nlohmann::json_pointer::</small>operator std::string
+# <small>nlohmann::json_pointer::</small>operator string_t
 
 ```cpp
-operator std::string() const
+operator string_t() const
 ```
 
 Return a string representation of the JSON pointer.
@@ -13,7 +13,7 @@ A string representation of the JSON pointer
 ## Possible implementation
 
 ```cpp
-operator std::string() const
+operator string_t() const
 {
     return to_string();
 }
@@ -21,4 +21,5 @@ operator std::string() const
 
 ## Version history
 
-Since version 2.0.0.
+- Since version 2.0.0.
+- Changed type to `string_t` in version 3.11.0.

doc/mkdocs/docs/api/json_pointer/push_back.md

@@ -1,9 +1,9 @@
 # <small>nlohmann::json_pointer::</small>push_back
 
 ```cpp
-void push_back(const std::string& token);
+void push_back(const string_t& token);
 
-void push_back(std::string&& token);
+void push_back(string_t&& token);
 ```
 
 Append an unescaped token at the end of the reference pointer.
@@ -35,4 +35,5 @@ Amortized constant.
 
 ## Version history
 
-Added in version 3.6.0.
+- Added in version 3.6.0.
+- Changed type of `token` to `string_t` in version 3.11.0.

doc/mkdocs/docs/api/json_pointer/string_t.md

@@ -0,0 +1,12 @@
+# <small>nlohmann::json_pointer::</small>string_t
+```cpp
+using string_t = RefStringType;
+```
+
+The string type used for the reference tokens making up the JSON pointer.
+
+See [`basic_json::string_t`](../basic_json/string_t.md) for more information.
+
+## Version history
+
+- Added in version 3.11.0.

doc/mkdocs/docs/api/json_pointer/to_string.md

@@ -1,7 +1,7 @@
 # <small>nlohmann::json_pointer::</small>to_string
 
 ```cpp
-std::string to_string() const;
+string_t to_string() const;
 ```
 
 Return a string representation of the JSON pointer.
@@ -36,4 +36,5 @@ ptr == json_pointer(ptr.to_string());
 
 ## Version history
 
-Since version 2.0.0.
+- Since version 2.0.0.
+- Changed return type to `string_t` in version 3.11.0.