API Documentation

The Value Class

class Value

A versatile class that can hold different JSON-compatible data types.

Encapsulates types such as null, boolean, integer, real, string, array, or object. Manages memory and supports deep copying and moving of its contents.

Public Functions

explicit Value(Type type)

Constructs a Value with a specific Type and its default value.

Parameters:

type – The initial type for this Value.

inline ~Value()

Destructor for Value.

Cleans up dynamically allocated resources depending on the current Type.

Value(const Value &other)

Copy constructor.

Creates a new Value by deep-copying the contents from another Value.

Parameters:

other – The Value to copy from.

Value(Value &&other)

Move constructor.

Transfers ownership of the resources from another Value to this one, leaving the other Value in a Null state.

Parameters:

other – The Value to move from.

Value &operator=(const Value &other)

Copy assignment operator.

Replaces the contents of the current Value by deep-copying from another Value.

Parameters:

other – The Value to copy from.

Returns:

A reference to this Value.

Value &operator=(Value &&other)

Move assignment operator.

Replaces the contents of the current Value by transferring ownership of the resources from another Value.

Parameters:

other – The Value to move from.

Returns:

A reference to this Value.

void reset()

Resets this Value to a Null type.

Frees any resources associated with the current type, if applicable.

inline bool isnull() const

Checks if this Value holds a Null type.

Returns:

True if the Value is Null, false otherwise.

inline bool isbool() const

Checks if this Value holds a Boolean type.

Returns:

True if the Value is a boolean, false otherwise.

inline bool isint() const

Checks if this Value holds an Integer type.

Returns:

True if the Value is an integer, false otherwise.

inline bool isreal() const

Checks if this Value holds a Real (floating-point) type.

Returns:

True if the Value is a floating-point number, false otherwise.

inline bool isstr() const

Checks if this Value holds a String type.

Returns:

True if the Value is a string, false otherwise.

inline bool isarr() const

Checks if this Value holds an Array type.

Returns:

True if the Value is an array, false otherwise.

inline bool isobj() const

Checks if this Value holds an Object type.

Returns:

True if the Value is an object, false otherwise.

inline bool isnum() const

Checks if this Value holds a numeric type (Integer or Real).

Returns:

True if the Value is numeric, false otherwise.

inline Value()

Default constructor.

Initializes the Value as Null.

inline Value(Boolean value)

Constructs a Value from a boolean.

Parameters:

value – The boolean value to store.

template<typename T, std::__enable_if_t<std::is_integral<T>::value, bool> = true>
inline Value(T value)

Constructs a Value from an integral type.

Template Parameters:

T – Must be an integral type.

Parameters:

value – The integral value to store.

template<typename T, std::__enable_if_t<std::is_floating_point<T>::value, bool> = true>
inline Value(T value)

Constructs a Value from a floating-point type.

Template Parameters:

T – Must be a floating-point type.

Parameters:

value – The floating-point value to store.

inline Value(const char *value)

Constructs a Value from a C-style string.

Parameters:

value – The C-style string to store.

inline Value(const String &value)

Constructs a Value from a constant std::string reference.

Parameters:

value – The string to copy into this Value.

inline Value(String &&value)

Constructs a Value by moving an std::string.

Parameters:

value – The string to move into this Value.

inline Value(const Array &value)

Constructs a Value from a constant Array reference.

Parameters:

value – The array to copy into this Value.

inline Value(Array &&value)

Constructs a Value by moving an Array.

Parameters:

value – The array to move into this Value.

inline Value(const Object &value)

Constructs a Value from a constant Object reference.

Parameters:

value – The object to copy into this Value.

inline Value(Object &&value)

Constructs a Value by moving an Object.

Parameters:

value – The object to move into this Value.

inline Value(const std::initializer_list<Value> &list)

Constructs a Value from an initializer list of Value objects (creates an Array).

Parameters:

list – The initializer list to store as an array.

inline Value &operator=(Boolean value)

Assigns a boolean value to this Value.

Resets the current Value, sets the type to Boolean, and stores the new boolean value.

Parameters:

value – The boolean value to be assigned.

Returns:

A reference to this Value.

template<typename T, std::__enable_if_t<std::is_integral<T>::value, bool> = true>
inline Value &operator=(T value)

Assigns an integral value to this Value.

Template Parameters:

T – An integral type (e.g., int, long, int64_t, etc.).

Parameters:

value – The integral value to be assigned.

Returns:

A reference to this Value.

template<typename T, std::__enable_if_t<std::is_floating_point<T>::value, bool> = true>
inline Value &operator=(T value)

Assigns a floating-point value to this Value.

Template Parameters:

T – A floating-point type (e.g., float, double, long double).

Parameters:

value – The floating-point value to be assigned.

Returns:

A reference to this Value.

inline Value &operator=(const char *value)

Assigns a C-style string to this Value.

Resets the current Value, sets the type to String, and stores a new string.

Parameters:

value – The C-style string to be assigned.

Returns:

A reference to this Value.

inline Value &operator=(const String &value)

Assigns a std::string to this Value by copy.

Resets the current Value, sets the type to String, and copies the string data.

Parameters:

value – The string to be assigned.

Returns:

A reference to this Value.

inline Value &operator=(String &&value)

Assigns a std::string to this Value by move.

Resets the current Value, sets the type to String, and moves the string data.

Parameters:

value – The string to be moved.

Returns:

A reference to this Value.

inline Value &operator=(const Array &value)

Assigns an Array to this Value by copy.

Resets the current Value, sets the type to Array, and copies the array data.

Parameters:

value – The array to be assigned.

Returns:

A reference to this Value.

inline Value &operator=(Array &&value)

Assigns an Array to this Value by move.

Resets the current Value, sets the type to Array, and moves the array data.

Parameters:

value – The array to be moved.

Returns:

A reference to this Value.

inline Value &operator=(const Object &value)

Assigns an Object to this Value by copy.

Resets the current Value, sets the type to Object, and copies the object data.

Parameters:

value – The object to be assigned.

Returns:

A reference to this Value.

inline Value &operator=(Object &&value)

Assigns an Object to this Value by move.

Resets the current Value, sets the type to Object, and moves the object data.

Parameters:

value – The object to be moved.

Returns:

A reference to this Value.

inline Value &operator=(const std::initializer_list<Value> &list)

Assigns an initializer list of Value objects to this Value as an Array.

Resets the current Value, sets the type to Array, and copies the list data into a new Array.

Parameters:

list – The initializer list to be assigned.

Returns:

A reference to this Value.

inline Boolean boolean() const

Retrieves the boolean stored in this Value.

Throws an exception if the current type is not Boolean.

Returns:

The stored boolean value.

inline Boolean &boolean()

Retrieves a reference to the boolean stored in this Value.

Throws an exception if the current type is not Boolean.

Returns:

A reference to the stored boolean value.

inline Boolean &boolean(Boolean value)

Sets the Value to a boolean and returns a reference to the stored boolean.

Parameters:

value – The boolean value to set.

Returns:

A reference to the stored boolean value.

inline Integer integer() const

Retrieves the integer stored in this Value.

Throws an exception if the current type is not Integer.

Returns:

The stored integer value.

inline Integer &integer()

Retrieves a reference to the integer stored in this Value.

Throws an exception if the current type is not Integer.

Returns:

A reference to the stored integer value.

inline Integer &integer(Integer value)

Sets the Value to an integer and returns a reference to the stored integer.

Parameters:

value – The integer value to set.

Returns:

A reference to the stored integer value.

inline Real real() const

Retrieves the floating-point number stored in this Value.

Throws an exception if the current type is not Real.

Returns:

The stored floating-point value.

inline Real &real()

Retrieves a reference to the floating-point number stored in this Value.

Throws an exception if the current type is not Real.

Returns:

A reference to the stored floating-point value.

inline Real &real(Real value)

Sets the Value to a floating-point number and returns a reference to the stored value.

Parameters:

value – The floating-point value to set.

Returns:

A reference to the stored floating-point value.

inline const String &string() const

Retrieves the string stored in this Value (const version).

Throws an exception if the current type is not String.

Returns:

A const reference to the stored string.

inline String &string()

Retrieves the string stored in this Value (non-const version).

Throws an exception if the current type is not String.

Returns:

A reference to the stored string.

inline String &string(const String &value)

Sets the Value to a string by copy and returns a reference to the stored string.

Parameters:

value – The string to set.

Returns:

A reference to the stored string.

inline String &string(String &&value)

Sets the Value to a string by move and returns a reference to the stored string.

Parameters:

value – The string to move.

Returns:

A reference to the stored string.

inline const Array &array() const

Retrieves the array stored in this Value (const version).

Throws an exception if the current type is not Array.

Returns:

A const reference to the stored array.

inline Array &array()

Retrieves the array stored in this Value (non-const version).

Throws an exception if the current type is not Array.

Returns:

A reference to the stored array.

inline Array &array(const Array &value)

Sets the Value to an array by copy and returns a reference to the stored array.

Parameters:

value – The array to copy.

Returns:

A reference to the stored array.

inline Array &array(Array &&value)

Sets the Value to an array by move and returns a reference to the stored array.

Parameters:

value – The array to move.

Returns:

A reference to the stored array.

inline const Object &object() const

Retrieves the object stored in this Value (const version).

Throws an exception if the current type is not Object.

Returns:

A const reference to the stored object.

inline Object &object()

Retrieves the object stored in this Value (non-const version).

Throws an exception if the current type is not Object.

Returns:

A reference to the stored object.

inline Object &object(const Object &value)

Sets the Value to an object by copy and returns a reference to the stored object.

Parameters:

value – The object to copy.

Returns:

A reference to the stored object.

inline Object &object(Object &&value)

Sets the Value to an object by move and returns a reference to the stored object.

Parameters:

value – The object to move.

Returns:

A reference to the stored object.

inline Boolean tobool() const

Retrieves a copy of the stored value interpreted as a boolean.

Calls the bool conversion operator under the hood.

Returns:

The boolean interpretation of this Value.

inline Integer toint() const

Retrieves a copy of the stored value interpreted as an integer.

Calls the integer conversion operator under the hood.

Returns:

The integer interpretation of this Value.

inline Real toreal() const

Retrieves a copy of the stored value interpreted as a real (floating-point) number.

Calls the real conversion operator under the hood.

Returns:

The real (floating-point) interpretation of this Value.

inline String tostr() const

Retrieves a copy of the stored value interpreted as a string.

Calls the string conversion operator under the hood.

Returns:

The string interpretation of this Value.

explicit operator Boolean() const

Converts this Value to a boolean.

If the Value cannot be converted to a boolean, a runtime exception is thrown.

Returns:

The boolean representation of this Value.

explicit operator Integer() const

