nlohmann::json_pointer< BasicJsonType > Class Template Reference

JSON Pointer. More...

`#include <json.hpp>`

Collaboration diagram for nlohmann::json_pointer< BasicJsonType >:

## Public Member Functions

| json_pointer (const std::string &s="")
| create JSON pointer More...
std::string | to_string () const
| return a string representation of the JSON pointer More...
| operator std::string () const
| return a string representation of the JSON pointer More...
json_pointer & | operator/= (const json_pointer &ptr)
| append another JSON pointer at the end of this JSON pointer More...
json_pointer & | operator/= (std::string token)
| append an unescaped reference token at the end of this JSON pointer More...
json_pointer & | operator/= (std::size_t array_idx)
| append an array index at the end of this JSON pointer More...
json_pointer | parent_pointer () const
| returns the parent of this JSON pointer More...
void | pop_back ()
| remove last reference token More...
const std::string & | back () const
| return last reference token More...
void | push_back (const std::string &token)
| append an unescaped token at the end of the reference pointer More...
void | push_back (std::string &&token)
| append an unescaped token at the end of the reference pointer More...
bool | empty () const noexcept
| return whether pointer points to the root document More...

## Private Member Functions

JSON_PRIVATE_UNLESS_TESTED JSON pointer has no | BasicJsonType ()))
BasicJsonType & | get_and_create (BasicJsonType &j) const
| create and return a reference to the pointed to value More...
BasicJsonType & | get_unchecked (BasicJsonType *ptr) const
| return a reference to the pointed to value More...
BasicJsonType & | get_checked (BasicJsonType *ptr) const
const BasicJsonType & | get_unchecked (const BasicJsonType *ptr) const
| return a const reference to the pointed to value More...
const BasicJsonType & | get_checked (const BasicJsonType *ptr) const
bool | contains (const BasicJsonType *ptr) const

## Static Private Member Functions

static BasicJsonType::size_type | array_index (const std::string &s)
static std::vector< std::string > | split (const std::string &reference_string)
| split the string input to reference tokens More...
static void | flatten (const std::string &reference_string, const BasicJsonType &value, BasicJsonType &result)
static BasicJsonType | unflatten (const BasicJsonType &value)

## Private Attributes

