Low-level JSON value storage type. More...

#include <nfx/json/Document.h>

Classes
class	ObjectIterator
	Object iterator wrapper that provides key() and value(). More...
class	KeysView
	Range adapter for object keys. More...
class	ValuesView
	Range adapter for object values. More...
class	MutableValuesView
	Mutable values view. More...
class	PathView
	Path iterator for traversing all paths in a JSON document. More...

Public Member Functions
	Document ()
	Default constructor.
	Document (bool value) noexcept
	Boolean constructor.
	Document (int value) noexcept
	Integer constructor.
	Document (unsigned int value) noexcept
	Unsigned integer constructor.
	Document (int64_t value) noexcept
	64-bit integer constructor
	Document (uint64_t value) noexcept
	Unsigned integer constructor.
	Document (double value) noexcept
	Double constructor.
	Document (std::string value)
	String constructor.
	Document (std::string_view value)
	String view constructor.
	Document (const char *value)
	C-string constructor.
template<size_t N>
	Document (const char(&value)[N])
	String literal constructor (non-explicit for convenience).
	Document (std::nullptr_t) noexcept
	nullptr constructor (creates null JSON value)
	Document (Array value)
	Array constructor.
	Document (Object value)
	Object constructor.
template<typename T>
	Document (T value, std::enable_if_t< std::is_same_v< T, long > &&!std::is_same_v< long, int > &&!std::is_same_v< long, int64_t >, int >=0) noexcept
	Long integer constructor (SFINAE overload for platforms where long != int && long != int64_t).
template<typename T>
	Document (T value, std::enable_if_t< std::is_same_v< T, unsigned long > &&!std::is_same_v< unsigned long, unsigned int > &&!std::is_same_v< unsigned long, uint64_t >, int >=0) noexcept
	Unsigned long integer constructor (SFINAE overload for platforms where unsigned long != unsigned int && unsigned long != uint64_t).
template<typename T>
	Document (T value, std::enable_if_t< std::is_same_v< T, long long > &&!std::is_same_v< long long, int64_t >, int >=0) noexcept
	Long long integer constructor (SFINAE overload for platforms where long long != int64_t).
template<typename T>
	Document (T value, std::enable_if_t< std::is_same_v< T, unsigned long long > &&!std::is_same_v< unsigned long long, uint64_t >, int >=0) noexcept
	Unsigned long long integer constructor (SFINAE overload for platforms where unsigned long long != uint64_t).
	Document (const Document &other)=default
	Copy constructor.
	Document (Document &&other) noexcept=default
	Move constructor.
	~Document ()=default
	Destructor.
Document &	operator= (const Document &other)=default
	Copy assignment.
Document &	operator= (Document &&other) noexcept=default
	Move assignment.
Document &	operator= (std::string value)
	Assignment from string.
Document &	operator= (bool value) noexcept
	Assignment from bool.
Document &	operator= (int64_t value) noexcept
	Assignment from int64_t.
Document &	operator= (uint64_t value) noexcept
	Assignment from uint64_t.
Document &	operator= (double value) noexcept
	Assignment from double.
Document &	operator= (std::nullptr_t) noexcept
	Assignment from nullptr (null).
bool	operator== (const Document &other) const noexcept
	Equality comparison.
std::strong_ordering	operator<=> (const Document &other) const noexcept
	Three-way comparison.
Type	type () const noexcept
	Get the JSON type.
template<Value T>
std::optional< T >	root () const
	Get the root value of this document (safe, returns optional).
template<Value T>
bool	root (T &out) const
	Get the root value of this document (output parameter version).
template<Value T>
std::optional< std::reference_wrapper< const T > >	rootRef () const
	Get a reference to the root value (safe, no copy for large objects).
template<Value T>
std::optional< std::reference_wrapper< T > >	rootRef ()
	Get a mutable reference to the root value (safe, no copy).
template<Checkable T>
bool	isRoot () const
	Check if the root value is of a specific type.
template<typename Visitor>
decltype(auto)	visit (Visitor &&visitor) const
	Visit the root value with a visitor (const version).
template<typename Visitor>
decltype(auto)	visit (Visitor &&visitor)
	Visit the root value with a visitor (mutable version).
Document *	find (std::string_view key) noexcept
	Get object member by key (mutable, returns nullptr if not found).
