JSON Pointer

A growing implementation of RFC 6901 JSON Pointer. More...

Classes
class	sourcemeta::core::PointerParseError
class	sourcemeta::core::GenericPointer< PropertyT, Hash >
class	sourcemeta::core::PointerPositionTracker
class	sourcemeta::core::GenericToken< PropertyT, Hash >
class	sourcemeta::core::GenericPointerWalker< PointerT >

Typedefs
using	sourcemeta::core::Pointer = GenericPointer<JSON::String, PropertyHashJSON<JSON::String>>
using	sourcemeta::core::WeakPointer
using	sourcemeta::core::PointerWalker = GenericPointerWalker<WeakPointer>

Functions
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::get (const JSON &document, const Pointer &pointer) -> const JSON &
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::get (const JSON &document, const WeakPointer &pointer) -> const JSON &
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::get (JSON &document, const WeakPointer &pointer) -> JSON &
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::try_get (const JSON &document, const Pointer &pointer) -> const JSON *
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::try_get (const JSON &document, const WeakPointer &pointer) -> const JSON *
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::get (JSON &document, const Pointer &pointer) -> JSON &
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::get (const JSON &document, const Pointer::Token &token) -> const JSON &
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::get (JSON &document, const Pointer::Token &token) -> JSON &
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::set (JSON &document, const Pointer &pointer, const JSON &value) -> void
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::set (JSON &document, const Pointer &pointer, JSON &&value) -> void
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::remove (JSON &document, const Pointer &pointer) -> bool
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::remove (JSON &document, const WeakPointer &pointer) -> bool
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_pointer (const JSON &document) -> Pointer
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_pointer (const std::basic_string_view< JSON::Char, JSON::CharTraits > input) -> Pointer
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::fragment_to_pointer (const URI &uri) -> std::optional< Pointer >
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_pointer (const WeakPointer &pointer) -> Pointer
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::is_pointer (std::string_view input) noexcept -> bool
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::is_relative_pointer (std::string_view input) noexcept -> bool
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_weak_pointer (const Pointer &pointer) -> WeakPointer
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::stringify (const Pointer &pointer, std::basic_ostream< JSON::Char, JSON::CharTraits > &stream) -> void
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::stringify (const WeakPointer &pointer, std::basic_ostream< JSON::Char, JSON::CharTraits > &stream) -> void
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_string (const Pointer &pointer) -> std::basic_string< JSON::Char, JSON::CharTraits, std::allocator< JSON::Char > >
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_string (const WeakPointer &pointer) -> std::basic_string< JSON::Char, JSON::CharTraits, std::allocator< JSON::Char > >
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_uri (const Pointer &pointer) -> URI
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_uri (const Pointer &pointer, const URI &base) -> URI
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_uri (const WeakPointer &pointer) -> URI
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_uri (const WeakPointer &pointer, const URI &base) -> URI
SOURCEMETA_CORE_JSONPOINTER_EXPORT auto	sourcemeta::core::to_uri (const WeakPointer &pointer, const std::string_view base) -> URI

Variables
const Pointer	sourcemeta::core::empty_pointer
const WeakPointer	sourcemeta::core::empty_weak_pointer

Detailed Description

A growing implementation of RFC 6901 JSON Pointer.

This functionality is included as follows:

#include <sourcemeta/core/jsonpointer.h>

---

Class Documentation

sourcemeta::core::PointerParseError

class sourcemeta::core::PointerParseError

This class represents a parsing error.

Inheritance diagram for sourcemeta::core::PointerParseError:

Public Member Functions
	PointerParseError (const std::uint64_t column)
	Create a parsing error.
Public Member Functions inherited from sourcemeta::core::JSONParseError
	JSONParseError (const std::uint64_t line, const std::uint64_t column)
	Create a parsing error.
	JSONParseError (const std::uint64_t line, const std::uint64_t column, const char *message)
	Create a parsing error with a custom error.
	JSONParseError (const std::uint64_t line, const std::uint64_t column, std::string message)=delete
	JSONParseError (const std::uint64_t line, const std::uint64_t column, std::string &&message)=delete
	JSONParseError (const std::uint64_t line, const std::uint64_t column, std::string_view message)=delete
auto	line () const noexcept -> std::uint64_t
	Get the line number of the error.
auto	column () const noexcept -> std::uint64_t
	Get the column number of the error.

sourcemeta::core::GenericPointer

class sourcemeta::core::GenericPointer

template<typename PropertyT, typename Hash>
class sourcemeta::core::GenericPointer< PropertyT, Hash >

A sequence of reference tokens that identifies a location within a JSON document.

Public Types
using	Token = GenericToken<PropertyT, Hash>
	A single reference token within this pointer.
using	Value = typename Token::Value
	The JSON value type used for serialisation.
using	Container = std::vector<Token>
	The underlying sequence container of tokens.
Public Member Functions
	GenericPointer () noexcept
	GenericPointer (std::initializer_list< Token > tokens)