Converts this Value to an integer.

If the Value cannot be converted to an integer, a runtime exception is thrown.

Returns:

The integer representation of this Value.

explicit operator Real() const

Converts this Value to a real (floating-point) number.

If the Value cannot be converted to a real, a runtime exception is thrown.

Returns:

The real (floating-point) representation of this Value.

explicit operator String() const

Converts this Value to a string.

If the Value cannot be converted to a string, a runtime exception is thrown.

Returns:

The string representation of this Value.

inline Type type() const

Retrieves the current Type of this Value.

Returns:

The Type enumeration value representing this Value’s type.

inline Value &operator()(const std::string &pointer)

Retrieves or navigates to a nested Value by a JSON Pointer-like string.

The specifics of how ‘pointer’ is interpreted may be determined by the implementation.

Parameters:

pointer – A string that denotes the path to a nested Value.

Returns:

A reference to the nested Value.

inline const Value &operator()(const std::string &pointer) const

Retrieves or navigates to a nested Value by a JSON Pointer-like string (const overload).

The specifics of how ‘pointer’ is interpreted may be determined by the implementation.

Parameters:

pointer – A string that denotes the path to a nested Value.

Returns:

A const reference to the nested Value.

inline bool operator==(Type type) const

Compares the current Value’s type to the specified Type.

Parameters:

type – The Type to compare against.

Returns:

True if this Value has the same Type, false otherwise.

inline bool operator!=(Type type) const

Compares the current Value’s type to the specified Type for inequality.

Parameters:

type – The Type to compare against.

Returns:

True if this Value does not have the same Type, false otherwise.

bool operator==(const Value &other) const

Checks whether this Value and another Value are equal.

The criteria for equality may depend on the type of each Value and the contents.

Parameters:

other – The Value to compare against.

Returns:

True if the two Values are considered equal, false otherwise.

bool operator<(const Value &other) const

Compares this Value with another Value to determine an ordering.

Parameters:

other – The Value to compare against.

Returns:

True if this Value is considered less than the other, false otherwise.

inline Value &operator[](size_t index)

Provides array-style access to the stored data by index.

If this Value is not an array, a runtime exception is thrown.

Parameters:

index – The array index to access.

Returns:

A reference to the Value at the specified index.

inline const Value &operator[](size_t index) const

Provides array-style access to the stored data by index (const version).

If this Value is not an array, a runtime exception is thrown.

Parameters:

index – The array index to access.

Returns:

A const reference to the Value at the specified index.

inline Value &operator[](const std::string &key)

Provides object-style access to the stored data by key.

If this Value is not an object, a runtime exception is thrown.

Parameters:

key – The key to access in the object.

Returns:

A reference to the Value associated with the specified key.

const Value &operator[](const std::string &key) const

Provides object-style access to the stored data by key (const version).

If this Value is not an object, or if the key is not found, a runtime exception is thrown.

Parameters:

key – The key to access in the object.

Returns:

A const reference to the Value associated with the specified key.

inline Array::const_iterator begin() const

Returns an iterator to the beginning of the array.

If the Value is not an array, a runtime exception is thrown.

Returns:

A const_iterator to the beginning of the array.

inline Array::iterator begin()

Returns an iterator to the beginning of the array (non-const version).

If the Value is not an array, a runtime exception is thrown.

Returns:

An iterator to the beginning of the array.

inline Array::const_iterator end() const

Returns an iterator to the end of the array.

If the Value is not an array, a runtime exception is thrown.

Returns:

A const_iterator to the end of the array.

inline Array::iterator end()

Returns an iterator to the end of the array (non-const version).

If the Value is not an array, a runtime exception is thrown.

Returns:

An iterator to the end of the array.

inline Value &add(const Value &value)

Adds a new element to the end of the array by copy.

If this Value is not an array, a runtime exception is thrown.

Parameters:

value – The Value to be added to the array.

Returns:

A reference to this Value (for chaining).

inline Value &add(Value &&value)

Adds a new element to the end of the array by move.

If this Value is not an array, a runtime exception is thrown.

Parameters:

value – The Value to be added (moved) into the array.

Returns:

A reference to this Value (for chaining).

inline Value &add(const String &key, const Value &value)

Inserts a key-value pair into the object by copy.

If this Value is not an object, a runtime exception is thrown.

Parameters:

• key – The key under which the Value will be stored.

• value – The Value to store under the provided key.

Returns:

A reference to this Value (for chaining).

inline Value &add(const String &key, Value &&value)

Inserts a key-value pair into the object by move.

If this Value is not an object, a runtime exception is thrown.

Parameters:

• key – The key under which the Value will be stored.

• value – The Value to store under the provided key (moved).

Returns:

A reference to this Value (for chaining).

bool contains(const String &key) const

Checks if the object contains a given key.

If this Value is not an object, a runtime exception is thrown.

Parameters:

key – The key to look for in the object.

Returns:

True if the key exists in the object, false otherwise.

size_t size() const

Returns the size of the array or object.

If this Value is neither an array nor an object, a runtime exception is thrown.

Returns:

The size of the array or object (number of elements).

bool empty() const

Checks if the array or object is empty.

If this Value is neither an array nor an object, a runtime exception is thrown.

Returns:

True if the array or object has no elements, false otherwise.

void clear()

Clears the contents of the array or object.

If this Value is neither an array nor an object, a runtime exception is thrown.

void remove(size_t index)

Removes an element from the array at the specified index.

If this Value is not an array, a runtime exception is thrown.

Parameters:

index – The index of the element to remove.

bool remove(const String &key)

Removes an element from the object by key.

If this Value is not an object, a runtime exception is thrown.

Parameters:

key – The key of the element to remove.

Returns:

True if the key existed and was removed, false otherwise.

Friends

friend void swap(Value &first, Value &second)

Swaps the contents of two Value objects.

This operation exchanges both the Value types and the underlying data.

Parameters:

• first – The first Value object.

• second – The second Value object.

The JSON Namespace

namespace Json

Enums

enum class Error

Enumeration of error codes that may result from parsing or writing JSON.

These error codes provide insight into why a JSON operation may have failed. For example, InvalidNumber indicates the parser encountered a malformed numeric value in the input.

Values:

enumerator None

No error occurred.

enumerator FileIOError

File could not be opened, read, or written to.

enumerator InvalidNumber

An invalid or malformed number was encountered during parsing.

enumerator InvalidString

An invalid or malformed string was encountered during parsing.

enumerator InvalidValueType

An invalid or unknown value type was encountered when writing.

enumerator ExpectedColon

Expected a colon ‘:’ in the JSON structure.

enumerator ExpectedComma

Expected a comma ‘,’ in the JSON structure.

enumerator ExpectedStart

Expected a valid JSON start.

enumerator ExpectedQuoteOpen

Expected a double-quote ‘”’ to open a string.

enumerator ExpectedQuoteClose

Expected a double-quote ‘”’ to close a string.

enumerator ExpectedBraceOpen

Expected an opening brace ‘{’ in the JSON object.

enumerator ExpectedBraceClose

Expected a closing brace ‘}’ in the JSON object.

enumerator ExpectedBracketOpen

Expected an opening bracket ‘[’ in the JSON array.

enumerator ExpectedBracketClose

Expected a closing bracket ‘]’ in the JSON array.

enumerator ExpectedCommaOrBraceClose

Expected either a comma ‘,’ or a closing brace ‘}’ to continue/close an object.

enumerator ExpectedCommaOrBracketClose

Expected either a comma ‘,’ or a closing bracket ‘]’ to continue/close an array.

enumerator FailedToReachEnd

The parser did not reach the end of the input as expected.

enumerator UnexpectedValueStart

An unexpected token was encountered where a JSON was supposed to start.

enum class Mode

An enumeration of modes for writing JSON.

These modes control the formatting of output when serializing a JSON Value to text.

Values:

enumerator Compact

Compact mode produces minimal whitespace and no newlines.

enumerator Readable

Readable mode uses indentation, spacing, and newlines for clarity.

Functions

Error readValue(Value &value, Parser &parser)

bool fixString(String &string, const char *ptr, size_t len)

Error readString(String &string, Parser &parser)

Error readObject(Object &object, Parser &parser)

Error readArray(Array &array, Parser &parser)

Error readNumber(Value &number, Parser &parser)

Error unfixString(String &string)

Error writeString(String string, std::ostream *stream)

Error writeReal(double number, std::ostream *stream)

Error writeValue(const Value &value, std::ostream *stream)

Error writeObject(const Object &object, std::ostream *stream)

Error writeArray(const Array &array, std::ostream *stream)

Error writeValue(const Value &value, std::ostream *stream, size_t indent)

Error writeObject(const Object &object, std::ostream *stream, size_t indent)

Error writeArray(const Array &array, std::ostream *stream, size_t indent)

Result read(Value &value, const char *str)

Result read(Value &value, const std::string &str)

Reads/parses a JSON document from an std::string into the given Value.

This function attempts to parse the string str and populate value with the resulting JSON structure.

Parameters:

• value – The Value that will be populated with the parsed JSON data.

• str – An std::string containing the JSON document.

Returns:

A Result indicating success (Error::None) or the type of error if parsing fails.

Result fread(Value &value, const std::string &path)

Reads/parses a JSON document from a file into the given Value.

This function attempts to open the file at path path, read its contents, and parse the data to populate value.

Parameters:

• value – The Value that will be populated with the parsed JSON data.

• path – The path to the file containing the JSON document.

Returns:

A Result indicating success (Error::None) or the type of error if reading/parsing fails.

Result write(const Value &value, std::ostream *stream, Mode mode = Mode::Readable)

Writes a JSON Value to a given output stream using the given mode.

This function serializes value into JSON text and writes it directly to the output stream pointed to by stream.

Parameters:

• value – The JSON Value to be serialized.

• stream – Pointer to a valid std::ostream instance where the JSON text will be written.

• mode – The desired output formatting mode. Defaults to Mode::Readable.

Returns:

A Result indicating success (Error::None) or the type of error if serialization fails.

Result write(const Value &value, std::string &data, Mode mode = Mode::Readable)

Writes a JSON Value to a string using the given output mode.

This function serializes value into a textual JSON representation and stores it in data. The mode parameter controls whether the output is formatted for readability or in a compact form.

Parameters:

• value – The JSON Value to be serialized.

• data – A reference to a std::string where the JSON text will be stored.

• mode – The desired output formatting mode. Defaults to Mode::Readable.

Returns:

A Result indicating success (Error::None) or the type of error if serialization fails.

Result fwrite(const Value &value, const std::string &path, Mode mode = Mode::Readable)

Writes a JSON Value to a file at the specified path using the given mode.