const Document *	find (std::string_view key) const noexcept
	Get object member by key (const version).
void	set (std::string key, Document value)
	Insert or assign object member.
bool	contains (std::string_view key) const noexcept
	Check if object contains key.
Document &	at (std::string_view key)
	Access object member by key (with bounds checking).
const Document &	at (std::string_view key) const
	Access object member by key (const version).
Document &	at (size_t index)
	Access array element with bounds checking.
const Document &	at (size_t index) const
	Access array element with bounds checking (const version).
Document &	operator[] (std::string_view key)
	Access or create object field.
const Document &	operator[] (std::string_view key) const
	Access object field (const).
Document &	operator[] (size_t index)
	Access or create array element.
const Document &	operator[] (size_t index) const
	Access array element (const).
void	clear ()
	Clear object or array.
size_t	erase (std::string_view key)
	Erase key from object.
size_t	erase (const char *key)
	Erase key from object (overload for const char*).
size_t	erase (const std::string &key)
	Erase key from object (overload for std::string).
template<typename iterator, typename = std::enable_if_t<!std::is_convertible_v<iterator, std::string_view>>>
iterator	erase (iterator it)
	Erase element from array by iterator.
template<typename iterator>
iterator	insert (iterator pos, Document value)
	Insert element into array at iterator position.
size_t	size () const noexcept
	Get array size.
bool	empty () const noexcept
	Check if container is empty.
void	push_back (Document value)
	Append to array.
void	reserve (size_t capacity)
	Reserve capacity for array or object.
size_t	capacity () const noexcept
	Get capacity of array or object.
Document &	front ()
	Get first element of array.
const Document &	front () const
	Get first element of array (const).
Document &	back ()
	Get last element of array.
const Document &	back () const
	Get last element of array (const).
auto	begin ()
	Begin iterator for arrays.
auto	end ()
	End iterator for arrays.
auto	begin () const
	Begin iterator for arrays (const).
auto	end () const
	End iterator for arrays (const).
ObjectIterator	objectBegin () const
	Begin iterator for objects (returns ObjectIterator with key/value).
ObjectIterator	objectEnd () const
	End iterator for objects.
KeysView	keys () const
	Get a range view of object keys.
ValuesView	values () const
	Get a range view of object values (const).
MutableValuesView	values ()
	Get a range view of object values (mutable).
std::string	toString (int indent=0, size_t bufferSize=0) const
	Convert to JSON string.
std::vector< uint8_t >	toBytes () const
	Convert to JSON bytes.
void	merge (const Document &other, bool overwriteArrays=true)
	Merge another Document into this one.
void	update (std::string_view path, const Document &value)
	Update value at specific path.
template<Value T>
std::optional< T >	get (std::string_view path) const
	Get typed value at specified path.
template<Value T>
bool	get (std::string_view path, T &value) const
	Get typed value at specified path into output parameter.
template<Value T>
std::optional< std::reference_wrapper< const T > >	getRef (std::string_view path) const
	Get a const reference to value at specified path.
template<Value T>
std::optional< std::reference_wrapper< T > >	getRef (std::string_view path)
	Get a mutable reference to value at specified path (zero-copy).
template<Value T>
void	set (std::string_view path, const T &value)
	Set typed value at specified path (copy version).
template<Value T>
void	set (std::string_view path, T &&value)
	Set typed value at specified path (move version).
template<Container T>
void	set (std::string_view path)
	Create empty container at specified path.
void	setNull (std::string_view path)
	Set null value at specified path.
template<Checkable T>
bool	is (std::string_view path) const
	Check if value at path is of specified type.
bool	isNull (std::string_view path) const
	Check if value at path is null.
bool	isValid () const
	Check if Document is in valid state.

Static Public Member Functions
static Document	object ()
	Create empty object.
static Document	array ()
	Create empty array.
static std::optional< Document >	fromString (std::string_view jsonStr)
	Create Document from JSON string.
static bool	fromString (std::string_view jsonStr, Document &value)
	Parse JSON string into existing Document.
static std::optional< Document >	fromBytes (const std::vector< uint8_t > &bytes)
	Create Document from JSON bytes.
static bool	fromBytes (const std::vector< uint8_t > &bytes, Document &value)
	Parse JSON bytes into existing Document.

Detailed Description

Low-level JSON value storage type.

