Renderd7-nightly v0.7.0

Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Friends | List of all members
nlohmann::json_pointer< BasicJsonType > Class Template Reference

JSON Pointer. More...

`#include <json.hpp>`

## 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
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 | replace_substring (std::string &s, const std::string &f, const std::string &t)
| replace all occurrences of a substring by another string More...
static std::string | escape (std::string s)
| escape "~" to "~0" and "/" to "~1"
static void | unescape (std::string &s)
| unescape "~1" to tilde and "~0" to slash (order is important!)
static void | flatten (const std::string &reference_string, const BasicJsonType &value, BasicJsonType &result)
static BasicJsonType | unflatten (const BasicJsonType &value)

## Private Attributes
std::vector< std::string > | reference_tokens
| the reference tokens

## Friends
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

## 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

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

Since
  version 2.0.0

## Member Function Documentation

## ◆ 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

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

Since
  version 2.0.0

## ◆ 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

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

Since
  version 2.0.0

## ◆ 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

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

@complexity Linear in the length of ptr.

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

Since
  version 3.6.0

## ◆ 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

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

@complexity Amortized constant.

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

Since
  version 3.6.0

## ◆ 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

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

@complexity Amortized constant.

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

Since
  version 3.6.0

## ◆ 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

@complexity Linear in the length of the JSON pointer.

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

Since
  version 3.6.0

## ◆ pop_back()

template<typename BasicJsonType >

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

remove last reference token

Precondition
  not `empty()`

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

@complexity Constant.

Exceptions

  out_of_range.405 | if JSON pointer has no parent

Since
  version 3.6.0

## ◆ 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

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

@complexity Constant.

Exceptions

  out_of_range.405 | if JSON pointer has no parent

Since
  version 3.6.0

## ◆ 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

@complexity Amortized constant.

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

Since
  version 3.6.0

## ◆ 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

@complexity Amortized constant.

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

Since
  version 3.6.0

## ◆ 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

@complexity Constant.

@exceptionsafety No-throw guarantee: this function never throws exceptions.

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

Since
  version 3.6.0

## ◆ 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

## ◆ 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

@complexity 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

## ◆ 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

@complexity 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

## ◆ 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

## ◆ 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

## ◆ 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

## ◆ 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

## ◆ 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'

## ◆ replace_substring()

template<typename BasicJsonType >

static void nlohmann::json_pointer< BasicJsonType >::replace_substring | ( | std::string & | s,
|  | const std::string & | f,
|  | const std::string & | t
| ) |  |
| inline static private

replace all occurrences of a substring by another string

Parameters

  [in,out] | s | the string to manipulate; changed so that all occurrences of f are replaced with t
  [in] | f | the substring to replace with t
  [in] | t | the string to replace f

Precondition
  The search string f must not be empty. This precondition is enforced with an assertion.

Since
  version 2.0.0

## ◆ 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`.

## ◆ 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

## Friends And Related Function Documentation

## ◆ 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

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

@complexity Linear in the length of lhs and rhs.

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

Since
  version 3.6.0

## ◆ 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

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

@complexity Linear in the length of ptr.

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

Since
  version 3.6.0

## ◆ 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

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

@complexity Linear in the length of ptr.

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

Since
  version 3.6.0

## ◆ 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

@complexity Linear in the length of the JSON pointer

@exceptionsafety No-throw guarantee: this function never throws exceptions.

## ◆ 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

@complexity Linear in the length of the JSON pointer

@exceptionsafety No-throw guarantee: this function never throws exceptions.

nlohmann::json_pointer::json_pointer
json_pointer(const std::string &s="")
create JSON pointer
Definition: json.hpp:11582