A type-safe wrapper around nlohmann::json for database operations. More...

#include <db.hpp>

Public Member Functions
	Db () noexcept
	Constructs a new Db object with an empty JSON object.

template<typename T> requires std::same_as<std::remove_cvref_t<T>, json_t>
	Db (T &&json) noexcept
	Constructs a new Db object from a JSON object (move or copy)

template<typename T> requires std::same_as<std::remove_cvref_t<T>, json_t>
	Db (std::reference_wrapper< T > const &json) noexcept
	Constructs a new Db object from a reference to an existing JSON object.

std::vector< std::string >	keys () const noexcept
	Retrieves all keys from the current JSON object or array.

std::vector< std::pair< std::string, Db > >	items () const noexcept
	Retrieves key-value pairs as Db objects from the current JSON.

template<typename V = Db>
Value< V >	value () noexcept
	Converts the current JSON entry to a specified type.

template<typename F, IsString Ks>
decltype(auto)	apply (F &&f, Ks &&ks)

Value< std::string >	dump ()
	Serializes the current JSON data to a formatted string.

bool	empty () const noexcept
	Checks whether the JSON data is empty.

template<IsString T>
bool	contains (T &&t) const noexcept
	Checks if the JSON contains a specific key.

KeyType	type () const noexcept
	Retrieves the type of the current JSON element.

template<IsString T>
bool	erase (T &&t)
	Removes a key from the JSON structure.

void	clear ()
	Resets the JSON data to an empty object.

json_t &	data ()
	Retrieves a mutable reference to the underlying JSON data.

json_t const &	data () const
	Retrieves a const reference to the underlying JSON data.

template<typename T>
Db &	operator= (T &&t)
	Assigns a new value to the underlying JSON data.

Db	operator() (std::string const &t)
	Accesses or creates a nested JSON entry by key.

Friends
std::ostream &	operator<< (std::ostream &os, Db const &db)
	Outputs the JSON data to an output stream.

Detailed Description

A type-safe wrapper around nlohmann::json for database operations.

The Db class provides a user-friendly interface to nlohmann::json objects with support for both owned and referenced JSON data. It can either own its JSON data directly or wrap a reference to external JSON, enabling flexible use cases. The class supports element access, serialization, deserialization, and common database operations like clearing, erasing, and type checking. All operations are designed to be exception-safe through the Value<T> error handling pattern.

Definition at line 63 of file db.hpp.

Constructor & Destructor Documentation

◆ Db() [1/3]

ns_db::Db::Db ( )

inlinenoexcept

Constructs a new Db object with an empty JSON object.

Initializes the database with an empty nlohmann::json object as the underlying storage. The variant m_json is set to hold a json_t::object() by default.

Definition at line 118 of file db.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Db() [2/3]

template<typename T>
requires std::same_as<std::remove_cvref_t<T>, json_t>

ns_db::Db::Db ( T && json )

inlineexplicitnoexcept

Constructs a new Db object from a JSON object (move or copy)

Creates a database by taking ownership of or copying a nlohmann::json object. The variant m_json directly stores the json_t value, supporting both move and copy construction depending on the value category of the passed argument.

Template Parameters

T	Type that is same as json_t (after removing cv and ref qualifiers)

Parameters

json	The nlohmann::json object to store in the database (forwarded)

Definition at line 149 of file db.hpp.

◆ Db() [3/3]

template<typename T>
requires std::same_as<std::remove_cvref_t<T>, json_t>

ns_db::Db::Db ( std::reference_wrapper< T > const & json )

inlineexplicitnoexcept

Constructs a new Db object from a reference to an existing JSON object.

Creates a database wrapper around an existing nlohmann::json object passed by reference_wrapper. This allows the Db to operate on external JSON data without copying. The variant m_json stores the reference_wrapper, enabling modification of the original JSON object through the Db interface.

Template Parameters