This function serializes value into JSON text and writes it to the file at path. The mode parameter controls whether the output is formatted for readability or in a compact form.

Parameters:

• value – The JSON Value to be serialized.

• path – The file path where the JSON text will be written.

• mode – The desired output formatting mode. Defaults to Mode::Readable.

Returns:

A Result indicating success (Error::None) or the type of error if the operation fails.

std::ostream &operator<<(std::ostream &os, Error error)

Outputs the textual representation of an Error code to the provided output stream.

This operator inserts a string or other representation of the error enum value into the provided os.

Parameters:

• os – The output stream to write to.

• error – The Error code to print.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, const Result &result)

Outputs the textual representation of a Result object to the provided output stream.

This operator inserts a string representation of both the error code and any relevant index information into the provided os.

Parameters:

• os – The output stream to write to.

• result – The Result object to print.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, Mode mode)

Outputs the textual representation of a Mode enum to the provided output stream.

This operator inserts a string indicating whether the mode is Compact or Readable.

Parameters:

• os – The output stream to write to.

• mode – The Mode enum value to print.

Returns:

A reference to the modified output stream.

Result sread(Value &value, const char *str)

Reads/parses a JSON document from a C-string into the given Value.

This function attempts to parse the null-terminated string str and populate value with the resulting JSON structure.

Parameters:

• value – The Value that will be populated with the parsed JSON data.

• str – A null-terminated C-string containing the JSON document.

Returns:

A Result indicating success (Error::None) or the type of error if parsing fails.

struct Parser

struct Result

#include <json.h>

A struct representing the result of parsing or writing a JSON document.

This struct holds the error code indicating whether the operation succeeded, and, in case of reading, how many bytes were processed.

Public Functions

inline Result(Error error = Error::None, size_t index = size_t(-1))

Constructs a Result object.

Parameters:

• error – The error code (defaults to Error::None).

• index – The number of bytes processed (defaults to size_t(-1)).

inline operator bool() const

Indicates success or failure of the operation as a boolean.

Returns:

True if error is Error::None, otherwise false.

Public Members

Error error

The error code indicating success or failure of the operation.

size_t index

The number of bytes processed (e.g., from an input string). Typically set when reading/parsing a JSON document.

The XML Namespace

namespace XML

Typedefs

using Nodes = std::vector<Node>

Alias representing a collection of Node objects.

Enums

enum class Error

Enumeration of possible errors that can occur while working with XML.

These errors indicate why an XML operation (such as reading or writing) might have failed.

Values:

enumerator None

No error occurred.

enumerator FileIOError

The file could not be opened, read, or written.

enumerator ParseError

A general parsing error occurred (malformed XML structure).

enum class Parse

Parsing modes for XML input.

These modes control how the XML input is parsed and trimmed.

Values:

enumerator ElementsTrimmed

Read only element nodes, trimming whitespace within elements.

enumerator FullTrimmed

Read the entire XML document, trimming all extraneous whitespace.

enumerator Elements

Read only element nodes without trimming whitespace.

enumerator Full

Read the entire XML document without trimming whitespace.

enum class Mode

Output modes for XML serialization.

These modes control the formatting of XML output when writing.

Values:

enumerator Compact

Compact output with minimal whitespace.

enumerator Readable

Readable output with indentation and newlines.

Functions

bool readAll(const std::string &path, std::string &content)

Result sread(Nodes &nodes, const char *input, Parse mode = Parse::ElementsTrimmed)

Parses an XML document from a C-string into a list of Nodes.

Depending on mode, whitespace and certain node types may be trimmed or discarded.

Parameters:

• nodes – Reference to a Nodes container where parsed nodes will be stored.

• input – A null-terminated C-string containing XML data.

• mode – The parsing mode indicating how whitespace and nodes are handled.

Returns:

A Result indicating success or error details if parsing fails.

Result read(Nodes &nodes, const std::string &input, Parse mode = Parse::ElementsTrimmed)

Parses an XML document from an std::string into a list of Nodes.

Depending on mode, whitespace and certain node types may be trimmed or discarded.

Parameters:

• nodes – Reference to a Nodes container where parsed nodes will be stored.

• input – A std::string containing XML data.

• mode – The parsing mode indicating how whitespace and nodes are handled.

Returns:

A Result indicating success or error details if parsing fails.

Result fread(Nodes &nodes, const std::string &path, Parse mode = Parse::ElementsTrimmed)

Reads and parses an XML document from a file into a list of Nodes.

Opens the file at path, reads its contents, and parses them according to mode.

Parameters:

• nodes – Reference to a Nodes container where parsed nodes will be stored.

• path – The path of the file containing the XML data.

• mode – The parsing mode indicating how whitespace and nodes are handled.

Returns:

A Result indicating success or error details if reading/parsing fails.

Result write(const Nodes &nodes, std::string &output, Mode mode = Mode::Readable)

Writes a list of Nodes to a string in XML format.

The mode parameter controls whether the output is compact or readable with indentation and newlines.

Parameters:

• nodes – The list of Nodes to serialize.

• output – A reference to the string where the XML data will be written.

• mode – The output mode (compact or readable).

Returns:

A Result indicating success or error details if writing fails.

Result write(const Nodes &nodes, std::ostream &stream, Mode mode = Mode::Readable)

Writes a list of Nodes to a given output stream in XML format.

The mode parameter controls whether the output is compact or readable with indentation and newlines.

Parameters:

• nodes – The list of Nodes to serialize.

• stream – The output stream to write to.

• mode – The output mode (compact or readable).

Returns:

A Result indicating success or error details if writing fails.

Result fwrite(const Nodes &nodes, std::string &path, Mode mode = Mode::Readable)

Writes a list of Nodes to a file at the specified path in XML format.

Opens or creates the file at path and writes the serialized XML data. The mode parameter controls whether the output is compact or readable.

Parameters:

• nodes – The list of Nodes to serialize.

• path – The file path where the XML data will be written.

• mode – The output mode (compact or readable).

Returns:

A Result indicating success or error details if writing fails.

std::ostream &operator<<(std::ostream &os, Error error)

Inserts a textual representation of an Error enum into the given output stream.

This operator typically displays the name of the error code (e.g., “None”, “FileIOError”, “ParseError”).

Parameters:

• os – The output stream to write to.

• error – The Error enum value to display.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, const Result &result)

Inserts a textual representation of a Result object into the given output stream.

This operator may display the error code, index, and any associated message.

Parameters:

• os – The output stream to write to.

• result – The Result object to display.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, const Nodes &nodes)

Inserts a textual representation of multiple Nodes into the given output stream.

The exact formatting is implementation-specific; typically prints each Node in turn.

Parameters:

• os – The output stream to write to.

• nodes – The list of Nodes to display.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, const Node &node)

Inserts a textual representation of a single Node into the given output stream.

The exact formatting is implementation-specific; typically includes node type, name, attributes, and value.

Parameters:

• os – The output stream to write to.

• node – The Node to display.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, Parse parse)

Inserts a textual representation of a Parse enum into the given output stream.

This operator typically displays the name of the parse mode (e.g., “ElementsTrimmed”).

Parameters:

• os – The output stream to write to.

• parse – The Parse enum value to display.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, Mode mode)

Inserts a textual representation of a Mode enum into the given output stream.

This operator typically displays either “Compact” or “Readable”.

Parameters:

• os – The output stream to write to.

• mode – The Mode enum value to display.

Returns:

A reference to the modified output stream.

void swap(Node &first, Node &second)

This function exchanges the type, name, value, attributes, and child nodes of first and second, providing a no-throw swap mechanism.

Parameters:

• first – The first Node.

• second – The second Node.

struct Reader

struct Writer

struct Result

#include <xml.h>

Result structure for XML operations.

This struct holds the status of an XML operation, including an error code, the position/index of the error if any, and an optional message.

Public Functions

inline Result(Error error = Error::None, size_t index = size_t(-1), const String &message = {})

Constructs a Result object.

Parameters:

• error – The error code. Defaults to Error::None (no error).

• index – The position where an error was encountered (if any). Defaults to size_t(-1).

• message – An optional string describing the error in more detail.

inline operator bool() const

Boolean conversion operator indicating success or failure.

Returns:

True if error is Error::None; otherwise false.

Public Members

Error error

The error code indicating success or type of failure.

size_t index

The index (e.g., character or byte position) where an error was detected.

std::string message

Additional message describing the error or context.

class Node

#include <xml.h>

A class representing an XML node.

Each Node may be one of several types (Element, CData, Comment, Declaration, DocType, ProcInfo) and may contain child nodes, attributes, or textual data.

Public Types

enum Type

Enumeration of node types.

Values:

enumerator Element

An element node, which may have a tag name, value, attributes, and child nodes.

enumerator CData

A CDATA section node, storing unescaped character data.

enumerator Comment

A comment node, storing comment text.

enumerator Declaration

An XML declaration node, possibly holding version, encoding, and standalone attributes.

enumerator DocType

A DOCTYPE node, storing the document type definition or reference.

enumerator ProcInfo

A processing instruction node, typically containing a target and instructions.

using Attribs = std::unordered_map<String, String>

A map of attribute key-value pairs for this Node.

Public Functions

inline explicit Node(Type type = Type::Element)

Constructs a Node with the specified type.

Parameters:

type – The type of the node. Defaults to Type::Element.

Node(const Node &other) = default

Copy constructor.

Parameters:

other – The Node to copy from.

Node(Node &&other) = default

Move constructor.

Parameters:

other – The Node to move from.

Node &operator=(const Node &other) = default

Copy assignment operator.

Parameters:

other – The Node to copy from.

Returns:

A reference to this Node.

Node &operator=(Node &&other) = default

Move assignment operator.

Parameters:

other – The Node to move from.

Returns:

A reference to this Node.

inline void reset()

Resets the Node to its default state (Type::Element with empty data).

This function clears the node name, value, attributes, and child nodes, and sets the node type to Element.

inline Type type() const

Gets the type of this Node.

Returns:

The current Type of this Node.

inline bool operator==(Type type) const

Checks if this Node is of the specified Type.

Parameters:

type – The Type to compare against.

Returns:

True if they match, otherwise false.

inline bool operator!=(Type type) const

Checks if this Node is not of the specified Type.

Parameters:

type – The Type to compare against.

Returns:

True if they differ, otherwise false.

inline bool operator==(const Node &other) const

Checks if this Node is equal to another Node.

Two Nodes are considered equal if they have the same type, name, value, attributes, and child nodes.

Parameters:

other – The Node to compare with.

Returns:

True if they are equal, otherwise false.

inline Node &operator[](size_t index)

Access the child node at the specified index (non-const).

This operator assumes that the current node can have child nodes (i.e., the Node is typically of Type::Element). If index is out of range, the behavior is undefined or may trigger an assertion.