auto	at (const size_type index) const -> const_reference
SOURCEMETA_FORCEINLINE auto	back () const -> const_reference
SOURCEMETA_FORCEINLINE auto	size () const noexcept -> size_type
SOURCEMETA_FORCEINLINE auto	empty () const noexcept -> bool
template<class... Args>
SOURCEMETA_FORCEINLINE auto	emplace_back (Args &&...args) -> reference
auto	reserve (const typename Container::size_type capacity) -> void
SOURCEMETA_FORCEINLINE auto	push_back (const GenericPointer< PropertyT, Hash > &other) -> void
SOURCEMETA_FORCEINLINE auto	push_back (GenericPointer< PropertyT, Hash > &&other) -> void
template<typename OtherT> requires std::is_same_v<PropertyT, std::reference_wrapper<const OtherT>>
SOURCEMETA_FORCEINLINE auto	push_back (const GenericPointer< OtherT, Hash > &other) -> void
SOURCEMETA_FORCEINLINE auto	push_back (const typename Token::Property &property) -> void
SOURCEMETA_FORCEINLINE auto	push_back (typename Token::Property &&property) -> void
SOURCEMETA_FORCEINLINE auto	push_back (const typename Token::Index &index) -> void
auto	pop_back () -> void
auto	pop_back (const size_type count) -> void
auto	initial () const -> GenericPointer< PropertyT, Hash >
auto	slice (const std::size_t index) const -> GenericPointer< PropertyT, Hash >
auto	slice (const std::size_t start, const std::size_t end) const -> GenericPointer< PropertyT, Hash >
auto	concat (const GenericPointer< PropertyT, Hash > &other) const -> GenericPointer< PropertyT, Hash >
auto	concat (const typename Token::Property &property) const -> GenericPointer< PropertyT, Hash >
auto	concat (const typename Token::Index &index) const -> GenericPointer< PropertyT, Hash >
auto	starts_with (const GenericPointer< PropertyT, Hash > &other) const -> bool
auto	starts_with (const GenericPointer< PropertyT, Hash > &other, const Token &tail) const -> bool
template<typename StringT>
auto	starts_with (const GenericPointer< PropertyT, Hash > &other, const StringT &tail) const -> bool
template<typename StringLeftT, typename StringRightT>
auto	starts_with (const GenericPointer< PropertyT, Hash > &other, const StringLeftT &tail_left, const StringRightT &tail_right) const -> bool
auto	shares_prefix (const GenericPointer< PropertyT, Hash > &other, const size_type prefix_size) const -> bool
auto	starts_with_strict (const GenericPointer< PropertyT, Hash > &other) const -> bool
auto	starts_with_initial (const GenericPointer< PropertyT, Hash > &other) const -> bool
auto	rebase (const GenericPointer< PropertyT, Hash > &prefix, const GenericPointer< PropertyT, Hash > &replacement) const -> GenericPointer< PropertyT, Hash >
auto	resolve_from (const GenericPointer< PropertyT, Hash > &base) const -> GenericPointer< PropertyT, Hash >
auto	to_json () const -> Value
	Serialise a JSON Pointer as a JSON array of tokens.
Static Public Member Functions
static auto	from_json (const Value &value) -> std::optional< GenericPointer< PropertyT, Hash > >
	Deserialise a JSON Pointer from a JSON array of tokens.

Constructor & Destructor Documentation

GenericPointer() [1/2]

template<typename PropertyT, typename Hash>

sourcemeta::core::GenericPointer< PropertyT, Hash >::GenericPointer ( )

inlinenoexcept

This constructor creates an empty JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer;
assert(pointer.empty());

GenericPointer() [2/2]

template<typename PropertyT, typename Hash>

sourcemeta::core::GenericPointer< PropertyT, Hash >::GenericPointer ( std::initializer_list< Token > tokens )

inline

This constructor is the preferred way of creating a pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
// Equivalent to /foo/bar/1
const sourcemeta::core::Pointer pointer{"foo", "bar", 1};
assert(pointer.size() == 3);

Member Function Documentation

at()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::at ( const size_type index ) const -> const_reference

inlinenodiscard

Access a token in a JSON Pointer at a given index. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", 1};
assert(pointer.at(1).is_property());
assert(pointer.at(1).to_property() == "bar");

back()

template<typename PropertyT, typename Hash>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::GenericPointer< PropertyT, Hash >::back ( ) const -> const_reference

inlinenodiscard

Access the last token in a JSON Pointer For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", 1};
assert(pointer.back().is_property());
assert(pointer.back().to_property() == "bar");

concat() [1/3]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::concat ( const GenericPointer< PropertyT, Hash > & other ) const -> GenericPointer< PropertyT, Hash >

inlinenodiscard

Concatenate a JSON Pointer with another JSON Pointer, getting a new pointer as a result. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer left{"foo"};
const sourcemeta::core::Pointer right{"bar", "baz"};
assert(left.concat(right) ==
  sourcemeta::core::Pointer{"foo", "bar", "baz"});

concat() [2/3]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::concat ( const typename Token::Index & index ) const -> GenericPointer< PropertyT, Hash >

inlinenodiscard

Concatenate a JSON Pointer with a single index token, getting a new pointer as a result. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo"};
assert(pointer.concat(0) == sourcemeta::core::Pointer{"foo", 0});

concat() [3/3]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::concat ( const typename Token::Property & property ) const -> GenericPointer< PropertyT, Hash >

inlinenodiscard

Concatenate a JSON Pointer with a single property token, getting a new pointer as a result. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo"};
assert(pointer.concat("bar") == sourcemeta::core::Pointer{"foo", "bar"});

emplace_back()

template<typename PropertyT, typename Hash>

template<class... Args>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::GenericPointer< PropertyT, Hash >::emplace_back ( Args &&... args ) -> reference

inline

Emplace a token into the back of a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
sourcemeta::core::Pointer pointer;
assert(pointer.empty());
auto &token{pointer.emplace_back("foo")};
assert(!pointer.empty());
assert(token.is_property());

empty()

template<typename PropertyT, typename Hash>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::GenericPointer< PropertyT, Hash >::empty ( ) const -> bool

inlinenodiscardnoexcept

Check if a JSON Pointer is the empty pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer empty_pointer;
const sourcemeta::core::Pointer non_empty_pointer{"foo", "bar"};
assert(empty_pointer.empty());
assert(!non_empty_pointer.empty());

initial()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::initial ( ) const -> GenericPointer< PropertyT, Hash >

inlinenodiscard