T	Type that is same as json_t (after removing cv and ref qualifiers)

Parameters

json	Reference wrapper containing the nlohmann::json object to wrap

Definition at line 134 of file db.hpp.

Member Function Documentation

◆ apply()

template<typename F, IsString Ks>

decltype(auto) ns_db::Db::apply	(	F &&	f,
		Ks &&	ks )

nodiscard

Todo: Delete unused function

Here is the call graph for this function:

◆ clear()

void ns_db::Db::clear ( )

inline

Resets the JSON data to an empty object.

Clears all existing content and reinitializes the underlying JSON data as an empty object ({}). This operation discards all keys, values, and nested structures.

Definition at line 370 of file db.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ contains()

template<IsString T>

bool ns_db::Db::contains ( T && key ) const

nodiscardnoexcept

Checks if the JSON contains a specific key.

Verifies whether the JSON object or array contains the specified key. Only valid for structured JSON types (objects and arrays); returns false for primitives. For objects, checks if the key exists as a property name. For arrays, checks if the key is a valid index.

Template Parameters

T	Type that satisfies the IsString concept (convertible to std::string)

Parameters

key	The key to search for in the JSON structure

Returns: bool True if the key exists in the JSON structure, false otherwise

Definition at line 309 of file db.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ data() [1/2]

json_t & ns_db::Db::data ( )

inline

Retrieves a mutable reference to the underlying JSON data.

Accesses the JSON object stored in the variant m_json. If the variant holds a reference_wrapper, it extracts and returns the wrapped reference. Otherwise, it returns the directly stored json_t object. This allows uniform access regardless of whether the Db owns the JSON data or references external data.

Returns: json_t& Mutable reference to the current JSON entry

Definition at line 163 of file db.hpp.

Here is the caller graph for this function:

◆ data() [2/2]

json_t const & ns_db::Db::data ( ) const

inline

Retrieves a const reference to the underlying JSON data.

Provides const access to the JSON object by delegating to the non-const data() method through const_cast. This maintains the same access logic for both const and non-const contexts without code duplication.

Returns: json_t const& Const reference to the current JSON entry

Definition at line 182 of file db.hpp.

Here is the call graph for this function:

◆ dump()

Value< std::string > ns_db::Db::dump ( )

inlinenodiscard

Serializes the current JSON data to a formatted string.

Converts the underlying nlohmann::json object to a string representation with 2-space indentation for readability. Uses the Try macro to safely handle any potential serialization errors and wrap them in the Value<std::string> result.

Returns: Value<std::string> The formatted JSON string on success, or error on serialization failure

Definition at line 277 of file db.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ empty()

bool ns_db::Db::empty ( ) const

inlinenodiscardnoexcept

Checks whether the JSON data is empty.

Delegates to nlohmann::json's empty() method to determine if the underlying JSON structure contains no elements. For objects, this means no key-value pairs; for arrays, no elements; for strings, zero length.

Returns: bool True if the JSON is empty, false otherwise

Definition at line 291 of file db.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ erase()

template<IsString T>

bool ns_db::Db::erase ( T && key )

nodiscard

Removes a key from the JSON structure.

Attempts to erase the specified key from the JSON data. Behavior depends on the JSON type:

Array: Searches for an element matching the key string and removes it by index
Object: Removes the key-value pair if the key exists
Other types: No operation, returns false Returns true if an element was successfully removed, false otherwise.

Template Parameters

T	Type that satisfies the IsString concept (convertible to std::string)

Parameters

key	The identifier of the key to remove

Returns: bool True if the key was found and removed, false otherwise

Definition at line 343 of file db.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ items()

std::vector< std::pair< std::string, Db > > ns_db::Db::items ( ) const

inlinenodiscardnoexcept

Retrieves key-value pairs as Db objects from the current JSON.