Parameters:

index – The zero-based index of the desired child node.

Returns:

A reference to the child node at the given index.

inline const Node &operator[](size_t index) const

Access the child node at the specified index (const).

This operator returns a const reference to the child node at index. If index is out of range, the behavior is undefined or may trigger an assertion.

Parameters:

index – The zero-based index of the desired child node.

Returns:

A const reference to the child node at the given index.

inline String &operator[](const String &key)

Access or create an attribute with the specified key (non-const).

If the attribute key exists, returns a reference to its value. Otherwise, creates a new attribute with key key and a default-constructed value, then returns a reference to that value.

Parameters:

key – The name of the attribute to access.

Returns:

A reference to the attribute value (which can be modified).

inline const String &operator[](const String &key) const

Access the attribute with the specified key (const).

If the attribute key exists, returns a const reference to its value. If the attribute does not exist, an assertion triggers a runtime exception.

Parameters:

key – The name of the attribute to access.

Returns:

A const reference to the attribute value.

inline Nodes::const_iterator begin() const

Returns a const iterator pointing to the first child node.

This function assumes the Node can hold child nodes (Type::Element). If there are no child nodes, begin() equals end().

Returns:

A const iterator to the beginning of the child node list.

inline Nodes::iterator begin()

Returns an iterator pointing to the first child node.

This function allows modification of child nodes. If there are no child nodes, begin() equals end().

Returns:

An iterator to the beginning of the child node list.

inline Nodes::const_iterator end() const

Returns a const iterator pointing to the end of the child node list.

This marks the past-the-end position; it does not refer to a valid child node.

Returns:

A const iterator to the end of the child node list.

inline Nodes::iterator end()

Returns an iterator pointing to the end of the child node list.

This marks the past-the-end position; it does not refer to a valid child node.

Returns:

An iterator to the end of the child node list.

inline Node &add(const Node &node)

Adds a copy of the given node to the child node list.

This function pushes node onto the list of child nodes. It is assumed the current Node can hold child nodes (Type::Element).

Parameters:

node – The Node to be copied and appended.

Returns:

A reference to the current Node (for chaining).

inline Node &add(Node &&node)

Adds a moved node to the child node list.

This function pushes node (via std::move) onto the list of child nodes. It is assumed the current Node can hold child nodes (Type::Element).

Parameters:

node – The Node to be moved and appended.

Returns:

A reference to the current Node (for chaining).

inline Node &add(const String &key, const String &value)

Adds or updates an attribute with the specified key-value pair (copy).

If the attribute key already exists, it is overwritten. Otherwise, a new attribute is created.

Parameters:

• key – The attribute name.

• value – The attribute value.

Returns:

A reference to the current Node (for chaining).

inline Node &add(const String &key, String &&value)

Adds or updates an attribute with the specified key-value pair (move).

If the attribute key already exists, it is overwritten. Otherwise, a new attribute is created using the moved string.

Parameters:

• key – The attribute name.

• value – The attribute value (will be moved).

Returns:

A reference to the current Node (for chaining).

inline size_t size() const

Returns the number of child nodes in this Node.

Returns:

The size of the child node list.

inline bool empty() const

Checks if this Node has any child nodes.

Returns:

True if there are no child nodes, otherwise false.

inline void clear()

Clears all child nodes from this Node.

This operation does not remove attributes or alter the node type/name/value. It only clears the child nodes vector.

inline void remove(size_t index)

Removes the child node at the specified index.

This function erases the child node at position index. If index is out of range, the behavior is undefined or may trigger an assertion.

Parameters:

index – The zero-based index of the child node to remove.

inline bool remove(const String &key)

Removes an attribute by its key.

If the attribute key exists, it is erased from the internal attributes map.

Parameters:

key – The name of the attribute to remove.

Returns:

True if the attribute was removed, otherwise false.

inline bool iselem() const

Checks if this Node is an Element type.

Returns:

True if the node type is Type::Element, otherwise false.

inline bool iscdata() const

Checks if this Node is a CData section type.

Returns:

True if the node type is Type::CData, otherwise false.

inline bool iscomment() const

Checks if this Node is a Comment type.

Returns:

True if the node type is Type::Comment, otherwise false.

inline bool isdecl() const

Checks if this Node is a Declaration type.

Returns:

True if the node type is Type::Declaration, otherwise false.

inline bool isdoctype() const

Checks if this Node is a DocType type.

Returns:

True if the node type is Type::DocType, otherwise false.

inline bool ispi() const

Checks if this Node is a Processing Instruction type.

Returns:

True if the node type is Type::ProcInfo, otherwise false.

inline const String &name() const

Gets the name of the Node (const).

This function is only valid if the Node type is either Element or ProcInfo. If the Node’s type is neither, an assertion triggers a runtime exception.

Returns:

A const reference to the Node’s name.

inline String &name()

Gets the name of the Node (non-const).

This function is only valid if the Node type is either Element or ProcInfo. If the Node’s type is neither, an assertion triggers a runtime exception.

Returns:

A reference to the Node’s name, allowing modification.

inline String &name(const String &name)

Sets the name of the Node using a copy, then returns a reference to it.

This function is only valid if the Node type is either Element or ProcInfo. If the Node’s type is neither, an assertion triggers a runtime exception.

Parameters:

name – The new name to assign to this Node.

Returns:

A reference to the Node’s name after assignment.

inline String &name(String &&name)

Sets the name of the Node using a move operation, then returns a reference to it.

This function is only valid if the Node type is either Element or ProcInfo. If the Node’s type is neither, an assertion triggers a runtime exception.

Parameters:

name – The new name to assign to this Node (will be moved).

Returns:

A reference to the Node’s name after assignment.

inline const String &value() const

Gets the value of the Node (const).

This function is not valid for Declaration nodes. If the Node’s type is Type::Declaration, an assertion triggers a runtime exception.

Returns:

A const reference to the Node’s value.

inline String &value()

Gets the value of the Node (non-const).

This function is not valid for Declaration nodes. If the Node’s type is Type::Declaration, an assertion triggers a runtime exception.

Returns:

A reference to the Node’s value, allowing modification.

inline String &value(const String &value)

Sets the value of the Node using a copy, then returns a reference to it.

This function is not valid for Declaration nodes. If the Node’s type is Type::Declaration, an assertion triggers a runtime exception.

Parameters:

value – The new value to assign to this Node.

Returns:

A reference to the Node’s value after assignment.

inline String &value(String &&value)

Sets the value of the Node using a move operation, then returns a reference to it.

This function is not valid for Declaration nodes. If the Node’s type is Type::Declaration, an assertion triggers a runtime exception.

Parameters:

value – The new value to assign to this Node (will be moved).

Returns:

A reference to the Node’s value after assignment.

inline Attribs &attribs()

Gets the attribute map (non-const).

This function is only valid if the Node type is Element or Declaration. Otherwise, an assertion triggers a runtime exception.

Returns:

A reference to the map of attribute key-value pairs.

inline const Attribs &attribs() const

Gets the attribute map (const).

This function is only valid if the Node type is Element or Declaration. Otherwise, an assertion triggers a runtime exception.

Returns:

A const reference to the map of attribute key-value pairs.

inline Attribs &attribs(const Attribs &attribs)

Sets the attribute map by copy, then returns a reference to it.

This function is only valid if the Node type is Element or Declaration. Otherwise, an assertion triggers a runtime exception.

Parameters:

attribs – The new attribute map to copy.

Returns:

A reference to the Node’s attribute map after assignment.

inline Attribs &attribs(Attribs &&attribs)

Sets the attribute map by move, then returns a reference to it.

This function is only valid if the Node type is Element or Declaration. Otherwise, an assertion triggers a runtime exception.

Parameters:

attribs – The new attribute map to move.

Returns:

A reference to the Node’s attribute map after assignment.

inline Nodes &nodes()

Gets the collection of child nodes (non-const).

This function is only valid if the Node type is Element. Otherwise, an assertion triggers a runtime exception.

Returns:

A reference to the vector of child nodes.

inline const Nodes &nodes() const

Gets the collection of child nodes (const).

This function is only valid if the Node type is Element. Otherwise, an assertion triggers a runtime exception.

Returns:

A const reference to the vector of child nodes.

inline Nodes &nodes(const Nodes &nodes)

Sets the collection of child nodes by copy, then returns a reference to it.

This function is only valid if the Node type is Element. Otherwise, an assertion triggers a runtime exception.

Parameters:

nodes – The new list of child nodes to copy.

Returns:

A reference to the Node’s children after assignment.

inline Nodes &nodes(Nodes &&nodes)

Sets the collection of child nodes by move, then returns a reference to it.

This function is only valid if the Node type is Element. Otherwise, an assertion triggers a runtime exception.

Parameters:

nodes – The new list of child nodes to move.

Returns:

A reference to the Node’s children after assignment.

Friends

friend void swap(Node &first, Node &second)

Swaps the contents of two Nodes.

This function exchanges the type, name, value, attributes, and child nodes of first and second, providing a no-throw swap mechanism.

Parameters:

• first – The first Node.

• second – The second Node.

The SQLite Namespace

Warning

doxygennamespace: Cannot find namespace “Neyson::SQLite” in doxygen xml output for project “Neyson” from directory: _build/xml/

The Neyson Namespace

namespace Neyson

Main namespace of the Neyson library.

Contains all fundamental components for handling JSON, XML, and SQLite

Typedefs

using Boolean = bool

Boolean data type that a Value can hold.

using Integer = int64_t

Integer data type that a Value can hold.

Uses a 64-bit signed integer type for storage.

using Real = double

Floating-point data type that a Value can hold.

Uses a double-precision floating-point type for storage.

using String = std::string

String data type that a Value can hold.

using Array = std::vector<Value>

Array data type that a Value can hold.

Internally represented as a std::vector of Value objects.

using Object = std::unordered_map<String, Value>

Object data type that a Value can hold.

Internally represented as a std::unordered_map of String-Value pairs.

Enums

enum class Type

The type enumeration that a Value can hold.

This enumeration defines the possible data types that can be stored in a Value object.

Values:

enumerator Null

Represents a null JSON value.

enumerator Boolean

Represents a boolean JSON value.

enumerator Integer

Represents an integer JSON value.

enumerator Real

Represents a real (floating-point) JSON value.

enumerator String

Represents a string JSON value.

enumerator Array

Represents an array JSON value.

enumerator Object

Represents an object JSON value.

Functions

template<typename T>
void print(T &&value)

template<typename Head, typename ...Tail>
void print(Head &&head, Tail&&... tail)

inline void print()

std::string _search(const std::string &pointer, size_t &start)

Value &search(Value &value, const std::string &pointer, size_t start)