Represents a single JSON value (null, bool, number, string, array, or object). Uses std::variant for efficient type-tagged storage with minimal overhead. Object preserves insertion order using std::vector of key-value pairs. This is the internal storage used by Document - prefer using Document for most operations.

Definition at line 107 of file Document.h.

Constructor & Destructor Documentation

◆ Document() [1/18]

nfx::json::Document::Document ( bool value )

inlinenoexcept

Boolean constructor.

Parameters

value The boolean value

◆ Document() [2/18]

nfx::json::Document::Document ( int value )

inlinenoexcept

Integer constructor.

Parameters

value The integer value

◆ Document() [3/18]

nfx::json::Document::Document ( unsigned int value )

inlinenoexcept

Unsigned integer constructor.

Parameters

value The unsigned integer value

◆ Document() [4/18]

nfx::json::Document::Document ( int64_t value )

inlinenoexcept

64-bit integer constructor

Parameters

value The 64-bit integer value

◆ Document() [5/18]

nfx::json::Document::Document ( uint64_t value )

inlinenoexcept

Unsigned integer constructor.

Parameters

value The unsigned integer value

◆ Document() [6/18]

nfx::json::Document::Document ( double value )

inlinenoexcept

Double constructor.

Parameters

value The double value

◆ Document() [7/18]

nfx::json::Document::Document ( std::string value )

inlineexplicit

String constructor.

Parameters

value The string value

◆ Document() [8/18]

nfx::json::Document::Document ( std::string_view value )

inlineexplicit

String view constructor.

Parameters

value The string view to convert to string

◆ Document() [9/18]

nfx::json::Document::Document ( const char * value )

inlineexplicit

C-string constructor.

Parameters

value The C-string to convert to string

◆ Document() [10/18]

template<size_t N>

nfx::json::Document::Document ( const char(&) value[N] )

inline

String literal constructor (non-explicit for convenience).

Template Parameters

N	Size of the string literal (including null terminator)

Parameters

value String literal

◆ Document() [11/18]

nfx::json::Document::Document ( Array value )

inlineexplicit

Array constructor.

Parameters

value The array value

◆ Document() [12/18]

nfx::json::Document::Document ( Object value )

inlineexplicit

Object constructor.

Parameters

value The object value

◆ Document() [13/18]

template<typename T>

nfx::json::Document::Document	(	T	value,
		std::enable_if_t< std::is_same_v< T, long > &&!std::is_same_v< long, int > &&!std::is_same_v< long, int64_t >, int >	= 0 )

inlinenoexcept

Long integer constructor (SFINAE overload for platforms where long != int && long != int64_t).

Parameters

value The long integer value

◆ Document() [14/18]

template<typename T>

nfx::json::Document::Document	(	T	value,
		std::enable_if_t< std::is_same_v< T, unsigned long > &&!std::is_same_v< unsigned long, unsigned int > &&!std::is_same_v< unsigned long, uint64_t >, int >	= 0 )

inlinenoexcept

Unsigned long integer constructor (SFINAE overload for platforms where unsigned long != unsigned int && unsigned long != uint64_t).

Parameters

value The unsigned long integer value

◆ Document() [15/18]

template<typename T>

nfx::json::Document::Document	(	T	value,
		std::enable_if_t< std::is_same_v< T, long long > &&!std::is_same_v< long long, int64_t >, int >	= 0 )

inlinenoexcept

Long long integer constructor (SFINAE overload for platforms where long long != int64_t).

Parameters

value The long long integer value

◆ Document() [16/18]

template<typename T>

nfx::json::Document::Document	(	T	value,
		std::enable_if_t< std::is_same_v< T, unsigned long long > &&!std::is_same_v< unsigned long long, uint64_t >, int >	= 0 )

inlinenoexcept

Unsigned long long integer constructor (SFINAE overload for platforms where unsigned long long != uint64_t).

Parameters

value The unsigned long long integer value

◆ Document() [17/18]

nfx::json::Document::Document ( const Document & other )

default

Copy constructor.

Parameters

◆ Document() [18/18]

nfx::json::Document::Document ( Document && other )

defaultnoexcept

Move constructor.

Parameters

Member Function Documentation

◆ array()

Document nfx::json::Document::array ( )

inlinestaticnodiscard

Create empty array.

Returns: A new Document containing an empty array

◆ at() [1/4]

Document & nfx::json::Document::at ( size_t index )