Get a copy of the JSON Pointer including every token except the last. This method is undefined if the JSON Pointer is empty. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", "baz"};
const sourcemeta::core::Pointer result{pointer.initial()};
assert(pointer.size() == 2);
assert(pointer.at(0).is_property());
assert(pointer.at(0).to_property() == "foo");
assert(pointer.at(1).is_property());
assert(pointer.at(1).to_property() == "bar");

pop_back() [1/2]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::pop_back ( ) -> void

inline

Remove the last token of a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
sourcemeta::core::Pointer pointer{"foo", "bar"};
pointer.pop_back();
assert(pointer.size() == 1);
assert(pointer.at(0).is_property());
assert(pointer.at(0).to_property() == "foo");

pop_back() [2/2]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::pop_back ( const size_type count ) -> void

inline

Remove a number of tokens from the back of a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
sourcemeta::core::Pointer pointer{"foo", "bar", "baz"};
pointer.pop_back(2);
assert(pointer.size() == 1);
assert(pointer.at(0).is_property());
assert(pointer.at(0).to_property() == "foo");

push_back() [1/6]

template<typename PropertyT, typename Hash>

template<typename OtherT>
requires std::is_same_v<PropertyT, std::reference_wrapper<const OtherT>>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::GenericPointer< PropertyT, Hash >::push_back ( const GenericPointer< OtherT, Hash > & other ) -> void

inline

Push a JSON Pointer into the back of a JSON WeakPointer. Make sure that the pointer you are pushing remains alive for the duration of the WeakPointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const std::string foo{"foo"};
sourcemeta::core::WeakPointer pointer{std::cref(foo)};
const sourcemeta::core::Pointer other{"bar", "baz"};
pointer.push_back(other);
assert(pointer.size() == 3);
 
assert(pointer.at(0).is_property());
assert(pointer.at(1).is_property());
assert(pointer.at(2).is_property());
 
assert(pointer.at(0).to_property() == "foo");
assert(pointer.at(1).to_property() == "bar");
assert(pointer.at(2).to_property() == "baz");

push_back() [2/6]

template<typename PropertyT, typename Hash>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::GenericPointer< PropertyT, Hash >::push_back ( const GenericPointer< PropertyT, Hash > & other ) -> void

inline

Push a copy of a JSON Pointer into the back of a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
sourcemeta::core::Pointer pointer{"foo"};
const sourcemeta::core::Pointer other{"bar", "baz"};
pointer.push_back(other);
assert(pointer.size() == 3);
 
assert(pointer.at(0).is_property());
assert(pointer.at(1).is_property());
assert(pointer.at(2).is_property());
 
assert(pointer.at(0).to_property() == "foo");
assert(pointer.at(1).to_property() == "bar");
assert(pointer.at(2).to_property() == "baz");

push_back() [3/6]

template<typename PropertyT, typename Hash>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::GenericPointer< PropertyT, Hash >::push_back ( const typename Token::Index & index ) -> void

inline

Push an index token into the back of a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
sourcemeta::core::Pointer pointer{"foo"};
const sourcemeta::core::Pointer other{0};
pointer.push_back(other.back().to_index());
assert(pointer.size() == 2);
 
assert(pointer.at(0).is_property());
assert(pointer.at(1).is_index());
 
assert(pointer.at(0).to_property() == "foo");
assert(pointer.at(1).to_index() == 0);

push_back() [4/6]

template<typename PropertyT, typename Hash>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::GenericPointer< PropertyT, Hash >::push_back ( const typename Token::Property & property ) -> void

inline

Push a property token into the back of a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
sourcemeta::core::Pointer pointer{"foo"};
const sourcemeta::core::Pointer other{"bar"};
pointer.push_back(other.back().to_property());
assert(pointer.size() == 2);
 
assert(pointer.at(0).is_property());
assert(pointer.at(1).is_property());
 
assert(pointer.at(0).to_property() == "foo");
assert(pointer.at(1).to_property() == "bar");

push_back() [5/6]

template<typename PropertyT, typename Hash>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::GenericPointer< PropertyT, Hash >::push_back ( GenericPointer< PropertyT, Hash > && other ) -> void

inline

Move a JSON Pointer into the back of a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <utility>
 
sourcemeta::core::Pointer pointer{"foo"};
sourcemeta::core::Pointer other{"bar", "baz"};
pointer.push_back(std::move(other));
assert(pointer.size() == 3);
 
assert(pointer.at(0).is_property());
assert(pointer.at(1).is_property());
assert(pointer.at(2).is_property());
 
assert(pointer.at(0).to_property() == "foo");
assert(pointer.at(1).to_property() == "bar");
assert(pointer.at(2).to_property() == "baz");

push_back() [6/6]

template<typename PropertyT, typename Hash>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::GenericPointer< PropertyT, Hash >::push_back ( typename Token::Property && property ) -> void

inline

Move a property token into the back of a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
sourcemeta::core::Pointer pointer{"foo"};
pointer.push_back("bar");
assert(pointer.size() == 2);
 
assert(pointer.at(0).is_property());
assert(pointer.at(1).is_property());
 
assert(pointer.at(0).to_property() == "foo");
assert(pointer.at(1).to_property() == "bar");

rebase()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::rebase ( const GenericPointer< PropertyT, Hash > & prefix, const GenericPointer< PropertyT, Hash > & replacement ) const -> GenericPointer< PropertyT, Hash >

inlinenodiscard

Replace a base of a JSON Pointer with another JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", "baz"};
const sourcemeta::core::Pointer prefix{"foo", "bar"};
const sourcemeta::core::Pointer replacement{"qux"};
 
assert(pointer.rebase(prefix, replacement) ==
  sourcemeta::core::Pointer{"qux", "baz"});

reserve()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::reserve ( const typename Container::size_type capacity ) -> void

inline

Reserve capacity for a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
 
sourcemeta::core::Pointer pointer;
pointer.reserve(1024);

resolve_from()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::resolve_from ( const GenericPointer< PropertyT, Hash > & base ) const -> GenericPointer< PropertyT, Hash >

