Update json_pointer docs

nlohmann · Apr 6, 2022 · efa7982 · efa7982
1 parent ef8d796
commit efa7982
Show file tree

Hide file tree

Showing 10 changed files with 53 additions and 22 deletions.
diff --git a/doc/mkdocs/docs/api/json_pointer/back.md b/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.10.6.
diff --git a/doc/mkdocs/docs/api/json_pointer/index.md b/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,11 +31,16 @@ 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
 - [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
 
 ## 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.10.6.
diff --git a/doc/mkdocs/docs/api/json_pointer/json_pointer.md b/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.10.6.
diff --git a/doc/mkdocs/docs/api/json_pointer/operator_slash.md b/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.10.6.
 3. Added in version 3.6.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/operator_slasheq.md b/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.10.6.
 3. Added in version 3.6.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/operator_string.md b/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,12 +13,13 @@ A string representation of the JSON pointer
 ## Possible implementation
 
 ```cpp
-operator std::string() const
+operator string_t() const
 {
     return to_string();
 }
 ```
 
 ## Version history
 
-Since version 2.0.0.
+- Since version 2.0.0.
+- Changed type to `string_t`.
diff --git a/doc/mkdocs/docs/api/json_pointer/push_back.md b/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.10.6.
diff --git a/doc/mkdocs/docs/api/json_pointer/string_t.md b/doc/mkdocs/docs/api/json_pointer/string_t.md
@@ -0,0 +1,16 @@
+# <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.
+
+## Notes
+
+When used for array access an equivalent function to `std::stoull` compatible with `string_t` must be findable by argument-dependent lookup (ADL).
+
+See [`basic_json::string_t`](../basic_json/string_t.md) for more information.
+
+## Version history
+
+- Added in version 3.10.6.
diff --git a/doc/mkdocs/docs/api/json_pointer/to_string.md b/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.10.6.
diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml
@@ -211,6 +211,7 @@ nav:
         - 'parent_pointer': api/json_pointer/parent_pointer.md
         - 'pop_back': api/json_pointer/pop_back.md
         - 'push_back': api/json_pointer/push_back.md
+        - 'string_t': api/json_pointer/string_t.md
         - 'to_string': api/json_pointer/to_string.md
       - json_sax:
         - 'Overview': api/json_sax/index.md