inlinenodiscard

Access array element with bounds checking.

Parameters

index The index to access

Returns: Reference to the value at the index

Exceptions

std::out_of_range	if index >= array size
std::runtime_error	if not an array

◆ at() [2/4]

const Document & nfx::json::Document::at ( size_t index ) const

inlinenodiscard

Access array element with bounds checking (const version).

Parameters

index The index to access

Returns: Const reference to the value at the index

Exceptions

std::out_of_range	if index >= array size
std::runtime_error	if not an array

◆ at() [3/4]

Document & nfx::json::Document::at ( std::string_view key )

inlinenodiscard

Access object member by key (with bounds checking).

Parameters

key	The key to access

Returns: Reference to the value at the key

Exceptions

std::runtime_error	if not an object
std::out_of_range	if key not found

◆ at() [4/4]

const Document & nfx::json::Document::at ( std::string_view key ) const

inlinenodiscard

Access object member by key (const version).

Parameters

key	The key to access

Returns: Const reference to the value at the key

Exceptions

std::runtime_error	if not an object
std::out_of_range	if key not found

◆ back() [1/2]

Document & nfx::json::Document::back ( )

inlinenodiscard

Get last element of array.

Returns: Reference to the last element

◆ back() [2/2]

const Document & nfx::json::Document::back ( ) const

inlinenodiscard

Get last element of array (const).

Returns: Const reference to the last element

◆ begin() [1/2]

auto nfx::json::Document::begin ( )

inlinenodiscard

Begin iterator for arrays.

Returns: iterator to the beginning

◆ begin() [2/2]

auto nfx::json::Document::begin ( ) const

inlinenodiscard

Begin iterator for arrays (const).

Returns: Const iterator to the beginning

◆ capacity()

size_t nfx::json::Document::capacity ( ) const

inlinenodiscardnoexcept

Get capacity of array or object.

Returns: The capacity of the underlying container, 0 otherwise

◆ contains()

bool nfx::json::Document::contains ( std::string_view key ) const

inlinenodiscardnoexcept

Check if object contains key.

Parameters

key	The key to search for (supports dot notation like "user.name" and array access like "data[0]")

Returns: true if the key exists, false otherwise

◆ empty()

bool nfx::json::Document::empty ( ) const

inlinenodiscardnoexcept

Check if container is empty.

Returns: True if array/object has no elements, or string has length 0, false otherwise

◆ end() [1/2]

auto nfx::json::Document::end ( )

inlinenodiscard

End iterator for arrays.

Returns: iterator to the end

◆ end() [2/2]

auto nfx::json::Document::end ( ) const

inlinenodiscard

End iterator for arrays (const).

Returns: Const iterator to the end

◆ erase() [1/4]

size_t nfx::json::Document::erase ( const char * key )

inline

Erase key from object (overload for const char*).

Parameters

key	The key to remove

Returns: 1 if the key was found and removed, 0 otherwise

◆ erase() [2/4]

size_t nfx::json::Document::erase ( const std::string & key )

inline

Erase key from object (overload for std::string).

Parameters

key	The key to remove

Returns: 1 if the key was found and removed, 0 otherwise

◆ erase() [3/4]

template<typename iterator, typename = std::enable_if_t<!std::is_convertible_v<iterator, std::string_view>>>

iterator nfx::json::Document::erase ( iterator it )

inline

Erase element from array by iterator.

Template Parameters

iterator The iterator type

Parameters

it	The iterator pointing to the element to remove

Returns: iterator to the element following the removed element

◆ erase() [4/4]

size_t nfx::json::Document::erase ( std::string_view key )

inline

Erase key from object.

Parameters

key	The key to remove (supports simple keys, dot notation, and JSON Pointer paths)

Returns: 1 if the key was found and removed, 0 otherwise

◆ find() [1/2]

const Document * nfx::json::Document::find ( std::string_view key ) const

inlinenodiscardnoexcept

Get object member by key (const version).

Parameters

key	The key to search for

Returns: Pointer to the value if found, nullptr otherwise

◆ find() [2/2]

Document * nfx::json::Document::find ( std::string_view key )

inlinenodiscardnoexcept

Get object member by key (mutable, returns nullptr if not found).

Parameters

key	The key to search for

Returns: Pointer to the value if found, nullptr otherwise

◆ fromBytes() [1/2]