inlinenodiscard

Resolve a JSON Pointer relative to another JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar"};
const sourcemeta::core::Pointer base{"foo"};
assert(pointer.resolve_from(base) ==
  sourcemeta::core::Pointer{"bar"});

If the JSON Pointer is not relative to the base, a copy of the original input pointer is returned.

shares_prefix()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::shares_prefix ( const GenericPointer< PropertyT, Hash > & other, const size_type prefix_size ) const -> bool

inlinenodiscard

Check whether two JSON Pointers are equal up to a given number of leading tokens. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", "baz"};
const sourcemeta::core::Pointer other{"foo", "bar", "qux"};
assert(pointer.shares_prefix(other, 2));
assert(!pointer.shares_prefix(other, 3));

size()

template<typename PropertyT, typename Hash>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::GenericPointer< PropertyT, Hash >::size ( ) const -> size_type

inlinenodiscardnoexcept

Get the number of tokens in a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar"};
assert(pointer.size() == 2);

slice() [1/2]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::slice ( const std::size_t index ) const -> GenericPointer< PropertyT, Hash >

inlinenodiscard

Get a copy of the JSON Pointer starting from a given token index. This method is undefined if the index is greater than the pointer size. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", "baz"};
const sourcemeta::core::Pointer result{pointer.slice(1)};
assert(result.size() == 2);
assert(result.at(0).is_property());
assert(result.at(0).to_property() == "bar");
assert(result.at(1).is_property());
assert(result.at(1).to_property() == "baz");

slice() [2/2]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::slice ( const std::size_t start, const std::size_t end ) const -> GenericPointer< PropertyT, Hash >

inlinenodiscard

Get a copy of the JSON Pointer starting from a given token index up to (but not including) a given end index. This method is undefined if the start index is greater than the end index or if the end index is greater than the pointer size. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", "baz", "qux"};
const sourcemeta::core::Pointer result{pointer.slice(1, 3)};
assert(result.size() == 2);
assert(result.at(0).is_property());
assert(result.at(0).to_property() == "bar");
assert(result.at(1).is_property());
assert(result.at(1).to_property() == "baz");

starts_with() [1/4]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::starts_with ( const GenericPointer< PropertyT, Hash > & other ) const -> bool

inlinenodiscard

Check whether a JSON Pointer starts with another JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", "baz"};
const sourcemeta::core::Pointer prefix{"foo", "bar"};
assert(pointer.starts_with(prefix));

starts_with() [2/4]

template<typename PropertyT, typename Hash>

template<typename StringLeftT, typename StringRightT>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::starts_with ( const GenericPointer< PropertyT, Hash > & other, const StringLeftT & tail_left, const StringRightT & tail_right ) const -> bool

inlinenodiscard

Check whether a JSON Pointer starts with another JSON Pointer followed by two property tokens. This is useful for checking nested container membership without allocating a new pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "$defs", "bar", "baz"};
const sourcemeta::core::Pointer prefix{"foo"};
assert(pointer.starts_with(prefix, "$defs", "bar"));
assert(!pointer.starts_with(prefix, "$defs", "other"));

starts_with() [3/4]

template<typename PropertyT, typename Hash>

template<typename StringT>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::starts_with ( const GenericPointer< PropertyT, Hash > & other, const StringT & tail ) const -> bool

inlinenodiscard

Check whether a JSON Pointer starts with another JSON Pointer followed by a property token. This is useful for checking container membership without allocating a new pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "$defs", "bar"};
const sourcemeta::core::Pointer prefix{"foo"};
assert(pointer.starts_with(prefix, "$defs"));
assert(!pointer.starts_with(prefix, "other"));

starts_with() [4/4]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::starts_with ( const GenericPointer< PropertyT, Hash > & other, const Token & tail ) const -> bool

inlinenodiscard

Check whether a JSON Pointer plus a given tail starts with another JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar"};
const sourcemeta::core::Pointer::Token tail{"baz"};
const sourcemeta::core::Pointer prefix{"foo", "bar", "baz"};
assert(pointer.starts_with(prefix, tail));

starts_with_initial()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::starts_with_initial ( const GenericPointer< PropertyT, Hash > & other ) const -> bool

inlinenodiscard

Check whether a JSON Pointer starts with the initial part of another JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", "baz"};
const sourcemeta::core::Pointer prefix{"foo", "bar", "qux"};
assert(pointer.starts_with_initial(prefix));

starts_with_strict()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericPointer< PropertyT, Hash >::starts_with_strict ( const GenericPointer< PropertyT, Hash > & other ) const -> bool

inlinenodiscard

Check whether a JSON Pointer starts with another JSON Pointer without the two being equal. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", "baz"};
const sourcemeta::core::Pointer prefix{"foo", "bar"};
assert(pointer.starts_with_strict(prefix));
assert(!pointer.starts_with_strict(pointer));

sourcemeta::core::PointerPositionTracker

class sourcemeta::core::PointerPositionTracker

A convenient parsing callback to obtain JSON document line/column information using JSON Pointer. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const auto input{"{\n  \"foo\": \"bar\"\n}"};;
sourcemeta::core::PointerPositionTracker tracker;
sourcemeta::core::JSON document{nullptr};
sourcemeta::core::parse_json(input, document, std::ref(tracker));
assert(tracker.size() == 2);
const auto foo{tracker.get(sourcemeta::core::Pointer{"foo"})};
assert(foo.has_value());
 
// Start line and column
assert(std::get<0>(foo.value()) == 2);
assert(std::get<1>(foo.value()) == 10);
 
// End line and column
assert(std::get<3>(foo.value()) == 2);
assert(std::get<4>(foo.value()) == 14);

The tracker keeps references to the property names of the document it was populated from, so that document must outlive every query against the tracker. Reading the tracker after the source document has been destroyed is undefined behavior.