const Value &search(const Value &value, const std::string &pointer, size_t start)

void swap(Value &first, Value &second)

This operation exchanges both the Value types and the underlying data.

Parameters:

• first – The first Value object.

• second – The second Value object.

std::ostream &operator<<(std::ostream &os, Type type)

Overloads the insertion operator to print the Type enumeration.

Parameters:

• os – The output stream.

• type – The Type to be printed.

Returns:

A reference to the output stream.

std::ostream &operator<<(std::ostream &os, const Value &value)

Outputs a Neyson::Value to the provided output stream.

The exact textual representation is determined by the implementation.

Parameters:

• os – The output stream where the Value will be written.

• value – The Value to print.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, const Array &array)

Outputs a Neyson::Array to the provided output stream.

The exact textual representation is determined by the implementation.

Parameters:

• os – The output stream where the Array will be written.

• array – The Array to print.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, const Object &object)

Outputs a Neyson::Object to the provided output stream.

The exact textual representation is determined by the implementation.

Parameters:

• os – The output stream where the Object will be written.

• object – The Object to print.

Returns:

A reference to the modified output stream.

struct Exception : public std::exception

#include <value.h>

Exception class used throughout the Neyson library.

Inherits from std::exception and stores a custom error message.

Public Functions

inline explicit Exception(const std::string &message)

Constructs an Exception with the specified message.

Parameters:

message – The error message associated with this exception.

inline virtual const char *what() const noexcept

Returns the error message as a C-style string.

Returns:

The error message.

virtual ~Exception() noexcept = default

Virtual destructor.

Public Members

std::string message

The stored error message.

class Value

#include <value.h>

A versatile class that can hold different JSON-compatible data types.

Encapsulates types such as null, boolean, integer, real, string, array, or object. Manages memory and supports deep copying and moving of its contents.

Public Functions

explicit Value(Type type)

Constructs a Value with a specific Type and its default value.

Parameters:

type – The initial type for this Value.

inline ~Value()

Destructor for Value.

Cleans up dynamically allocated resources depending on the current Type.

Value(const Value &other)

Copy constructor.

Creates a new Value by deep-copying the contents from another Value.

Parameters:

other – The Value to copy from.

Value(Value &&other)

Move constructor.

Transfers ownership of the resources from another Value to this one, leaving the other Value in a Null state.

Parameters:

other – The Value to move from.

Value &operator=(const Value &other)

Copy assignment operator.

Replaces the contents of the current Value by deep-copying from another Value.

Parameters:

other – The Value to copy from.

Returns:

A reference to this Value.

Value &operator=(Value &&other)

Move assignment operator.

Replaces the contents of the current Value by transferring ownership of the resources from another Value.

Parameters:

other – The Value to move from.

Returns:

A reference to this Value.

void reset()

Resets this Value to a Null type.

Frees any resources associated with the current type, if applicable.

inline bool isnull() const

Checks if this Value holds a Null type.

Returns:

True if the Value is Null, false otherwise.

inline bool isbool() const

Checks if this Value holds a Boolean type.

Returns:

True if the Value is a boolean, false otherwise.

inline bool isint() const

Checks if this Value holds an Integer type.

Returns:

True if the Value is an integer, false otherwise.

inline bool isreal() const

Checks if this Value holds a Real (floating-point) type.

Returns:

True if the Value is a floating-point number, false otherwise.

inline bool isstr() const

Checks if this Value holds a String type.

Returns:

True if the Value is a string, false otherwise.

inline bool isarr() const

Checks if this Value holds an Array type.

Returns:

True if the Value is an array, false otherwise.

inline bool isobj() const

Checks if this Value holds an Object type.

Returns:

True if the Value is an object, false otherwise.

inline bool isnum() const

Checks if this Value holds a numeric type (Integer or Real).

Returns:

True if the Value is numeric, false otherwise.

inline Value()

Default constructor.

Initializes the Value as Null.

inline Value(Boolean value)

Constructs a Value from a boolean.

Parameters:

value – The boolean value to store.

template<typename T, std::__enable_if_t<std::is_integral<T>::value, bool> = true>
inline Value(T value)

Constructs a Value from an integral type.

Template Parameters:

T – Must be an integral type.

Parameters:

value – The integral value to store.

template<typename T, std::__enable_if_t<std::is_floating_point<T>::value, bool> = true>
inline Value(T value)

Constructs a Value from a floating-point type.

Template Parameters:

T – Must be a floating-point type.

Parameters:

value – The floating-point value to store.

inline Value(const char *value)

Constructs a Value from a C-style string.

Parameters:

value – The C-style string to store.

inline Value(const String &value)

Constructs a Value from a constant std::string reference.

Parameters:

value – The string to copy into this Value.

inline Value(String &&value)

Constructs a Value by moving an std::string.

Parameters:

value – The string to move into this Value.

inline Value(const Array &value)

Constructs a Value from a constant Array reference.

Parameters:

value – The array to copy into this Value.

inline Value(Array &&value)

Constructs a Value by moving an Array.

Parameters:

value – The array to move into this Value.

inline Value(const Object &value)

Constructs a Value from a constant Object reference.

Parameters:

value – The object to copy into this Value.

inline Value(Object &&value)

Constructs a Value by moving an Object.

Parameters:

value – The object to move into this Value.

inline Value(const std::initializer_list<Value> &list)

Constructs a Value from an initializer list of Value objects (creates an Array).

Parameters:

list – The initializer list to store as an array.

inline Value &operator=(Boolean value)

Assigns a boolean value to this Value.

Resets the current Value, sets the type to Boolean, and stores the new boolean value.

Parameters:

value – The boolean value to be assigned.

Returns:

A reference to this Value.

template<typename T, std::__enable_if_t<std::is_integral<T>::value, bool> = true>
inline Value &operator=(T value)

Assigns an integral value to this Value.

Template Parameters:

T – An integral type (e.g., int, long, int64_t, etc.).

Parameters:

value – The integral value to be assigned.

Returns:

A reference to this Value.

template<typename T, std::__enable_if_t<std::is_floating_point<T>::value, bool> = true>
inline Value &operator=(T value)

Assigns a floating-point value to this Value.

Template Parameters:

T – A floating-point type (e.g., float, double, long double).

Parameters:

value – The floating-point value to be assigned.

Returns:

A reference to this Value.

inline Value &operator=(const char *value)

Assigns a C-style string to this Value.

Resets the current Value, sets the type to String, and stores a new string.

Parameters:

value – The C-style string to be assigned.

Returns:

A reference to this Value.

inline Value &operator=(const String &value)

Assigns a std::string to this Value by copy.

Resets the current Value, sets the type to String, and copies the string data.

Parameters:

value – The string to be assigned.

Returns:

A reference to this Value.

inline Value &operator=(String &&value)

Assigns a std::string to this Value by move.

Resets the current Value, sets the type to String, and moves the string data.

Parameters:

value – The string to be moved.

Returns:

A reference to this Value.

inline Value &operator=(const Array &value)

Assigns an Array to this Value by copy.

Resets the current Value, sets the type to Array, and copies the array data.

Parameters:

value – The array to be assigned.

Returns:

A reference to this Value.

inline Value &operator=(Array &&value)

Assigns an Array to this Value by move.

Resets the current Value, sets the type to Array, and moves the array data.

Parameters:

value – The array to be moved.

Returns:

A reference to this Value.

inline Value &operator=(const Object &value)

Assigns an Object to this Value by copy.

Resets the current Value, sets the type to Object, and copies the object data.

Parameters:

value – The object to be assigned.

Returns:

A reference to this Value.

inline Value &operator=(Object &&value)

Assigns an Object to this Value by move.

Resets the current Value, sets the type to Object, and moves the object data.

Parameters:

value – The object to be moved.

Returns:

A reference to this Value.

inline Value &operator=(const std::initializer_list<Value> &list)

Assigns an initializer list of Value objects to this Value as an Array.

Resets the current Value, sets the type to Array, and copies the list data into a new Array.

Parameters:

list – The initializer list to be assigned.

Returns:

A reference to this Value.

inline Boolean boolean() const

Retrieves the boolean stored in this Value.

Throws an exception if the current type is not Boolean.

Returns:

The stored boolean value.

inline Boolean &boolean()

Retrieves a reference to the boolean stored in this Value.

Throws an exception if the current type is not Boolean.

Returns:

A reference to the stored boolean value.

inline Boolean &boolean(Boolean value)

Sets the Value to a boolean and returns a reference to the stored boolean.

Parameters:

value – The boolean value to set.

Returns:

A reference to the stored boolean value.

inline Integer integer() const

Retrieves the integer stored in this Value.

Throws an exception if the current type is not Integer.

Returns:

The stored integer value.

inline Integer &integer()

Retrieves a reference to the integer stored in this Value.

Throws an exception if the current type is not Integer.

Returns:

A reference to the stored integer value.

inline Integer &integer(Integer value)

Sets the Value to an integer and returns a reference to the stored integer.

Parameters:

value – The integer value to set.

Returns:

A reference to the stored integer value.

inline Real real() const

Retrieves the floating-point number stored in this Value.

Throws an exception if the current type is not Real.

Returns:

The stored floating-point value.

inline Real &real()

Retrieves a reference to the floating-point number stored in this Value.

Throws an exception if the current type is not Real.

Returns:

A reference to the stored floating-point value.

inline Real &real(Real value)

Sets the Value to a floating-point number and returns a reference to the stored value.

Parameters:

value – The floating-point value to set.

Returns:

A reference to the stored floating-point value.

inline const String &string() const

Retrieves the string stored in this Value (const version).

Throws an exception if the current type is not String.

Returns:

A const reference to the stored string.

inline String &string()

Retrieves the string stored in this Value (non-const version).

Throws an exception if the current type is not String.

Returns:

A reference to the stored string.

inline String &string(const String &value)

Sets the Value to a string by copy and returns a reference to the stored string.

Parameters:

value – The string to set.

Returns:

A reference to the stored string.

inline String &string(String &&value)

Sets the Value to a string by move and returns a reference to the stored string.

Parameters:

value – The string to move.

Returns:

A reference to the stored string.

inline const Array &array() const

Retrieves the array stored in this Value (const version).

Throws an exception if the current type is not Array.

Returns:

A const reference to the stored array.

inline Array &array()

Retrieves the array stored in this Value (non-const version).

Throws an exception if the current type is not Array.

Returns:

A reference to the stored array.

inline Array &array(const Array &value)

Sets the Value to an array by copy and returns a reference to the stored array.

Parameters:

value – The array to copy.

Returns:

A reference to the stored array.

inline Array &array(Array &&value)

Sets the Value to an array by move and returns a reference to the stored array.

Parameters:

value – The array to move.