std::optional< Document > nfx::json::Document::fromBytes ( const std::vector< uint8_t > & bytes )

staticnodiscard

Create Document from JSON bytes.

Parameters

bytes JSON bytes to parse

Returns: Optional Document if parsing succeeds, empty optional otherwise

◆ fromBytes() [2/2]

bool nfx::json::Document::fromBytes	(	const std::vector< uint8_t > &	bytes,
		Document &	value )

staticnodiscard

Parse JSON bytes into existing Document.

Parameters

	bytes	JSON bytes to parse
[out]	value	Document to populate

Returns: true if parsing succeeds, false otherwise

◆ fromString() [1/2]

std::optional< Document > nfx::json::Document::fromString ( std::string_view jsonStr )

staticnodiscard

Create Document from JSON string.

Parameters

jsonStr JSON string to parse

Returns: Optional Document if parsing succeeds, empty optional otherwise

◆ fromString() [2/2]

bool nfx::json::Document::fromString	(	std::string_view	jsonStr,
		Document &	value )

staticnodiscard

Parse JSON string into existing Document.

Parameters

	jsonStr	JSON string to parse
[out]	value	Document to populate

Returns: true if parsing succeeds, false otherwise

◆ front() [1/2]

Document & nfx::json::Document::front ( )

inlinenodiscard

Get first element of array.

Returns: Reference to the first element

Exceptions

std::out_of_range if array is empty

◆ front() [2/2]

const Document & nfx::json::Document::front ( ) const

inlinenodiscard

Get first element of array (const).

Returns: Const reference to the first element

Exceptions

std::out_of_range if array is empty

◆ get() [1/2]

template<Value T>

std::optional< T > nfx::json::Document::get ( std::string_view path ) const

nodiscard

Get typed value at specified path.

Template Parameters

T	Type to retrieve (string, int, double, bool, Document)

Parameters

path	Path to value (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)

Returns: Optional containing value if exists and correct type, empty otherwise

◆ get() [2/2]

template<Value T>

bool nfx::json::Document::get	(	std::string_view	path,
		T &	value ) const

nodiscard

Get typed value at specified path into output parameter.

Template Parameters

T	Type to retrieve (string, int, double, bool, Document)

Parameters

	path	Path to value (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)
[out]	value	Output parameter to store the result

Returns: true if value exists and was successfully retrieved, false otherwise

◆ getRef() [1/2]

template<Value T>

std::optional< std::reference_wrapper< T > > nfx::json::Document::getRef ( std::string_view path )

nodiscard

Get a mutable reference to value at specified path (zero-copy).

Template Parameters

T	Type to retrieve reference to

Parameters

path	Path to value (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)

Returns: std::optional<std::reference_wrapper<T>> containing mutable reference if exists and correct type

Note: Allows direct modification of large containers; Returns reference wrapped in optional - always safe

◆ getRef() [2/2]

template<Value T>

std::optional< std::reference_wrapper< const T > > nfx::json::Document::getRef ( std::string_view path ) const

nodiscard

Get a const reference to value at specified path.

Template Parameters

T	Type to retrieve reference to

Parameters

path	Path to value (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)

Returns: std::optional<std::reference_wrapper<const T>> containing reference if exists and correct type

Note: Preferred for large Object/Array to avoid copying; Returns reference wrapped in optional - always safe; Example: auto obj_ref = doc.getRef<Object>("settings"); if(obj_ref) { const Object& obj = obj_ref->get(); }

◆ insert()

template<typename iterator>

iterator nfx::json::Document::insert	(	iterator	pos,
		Document	value )

inline

Insert element into array at iterator position.

Template Parameters

iterator The iterator type

Parameters

pos	The position to insert at
value	The value to insert

Returns: iterator pointing to the inserted element

◆ is()

template<Checkable T>

bool nfx::json::Document::is ( std::string_view path ) const

nodiscard

Check if value at path is of specified type.

Template Parameters

T	Type to check for

Parameters

path	Path to check (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)

Returns: true if value exists and is of type T, false otherwise

◆ isNull()

bool nfx::json::Document::isNull ( std::string_view path ) const

nodiscard

Check if value at path is null.

Parameters

path	Path to check (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)

Returns: true if value is null, false otherwise

◆ isRoot()

template<Checkable T>

bool nfx::json::Document::isRoot ( ) const

inlinenodiscard

