Template Class json_pointer

Class Documentation

template<typename BasicJsonType>
class json_pointer

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

Public Functions

inline explicit json_pointer(const std::string &s = "")

create JSON pointer

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

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

Since

version 2.0.0

Parameters:

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

Throws:

  • 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

inline std::string to_string() const

return a string representation of the JSON pointer

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

Invariant

For each JSON pointer ptr, it holds: 

ptr == json_pointer(ptr.to_string());

Since

version 2.0.0

Returns:

a string representation of the JSON pointer

inline operator std::string() const

return a string representation of the JSON pointer

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

Invariant

For each JSON pointer ptr, it holds: 

ptr == json_pointer(ptr.to_string());

Since

version 2.0.0

Returns:

a string representation of the JSON pointer

inline json_pointer &operator/=(const json_pointer &ptr)

append another JSON pointer at the end of this JSON pointer

@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

See also

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

See also

operator/(const json_pointer&, const json_pointer&) for a binary operator

Since

version 3.6.0

Parameters:

ptr – [in] JSON pointer to append

Returns:

JSON pointer with ptr appended

inline json_pointer &operator/=(std::string token)

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

@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

See also

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

See also

operator/(const json_pointer&, std::size_t) for a binary operator

Since

version 3.6.0

Parameters:

token – [in] reference token to append

Returns:

JSON pointer with token appended without escaping token

inline json_pointer &operator/=(std::size_t array_index)

append an array index at the end of this JSON pointer

@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

See also

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

See also

operator/(const json_pointer&, std::string) for a binary operator

Since

version 3.6.0

Parameters:

array_index – [in] array index to append

Returns:

JSON pointer with array_index appended

inline json_pointer parent_pointer() const

returns the parent of this JSON pointer

@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

Returns:

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

inline void pop_back()

remove last reference token

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

@complexity Constant.

Since

version 3.6.0

Pre:

not empty()

Throws:

out_of_range.405 – if JSON pointer has no parent

inline const std::string &back() const

return last reference token

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

@complexity Constant.

Since

version 3.6.0

Pre:

not empty()

Returns:

last reference token

Throws:

out_of_range.405 – if JSON pointer has no parent

inline void push_back(const std::string &token)

append an unescaped token at the end of the reference pointer

@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

Parameters:

token – [in] token to add

inline void push_back(std::string &&token)

append an unescaped token at the end of the reference pointer

@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

Parameters:

token – [in] token to add

inline bool empty() const noexcept

return whether 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

Returns:

true iff the JSON pointer points to the root document

inline explicit json_pointer(const std::string &s = "")

create JSON pointer

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

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

Since

version 2.0.0

Parameters:

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

Throws:

  • 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

inline std::string to_string() const

return a string representation of the JSON pointer

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

Invariant

For each JSON pointer ptr, it holds: 

ptr == json_pointer(ptr.to_string());

Since

version 2.0.0

Returns:

a string representation of the JSON pointer

inline operator std::string() const

return a string representation of the JSON pointer

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

Invariant

For each JSON pointer ptr, it holds: 

ptr == json_pointer(ptr.to_string());

Since

version 2.0.0

Returns:

a string representation of the JSON pointer

inline json_pointer &operator/=(const json_pointer &ptr)

append another JSON pointer at the end of this JSON pointer

@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

See also

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

See also

operator/(const json_pointer&, const json_pointer&) for a binary operator

Since

version 3.6.0

Parameters:

ptr – [in] JSON pointer to append

Returns:

JSON pointer with ptr appended

inline json_pointer &operator/=(std::string token)

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

@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

See also

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

See also

operator/(const json_pointer&, std::size_t) for a binary operator

Since

version 3.6.0

Parameters:

token – [in] reference token to append

Returns:

JSON pointer with token appended without escaping token

inline json_pointer &operator/=(std::size_t array_idx)

append an array index at the end of this JSON pointer

@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

See also

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

See also

operator/(const json_pointer&, std::string) for a binary operator

Since

version 3.6.0

Parameters:

array_idx – [in] array index to append

Returns:

JSON pointer with array_idx appended

inline json_pointer parent_pointer() const

returns the parent of this JSON pointer

@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

Returns:

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

inline void pop_back()

remove last reference token

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

@complexity Constant.

Since

version 3.6.0

Pre:

not empty()

Throws:

out_of_range.405 – if JSON pointer has no parent

inline const std::string &back() const

return last reference token

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

@complexity Constant.

Since

version 3.6.0

Pre:

not empty()

Returns:

last reference token

Throws:

out_of_range.405 – if JSON pointer has no parent

inline void push_back(const std::string &token)

append an unescaped token at the end of the reference pointer

@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

Parameters:

token – [in] token to add

inline void push_back(std::string &&token)

append an unescaped token at the end of the reference pointer

@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

Parameters:

token – [in] token to add

inline bool empty() const noexcept

return whether 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

Returns:

true iff the JSON pointer points to the root document

Friends

inline friend 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

@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

Parameters:

  • lhs – [in] JSON pointer

  • rhs – [in] JSON pointer

Returns:

a new JSON pointer with rhs appended to lhs

inline friend 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

@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

Parameters:

  • ptr – [in] JSON pointer

  • token – [in] reference token

Returns:

a new JSON pointer with unescaped token appended to ptr

inline friend json_pointer operator/(const json_pointer &ptr, std::size_t array_index)

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

@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

Parameters:

  • ptr – [in] JSON pointer

  • array_index – [in] array index

Returns:

a new JSON pointer with array_index appended to ptr

inline friend 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

@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

Parameters:

  • lhs – [in] JSON pointer

  • rhs – [in] JSON pointer

Returns:

a new JSON pointer with rhs appended to lhs

inline friend 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

@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

Parameters:

  • ptr – [in] JSON pointer

  • token – [in] reference token

Returns:

a new JSON pointer with unescaped token appended to ptr

inline friend 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

@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

Parameters:

  • ptr – [in] JSON pointer

  • array_idx – [in] array index

Returns:

a new JSON pointer with array_idx appended to ptr