Public Types
using	Pointer = GenericPointer<JSON::String, PropertyHashJSON<JSON::String>>
	The pointer type used to look up positions.
using	Position
	The start and end line and column numbers of a value.
Public Member Functions
auto	get (const Pointer &pointer) const -> std::optional< Position >
	Get the position of the value at a given pointer.
auto	size () const -> std::size_t
	Get the number of tracked positions.
auto	to_json () const -> JSON
	Serialise the tracked positions as a JSON document.

Member Typedef Documentation

Position

using sourcemeta::core::PointerPositionTracker::Position

Initial value:

 
std::tuple<std::uint64_t, std::uint64_t, std::uint64_t, std::uint64_t>

The start and end line and column numbers of a value.

sourcemeta::core::GenericToken

class sourcemeta::core::GenericToken

template<typename PropertyT, typename Hash>
class sourcemeta::core::GenericToken< PropertyT, Hash >

A single reference token of a JSON Pointer, holding either an object property or an array index.

Public Types
using	Value = JSON
	The JSON value type these tokens convert to.
using	Property = PropertyT
	The stored type of an object property token.
using	Index = typename Value::Array::size_type
	The stored type of an array index token.
Public Member Functions
	GenericToken (Property value, const typename Hash::hash_type property_hash)
	GenericToken (const Property &value)
	GenericToken (Property &&value)
	GenericToken (const JSON::Char *const value)
	GenericToken (const JSON::Char value)
	GenericToken (const Index value)
	GenericToken (const int value)
auto	is_property () const noexcept -> bool
auto	is_hyphen () const noexcept -> bool
auto	is_index () const noexcept -> bool
auto	to_property () const noexcept -> const auto &
auto	property_hash () const noexcept -> typename Hash::hash_type
auto	property_equals (const JSON::StringView value, const typename Hash::hash_type value_hash) const noexcept -> bool
auto	to_property () noexcept -> auto &
auto	to_index () const noexcept -> Index
auto	to_json () const -> JSON

Constructor & Destructor Documentation

GenericToken() [1/7]

template<typename PropertyT, typename Hash>

sourcemeta::core::GenericToken< PropertyT, Hash >::GenericToken ( Property value, const typename Hash::hash_type property_hash )

inline

This constructor creates an JSON Pointer token from a string given its precomputed hash. This is advanced functionality that should be used with care.

GenericToken() [2/7]

template<typename PropertyT, typename Hash>

sourcemeta::core::GenericToken< PropertyT, Hash >::GenericToken ( const Property & value )

inline

This constructor creates an JSON Pointer token from a string. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{"foo"};

GenericToken() [3/7]

template<typename PropertyT, typename Hash>

sourcemeta::core::GenericToken< PropertyT, Hash >::GenericToken ( Property && value )

inline

This constructor creates an JSON Pointer token by taking ownership of a string. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
std::string name{"foo"};
const sourcemeta::core::Pointer::Token token{std::move(name)};

GenericToken() [4/7]

template<typename PropertyT, typename Hash>

sourcemeta::core::GenericToken< PropertyT, Hash >::GenericToken ( const JSON::Char *const value )

inline

This constructor creates an JSON Pointer token from a string. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{"foo"};

GenericToken() [5/7]

template<typename PropertyT, typename Hash>

sourcemeta::core::GenericToken< PropertyT, Hash >::GenericToken ( const JSON::Char value )

inline

This constructor creates an JSON Pointer token from a character. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{'a'};

GenericToken() [6/7]

template<typename PropertyT, typename Hash>

sourcemeta::core::GenericToken< PropertyT, Hash >::GenericToken ( const Index value )

inline

This constructor creates an JSON Pointer token from an item index. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{1};

GenericToken() [7/7]

template<typename PropertyT, typename Hash>

sourcemeta::core::GenericToken< PropertyT, Hash >::GenericToken ( const int value )

inline

This constructor creates an JSON Pointer token from an item index. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{1};

Member Function Documentation

is_hyphen()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericToken< PropertyT, Hash >::is_hyphen ( ) const -> bool

inlinenodiscardnoexcept

Check if a JSON Pointer token represents the hyphen constant For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token_1{"-"};
const sourcemeta::core::Pointer::Token token_2{'-'};
assert(token_1.is_hyphen());
assert(token_2.is_hyphen());

is_index()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericToken< PropertyT, Hash >::is_index ( ) const -> bool

inlinenodiscardnoexcept

Check if a JSON Pointer token represents an array index. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{2};
assert(token.is_index());

is_property()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericToken< PropertyT, Hash >::is_property ( ) const -> bool

inlinenodiscardnoexcept

Check if a JSON Pointer token represents an object property. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{"foo"};
assert(token.is_property());

property_equals()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericToken< PropertyT, Hash >::property_equals ( const JSON::StringView value, const typename Hash::hash_type value_hash ) const -> bool

inlinenodiscardnoexcept

Check whether a JSON Pointer property token equals the given string, comparing the precomputed hashes first and only falling back to a string comparison when the hash is not perfect. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{"foo"};
assert(token.property_equals(
    "foo", sourcemeta::core::JSON::Object::hash("foo")));

property_hash()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericToken< PropertyT, Hash >::property_hash ( ) const -> typename Hash::hash_type

inlinenodiscardnoexcept

If the JSON Pointer token is a property, get its pre-computed string hash. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{"foo"};
assert(token.is_property());
assert(token.property_hash() >= 0);

to_index()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericToken< PropertyT, Hash >::to_index ( ) const -> Index

inlinenodiscardnoexcept

Get the underlying value of a JSON Pointer array index token For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{2};
assert(token.is_index());
assert(token.to_index() == 2);

to_json()

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericToken< PropertyT, Hash >::to_json ( ) const -> JSON

