3 // Copyright (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip.
6 // in compliance with the License. You may obtain a copy of the License at
38 //! Represents a JSON Pointer. Use Pointer for UTF8 encoding and default allocator.
43     A JSON pointer is for identifying a specific value in a JSON document
47     After it parses a string representation (e.g. "/foo/0" or URI fragment
49     it can be used to resolve a specific value in multiple documents, or sub-tree
53     Apart from assignment, a Pointer cannot be modified after construction.
56     involves parsing and dynamic memory allocation. A special constructor with user-
75   //! A token is the basic units of internal representation.
77         A JSON pointer string representation "/foo/123" is parsed to two tokens:
85         This struct is public so that user can create a Pointer without parsing and
86         allocation, using a special constructor.
91 …  SizeType index;             //!< A valid array index, if it is not equal to kPointerInvalidIndex.
100     //! Constructor that parses a string or URI fragment representation.
102         \param source A null-terminated, string or URI fragment representation of JSON pointer.
103 …User supplied allocator for this pointer. If no allocator is provided, it creates a self-owned one.
110     //! Constructor that parses a string or URI fragment representation.
112         \param source A string or URI fragment representation of JSON pointer.
113 …User supplied allocator for this pointer. If no allocator is provided, it creates a self-owned one.
121 …//! Constructor that parses a string or URI fragment representation, with length of the source str…
123         \param source A string or URI fragment representation of JSON pointer.
125 …User supplied allocator for this pointer. If no allocator is provided, it creates a self-owned one.
214         void swap(MyClass& a, MyClass& b) {
216             swap(a.pointer, b.pointer);
222     friend inline void swap(GenericPointer& a, GenericPointer& b) RAPIDJSON_NOEXCEPT { a.Swap(b); }  in swap()  argument
229     //! Append a token and return a new Pointer
233         \return A new Pointer with appended token.
246     //! Append a name token with length, and return a new Pointer
251         \return A new Pointer with appended token.
258     //! Append a name token without length, and return a new Pointer
262         \return A new Pointer with appended token.
271     //! Append a name token, and return a new Pointer
275         \return A new Pointer with appended token.
282     //! Append a index token, and return a new Pointer
286         \return A new Pointer with appended token.
307     //! Append a token by value, and return a new Pointer
311         \return A new Pointer with appended token.
326     //! Check whether this is a valid pointer.
437     //! Create a value in a subtree.
439         If the value is not exist, it creates all parent values and a JSON Null value.
443         potentially removes previously stored values. For example, if a document
444         was an array, and "/foo" is used to create a value, then the document
447 …\param root Root value of a DOM subtree to be resolved. It can be any value other than document ro…
450         \return The resolved newly created (a JSON Null value), or already exists value.
501     //! Creates a value in a document.
503         \param document A document to be resolved.
517     //! Compute the in-scope URI for a subtree.
520 …\param root Root value of a DOM sub-tree to be resolved. It can be any value other than document r…
522 …\param unresolvedTokenIndex If the pointer cannot resolve a token in the pointer, this parameter c…
527         There are only 3 situations when a URI cannot be resolved:
528         1. A value in the path is neither an array nor object.
530         3. A token is out of range of an array value.
581     //! Query a value in a subtree.
583 …\param root Root value of a DOM sub-tree to be resolved. It can be any value other than document r…
584 …\param unresolvedTokenIndex If the pointer cannot resolve a token in the pointer, this parameter c…
588         There are only 3 situations when a value cannot be resolved:
589         1. A value in the path is neither an array nor object.
591         3. A token is out of range of an array value.
625     //! Query a const value in a const subtree.
627 …\param root Root value of a DOM sub-tree to be resolved. It can be any value other than document r…
636     //!@name Query a value with default
639     //! Query a value in a subtree with default value.
644 …\param root Root value of a DOM sub-tree to be resolved. It can be any value other than document r…
655     //! Query a value in a subtree with default null-terminated string.
663     //! Query a value in a subtree with default std::basic_string.
671     //! Query a value in a subtree with default primitive value.
681     //! Query a value in a document with default value.
687     //! Query a value in a document with default null-terminated string.
694     //! Query a value in a document with default std::basic_string.
701     //! Query a value in a document with default primitive value.
713     //!@name Set a value
716     //! Set a value in a subtree, with move semantics.
721 …\param root Root value of a DOM sub-tree to be resolved. It can be any value other than document r…
730     //! Set a value in a subtree, with copy semantics.
735     //! Set a null-terminated string in a subtree.
741     //! Set a std::basic_string in a subtree.
747     //! Set a primitive value in a subtree.
757     //! Set a value in a document, with move semantics.
763     //! Set a value in a document, with copy semantics.
769     //! Set a null-terminated string in a document.
776     //! Sets a std::basic_string in a document.
783     //! Set a primitive value in a document.
795     //!@name Swap a value
798     //! Swap a value with a value in a subtree.
803 …\param root Root value of a DOM sub-tree to be resolved. It can be any value other than document r…
812     //! Swap a value with a value in a document.
820     //! Erase a value in a subtree.
822 …\param root Root value of a DOM sub-tree to be resolved. It can be any value other than document r…
901     //! Check whether a character should be percent-encoded.
907 …return !((c >= '0' && c <= '9') || (c >= 'A' && c <='Z') || (c >= 'a' && c <= 'z') || c == '-' || …  in NeedPercentEncode()
910     //! Parse a JSON String or its URI fragment representation into tokens.
913 …\param source Either a JSON Pointer string, or its URI fragment representation. Not need to be nul…
937         // Detect if it is a URI fragment  in Parse()
1090     //! A helper stream for decoding a percent-encoded sequence into code unit.
1118                 else if (h >= 'A' && h <= 'F') c = static_cast<Ch>(c + h - 'A' + 10);  in Take()
1119                 else if (h >= 'a' && h <= 'f') c = static_cast<Ch>(c + h - 'a' + 10);  in Take()
1139     //! A helper stream to encode character (UTF-8 code unit) into percent-encoded sequence.
1146 …t char hexDigits[16] = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E'…  in Put()
1157     Ch* nameBuffer_;                        //!< A buffer containing all names in tokens.
1158     Token* tokens_;                         //!< A list of tokens.
1173 …nter(T& root, const GenericPointer<typename T::ValueType>& pointer, typename T::AllocatorType& a) {  in CreateValueByPointer()  argument
1174     return pointer.Create(root, a);  in CreateValueByPointer()
1178 …alueType& CreateValueByPointer(T& root, const CharType(&source)[N], typename T::AllocatorType& a) {  in CreateValueByPointer()  argument
1179     return GenericPointer<typename T::ValueType>(source, N - 1).Create(root, a);  in CreateValueByPointer()
1219 … T::ValueType>& pointer, const typename T::ValueType& defaultValue, typename T::AllocatorType& a) {  in GetValueByPointerWithDefault()  argument
1220     return pointer.GetWithDefault(root, defaultValue, a);  in GetValueByPointerWithDefault()
1224 …ypename T::ValueType>& pointer, const typename T::Ch* defaultValue, typename T::AllocatorType& a) {  in GetValueByPointerWithDefault()  argument
1225     return pointer.GetWithDefault(root, defaultValue, a);  in GetValueByPointerWithDefault()
1230 …e>& pointer, const std::basic_string<typename T::Ch>& defaultValue, typename T::AllocatorType& a) {  in GetValueByPointerWithDefault()  argument
1231     return pointer.GetWithDefault(root, defaultValue, a);  in GetValueByPointerWithDefault()
1237 …st GenericPointer<typename T::ValueType>& pointer, T2 defaultValue, typename T::AllocatorType& a) {  in GetValueByPointerWithDefault()  argument
1238     return pointer.GetWithDefault(root, defaultValue, a);  in GetValueByPointerWithDefault()
1242 …st CharType(&source)[N], const typename T::ValueType& defaultValue, typename T::AllocatorType& a) {  in GetValueByPointerWithDefault()  argument
1243 … return GenericPointer<typename T::ValueType>(source, N - 1).GetWithDefault(root, defaultValue, a);  in GetValueByPointerWithDefault()
1247 …ot, const CharType(&source)[N], const typename T::Ch* defaultValue, typename T::AllocatorType& a) {  in GetValueByPointerWithDefault()  argument
1248 … return GenericPointer<typename T::ValueType>(source, N - 1).GetWithDefault(root, defaultValue, a);  in GetValueByPointerWithDefault()
1253 …&source)[N], const std::basic_string<typename T::Ch>& defaultValue, typename T::AllocatorType& a) {  in GetValueByPointerWithDefault()  argument
1254 … return GenericPointer<typename T::ValueType>(source, N - 1).GetWithDefault(root, defaultValue, a);  in GetValueByPointerWithDefault()
1260 …erWithDefault(T& root, const CharType(&source)[N], T2 defaultValue, typename T::AllocatorType& a) {  in GetValueByPointerWithDefault()  argument
1261 … return GenericPointer<typename T::ValueType>(source, N - 1).GetWithDefault(root, defaultValue, a);  in GetValueByPointerWithDefault()
1315 …nter<typename T::ValueType>& pointer, typename T::ValueType& value, typename T::AllocatorType& a) {  in SetValueByPointer()  argument
1316     return pointer.Set(root, value, a);  in SetValueByPointer()
1320 …ypename T::ValueType>& pointer, const typename T::ValueType& value, typename T::AllocatorType& a) {  in SetValueByPointer()  argument
1321     return pointer.Set(root, value, a);  in SetValueByPointer()
1325 …inter<typename T::ValueType>& pointer, const typename T::Ch* value, typename T::AllocatorType& a) {  in SetValueByPointer()  argument
1326     return pointer.Set(root, value, a);  in SetValueByPointer()
1331 …alueType>& pointer, const std::basic_string<typename T::Ch>& value, typename T::AllocatorType& a) {  in SetValueByPointer()  argument
1332     return pointer.Set(root, value, a);  in SetValueByPointer()
1338 …ot, const GenericPointer<typename T::ValueType>& pointer, T2 value, typename T::AllocatorType& a) {  in SetValueByPointer()  argument
1339     return pointer.Set(root, value, a);  in SetValueByPointer()
1343 …(T& root, const CharType(&source)[N], typename T::ValueType& value, typename T::AllocatorType& a) {  in SetValueByPointer()  argument
1344     return GenericPointer<typename T::ValueType>(source, N - 1).Set(root, value, a);  in SetValueByPointer()
1348 …ot, const CharType(&source)[N], const typename T::ValueType& value, typename T::AllocatorType& a) {  in SetValueByPointer()  argument
1349     return GenericPointer<typename T::ValueType>(source, N - 1).Set(root, value, a);  in SetValueByPointer()
1353 …r(T& root, const CharType(&source)[N], const typename T::Ch* value, typename T::AllocatorType& a) {  in SetValueByPointer()  argument
1354     return GenericPointer<typename T::ValueType>(source, N - 1).Set(root, value, a);  in SetValueByPointer()
1359 …arType(&source)[N], const std::basic_string<typename T::Ch>& value, typename T::AllocatorType& a) {  in SetValueByPointer()  argument
1360     return GenericPointer<typename T::ValueType>(source, N - 1).Set(root, value, a);  in SetValueByPointer()
1366 SetValueByPointer(T& root, const CharType(&source)[N], T2 value, typename T::AllocatorType& a) {  in SetValueByPointer()  argument
1367     return GenericPointer<typename T::ValueType>(source, N - 1).Set(root, value, a);  in SetValueByPointer()
1431 …nter<typename T::ValueType>& pointer, typename T::ValueType& value, typename T::AllocatorType& a) {  in SwapValueByPointer()  argument
1432     return pointer.Swap(root, value, a);  in SwapValueByPointer()
1436 …(T& root, const CharType(&source)[N], typename T::ValueType& value, typename T::AllocatorType& a) {  in SwapValueByPointer()  argument
1437     return GenericPointer<typename T::ValueType>(source, N - 1).Swap(root, value, a);  in SwapValueByPointer()