Returns:

A reference to the stored array.

inline const Object &object() const

Retrieves the object stored in this Value (const version).

Throws an exception if the current type is not Object.

Returns:

A const reference to the stored object.

inline Object &object()

Retrieves the object stored in this Value (non-const version).

Throws an exception if the current type is not Object.

Returns:

A reference to the stored object.

inline Object &object(const Object &value)

Sets the Value to an object by copy and returns a reference to the stored object.

Parameters:

value – The object to copy.

Returns:

A reference to the stored object.

inline Object &object(Object &&value)

Sets the Value to an object by move and returns a reference to the stored object.

Parameters:

value – The object to move.

Returns:

A reference to the stored object.

inline Boolean tobool() const

Retrieves a copy of the stored value interpreted as a boolean.

Calls the bool conversion operator under the hood.

Returns:

The boolean interpretation of this Value.

inline Integer toint() const

Retrieves a copy of the stored value interpreted as an integer.

Calls the integer conversion operator under the hood.

Returns:

The integer interpretation of this Value.

inline Real toreal() const

Retrieves a copy of the stored value interpreted as a real (floating-point) number.

Calls the real conversion operator under the hood.

Returns:

The real (floating-point) interpretation of this Value.

inline String tostr() const

Retrieves a copy of the stored value interpreted as a string.

Calls the string conversion operator under the hood.

Returns:

The string interpretation of this Value.

explicit operator Boolean() const

Converts this Value to a boolean.

If the Value cannot be converted to a boolean, a runtime exception is thrown.

Returns:

The boolean representation of this Value.

explicit operator Integer() const

Converts this Value to an integer.

If the Value cannot be converted to an integer, a runtime exception is thrown.

Returns:

The integer representation of this Value.

explicit operator Real() const

Converts this Value to a real (floating-point) number.

If the Value cannot be converted to a real, a runtime exception is thrown.

Returns:

The real (floating-point) representation of this Value.

explicit operator String() const

Converts this Value to a string.

If the Value cannot be converted to a string, a runtime exception is thrown.

Returns:

The string representation of this Value.

inline Type type() const

Retrieves the current Type of this Value.

Returns:

The Type enumeration value representing this Value’s type.

inline Value &operator()(const std::string &pointer)

Retrieves or navigates to a nested Value by a JSON Pointer-like string.

The specifics of how ‘pointer’ is interpreted may be determined by the implementation.

Parameters:

pointer – A string that denotes the path to a nested Value.

Returns:

A reference to the nested Value.

inline const Value &operator()(const std::string &pointer) const

Retrieves or navigates to a nested Value by a JSON Pointer-like string (const overload).

The specifics of how ‘pointer’ is interpreted may be determined by the implementation.

Parameters:

pointer – A string that denotes the path to a nested Value.

Returns:

A const reference to the nested Value.

inline bool operator==(Type type) const

Compares the current Value’s type to the specified Type.

Parameters:

type – The Type to compare against.

Returns:

True if this Value has the same Type, false otherwise.

inline bool operator!=(Type type) const

Compares the current Value’s type to the specified Type for inequality.

Parameters:

type – The Type to compare against.

Returns:

True if this Value does not have the same Type, false otherwise.

bool operator==(const Value &other) const

Checks whether this Value and another Value are equal.

The criteria for equality may depend on the type of each Value and the contents.

Parameters:

other – The Value to compare against.

Returns:

True if the two Values are considered equal, false otherwise.

bool operator<(const Value &other) const

Compares this Value with another Value to determine an ordering.

Parameters:

other – The Value to compare against.

Returns:

True if this Value is considered less than the other, false otherwise.

inline Value &operator[](size_t index)

Provides array-style access to the stored data by index.

If this Value is not an array, a runtime exception is thrown.

Parameters:

index – The array index to access.

Returns:

A reference to the Value at the specified index.

inline const Value &operator[](size_t index) const

Provides array-style access to the stored data by index (const version).

If this Value is not an array, a runtime exception is thrown.

Parameters:

index – The array index to access.

Returns:

A const reference to the Value at the specified index.

inline Value &operator[](const std::string &key)

Provides object-style access to the stored data by key.

If this Value is not an object, a runtime exception is thrown.

Parameters:

key – The key to access in the object.

Returns:

A reference to the Value associated with the specified key.

const Value &operator[](const std::string &key) const

Provides object-style access to the stored data by key (const version).

If this Value is not an object, or if the key is not found, a runtime exception is thrown.

Parameters:

key – The key to access in the object.

Returns:

A const reference to the Value associated with the specified key.

inline Array::const_iterator begin() const

Returns an iterator to the beginning of the array.

If the Value is not an array, a runtime exception is thrown.

Returns:

A const_iterator to the beginning of the array.

inline Array::iterator begin()

Returns an iterator to the beginning of the array (non-const version).

If the Value is not an array, a runtime exception is thrown.

Returns:

An iterator to the beginning of the array.

inline Array::const_iterator end() const

Returns an iterator to the end of the array.

If the Value is not an array, a runtime exception is thrown.

Returns:

A const_iterator to the end of the array.

inline Array::iterator end()

Returns an iterator to the end of the array (non-const version).

If the Value is not an array, a runtime exception is thrown.

Returns:

An iterator to the end of the array.

inline Value &add(const Value &value)

Adds a new element to the end of the array by copy.

If this Value is not an array, a runtime exception is thrown.

Parameters:

value – The Value to be added to the array.

Returns:

A reference to this Value (for chaining).

inline Value &add(Value &&value)

Adds a new element to the end of the array by move.

If this Value is not an array, a runtime exception is thrown.

Parameters:

value – The Value to be added (moved) into the array.

Returns:

A reference to this Value (for chaining).

inline Value &add(const String &key, const Value &value)

Inserts a key-value pair into the object by copy.

If this Value is not an object, a runtime exception is thrown.

Parameters:

• key – The key under which the Value will be stored.

• value – The Value to store under the provided key.

Returns:

A reference to this Value (for chaining).

inline Value &add(const String &key, Value &&value)

Inserts a key-value pair into the object by move.

If this Value is not an object, a runtime exception is thrown.

Parameters:

• key – The key under which the Value will be stored.

• value – The Value to store under the provided key (moved).

Returns:

A reference to this Value (for chaining).

bool contains(const String &key) const

Checks if the object contains a given key.

If this Value is not an object, a runtime exception is thrown.

Parameters:

key – The key to look for in the object.

Returns:

True if the key exists in the object, false otherwise.

size_t size() const

Returns the size of the array or object.

If this Value is neither an array nor an object, a runtime exception is thrown.

Returns:

The size of the array or object (number of elements).

bool empty() const

Checks if the array or object is empty.

If this Value is neither an array nor an object, a runtime exception is thrown.

Returns:

True if the array or object has no elements, false otherwise.

void clear()

Clears the contents of the array or object.

If this Value is neither an array nor an object, a runtime exception is thrown.

void remove(size_t index)

Removes an element from the array at the specified index.

If this Value is not an array, a runtime exception is thrown.

Parameters:

index – The index of the element to remove.

bool remove(const String &key)

Removes an element from the object by key.

If this Value is not an object, a runtime exception is thrown.

Parameters:

key – The key of the element to remove.

Returns:

True if the key existed and was removed, false otherwise.

Friends

friend void swap(Value &first, Value &second)

Swaps the contents of two Value objects.

This operation exchanges both the Value types and the underlying data.

Parameters:

• first – The first Value object.

• second – The second Value object.

namespace Json

Enums

enum class Error

Enumeration of error codes that may result from parsing or writing JSON.

These error codes provide insight into why a JSON operation may have failed. For example, InvalidNumber indicates the parser encountered a malformed numeric value in the input.

Values:

enumerator None

No error occurred.

enumerator FileIOError

File could not be opened, read, or written to.

enumerator InvalidNumber

An invalid or malformed number was encountered during parsing.

enumerator InvalidString

An invalid or malformed string was encountered during parsing.

enumerator InvalidValueType

An invalid or unknown value type was encountered when writing.

enumerator ExpectedColon

Expected a colon ‘:’ in the JSON structure.

enumerator ExpectedComma

Expected a comma ‘,’ in the JSON structure.

enumerator ExpectedStart

Expected a valid JSON start.

enumerator ExpectedQuoteOpen

Expected a double-quote ‘”’ to open a string.

enumerator ExpectedQuoteClose

Expected a double-quote ‘”’ to close a string.

enumerator ExpectedBraceOpen

Expected an opening brace ‘{’ in the JSON object.

enumerator ExpectedBraceClose

Expected a closing brace ‘}’ in the JSON object.

enumerator ExpectedBracketOpen

Expected an opening bracket ‘[’ in the JSON array.

enumerator ExpectedBracketClose

Expected a closing bracket ‘]’ in the JSON array.

enumerator ExpectedCommaOrBraceClose

Expected either a comma ‘,’ or a closing brace ‘}’ to continue/close an object.

enumerator ExpectedCommaOrBracketClose

Expected either a comma ‘,’ or a closing bracket ‘]’ to continue/close an array.

enumerator FailedToReachEnd

The parser did not reach the end of the input as expected.

enumerator UnexpectedValueStart

An unexpected token was encountered where a JSON was supposed to start.

enum class Mode

An enumeration of modes for writing JSON.

These modes control the formatting of output when serializing a JSON Value to text.

Values:

enumerator Compact

Compact mode produces minimal whitespace and no newlines.

enumerator Readable

Readable mode uses indentation, spacing, and newlines for clarity.

Functions

Error readValue(Value &value, Parser &parser)

bool fixString(String &string, const char *ptr, size_t len)

Error readString(String &string, Parser &parser)

Error readObject(Object &object, Parser &parser)

Error readArray(Array &array, Parser &parser)

Error readNumber(Value &number, Parser &parser)

Error unfixString(String &string)

Error writeString(String string, std::ostream *stream)

Error writeReal(double number, std::ostream *stream)

Error writeValue(const Value &value, std::ostream *stream)

Error writeObject(const Object &object, std::ostream *stream)

Error writeArray(const Array &array, std::ostream *stream)

Error writeValue(const Value &value, std::ostream *stream, size_t indent)

Error writeObject(const Object &object, std::ostream *stream, size_t indent)

Error writeArray(const Array &array, std::ostream *stream, size_t indent)

Result read(Value &value, const char *str)

Result read(Value &value, const std::string &str)

Reads/parses a JSON document from an std::string into the given Value.

This function attempts to parse the string str and populate value with the resulting JSON structure.

Parameters:

• value – The Value that will be populated with the parsed JSON data.

• str – An std::string containing the JSON document.

Returns:

A Result indicating success (Error::None) or the type of error if parsing fails.