inlinenodiscard

Convert a JSON Pointer token into a JSON document, whether it represents a property or an index. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token index{1};
const sourcemeta::core::Pointer::Token property{"foo"};
 
const sourcemeta::core::JSON json_index{index.to_json()};
const sourcemeta::core::JSON json_property{property.to_json()};
 
assert(json_index.is_integer());
assert(json_property.is_string());

to_property() [1/2]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericToken< PropertyT, Hash >::to_property ( ) const -> const auto &

inlinenodiscardnoexcept

Get the underlying value of a JSON Pointer object property token (const overload). For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer::Token token{"foo"};
assert(token.is_property());
assert(token.to_property() == "foo");

to_property() [2/2]

template<typename PropertyT, typename Hash>

auto sourcemeta::core::GenericToken< PropertyT, Hash >::to_property ( ) -> auto &

inlinenoexcept

Get the underlying value of a JSON Pointer object property token (non-const overload). For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
sourcemeta::core::Pointer::Token token{"foo"};
assert(token.is_property());
assert(token.to_property() == "foo");

sourcemeta::core::GenericPointerWalker

class sourcemeta::core::GenericPointerWalker

template<typename PointerT>
class sourcemeta::core::GenericPointerWalker< PointerT >

A walker to get every JSON Pointer in a JSON document. Note that no specific ordering is guaranteed. If you expect any ordering, sort afterwards.

Public Member Functions
	GenericPointerWalker (const JSON &document)
	Construct a walker over every location in a JSON document.

Typedef Documentation

Pointer

using sourcemeta::core::Pointer = GenericPointer<JSON::String, PropertyHashJSON<JSON::String>>

A JSON Pointer whose object property tokens own their string values.

PointerWalker

using sourcemeta::core::PointerWalker = GenericPointerWalker<WeakPointer>

Walk over every element of a JSON document, top-down, using weak pointers. Note that the resulting weak pointers hold references to strings in the JSON document, so the document must outlive the walker and any pointers obtained from it. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <string>
#include <vector>
 
const sourcemeta::core::JSON document =
  sourcemeta::core::parse_json("[ 1, 2, 3 ]");
std::vector<std::string> subpointers;
 
for (const auto &subpointer :
  sourcemeta::core::PointerWalker{document}) {
  subpointers.push_back(sourcemeta::core::to_string(subpointer));
}
 
assert(subpointers.size() == 4);
assert(subpointers.at(0) == "");
assert(subpointers.at(1) == "/0");
assert(subpointers.at(2) == "/1");
assert(subpointers.at(3) == "/2");

WeakPointer

using sourcemeta::core::WeakPointer

Initial value:

GenericPointer<
   
   std::reference_wrapper<const std::string>, PropertyHashJSON<JSON::String>>

A JSON Pointer whose object property tokens reference externally owned strings.

Function Documentation

fragment_to_pointer()

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::fragment_to_pointer

(

const URI &

uri

)

-> std::optional< Pointer >

Parse the URI fragment representation of a JSON Pointer, percent-decoding the fragment data before interpretation as mandated by RFC 3986, Section 2.4 and RFC 6901, Section 6. The result is not set if the URI has no fragment or if its fragment is not a valid JSON Pointer. For example:

#include <sourcemeta/core/uri.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::URI uri{"https://www.example.com#/foo/bar"};
const auto pointer{sourcemeta::core::fragment_to_pointer(uri)};
assert(pointer.has_value());
assert(pointer.value().size() == 2);

get() [1/6]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::get	(	const JSON &	document,
		const Pointer &	pointer ) -> const JSON &

Get a value from a JSON document using a JSON Pointer (const overload).

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"[ { \"foo\": 1 }, { \"bar\": 2 } ]"};
const sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(stream);
 
const sourcemeta::core::Pointer pointer{1, "bar"};
const sourcemeta::core::JSON &value{
  sourcemeta::core::get(document, pointer)};
assert(value.is_integer());
assert(value.to_integer() == 2);

get() [2/6]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::get	(	const JSON &	document,
		const Pointer::Token &	token ) -> const JSON &

Get a value from a JSON document using a JSON Pointer token (const overload).

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"{ \"foo\": 1 }"};
const sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(stream);
 
const sourcemeta::core::JSON &value{
  sourcemeta::core::get(document,
  sourcemeta::core::Pointer{"foo"})};
assert(value.is_integer());
assert(value.to_integer() == 1);

Get a value from a JSON document using a JSON WeakPointer token (const overload).

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"{ \"foo\": 1 }"};
const sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(stream);
 
const std::string foo = "foo";
const sourcemeta::core::JSON &value{
  sourcemeta::core::get(document,
  sourcemeta::core::WeakPointer{std::cref(foo)})};
assert(value.is_integer());
assert(value.to_integer() == 1);

get() [3/6]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::get	(	const JSON &	document,
		const WeakPointer &	pointer ) -> const JSON &

Get a value from a JSON document using a JSON WeakPointer (const overload).

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"[ { \"foo\": 1 }, { \"bar\": 2 } ]"};
const sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(stream);
 
const std::string bar = "bar";
const sourcemeta::core::WeakPointer pointer{1, std::cref(bar)};
const sourcemeta::core::JSON &value{
  sourcemeta::core::get(document, pointer)};
assert(value.is_integer());
assert(value.to_integer() == 2);

get() [4/6]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::get	(	JSON &	document,
		const Pointer &	pointer ) -> JSON &

Get a value from a JSON document using a JSON Pointer (non-const overload).

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"[ { \"foo\": 1 }, { \"bar\": 2 } ]"};
sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(stream);
assert(document.at("foo").to_integer() == 1);
 
const sourcemeta::core::Pointer pointer{1, "bar"};
sourcemeta::core::JSON &value{
  sourcemeta::core::get(document, pointer)};