Iterates over all entries in a structured JSON (object or array) and creates a pair containing the key as a string and the value wrapped in a new Db object. Returns an empty vector if the JSON is not structured. Each value is wrapped in its own Db instance, allowing nested database operations.

Returns: std::vector<std::pair<std::string,Db>> Vector of key-value pairs, or empty vector if invalid

Definition at line 216 of file db.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ keys()

std::vector< std::string > ns_db::Db::keys ( ) const

inlinenodiscardnoexcept

Retrieves all keys from the current JSON object or array.

Extracts the keys from a structured JSON element (object or array). For JSON objects, returns the property names. For arrays, returns string representations of indices. Returns an empty vector if the JSON is not structured. Uses C++20 ranges to transform the items view into a vector of strings.

Returns: std::vector<std::string> Vector containing all keys as strings, or empty vector if invalid

Definition at line 197 of file db.hpp.

Here is the call graph for this function:

◆ operator()()

Db ns_db::Db::operator() ( std::string const & key )

inlinenodiscard

Accesses or creates a nested JSON entry by key.

Provides subscript-style access to JSON object properties. If the current JSON is an object or empty, accesses (or creates) the specified key and returns a new Db wrapping a reference to that nested element. If the JSON is not an object or empty, returns a copy of the current Db (no operation). Enables nested access like db("key1")("key2").

Parameters

key	The key to access or create in the JSON object

Returns: Db A new Db with a reference to the nested element, or the current object on failure

Definition at line 404 of file db.hpp.

Here is the call graph for this function:

◆ operator=()

template<typename T>

Db & ns_db::Db::operator= ( T && value )

Assigns a new value to the underlying JSON data.

Replaces the current JSON content with the provided value using perfect forwarding. The value is converted to a JSON-compatible type by nlohmann::json's assignment operator. Returns a reference to this Db object to enable method chaining.

Template Parameters

T	Type of the value to assign (automatically deduced)

Parameters

value The value to assign to the JSON data

Returns: Db& Reference to this database object

Definition at line 387 of file db.hpp.

Here is the call graph for this function:

◆ type()

KeyType ns_db::Db::type ( ) const

inlinenodiscardnoexcept

Retrieves the type of the current JSON element.

Returns an enumeration value from nlohmann::json::value_t that indicates the JSON element's type (null, boolean, number_integer, number_unsigned, number_float, object, array, string, binary, or discarded).

Returns: KeyType Enumeration representing the JSON element's type

Definition at line 324 of file db.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ value()

template<typename V>

Value< V > ns_db::Db::value ( )

nodiscardnoexcept

Converts the current JSON entry to a specified type.

Performs type-safe conversion of the JSON entry to the requested type V. Supports:

Db: Returns a new database wrapper for the current entry
std::vector<std::string>: Converts JSON array to string vector (validates all elements are strings)
String types: Converts JSON string values to string-constructible types Returns an error if the conversion is not possible or the JSON type doesn't match expectations.

Template Parameters

V	The target type to convert to (default: Db)

Returns: Value<V> The converted object on success, or error on type mismatch/invalid conversion

Definition at line 238 of file db.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		Db const &	db )

friend

Outputs the JSON data to an output stream.

Serializes the underlying nlohmann::json object and writes it to the provided output stream. This enables standard stream operations like std::cout << db. Uses nlohmann::json's built-in stream insertion operator for formatting.

Parameters

os	The target output stream
db	The database object to print

Returns: std::ostream& Reference to the output stream for chaining

Definition at line 427 of file db.hpp.

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

src/db/db.hpp

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Db() [1/3]

◆ Db() [2/3]

◆ Db() [3/3]

Member Function Documentation

◆ apply()

◆ clear()

◆ contains()

◆ data() [1/2]

◆ data() [2/2]

◆ dump()

◆ empty()

◆ erase()

◆ items()

◆ keys()

◆ operator()()

◆ operator=()

◆ type()

◆ value()

Friends And Related Symbol Documentation

◆ operator<<