Result fread(Value &value, const std::string &path)

Reads/parses a JSON document from a file into the given Value.

This function attempts to open the file at path path, read its contents, and parse the data to populate value.

Parameters:

• value – The Value that will be populated with the parsed JSON data.

• path – The path to the file containing the JSON document.

Returns:

A Result indicating success (Error::None) or the type of error if reading/parsing fails.

Result write(const Value &value, std::ostream *stream, Mode mode = Mode::Readable)

Writes a JSON Value to a given output stream using the given mode.

This function serializes value into JSON text and writes it directly to the output stream pointed to by stream.

Parameters:

• value – The JSON Value to be serialized.

• stream – Pointer to a valid std::ostream instance where the JSON text will be written.

• mode – The desired output formatting mode. Defaults to Mode::Readable.

Returns:

A Result indicating success (Error::None) or the type of error if serialization fails.

Result write(const Value &value, std::string &data, Mode mode = Mode::Readable)

Writes a JSON Value to a string using the given output mode.

This function serializes value into a textual JSON representation and stores it in data. The mode parameter controls whether the output is formatted for readability or in a compact form.

Parameters:

• value – The JSON Value to be serialized.

• data – A reference to a std::string where the JSON text will be stored.

• mode – The desired output formatting mode. Defaults to Mode::Readable.

Returns:

A Result indicating success (Error::None) or the type of error if serialization fails.

Result fwrite(const Value &value, const std::string &path, Mode mode = Mode::Readable)

Writes a JSON Value to a file at the specified path using the given mode.

This function serializes value into JSON text and writes it to the file at path. The mode parameter controls whether the output is formatted for readability or in a compact form.

Parameters:

• value – The JSON Value to be serialized.

• path – The file path where the JSON text will be written.

• mode – The desired output formatting mode. Defaults to Mode::Readable.

Returns:

A Result indicating success (Error::None) or the type of error if the operation fails.

std::ostream &operator<<(std::ostream &os, Error error)

Outputs the textual representation of an Error code to the provided output stream.

This operator inserts a string or other representation of the error enum value into the provided os.

Parameters:

• os – The output stream to write to.

• error – The Error code to print.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, const Result &result)

Outputs the textual representation of a Result object to the provided output stream.

This operator inserts a string representation of both the error code and any relevant index information into the provided os.

Parameters:

• os – The output stream to write to.

• result – The Result object to print.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, Mode mode)

Outputs the textual representation of a Mode enum to the provided output stream.

This operator inserts a string indicating whether the mode is Compact or Readable.

Parameters:

• os – The output stream to write to.

• mode – The Mode enum value to print.

Returns:

A reference to the modified output stream.

Result sread(Value &value, const char *str)

Reads/parses a JSON document from a C-string into the given Value.

This function attempts to parse the null-terminated string str and populate value with the resulting JSON structure.

Parameters:

• value – The Value that will be populated with the parsed JSON data.

• str – A null-terminated C-string containing the JSON document.

Returns:

A Result indicating success (Error::None) or the type of error if parsing fails.

struct Parser

struct Result

#include <json.h>

A struct representing the result of parsing or writing a JSON document.

This struct holds the error code indicating whether the operation succeeded, and, in case of reading, how many bytes were processed.

Public Functions

inline Result(Error error = Error::None, size_t index = size_t(-1))

Constructs a Result object.

Parameters:

• error – The error code (defaults to Error::None).

• index – The number of bytes processed (defaults to size_t(-1)).

inline operator bool() const

Indicates success or failure of the operation as a boolean.

Returns:

True if error is Error::None, otherwise false.

Public Members

Error error

The error code indicating success or failure of the operation.

size_t index

The number of bytes processed (e.g., from an input string). Typically set when reading/parsing a JSON document.

namespace XML

Typedefs

using Nodes = std::vector<Node>

Alias representing a collection of Node objects.

Enums

enum class Error

Enumeration of possible errors that can occur while working with XML.

These errors indicate why an XML operation (such as reading or writing) might have failed.

Values:

enumerator None

No error occurred.

enumerator FileIOError

The file could not be opened, read, or written.

enumerator ParseError

A general parsing error occurred (malformed XML structure).

enum class Parse

Parsing modes for XML input.

These modes control how the XML input is parsed and trimmed.

Values:

enumerator ElementsTrimmed

Read only element nodes, trimming whitespace within elements.

enumerator FullTrimmed

Read the entire XML document, trimming all extraneous whitespace.

enumerator Elements

Read only element nodes without trimming whitespace.

enumerator Full

Read the entire XML document without trimming whitespace.

enum class Mode

Output modes for XML serialization.

These modes control the formatting of XML output when writing.

Values:

enumerator Compact

Compact output with minimal whitespace.

enumerator Readable

Readable output with indentation and newlines.

Functions

bool readAll(const std::string &path, std::string &content)

Result sread(Nodes &nodes, const char *input, Parse mode = Parse::ElementsTrimmed)

Parses an XML document from a C-string into a list of Nodes.

Depending on mode, whitespace and certain node types may be trimmed or discarded.

Parameters:

• nodes – Reference to a Nodes container where parsed nodes will be stored.

• input – A null-terminated C-string containing XML data.

• mode – The parsing mode indicating how whitespace and nodes are handled.

Returns:

A Result indicating success or error details if parsing fails.

Result read(Nodes &nodes, const std::string &input, Parse mode = Parse::ElementsTrimmed)

Parses an XML document from an std::string into a list of Nodes.

Depending on mode, whitespace and certain node types may be trimmed or discarded.

Parameters:

• nodes – Reference to a Nodes container where parsed nodes will be stored.

• input – A std::string containing XML data.

• mode – The parsing mode indicating how whitespace and nodes are handled.

Returns:

A Result indicating success or error details if parsing fails.

Result fread(Nodes &nodes, const std::string &path, Parse mode = Parse::ElementsTrimmed)

Reads and parses an XML document from a file into a list of Nodes.

Opens the file at path, reads its contents, and parses them according to mode.

Parameters:

• nodes – Reference to a Nodes container where parsed nodes will be stored.

• path – The path of the file containing the XML data.

• mode – The parsing mode indicating how whitespace and nodes are handled.

Returns:

A Result indicating success or error details if reading/parsing fails.

Result write(const Nodes &nodes, std::string &output, Mode mode = Mode::Readable)

Writes a list of Nodes to a string in XML format.

The mode parameter controls whether the output is compact or readable with indentation and newlines.

Parameters:

• nodes – The list of Nodes to serialize.

• output – A reference to the string where the XML data will be written.

• mode – The output mode (compact or readable).

Returns:

A Result indicating success or error details if writing fails.

Result write(const Nodes &nodes, std::ostream &stream, Mode mode = Mode::Readable)

Writes a list of Nodes to a given output stream in XML format.

The mode parameter controls whether the output is compact or readable with indentation and newlines.

Parameters:

• nodes – The list of Nodes to serialize.

• stream – The output stream to write to.

• mode – The output mode (compact or readable).

Returns:

A Result indicating success or error details if writing fails.

Result fwrite(const Nodes &nodes, std::string &path, Mode mode = Mode::Readable)

Writes a list of Nodes to a file at the specified path in XML format.

Opens or creates the file at path and writes the serialized XML data. The mode parameter controls whether the output is compact or readable.

Parameters:

• nodes – The list of Nodes to serialize.

• path – The file path where the XML data will be written.

• mode – The output mode (compact or readable).

Returns:

A Result indicating success or error details if writing fails.

std::ostream &operator<<(std::ostream &os, Error error)

Inserts a textual representation of an Error enum into the given output stream.

This operator typically displays the name of the error code (e.g., “None”, “FileIOError”, “ParseError”).

Parameters:

• os – The output stream to write to.

• error – The Error enum value to display.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, const Result &result)

Inserts a textual representation of a Result object into the given output stream.

This operator may display the error code, index, and any associated message.

Parameters:

• os – The output stream to write to.

• result – The Result object to display.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, const Nodes &nodes)

Inserts a textual representation of multiple Nodes into the given output stream.

The exact formatting is implementation-specific; typically prints each Node in turn.

Parameters:

• os – The output stream to write to.

• nodes – The list of Nodes to display.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, const Node &node)

Inserts a textual representation of a single Node into the given output stream.

The exact formatting is implementation-specific; typically includes node type, name, attributes, and value.

Parameters:

• os – The output stream to write to.

• node – The Node to display.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, Parse parse)

Inserts a textual representation of a Parse enum into the given output stream.

This operator typically displays the name of the parse mode (e.g., “ElementsTrimmed”).

Parameters:

• os – The output stream to write to.

• parse – The Parse enum value to display.

Returns:

A reference to the modified output stream.

std::ostream &operator<<(std::ostream &os, Mode mode)

Inserts a textual representation of a Mode enum into the given output stream.

This operator typically displays either “Compact” or “Readable”.

Parameters:

• os – The output stream to write to.

• mode – The Mode enum value to display.

Returns:

A reference to the modified output stream.

void swap(Node &first, Node &second)

This function exchanges the type, name, value, attributes, and child nodes of first and second, providing a no-throw swap mechanism.

Parameters:

• first – The first Node.

• second – The second Node.

struct Reader

struct Writer

struct Result

#include <xml.h>

Result structure for XML operations.

This struct holds the status of an XML operation, including an error code, the position/index of the error if any, and an optional message.

Public Functions

inline Result(Error error = Error::None, size_t index = size_t(-1), const String &message = {})

Constructs a Result object.

Parameters:

• error – The error code. Defaults to Error::None (no error).

• index – The position where an error was encountered (if any). Defaults to size_t(-1).

• message – An optional string describing the error in more detail.

inline operator bool() const

Boolean conversion operator indicating success or failure.

Returns:

True if error is Error::None; otherwise false.

Public Members

Error error

The error code indicating success or type of failure.

size_t index

The index (e.g., character or byte position) where an error was detected.

std::string message

Additional message describing the error or context.

class Node

#include <xml.h>

A class representing an XML node.

Each Node may be one of several types (Element, CData, Comment, Declaration, DocType, ProcInfo) and may contain child nodes, attributes, or textual data.

Public Types

enum Type

Enumeration of node types.

Values:

enumerator Element

An element node, which may have a tag name, value, attributes, and child nodes.

enumerator CData

A CDATA section node, storing unescaped character data.

enumerator Comment

A comment node, storing comment text.

enumerator Declaration

An XML declaration node, possibly holding version, encoding, and standalone attributes.

enumerator DocType

A DOCTYPE node, storing the document type definition or reference.

enumerator ProcInfo

A processing instruction node, typically containing a target and instructions.

using Attribs = std::unordered_map<String, String>

A map of attribute key-value pairs for this Node.