Check if the root value is of a specific type.

Template Parameters

T	Type to check for (must satisfy Checkable concept)

Returns: true if root value is of type T, false otherwise

Note: More explicit than is<T>("") - clearly indicates root check

◆ isValid()

bool nfx::json::Document::isValid ( ) const

nodiscard

Check if Document is in valid state.

Returns: true if valid, false otherwise

◆ keys()

KeysView nfx::json::Document::keys ( ) const

inlinenodiscard

Get a range view of object keys.

Returns: Range adapter that iterates over keys only

Note: Returns empty range for non-object types

◆ merge()

void nfx::json::Document::merge	(	const Document &	other,
		bool	overwriteArrays = true )

Merge another Document into this one.

Parameters

other	Document to merge
overwriteArrays	Whether to overwrite arrays or merge them

◆ object()

Document nfx::json::Document::object ( )

inlinestaticnodiscard

Create empty object.

Returns: A new Document containing an empty object

◆ objectBegin()

ObjectIterator nfx::json::Document::objectBegin ( ) const

inlinenodiscard

Begin iterator for objects (returns ObjectIterator with key/value).

Returns: iterator to the beginning of the object

◆ objectEnd()

ObjectIterator nfx::json::Document::objectEnd ( ) const

inlinenodiscard

End iterator for objects.

Returns: iterator to the end of the object

◆ operator<=>()

std::strong_ordering nfx::json::Document::operator<=> ( const Document & other ) const

noexcept

Three-way comparison.

Parameters

◆ operator=() [1/8]

Document & nfx::json::Document::operator= ( bool value )

inlinenoexcept

Assignment from bool.

Parameters

value The boolean value to assign

Returns: Reference to this Document

◆ operator=() [2/8]

Document & nfx::json::Document::operator= ( const Document & other )

default

Copy assignment.

Parameters

◆ operator=() [3/8]

Document & nfx::json::Document::operator= ( Document && other )

defaultnoexcept

Move assignment.

Parameters

◆ operator=() [4/8]

Document & nfx::json::Document::operator= ( double value )

inlinenoexcept

Assignment from double.

Parameters

value The double value to assign

Returns: Reference to this Document

◆ operator=() [5/8]

Document & nfx::json::Document::operator= ( int64_t value )

inlinenoexcept

Assignment from int64_t.

Parameters

value The integer value to assign

Returns: Reference to this Document

◆ operator=() [6/8]

Document & nfx::json::Document::operator= ( std::nullptr_t )

inlinenoexcept

Assignment from nullptr (null).

Returns: Reference to this Document

◆ operator=() [7/8]

Document & nfx::json::Document::operator= ( std::string value )

inline

Assignment from string.

Parameters

value The string value to assign

Returns: Reference to this Document

◆ operator=() [8/8]

Document & nfx::json::Document::operator= ( uint64_t value )

inlinenoexcept

Assignment from uint64_t.

Parameters

value The unsigned integer value to assign

Returns: Reference to this Document

◆ operator==()

bool nfx::json::Document::operator== ( const Document & other ) const

inlinenoexcept

Equality comparison.

Parameters

◆ operator[]() [1/4]

Document & nfx::json::Document::operator[] ( size_t index )

inlinenodiscard

Access or create array element.

Parameters

index The index to access or create

Returns: Reference to the value at the index

Note: Auto-converts Null to Array on first access (common pattern); Extends array with null values if index >= size; In DEBUG builds: throws std::runtime_error on type mismatch; In RELEASE builds: undefined behavior on type mismatch (no overhead); For safe access with bounds checking, use at()

Warning: Performance-critical path - minimal error checking in release builds

◆ operator[]() [2/4]

const Document & nfx::json::Document::operator[] ( size_t index ) const

inlinenodiscard

Access array element (const).

Parameters

index The index to access

Returns: Const reference to the value, or null value if out of bounds

◆ operator[]() [3/4]

Document & nfx::json::Document::operator[] ( std::string_view key )

inline

Access or create object field.

Parameters

key	The key to access or create

Returns: Reference to the value at the key

Note: Auto-converts Null to Object on first access (common pattern); In DEBUG builds: throws std::runtime_error on type mismatch; In RELEASE builds: undefined behavior on type mismatch (no overhead); For safe access with error checking, use at() or find()

Warning: Performance-critical path - minimal error checking in release builds