assert(value.is_integer());
assert(value.to_integer() == 2);

get() [5/6]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::get	(	JSON &	document,
		const Pointer::Token &	token ) -> JSON &

Get a value from a JSON document using a JSON Pointer token (non-const overload).

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"{ \"foo\": 1 }"};
sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(stream);
 
sourcemeta::core::JSON &value{
  sourcemeta::core::get(document, "bar")};
assert(value.is_integer());
assert(value.to_integer() == 2);

get() [6/6]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::get	(	JSON &	document,
		const WeakPointer &	pointer ) -> JSON &

Get a value from a JSON document using a JSON WeakPointer (non-const overload). For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"[ { \"foo\": 1 }, { \"bar\": 2 } ]"};
auto document{sourcemeta::core::parse_json(stream)};
const sourcemeta::core::Pointer pointer{1, "bar"};
sourcemeta::core::JSON &value{
  sourcemeta::core::get(document,
  sourcemeta::core::to_weak_pointer(pointer))};
value = sourcemeta::core::JSON{3};
assert(document.at(1).at("bar").to_integer() == 3);

is_pointer()

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::is_pointer ( std::string_view input ) -> bool

noexcept

Check if the given string is a valid JSON Pointer per RFC 6901 without constructing a JSON Pointer object. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
assert(sourcemeta::core::is_pointer("/foo/bar/0"));
assert(sourcemeta::core::is_pointer(""));
assert(!sourcemeta::core::is_pointer("foo"));

is_relative_pointer()

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::is_relative_pointer ( std::string_view input ) -> bool

noexcept

Check if the given string is a valid Relative JSON Pointer per draft-handrews-relative-json-pointer-01 without constructing a pointer object. The grammar is a non-negative integer prefix (no leading zeros, no sign) followed by either a "#" or an RFC 6901 JSON Pointer suffix. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
assert(sourcemeta::core::is_relative_pointer("0/foo/bar"));
assert(sourcemeta::core::is_relative_pointer("0#"));
assert(sourcemeta::core::is_relative_pointer("120/foo"));
assert(!sourcemeta::core::is_relative_pointer("/foo/bar"));
assert(!sourcemeta::core::is_relative_pointer("01/a"));

remove() [1/2]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::remove	(	JSON &	document,
		const Pointer &	pointer ) -> bool

Remove a value from a JSON document using a JSON Pointer. Returns true if a value is removed, false otherwise.

Removing an empty pointer Pointer{}, i.e. the root, is a noop.

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"[ { \"foo\": 1, \"baz\": 1 }, { \"bar\": 2 } ]"};
sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(stream);
assert(document.at(0).defines("foo"));
 
const sourcemeta::core::Pointer pointer{0, "foo"};
sourcemeta::core::remove(document, pointer);
assert(!document.at(0).defines("foo"));
assert(document.at(0).defines("baz"));

remove() [2/2]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::remove	(	JSON &	document,
		const WeakPointer &	pointer ) -> bool

Remove a value from a JSON document using a JSON WeakPointer. Returns true if a value is removed, false otherwise.

Removing an empty pointer WeakPointer{}, i.e. the root, is a noop.

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"[ { \"foo\": 1, \"baz\": 1 }, { \"bar\": 2 } ]"};
sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(stream);
assert(document.at(0).defines("foo"));
 
const std::string foo = "foo";
const sourcemeta::core::WeakPointer pointer{0, std::cref(foo)};
sourcemeta::core::remove(document, pointer);
assert(!document.at(0).defines("foo"));
assert(document.at(0).defines("baz"));

set() [1/2]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::set	(	JSON &	document,
		const Pointer &	pointer,
		const JSON &	value ) -> void

Set a value in a JSON document using a JSON Pointer (const overload).

If the last token of the JSON Pointer is the constant - and the tail instance is an array, then the operation is equivalent to sourcemeta::core::JSON::push_back.

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"{ \"foo\": 1 }"};
sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(stream);
assert(document.at("foo").to_integer() == 1);
 
const sourcemeta::core::Pointer pointer{"foo"};
const sourcemeta::core::JSON value{2};
sourcemeta::core::set(document, pointer, value);
assert(document.at("foo").to_integer() == 2);

set() [2/2]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::set	(	JSON &	document,
		const Pointer &	pointer,
		JSON &&	value ) -> void

Set a value in a JSON document using a JSON Pointer (non-const overload).

If the last token of the JSON Pointer is the constant - and the tail instance is an array, then the operation is equivalent to sourcemeta::core::JSON::push_back.

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"{ \"foo\": 1 }"};
sourcemeta::core::JSON document =
  sourcemeta::core::parse_json(stream);
 
const sourcemeta::core::Pointer pointer{"foo"};
sourcemeta::core::set(document, pointer,
  sourcemeta::core::JSON{2});
assert(document.at("foo").to_integer() == 2);

stringify() [1/2]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::stringify	(	const Pointer &	pointer,
		std::basic_ostream< JSON::Char, JSON::CharTraits > &	stream ) -> void

Stringify the input JSON Pointer into a given C++ standard output stream. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <iostream>
#include <sstream>
 
const sourcemeta::core::Pointer pointer{"foo"};
std::ostringstream stream;
sourcemeta::core::stringify(pointer, stream);
std::cout << stream.str() << std::endl;

stringify() [2/2]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::stringify	(	const WeakPointer &	pointer,
		std::basic_ostream< JSON::Char, JSON::CharTraits > &	stream ) -> void

Stringify the input JSON WeakPointer into a given C++ standard output stream. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <iostream>
#include <sstream>
 
const std::string foo = "foo";
const sourcemeta::core::WeakPointer pointer{std::cref(foo)};
std::ostringstream stream;
sourcemeta::core::stringify(pointer, stream);
std::cout << stream.str() << std::endl;

to_pointer() [1/3]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_pointer