Public Functions

inline explicit Node(Type type = Type::Element)

Constructs a Node with the specified type.

Parameters:

type – The type of the node. Defaults to Type::Element.

Node(const Node &other) = default

Copy constructor.

Parameters:

other – The Node to copy from.

Node(Node &&other) = default

Move constructor.

Parameters:

other – The Node to move from.

Node &operator=(const Node &other) = default

Copy assignment operator.

Parameters:

other – The Node to copy from.

Returns:

A reference to this Node.

Node &operator=(Node &&other) = default

Move assignment operator.

Parameters:

other – The Node to move from.

Returns:

A reference to this Node.

inline void reset()

Resets the Node to its default state (Type::Element with empty data).

This function clears the node name, value, attributes, and child nodes, and sets the node type to Element.

inline Type type() const

Gets the type of this Node.

Returns:

The current Type of this Node.

inline bool operator==(Type type) const

Checks if this Node is of the specified Type.

Parameters:

type – The Type to compare against.

Returns:

True if they match, otherwise false.

inline bool operator!=(Type type) const

Checks if this Node is not of the specified Type.

Parameters:

type – The Type to compare against.

Returns:

True if they differ, otherwise false.

inline bool operator==(const Node &other) const

Checks if this Node is equal to another Node.

Two Nodes are considered equal if they have the same type, name, value, attributes, and child nodes.

Parameters:

other – The Node to compare with.

Returns:

True if they are equal, otherwise false.

inline Node &operator[](size_t index)

Access the child node at the specified index (non-const).

This operator assumes that the current node can have child nodes (i.e., the Node is typically of Type::Element). If index is out of range, the behavior is undefined or may trigger an assertion.

Parameters:

index – The zero-based index of the desired child node.

Returns:

A reference to the child node at the given index.

inline const Node &operator[](size_t index) const

Access the child node at the specified index (const).

This operator returns a const reference to the child node at index. If index is out of range, the behavior is undefined or may trigger an assertion.

Parameters:

index – The zero-based index of the desired child node.

Returns:

A const reference to the child node at the given index.

inline String &operator[](const String &key)

Access or create an attribute with the specified key (non-const).

If the attribute key exists, returns a reference to its value. Otherwise, creates a new attribute with key key and a default-constructed value, then returns a reference to that value.

Parameters:

key – The name of the attribute to access.

Returns:

A reference to the attribute value (which can be modified).

inline const String &operator[](const String &key) const

Access the attribute with the specified key (const).

If the attribute key exists, returns a const reference to its value. If the attribute does not exist, an assertion triggers a runtime exception.

Parameters:

key – The name of the attribute to access.

Returns:

A const reference to the attribute value.

inline Nodes::const_iterator begin() const

Returns a const iterator pointing to the first child node.

This function assumes the Node can hold child nodes (Type::Element). If there are no child nodes, begin() equals end().

Returns:

A const iterator to the beginning of the child node list.

inline Nodes::iterator begin()

Returns an iterator pointing to the first child node.

This function allows modification of child nodes. If there are no child nodes, begin() equals end().

Returns:

An iterator to the beginning of the child node list.

inline Nodes::const_iterator end() const

Returns a const iterator pointing to the end of the child node list.

This marks the past-the-end position; it does not refer to a valid child node.

Returns:

A const iterator to the end of the child node list.

inline Nodes::iterator end()

Returns an iterator pointing to the end of the child node list.

This marks the past-the-end position; it does not refer to a valid child node.

Returns:

An iterator to the end of the child node list.

inline Node &add(const Node &node)

Adds a copy of the given node to the child node list.

This function pushes node onto the list of child nodes. It is assumed the current Node can hold child nodes (Type::Element).

Parameters:

node – The Node to be copied and appended.

Returns:

A reference to the current Node (for chaining).

inline Node &add(Node &&node)

Adds a moved node to the child node list.

This function pushes node (via std::move) onto the list of child nodes. It is assumed the current Node can hold child nodes (Type::Element).

Parameters:

node – The Node to be moved and appended.

Returns:

A reference to the current Node (for chaining).

inline Node &add(const String &key, const String &value)

Adds or updates an attribute with the specified key-value pair (copy).

If the attribute key already exists, it is overwritten. Otherwise, a new attribute is created.

Parameters:

• key – The attribute name.

• value – The attribute value.

Returns:

A reference to the current Node (for chaining).

inline Node &add(const String &key, String &&value)

Adds or updates an attribute with the specified key-value pair (move).

If the attribute key already exists, it is overwritten. Otherwise, a new attribute is created using the moved string.

Parameters:

• key – The attribute name.

• value – The attribute value (will be moved).

Returns:

A reference to the current Node (for chaining).

inline size_t size() const

Returns the number of child nodes in this Node.

Returns:

The size of the child node list.

inline bool empty() const

Checks if this Node has any child nodes.

Returns:

True if there are no child nodes, otherwise false.

inline void clear()

Clears all child nodes from this Node.

This operation does not remove attributes or alter the node type/name/value. It only clears the child nodes vector.

inline void remove(size_t index)

Removes the child node at the specified index.

This function erases the child node at position index. If index is out of range, the behavior is undefined or may trigger an assertion.

Parameters:

index – The zero-based index of the child node to remove.

inline bool remove(const String &key)

Removes an attribute by its key.

If the attribute key exists, it is erased from the internal attributes map.

Parameters:

key – The name of the attribute to remove.

Returns:

True if the attribute was removed, otherwise false.

inline bool iselem() const

Checks if this Node is an Element type.

Returns:

True if the node type is Type::Element, otherwise false.

inline bool iscdata() const

Checks if this Node is a CData section type.

Returns:

True if the node type is Type::CData, otherwise false.

inline bool iscomment() const

Checks if this Node is a Comment type.

Returns:

True if the node type is Type::Comment, otherwise false.

inline bool isdecl() const

Checks if this Node is a Declaration type.

Returns:

True if the node type is Type::Declaration, otherwise false.

inline bool isdoctype() const

Checks if this Node is a DocType type.

Returns:

True if the node type is Type::DocType, otherwise false.

inline bool ispi() const

Checks if this Node is a Processing Instruction type.

Returns:

True if the node type is Type::ProcInfo, otherwise false.

inline const String &name() const

Gets the name of the Node (const).

This function is only valid if the Node type is either Element or ProcInfo. If the Node’s type is neither, an assertion triggers a runtime exception.

Returns:

A const reference to the Node’s name.

inline String &name()

Gets the name of the Node (non-const).

This function is only valid if the Node type is either Element or ProcInfo. If the Node’s type is neither, an assertion triggers a runtime exception.

Returns:

A reference to the Node’s name, allowing modification.

inline String &name(const String &name)

Sets the name of the Node using a copy, then returns a reference to it.

This function is only valid if the Node type is either Element or ProcInfo. If the Node’s type is neither, an assertion triggers a runtime exception.

Parameters:

name – The new name to assign to this Node.

Returns:

A reference to the Node’s name after assignment.

inline String &name(String &&name)

Sets the name of the Node using a move operation, then returns a reference to it.

This function is only valid if the Node type is either Element or ProcInfo. If the Node’s type is neither, an assertion triggers a runtime exception.

Parameters:

name – The new name to assign to this Node (will be moved).

Returns:

A reference to the Node’s name after assignment.

inline const String &value() const

Gets the value of the Node (const).

This function is not valid for Declaration nodes. If the Node’s type is Type::Declaration, an assertion triggers a runtime exception.

Returns:

A const reference to the Node’s value.

inline String &value()

Gets the value of the Node (non-const).

This function is not valid for Declaration nodes. If the Node’s type is Type::Declaration, an assertion triggers a runtime exception.

Returns:

A reference to the Node’s value, allowing modification.

inline String &value(const String &value)

Sets the value of the Node using a copy, then returns a reference to it.

This function is not valid for Declaration nodes. If the Node’s type is Type::Declaration, an assertion triggers a runtime exception.

Parameters:

value – The new value to assign to this Node.

Returns:

A reference to the Node’s value after assignment.

inline String &value(String &&value)

Sets the value of the Node using a move operation, then returns a reference to it.

This function is not valid for Declaration nodes. If the Node’s type is Type::Declaration, an assertion triggers a runtime exception.

Parameters:

value – The new value to assign to this Node (will be moved).

Returns:

A reference to the Node’s value after assignment.

inline Attribs &attribs()

Gets the attribute map (non-const).

This function is only valid if the Node type is Element or Declaration. Otherwise, an assertion triggers a runtime exception.

Returns:

A reference to the map of attribute key-value pairs.

inline const Attribs &attribs() const

Gets the attribute map (const).

This function is only valid if the Node type is Element or Declaration. Otherwise, an assertion triggers a runtime exception.

Returns:

A const reference to the map of attribute key-value pairs.

inline Attribs &attribs(const Attribs &attribs)

Sets the attribute map by copy, then returns a reference to it.

This function is only valid if the Node type is Element or Declaration. Otherwise, an assertion triggers a runtime exception.

Parameters:

attribs – The new attribute map to copy.

Returns:

A reference to the Node’s attribute map after assignment.

inline Attribs &attribs(Attribs &&attribs)

Sets the attribute map by move, then returns a reference to it.

This function is only valid if the Node type is Element or Declaration. Otherwise, an assertion triggers a runtime exception.

Parameters:

attribs – The new attribute map to move.

Returns:

A reference to the Node’s attribute map after assignment.

inline Nodes &nodes()

Gets the collection of child nodes (non-const).

This function is only valid if the Node type is Element. Otherwise, an assertion triggers a runtime exception.

Returns:

A reference to the vector of child nodes.

inline const Nodes &nodes() const

Gets the collection of child nodes (const).

This function is only valid if the Node type is Element. Otherwise, an assertion triggers a runtime exception.

Returns:

A const reference to the vector of child nodes.

inline Nodes &nodes(const Nodes &nodes)

Sets the collection of child nodes by copy, then returns a reference to it.

This function is only valid if the Node type is Element. Otherwise, an assertion triggers a runtime exception.

Parameters:

nodes – The new list of child nodes to copy.

Returns:

A reference to the Node’s children after assignment.

inline Nodes &nodes(Nodes &&nodes)

Sets the collection of child nodes by move, then returns a reference to it.

This function is only valid if the Node type is Element. Otherwise, an assertion triggers a runtime exception.

Parameters:

nodes – The new list of child nodes to move.

Returns:

A reference to the Node’s children after assignment.

Friends

friend void swap(Node &first, Node &second)

Swaps the contents of two Nodes.

This function exchanges the type, name, value, attributes, and child nodes of first and second, providing a no-throw swap mechanism.

Parameters:

• first – The first Node.

• second – The second Node.