◆ operator[]() [4/4]

const Document & nfx::json::Document::operator[] ( std::string_view key ) const

inlinenodiscard

Access object field (const).

Parameters

key	The key to access

Returns: Const reference to the value, or null value if not found

◆ push_back()

void nfx::json::Document::push_back ( Document value )

inline

Append to array.

Parameters

value The value to append

◆ reserve()

void nfx::json::Document::reserve ( size_t capacity )

inline

Reserve capacity for array or object.

Parameters

capacity The number of elements to reserve space for

Note: For arrays, reserves space in the underlying vector; For objects, reserves space in the underlying vector of key-value pairs

◆ root() [1/2]

template<Value T>

std::optional< T > nfx::json::Document::root ( ) const

inlinenodiscard

Get the root value of this document (safe, returns optional).

Template Parameters

T	Type to retrieve

Returns: std::optional<T> containing the value if type matches, empty otherwise

Note: This method never throws exceptions; For primitives (int, double, string): lightweight copy; For large containers (Object, Array): consider rootRef<T>() to avoid copy overhead

◆ root() [2/2]

template<Value T>

bool nfx::json::Document::root ( T & out ) const

inlinenodiscard

Get the root value of this document (output parameter version).

Template Parameters

T	Type to retrieve

Parameters

[out] out Variable to fill with the value

Returns: true if value was extracted successfully, false otherwise

Note: Use this variant when you prefer output parameter style over optional

◆ rootRef() [1/2]

template<Value T>

std::optional< std::reference_wrapper< T > > nfx::json::Document::rootRef ( )

inlinenodiscard

Get a mutable reference to the root value (safe, no copy).

Template Parameters

T	Type to retrieve reference to

Returns: std::optional<std::reference_wrapper<T>> containing mutable reference if type matches

Note: Allows direct modification of large containers without copy; Returns reference wrapped in optional - always safe (no raw pointers)

◆ rootRef() [2/2]

template<Value T>

std::optional< std::reference_wrapper< const T > > nfx::json::Document::rootRef ( ) const

inlinenodiscard

Get a reference to the root value (safe, no copy for large objects).

Template Parameters

T	Type to retrieve reference to

Returns: std::optional<std::reference_wrapper<const T>> containing reference if type matches

Note: Preferred for large Object/Array to avoid copy overhead; Returns reference wrapped in optional - always safe (no raw pointers); Use root<T>() for primitives where copy is cheap

◆ set() [1/4]

void nfx::json::Document::set	(	std::string	key,
		Document	value )

inline

Insert or assign object member.

Parameters

key	The key to set
value	The value to assign

◆ set() [2/4]

template<Container T>

void nfx::json::Document::set ( std::string_view path )

Create empty container at specified path.

Template Parameters

T	Container type (Document, Object, Array)

Parameters

path	Path where to create container (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)

◆ set() [3/4]

template<Value T>

void nfx::json::Document::set	(	std::string_view	path,
		const T &	value )

Set typed value at specified path (copy version).

Template Parameters

T	Type to set (string, int, double, bool, Document)

Parameters

path	Path where to set value (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)
value	Value to set (copied)

◆ set() [4/4]

template<Value T>

void nfx::json::Document::set	(	std::string_view	path,
		T &&	value )

Set typed value at specified path (move version).

Template Parameters

T	Type to set (string, int, double, bool, Document)

Parameters

path	Path where to set value (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)
value	Value to set (moved)

◆ setNull()

void nfx::json::Document::setNull ( std::string_view path )

Set null value at specified path.

Parameters

path	Path where to set null (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)

◆ size()

size_t nfx::json::Document::size ( ) const

inlinenodiscardnoexcept

Get array size.

Returns: The number of elements in the array or object, 0 otherwise

◆ toBytes()

std::vector< uint8_t > nfx::json::Document::toBytes ( ) const

inlinenodiscard

Convert to JSON bytes.

Returns: JSON byte representation

◆ toString()

std::string nfx::json::Document::toString	(	int	indent = 0,
		size_t	bufferSize = 0 ) const

nodiscard

Convert to JSON string.

Parameters

indent	Indentation level (0 = compact output, >0 = pretty printing with N spaces)
bufferSize	Initial buffer capacity hint (0 = use default 4KB)

Returns: JSON string representation

◆ type()

Type nfx::json::Document::type ( ) const