(

const JSON &

document

)

-> Pointer

Create a JSON Pointer from a JSON string value. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::JSON document{"/foo/bar/0"};
assert(document.is_string());
const sourcemeta::core::Pointer pointer =
  sourcemeta::core::to_pointer(document);
assert(pointer.size() == 3);

to_pointer() [2/3]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_pointer

(

const std::basic_string_view< JSON::Char, JSON::CharTraits >

input

)

-> Pointer

Create a JSON Pointer from a standard C++ string. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer =
  sourcemeta::core::to_pointer("/foo/bar/0");
assert(pointer.size() == 3);

to_pointer() [3/3]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_pointer

(

const WeakPointer &

pointer

)

-> Pointer

Convert a JSON WeakPointer into a JSON Pointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const std::string foo = "foo";
const sourcemeta::core::WeakPointer pointer{std::cref(foo)};
const sourcemeta::core::Pointer result{
  sourcemeta::core::to_pointer(pointer)};
assert(result.size() == 1);
assert(result.at(0).is_property());
assert(result.at(0).to_property() == "foo");

to_string() [1/2]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_string

(

const Pointer &

pointer

)

-> std::basic_string< JSON::Char, JSON::CharTraits, std::allocator< JSON::Char > >

Stringify the input JSON Pointer into a C++ standard string. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <string>
#include <iostream>
 
const sourcemeta::core::Pointer pointer{"foo"};
const std::string result{sourcemeta::core::to_string(pointer)};
std::cout << result << std::endl;

to_string() [2/2]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_string

(

const WeakPointer &

pointer

)

-> std::basic_string< JSON::Char, JSON::CharTraits, std::allocator< JSON::Char > >

Stringify the input JSON WeakPointer into a C++ standard string. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <string>
#include <iostream>
 
const std::string foo = "foo";
const sourcemeta::core::WeakPointer pointer{foo};
const std::string result{sourcemeta::core::to_string(pointer)};
std::cout << result << std::endl;

to_uri() [1/5]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_uri

(

const Pointer &

pointer

)

-> URI

Stringify the input JSON Pointer into a properly escaped URI fragment. For example:

#include <sourcemeta/core/uri.h>
#include <sourcemeta/core/jsonpointer.h>
 
#include <assert>
 
const sourcemeta::core::Pointer pointer{"foo"};
const sourcemeta::core::URI fragment{
  sourcemeta::core::to_uri(pointer)};
assert(fragment.recompose() == "#/foo");

to_uri() [2/5]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_uri	(	const Pointer &	pointer,
		const URI &	base ) -> URI

Stringify the input JSON Pointer into a properly escaped URI fragment alongside a base URI. For example:

#include <sourcemeta/core/uri.h>
#include <sourcemeta/core/jsonpointer.h>
 
#include <assert>
 
const sourcemeta::core::Pointer pointer{"foo"};
const sourcemeta::core::URI base{"https://www.example.com"};
const sourcemeta::core::URI fragment{
  sourcemeta::core::to_uri(pointer, base)};
assert(fragment.recompose() == "https://example.com#/foo");

to_uri() [3/5]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_uri

(

const WeakPointer &

pointer

)

-> URI

Stringify the input JSON Pointer into a properly escaped URI fragment.

to_uri() [4/5]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_uri	(	const WeakPointer &	pointer,
		const std::string_view	base ) -> URI

Stringify the input JSON Pointer into a properly escaped URI fragment alongside a base URI.

to_uri() [5/5]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_uri	(	const WeakPointer &	pointer,
		const URI &	base ) -> URI

Stringify the input JSON Pointer into a properly escaped URI fragment alongside a base URI.

to_weak_pointer()

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::to_weak_pointer

(

const Pointer &

pointer

)

-> WeakPointer

Convert a JSON Pointer into a JSON WeakPointer. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
 
const sourcemeta::core::Pointer pointer{"foo", "bar", "baz"};
const auto result{sourcemeta::core::to_weak_pointer(pointer)};
assert(result.size() == 3);
assert(result.at(0).is_property());
assert(result.at(0).to_property() == "foo");
assert(result.at(1).is_property());
assert(result.at(1).to_property() == "bar");
assert(result.at(2).is_property());
assert(result.at(2).to_property() == "baz");

try_get() [1/2]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::try_get	(	const JSON &	document,
		const Pointer &	pointer ) -> const JSON *

Get a value from a JSON document using a Pointer, returning an optional that is not set if the path does not exist in the document. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"[ { \"foo\": 1 }, { \"bar\": 2 } ]"};
const auto document{sourcemeta::core::parse_json(stream)};
const sourcemeta::core::Pointer pointer{1, "bar"};
const auto result{sourcemeta::core::try_get(document, pointer)};
assert(result);
assert(*result == document.at(1).at("bar"));

try_get() [2/2]

SOURCEMETA_CORE_JSONPOINTER_EXPORT auto sourcemeta::core::try_get	(	const JSON &	document,
		const WeakPointer &	pointer ) -> const JSON *

Get a value from a JSON document using a WeakPointer, returning an optional that is not set if the path does not exist in the document. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <cassert>
#include <sstream>
 
std::istringstream stream{"[ { \"foo\": 1 }, { \"bar\": 2 } ]"};
const auto document{sourcemeta::core::parse_json(stream)};
const std::string bar = "bar";
const sourcemeta::core::WeakPointer pointer{1, std::cref(bar)};
const auto result{sourcemeta::core::try_get(document, pointer)};
assert(result);
assert(*result == document.at(1).at("bar"));

Variable Documentation

empty_pointer

const Pointer sourcemeta::core::empty_pointer

A global constant instance of the empty JSON Pointer.

empty_weak_pointer

const WeakPointer sourcemeta::core::empty_weak_pointer

A global constant instance of the empty JSON WeakPointer.