JSON_PRIVATE_UNLESS_TESTED | __pad0__: json_pointer top() const { if (JSON_HEDLEY_UNLIKELY(empty())) { JSON_THROW(detail::out_of_range::create(405
JSON_PRIVATE_UNLESS_TESTED JSON pointer has no | parent
json_pointer | result = *this
result | reference_tokens = {reference_tokens[0]}
return | result
std::vector< std::string > | reference_tokens
| the reference tokens More...

## Friends

class | basic_json
json_pointer | operator/ (const json_pointer &lhs, const json_pointer &rhs)
| create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer More...
json_pointer | operator/ (const json_pointer &ptr, std::string token)
| create a new JSON pointer by appending the unescaped token at the end of the JSON pointer More...
json_pointer | operator/ (const json_pointer &ptr, std::size_t array_idx)
| create a new JSON pointer by appending the array-index-token at the end of the JSON pointer More...
bool | operator== (json_pointer const &lhs, json_pointer const &rhs) noexcept
| compares two JSON pointers for equality More...
bool | operator!= (json_pointer const &lhs, json_pointer const &rhs) noexcept
| compares two JSON pointers for inequality More...

## Detailed Description

### template<typename BasicJsonType>
class nlohmann::json_pointer< BasicJsonType >

JSON Pointer.

A JSON pointer defines a string syntax for identifying a specific value within a JSON document. It can be used with functions `at` and `operator[]`. Furthermore, JSON pointers are the base for JSON patches.

See also
  RFC 6901

Since
  version 2.0.0

Definition at line 3380 of file json.hpp.

## Constructor & Destructor Documentation

## json_pointer()

template<typename BasicJsonType >

nlohmann::json_pointer< BasicJsonType >::json_pointer | ( | const std::string & | s = `""` | ) |

inline explicit

create JSON pointer

Create a JSON pointer according to the syntax described in Section 3 of RFC6901.

Parameters

  [in] | s | string representing the JSON pointer; if omitted, the empty string is assumed which references the whole JSON value

Exceptions

  parse_error.107 | if the given JSON pointer s is nonempty and does not begin with a slash (`/`); see example below
  parse_error.108 | if a tilde (`~`) in the given JSON pointer s is not followed by `0` (representing `~`) or `1` (representing `/`); see example below

{The example shows the construction several valid JSON pointers as well as the exceptional behavior.,json_pointer}

Since
  version 2.0.0

Definition at line 12133 of file json.hpp.

## Member Function Documentation

## array_index()

template<typename BasicJsonType >

static BasicJsonType::size_type nlohmann::json_pointer< BasicJsonType >::array_index | ( | const std::string & | s | ) |

inline static private

Parameters

  [in] | s | reference token to be converted into an array index

Returns
  integer representation of s

Exceptions

  parse_error.106 | if an array index begins with '0'
  parse_error.109 | if an array index begins not with a digit
  out_of_range.404 | if string s could not be converted to an integer
  out_of_range.410 | if an array index exceeds size_type

Definition at line 12420 of file json.hpp.

References nlohmann::detail::parse_error::create(), nlohmann::detail::out_of_range::create(), JSON_CATCH, JSON_HEDLEY_UNLIKELY, JSON_PRIVATE_UNLESS_TESTED, JSON_THROW, and JSON_TRY.

Referenced by nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::patch().

## back()

template<typename BasicJsonType >

const std::string& nlohmann::json_pointer< BasicJsonType >::back | ( |  | ) | const

inline

return last reference token

Precondition
  not `empty()`

Returns
  last reference token

{The example shows the usage of `back`.,json_pointer__back}

Constant.

Exceptions

  out_of_range.405 | if JSON pointer has no parent

Since
  version 3.6.0

Definition at line 12357 of file json.hpp.

References nlohmann::detail::out_of_range::create(), JSON_HEDLEY_UNLIKELY, and JSON_THROW.

Referenced by nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::patch().

## BasicJsonType()

template<typename BasicJsonType >

JSON_PRIVATE_UNLESS_TESTED JSON pointer has no nlohmann::json_pointer< BasicJsonType >::BasicJsonType | ( |  | ) |

private

## contains()

template<typename BasicJsonType >

bool nlohmann::json_pointer< BasicJsonType >::contains | ( | const BasicJsonType * | ptr | ) | const

inline private

Exceptions

  parse_error.106 | if an array index begins with '0'
  parse_error.109 | if an array index was not a number

Definition at line 12745 of file json.hpp.

References nlohmann::detail::array, JSON_HEDLEY_UNLIKELY, and nlohmann::detail::object.

Referenced by nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::contains().

## empty()

template<typename BasicJsonType >

bool nlohmann::json_pointer< BasicJsonType >::empty | ( |  | ) | const

inline noexcept

return whether pointer points to the root document

Returns
  true iff the JSON pointer points to the root document

Constant.

No-throw guarantee: this function never throws exceptions.

{The example shows the result of `empty` for different JSON Pointers.,json_pointer__empty}

Since
  version 3.6.0

Definition at line 12404 of file json.hpp.

Referenced by nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::patch().

## flatten()

template<typename BasicJsonType >

static void nlohmann::json_pointer< BasicJsonType >::flatten | ( | const std::string & | reference_string,
|  | const BasicJsonType & | value,
|  | BasicJsonType & | result
| ) |  |

inline static private

Parameters

  [in] | reference_string | the reference string to the current value
  [in] | value | the value to consider
  [in,out] | result | the result object to insert values to

Note
  Empty objects or arrays are flattened to `null`.

Definition at line 12893 of file json.hpp.

References nlohmann::detail::array, nlohmann::detail::escape(), nlohmann::detail::object, nlohmann::to_string(), and nlohmann::detail::value.

Referenced by nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::flatten().

## get_and_create()

template<typename BasicJsonType >

BasicJsonType& nlohmann::json_pointer< BasicJsonType >::get_and_create | ( | BasicJsonType & | j | ) | const

inline private

create and return a reference to the pointed to value

Linear in the number of reference tokens.

Exceptions

  parse_error.109 | if array index is not a number
  type_error.313 | if value cannot be unflattened

Definition at line 12485 of file json.hpp.

References nlohmann::detail::array, nlohmann::detail::type_error::create(), JSON_THROW, nlohmann::detail::null, and nlohmann::detail::object.

Referenced by nlohmann::json_pointer< BasicJsonType >::unflatten().

## get_checked() [1/2]

template<typename BasicJsonType >

BasicJsonType& nlohmann::json_pointer< BasicJsonType >::get_checked | ( | BasicJsonType * | ptr | ) | const

inline private

Exceptions

  parse_error.106 | if an array index begins with '0'
  parse_error.109 | if an array index was not a number
  out_of_range.402 | if the array index '-' is used
  out_of_range.404 | if the JSON pointer can not be resolved

Definition at line 12616 of file json.hpp.

References nlohmann::detail::array, nlohmann::detail::out_of_range::create(), JSON_HEDLEY_UNLIKELY, JSON_THROW, nlohmann::detail::object, and nlohmann::to_string().

Referenced by nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::at(), and nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::value().

## get_checked() [2/2]

template<typename BasicJsonType >

const BasicJsonType& nlohmann::json_pointer< BasicJsonType >::get_checked | ( | const BasicJsonType * | ptr | ) | const

inline private

Exceptions

  parse_error.106 | if an array index begins with '0'
  parse_error.109 | if an array index was not a number
  out_of_range.402 | if the array index '-' is used
  out_of_range.404 | if the JSON pointer can not be resolved

Definition at line 12705 of file json.hpp.

References nlohmann::detail::array, nlohmann::detail::out_of_range::create(), JSON_HEDLEY_UNLIKELY, JSON_THROW, nlohmann::detail::object, and nlohmann::to_string().

## get_unchecked() [1/2]

template<typename BasicJsonType >

BasicJsonType& nlohmann::json_pointer< BasicJsonType >::get_unchecked | ( | BasicJsonType * | ptr | ) | const

inline private

return a reference to the pointed to value

Note
  This version does not throw if a value is not present, but tries to create nested values instead. For instance, calling this function with pointer `"/this/that"` on a null value is equivalent to calling `operator[]("this").operator[]("that")` on that value, effectively changing the null value to an object.

Parameters

  [in] | ptr | a JSON value

Returns
  reference to the JSON value pointed to by the JSON pointer

Linear in the length of the JSON pointer.

Exceptions

  parse_error.106 | if an array index begins with '0'
  parse_error.109 | if an array index was not a number
  out_of_range.404 | if the JSON pointer can not be resolved

Definition at line 12557 of file json.hpp.

References nlohmann::detail::array, nlohmann::detail::out_of_range::create(), JSON_THROW, and nlohmann::detail::object.

Referenced by nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::operator[]().

## get_unchecked() [2/2]

template<typename BasicJsonType >

const BasicJsonType& nlohmann::json_pointer< BasicJsonType >::get_unchecked | ( | const BasicJsonType * | ptr | ) | const

inline private

return a const reference to the pointed to value

Parameters

  [in] | ptr | a JSON value

Returns
  const reference to the JSON value pointed to by the JSON pointer

Exceptions

  parse_error.106 | if an array index begins with '0'
  parse_error.109 | if an array index was not a number
  out_of_range.402 | if the array index '-' is used
  out_of_range.404 | if the JSON pointer can not be resolved

Definition at line 12665 of file json.hpp.

References nlohmann::detail::array, nlohmann::detail::out_of_range::create(), JSON_HEDLEY_UNLIKELY, JSON_THROW, nlohmann::detail::object, and nlohmann::to_string().

## operator std::string()

template<typename BasicJsonType >

nlohmann::json_pointer< BasicJsonType >::operator std::string | ( |  | ) | const

inline

return a string representation of the JSON pointer

Invariant
  For each JSON pointer `ptr`, it holds:
  ptr == json_pointer(ptr.to_string());

Returns
  a string representation of the JSON pointer

{The example shows the result of `to_string`.,json_pointer__to_string}

Since
  version 2.0.0

Definition at line 12162 of file json.hpp.

References nlohmann::to_string().

## operator/=() [1/3]

template<typename BasicJsonType >

json_pointer& nlohmann::json_pointer< BasicJsonType >::operator/= | ( | const json_pointer< BasicJsonType > & | ptr | ) |

inline

append another JSON pointer at the end of this JSON pointer

Parameters

  [in] | ptr | JSON pointer to append

Returns
  JSON pointer with ptr appended

{The example shows the usage of `operator/=`.,json_pointer__operator_add}

Linear in the length of ptr.

See also
  see operator/=(std::string) to append a reference token
  see operator/=(std::size_t) to append an array index
  see operator/(const json_pointer&, const json_pointer&) for a binary operator

Since
  version 3.6.0

Definition at line 12183 of file json.hpp.

References nlohmann::json_pointer< BasicJsonType >::reference_tokens.

## operator/=() [2/3]

template<typename BasicJsonType >

json_pointer& nlohmann::json_pointer< BasicJsonType >::operator/= | ( | std::string | token | ) |

inline

append an unescaped reference token at the end of this JSON pointer

Parameters

  [in] | token | reference token to append

Returns
  JSON pointer with token appended without escaping token

{The example shows the usage of `operator/=`.,json_pointer__operator_add}

Amortized constant.

See also
  see operator/=(const json_pointer&) to append a JSON pointer
  see operator/=(std::size_t) to append an array index
  see operator/(const json_pointer&, std::size_t) for a binary operator

Since
  version 3.6.0

Definition at line 12207 of file json.hpp.

## operator/=() [3/3]

template<typename BasicJsonType >

json_pointer& nlohmann::json_pointer< BasicJsonType >::operator/= | ( | std::size_t | array_idx | ) |

inline

append an array index at the end of this JSON pointer

Parameters

  [in] | array_idx | array index to append

Returns
  JSON pointer with array_idx appended

{The example shows the usage of `operator/=`.,json_pointer__operator_add}

Amortized constant.

See also
  see operator/=(const json_pointer&) to append a JSON pointer
  see operator/=(std::string) to append a reference token
  see operator/(const json_pointer&, std::string) for a binary operator

Since
  version 3.6.0

Definition at line 12229 of file json.hpp.

References nlohmann::to_string().

## parent_pointer()

template<typename BasicJsonType >

json_pointer nlohmann::json_pointer< BasicJsonType >::parent_pointer | ( |  | ) | const

inline

returns the parent of this JSON pointer

Returns
  parent of this JSON pointer; in case this JSON pointer is the root, the root itself is returned

Linear in the length of the JSON pointer.

{The example shows the result of `parent_pointer` for different JSON Pointers.,json_pointer__parent_pointer}

Since
  version 3.6.0

Definition at line 12308 of file json.hpp.

References nlohmann::json_pointer< BasicJsonType >::pop_back().

## pop_back()

template<typename BasicJsonType >

void nlohmann::json_pointer< BasicJsonType >::pop_back | ( |  | ) |

inline

remove last reference token

Precondition
  not `empty()`

{The example shows the usage of `pop_back`.,json_pointer__pop_back}

Constant.

Exceptions

  out_of_range.405 | if JSON pointer has no parent

Since
  version 3.6.0

Definition at line 12333 of file json.hpp.

References nlohmann::detail::out_of_range::create(), JSON_HEDLEY_UNLIKELY, and JSON_THROW.

Referenced by nlohmann::json_pointer< BasicJsonType >::parent_pointer(), and nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::patch().

## push_back() [1/2]

template<typename BasicJsonType >

void nlohmann::json_pointer< BasicJsonType >::push_back | ( | const std::string & | token | ) |

inline

append an unescaped token at the end of the reference pointer

Parameters

  [in] | token | token to add

Amortized constant.

{The example shows the result of `push_back` for different JSON Pointers.,json_pointer__push_back}

Since
  version 3.6.0

Definition at line 12379 of file json.hpp.

## push_back() [2/2]

template<typename BasicJsonType >

void nlohmann::json_pointer< BasicJsonType >::push_back | ( | std::string && | token | ) |

inline

append an unescaped token at the end of the reference pointer

Parameters

  [in] | token | token to add

Amortized constant.

{The example shows the result of `push_back` for different JSON Pointers.,json_pointer__push_back}

Since
  version 3.6.0

Definition at line 12385 of file json.hpp.

## split()

template<typename BasicJsonType >

static std::vector<std::string> nlohmann::json_pointer< BasicJsonType >::split | ( | const std::string & | reference_string | ) |

inline static private

split the string input to reference tokens

Note
  This function is only called by the json_pointer constructor. All exceptions below are documented there.

Exceptions

  parse_error.107 | if the pointer is not empty or begins with '/'
  parse_error.108 | if character '~' is not followed by '0' or '1'

Definition at line 12825 of file json.hpp.

References nlohmann::detail::parse_error::create(), JSON_ASSERT, JSON_HEDLEY_UNLIKELY, JSON_THROW, and nlohmann::detail::unescape().

## to_string()

template<typename BasicJsonType >

std::string nlohmann::json_pointer< BasicJsonType >::to_string | ( |  | ) | const

inline

return a string representation of the JSON pointer

Invariant
  For each JSON pointer `ptr`, it holds:
  ptr == json_pointer(ptr.to_string());

Returns
  a string representation of the JSON pointer

{The example shows the result of `to_string`.,json_pointer__to_string}

Since
  version 2.0.0

Definition at line 12151 of file json.hpp.

References nlohmann::detail::escape(), and nlohmann::detail::string.

## unflatten()

template<typename BasicJsonType >

static BasicJsonType nlohmann::json_pointer< BasicJsonType >::unflatten | ( | const BasicJsonType & | value | ) |

inline static private

Parameters

  [in] | value | flattened JSON

Returns
  unflattened JSON

Exceptions

  parse_error.109 | if array index is not a number
  type_error.314 | if value is not an object
  type_error.315 | if object values are not primitive
  type_error.313 | if value cannot be unflattened

Definition at line 12956 of file json.hpp.

References nlohmann::detail::type_error::create(), nlohmann::json_pointer< BasicJsonType >::get_and_create(), JSON_HEDLEY_UNLIKELY, and JSON_THROW.

Referenced by nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::unflatten().

## Friends And Related Function Documentation

## basic_json

template<typename BasicJsonType >

friend class basic_json

friend

Definition at line 12109 of file json.hpp.

## operator!=

template<typename BasicJsonType >

bool operator!= | ( | json_pointer< BasicJsonType > const & | lhs,
|  | json_pointer< BasicJsonType > const & | rhs
| ) |  |

friend

compares two JSON pointers for inequality

Parameters

  [in] | lhs | JSON pointer to compare
  [in] | rhs | JSON pointer to compare

Returns
  whether lhs is not equal rhs

Linear in the length of the JSON pointer

No-throw guarantee: this function never throws exceptions.

Definition at line 13011 of file json.hpp.

## operator/ [1/3]

template<typename BasicJsonType >

json_pointer operator/ | ( | const json_pointer< BasicJsonType > & | lhs,
|  | const json_pointer< BasicJsonType > & | rhs
| ) |  |

friend

create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer

Parameters

  [in] | lhs | JSON pointer
  [in] | rhs | JSON pointer

Returns
  a new JSON pointer with rhs appended to lhs

{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}

Linear in the length of lhs and rhs.

See also
  see operator/=(const json_pointer&) to append a JSON pointer

Since
  version 3.6.0

Definition at line 12249 of file json.hpp.

## operator/ [2/3]

template<typename BasicJsonType >

json_pointer operator/ | ( | const json_pointer< BasicJsonType > & | ptr,
|  | std::string | token
| ) |  |

friend

create a new JSON pointer by appending the unescaped token at the end of the JSON pointer

Parameters

  [in] | ptr | JSON pointer
  [in] | token | reference token

Returns
  a new JSON pointer with unescaped token appended to ptr

{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}

Linear in the length of ptr.

See also
  see operator/=(std::string) to append a reference token

Since
  version 3.6.0

Definition at line 12270 of file json.hpp.

## operator/ [3/3]

template<typename BasicJsonType >

json_pointer operator/ | ( | const json_pointer< BasicJsonType > & | ptr,
|  | std::size_t | array_idx
| ) |  |

friend

create a new JSON pointer by appending the array-index-token at the end of the JSON pointer

Parameters

  [in] | ptr | JSON pointer
  [in] | array_idx | array index

Returns
  a new JSON pointer with array_idx appended to ptr

{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}

Linear in the length of ptr.

See also
  see operator/=(std::size_t) to append an array index

Since
  version 3.6.0

Definition at line 12290 of file json.hpp.

## operator==

template<typename BasicJsonType >

bool operator== | ( | json_pointer< BasicJsonType > const & | lhs,
|  | json_pointer< BasicJsonType > const & | rhs
| ) |  |

friend

compares two JSON pointers for equality

Parameters

  [in] | lhs | JSON pointer to compare
  [in] | rhs | JSON pointer to compare

Returns
  whether lhs is equal to rhs

Linear in the length of the JSON pointer

No-throw guarantee: this function never throws exceptions.

Definition at line 12994 of file json.hpp.

## Member Data Documentation

## __pad0__

template<typename BasicJsonType >

JSON_PRIVATE_UNLESS_TESTED nlohmann::json_pointer< BasicJsonType >::__pad0__

private

Definition at line 12468 of file json.hpp.

## parent

template<typename BasicJsonType >

JSON_PRIVATE_UNLESS_TESTED JSON pointer has no nlohmann::json_pointer< BasicJsonType >::parent

private

Definition at line 12468 of file json.hpp.

## reference_tokens [1/2]

template<typename BasicJsonType >

result nlohmann::json_pointer< BasicJsonType >::reference_tokens = {reference_tokens[0]}

private

Definition at line 12472 of file json.hpp.

Referenced by nlohmann::json_pointer< BasicJsonType >::operator/=().

## reference_tokens [2/2]

template<typename BasicJsonType >

std::vector<std::string> nlohmann::json_pointer< BasicJsonType >::reference_tokens

private

the reference tokens

Definition at line 13018 of file json.hpp.

## result [1/2]

template<typename BasicJsonType >

json_pointer nlohmann::json_pointer< BasicJsonType >::result = *this

private

Definition at line 12471 of file json.hpp.

## result [2/2]

template<typename BasicJsonType >

return nlohmann::json_pointer< BasicJsonType >::result

private

Definition at line 12473 of file json.hpp.

The documentation for this class was generated from the following file:

- json.hpp