inlinenodiscardnoexcept

Get the JSON type.

Returns: The JSON type enumeration value

◆ update()

void nfx::json::Document::update	(	std::string_view	path,
		const Document &	value )

Update value at specific path.

Parameters

path	Path to update (supports: "/key/subkey" JSON Pointer, "key.subkey" dot notation, "arr[0]" array syntax)
value	New value to set

◆ values() [1/2]

MutableValuesView nfx::json::Document::values ( )

inlinenodiscard

Get a range view of object values (mutable).

Returns: Range adapter that iterates over mutable values

Note: Returns empty range for non-object types

◆ values() [2/2]

ValuesView nfx::json::Document::values ( ) const

inlinenodiscard

Get a range view of object values (const).

Returns: Range adapter that iterates over values only

Note: Returns empty range for non-object types

◆ visit() [1/2]

template<typename Visitor>

decltype(auto) nfx::json::Document::visit ( Visitor && visitor )

inline

Visit the root value with a visitor (mutable version).

Template Parameters

Visitor Callable accepting any variant alternative type

Parameters

visitor Function/lambda to call with the underlying value

Returns: Result of the visitor call

Note: Allows modification of the underlying value through the visitor

◆ visit() [2/2]

template<typename Visitor>

decltype(auto) nfx::json::Document::visit ( Visitor && visitor ) const

inline

Visit the root value with a visitor (const version).

Template Parameters

Visitor Callable accepting any variant alternative type

Parameters

visitor Function/lambda to call with the underlying value

Returns: Result of the visitor call

Note: Enables compile-time type-safe pattern matching on JSON types; More efficient than runtime is<T>() checks - uses std::visit

Example usage with generic lambda:

doc.visit([](auto&& value) {
    using T = std::decay_t<decltype(value)>;
    if constexpr (std::is_same_v<T, int64_t>) {
        std::cout << "Integer: " << value << "\n";
    } else if constexpr (std::is_same_v<T, std::string>) {
        std::cout << "String: " << value << "\n";
    }
    // ... handle other types
});

Example with overloaded lambdas:

doc.visit(overloaded{
    [](int64_t i) { std::cout << "Int: " << i; },
    [](const std::string& s) { std::cout << "String: " << s; },
    [](const Array& a) { std::cout << "Array[" << a.size() << "]"; },
    [](auto&&) { std::cout << "Other type"; }
});

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

Document.h

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Document() [1/18]

◆ Document() [2/18]

◆ Document() [3/18]

◆ Document() [4/18]

◆ Document() [5/18]

◆ Document() [6/18]

◆ Document() [7/18]

◆ Document() [8/18]

◆ Document() [9/18]

◆ Document() [10/18]

◆ Document() [11/18]

◆ Document() [12/18]

◆ Document() [13/18]

◆ Document() [14/18]

◆ Document() [15/18]

◆ Document() [16/18]

◆ Document() [17/18]

◆ Document() [18/18]

Member Function Documentation

◆ array()

◆ at() [1/4]

◆ at() [2/4]

◆ at() [3/4]

◆ at() [4/4]

◆ back() [1/2]

◆ back() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity()

◆ contains()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ erase() [1/4]

◆ erase() [2/4]

◆ erase() [3/4]

◆ erase() [4/4]

◆ find() [1/2]

◆ find() [2/2]

◆ fromBytes() [1/2]

◆ fromBytes() [2/2]

◆ fromString() [1/2]

◆ fromString() [2/2]

◆ front() [1/2]

◆ front() [2/2]

◆ get() [1/2]

◆ get() [2/2]

◆ getRef() [1/2]

◆ getRef() [2/2]

◆ insert()

◆ is()

◆ isNull()

◆ isRoot()

◆ isValid()

◆ keys()

◆ merge()

◆ object()

◆ objectBegin()

◆ objectEnd()

◆ operator<=>()

◆ operator=() [1/8]

◆ operator=() [2/8]

◆ operator=() [3/8]

◆ operator=() [4/8]

◆ operator=() [5/8]

◆ operator=() [6/8]

◆ operator=() [7/8]

◆ operator=() [8/8]

◆ operator==()

◆ operator[]() [1/4]

◆ operator[]() [2/4]

◆ operator[]() [3/4]

◆ operator[]() [4/4]

◆ push_back()

◆ reserve()