Template class for managing key-value pairs in an MDBX database. More...

#include <KeyValueTable.hpp>

Inheritance diagram for mdbxc::KeyValueTable< KeyT, ValueT >:

Classes
class	AssignmentProxy
	Helper proxy for convenient assignment via operator[]. More...

Public Member Functions
	KeyValueTable (std::shared_ptr< Connection > connection, std::string name="kv_store", MDBX_db_flags_t flags=MDBX_DB_DEFAULTS\|MDBX_CREATE)
	Default constructor.

	KeyValueTable (const Config &config, std::string name="kv_store", MDBX_db_flags_t flags=MDBX_DB_DEFAULTS\|MDBX_CREATE)
	Constructor with configuration.

	~KeyValueTable () override final=default
	Destructor.

template<template< class... > class ContainerT>
KeyValueTable &	operator= (const ContainerT< KeyT, ValueT > &container)
	Assigns a container (e.g., std::map or std::unordered_map) to the database.

KeyValueTable &	operator= (const std::vector< std::pair< KeyT, ValueT > > &container)
	Assigns a vector of key-value pairs to the database.

template<template< class... > class ContainerT = std::map>
std::conditional< std::is_same< ContainerT< KeyT, ValueT >, std::vector< std::pair< KeyT, ValueT > > >::value, std::vector< std::pair< KeyT, ValueT > >, ContainerT< KeyT, ValueT > >::type	operator() ()
	Loads all key-value pairs from the database into a container.

AssignmentProxy	operator[] (const KeyT &key)
	Provides convenient access to insert or read a value by key.

template<template< class... > class ContainerT>
void	load (ContainerT< KeyT, ValueT > &container, MDBX_txn *txn=nullptr)
	Loads data from the database into the container.

template<template< class... > class ContainerT>
void	load (ContainerT< KeyT, ValueT > &container, const Transaction &txn)
	Loads data from the database into the container using provided transaction.

void	load (std::vector< std::pair< KeyT, ValueT > > &container, MDBX_txn *txn=nullptr)
	Loads all key-value pairs into a std::vector of pairs.

void	load (std::vector< std::pair< KeyT, ValueT > > &container, const Transaction &txn)
	Loads all key-value pairs into a std::vector of pairs.

template<template< class... > class ContainerT = std::map>
std::conditional< std::is_same< ContainerT< KeyT, ValueT >, std::vector< std::pair< KeyT, ValueT > > >::value, std::vector< std::pair< KeyT, ValueT > >, ContainerT< KeyT, ValueT > >::type	retrieve_all (MDBX_txn *txn=nullptr)
	Retrieves all key-value pairs into the specified container type.

template<template< class... > class ContainerT = std::map>
std::conditional< std::is_same< ContainerT< KeyT, ValueT >, std::vector< std::pair< KeyT, ValueT > > >::value, std::vector< std::pair< KeyT, ValueT > >, ContainerT< KeyT, ValueT > >::type	retrieve_all (const Transaction &txn)
	Retrieves all key-value pairs into the specified container type.

template<template< class... > class ContainerT>
void	append (const ContainerT< KeyT, ValueT > &container, MDBX_txn *txn=nullptr)
	Appends data to the database.

template<template< class... > class ContainerT>
void	append (const ContainerT< KeyT, ValueT > &container, const Transaction &txn)
	Appends data to the database.

void	append (const std::vector< std::pair< KeyT, ValueT > > &container, MDBX_txn *txn=nullptr)
	Appends data from a vector to the database.

void	append (const std::vector< std::pair< KeyT, ValueT > > &container, const Transaction &txn)
	Appends data from a vector to the database using a provided transaction.

template<template< class... > class ContainerT>
void	reconcile (const ContainerT< KeyT, ValueT > &container, MDBX_txn *txn=nullptr)
	Reconciles the database with the container.

template<template< class... > class ContainerT>
void	reconcile (const ContainerT< KeyT, ValueT > &container, const Transaction &txn)
	Reconciles the database with the container.

void	reconcile (const std::vector< std::pair< KeyT, ValueT > > &container, MDBX_txn *txn=nullptr)
	Reconciles the database with the vector of key-value pairs.

void	reconcile (const std::vector< std::pair< KeyT, ValueT > > &container, const Transaction &txn)
	Reconciles the database with the vector of key-value pairs using provided transaction.

bool	insert (const KeyT &key, const ValueT &value, MDBX_txn *txn=nullptr)
	Inserts key-value only if key is absent.

bool	insert (const KeyT &key, const ValueT &value, const Transaction &txn)
	Inserts key-value only if key is absent.

bool	insert (const std::pair< KeyT, ValueT > &pair, MDBX_txn *txn=nullptr)
	Inserts key-value only if key is absent.

bool	insert (const std::pair< KeyT, ValueT > &pair, const Transaction &txn)
	Inserts key-value only if key is absent.

void	insert_or_assign (const KeyT &key, const ValueT &value, MDBX_txn *txn=nullptr)
	Inserts or replaces key-value pair.

void	insert_or_assign (const KeyT &key, const ValueT &value, const Transaction &txn)
	Inserts or replaces key-value pair.

void	insert_or_assign (const std::pair< KeyT, ValueT > &pair, MDBX_txn *txn=nullptr)
	Inserts or replaces key-value pair.

void	insert_or_assign (const std::pair< KeyT, ValueT > &pair, const Transaction &txn)
	Inserts or replaces key-value pair.

ValueT	at (const KeyT &key, MDBX_txn *txn=nullptr) const
	Retrieves value by key or throws.

ValueT	at (const KeyT &key, const Transaction &txn) const
	Retrieves value by key or throws.

bool	try_get (const KeyT &key, ValueT &out, MDBX_txn *txn) const
	Tries to find value by key.

bool	try_get (const KeyT &key, ValueT &out, const Transaction &txn) const
	Tries to find value by key.

std::pair< bool, ValueT >	find (const KeyT &key, MDBX_txn *txn=nullptr) const
	Finds value by key.

std::pair< bool, ValueT >	find (const KeyT &key, const Transaction &txn) const
	Finds value by key.

std::pair< bool, ValueT >	find_compat (const KeyT &key, MDBX_txn *txn=nullptr) const
	Finds value by key.

std::pair< bool, ValueT >	find_compat (const KeyT &key, const Transaction &txn) const
	Finds value by key.

bool	contains (const KeyT &key, MDBX_txn *txn=nullptr) const
	Checks whether a key exists in the database.

bool	contains (const KeyT &key, const Transaction &txn) const
	Checks whether a key exists in the database.

std::size_t	count (MDBX_txn *txn=nullptr) const
	Returns the number of elements in the database.

std::size_t	count (const Transaction &txn) const
	Returns the number of elements in the database.

bool	empty (MDBX_txn *txn=nullptr) const
	Checks if the database is empty.

bool	empty (const Transaction &txn) const
	Checks if the database is empty.

bool	erase (const KeyT &key, MDBX_txn *txn=nullptr)
	Removes key from DB.

bool	erase (const KeyT &key, const Transaction &txn)
	Removes key from DB.

void	clear (MDBX_txn *txn=nullptr)
	Clears all key-value pairs from the database.

void	clear (const Transaction &txn)
	Clears all key-value pairs from the database.

Public Member Functions inherited from mdbxc::BaseTable
	BaseTable (std::shared_ptr< Connection > connection, std::string name, MDBX_db_flags_t flags)
	Construct the database table accessor.

virtual	~BaseTable ()=default

bool	is_connected () const
	Checks if the connection is currently active.

void	connect ()
	Connects to the MDBX environment if not already connected.

void	disconnect ()
	Disconnects the MDBX environment.

void	begin (TransactionMode mode=TransactionMode::WRITABLE)
	Begins a manual transaction (must be committed or rolled back later).

void	commit ()
	Commits the current manual transaction.

void	rollback ()
	Rolls back the current manual transaction.

template<typename Func>
void	execute_in_transaction (Func operation, TransactionMode mode=TransactionMode::WRITABLE)
	Executes an operation inside an automatic transaction.

Private Member Functions
template<typename F>
void	with_transaction (F &&action, TransactionMode mode=TransactionMode::WRITABLE, MDBX_txn *txn=nullptr) const
	Executes a functor within a transaction context.

template<template< class... > class ContainerT>
void	db_load (ContainerT< KeyT, ValueT > &container, MDBX_txn *txn_handle)
	Loads data from the database into the container.

void	db_load (std::vector< std::pair< KeyT, ValueT > > &out_vector, MDBX_txn *txn)
	Loads all key-value pairs into a std::vector of pairs.

bool	db_get (const KeyT &key, ValueT &value, MDBX_txn *txn_handle) const
	Gets a value by key from the database.

bool	db_contains (const KeyT &key, MDBX_txn *txn_handle) const
	Checks whether a key exists in the database.

std::size_t	db_count (MDBX_txn *txn_handle) const
	Returns the number of elements in the database.

template<template< class... > class ContainerT>
void	db_append (const ContainerT< KeyT, ValueT > &container, MDBX_txn *txn_handle)
	Appends the content of the container to the database.

void	db_append (const std::vector< std::pair< KeyT, ValueT > > &container, MDBX_txn *txn_handle)
	Appends the content of the vector to the database.

template<template< class... > class ContainerT>
void	db_reconcile (const ContainerT< KeyT, ValueT > &container, MDBX_txn *txn_handle)
	Reconciles the content of the database with the container.

void	db_reconcile (const std::vector< std::pair< KeyT, ValueT > > &container, MDBX_txn *txn_handle)
	Reconciles the content of the database with the given vector of key-value pairs.

bool	db_insert_if_absent (const KeyT &key, const ValueT &value, MDBX_txn *txn_handle)
	Inserts a key-value pair only if the key does not already exist.

void	db_insert_or_assign (const KeyT &key, const ValueT &value, MDBX_txn *txn_handle)
	Inserts or replaces the key-value pair.

bool	db_erase (const KeyT &key, MDBX_txn *txn_handle)
	Removes a key from the database.

void	db_clear (MDBX_txn *txn_handle)
	Clears all key-value pairs from the database.

Additional Inherited Members
Protected Member Functions inherited from mdbxc::BaseTable
MDBX_txn *	thread_txn () const
	Returns the transaction bound to the current thread, if any.

MDBX_dbi	handle () const
	Gets the raw DBI handle.

Protected Attributes inherited from mdbxc::BaseTable
std::shared_ptr< Connection >	m_connection
	Shared connection to MDBX environment.

MDBX_dbi	m_dbi {}
	DBI handle for the opened table.

Detailed Description

template<class KeyT, class ValueT>
class mdbxc::KeyValueTable< KeyT, ValueT >

Template class for managing key-value pairs in an MDBX database.

Template Parameters

KeyT	Type of the keys.
ValueT	Type of the values.

This class provides functionality to store, retrieve, and manipulate key-value pairs in an MDBX database. It supports various container types, such as std::map, std::unordered_map, std::vector, and std::list. Key-value pairs can be inserted, reconciled, retrieved, and removed with transaction support. The class includes methods for bulk loading and appending data with transactional integrity, ensuring that operations are safely executed in a database environment. Additionally, temporary tables are used during reconciliation to ensure consistent data synchronization. This class also provides methods for checking the count and emptiness of the database, and efficiently handles database errors with detailed exception handling.

Definition at line 27 of file KeyValueTable.hpp.

Constructor & Destructor Documentation

◆ KeyValueTable() [1/2]

template<class KeyT, class ValueT>

mdbxc::KeyValueTable< KeyT, ValueT >::KeyValueTable	(	std::shared_ptr< Connection >	connection,
		std::string	name = "kv_store",
		MDBX_db_flags_t	flags = MDBX_DB_DEFAULTS \| MDBX_CREATE )

inline

Default constructor.

Parameters

connection	Existing Connection instance.
name	Name of the table within the MDBX environment.
flags	Additional MDBX database flags.

Definition at line 34 of file KeyValueTable.hpp.

◆ KeyValueTable() [2/2]

template<class KeyT, class ValueT>

mdbxc::KeyValueTable< KeyT, ValueT >::KeyValueTable	(	const Config &	config,
		std::string	name = "kv_store",
		MDBX_db_flags_t	flags = MDBX_DB_DEFAULTS \| MDBX_CREATE )

inlineexplicit

Constructor with configuration.

Parameters

config	Configuration settings for the database.
name	Name of the table within the MDBX environment.
flags	Additional MDBX database flags.

Definition at line 45 of file KeyValueTable.hpp.

◆ ~KeyValueTable()

template<class KeyT, class ValueT>

mdbxc::KeyValueTable< KeyT, ValueT >::~KeyValueTable ( )

finaloverridedefault

Destructor.

Member Function Documentation

◆ append() [1/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::append	(	const ContainerT< KeyT, ValueT > &	container,
		const Transaction &	txn )

inline

Appends data to the database.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container with content to be synchronized.
txn	Optional transaction handle.

Exceptions

MdbxException if a database error occurs.

Definition at line 289 of file KeyValueTable.hpp.

◆ append() [2/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::append	(	const ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn = nullptr )

inline

Appends data to the database.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container with content to be synchronized.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 277 of file KeyValueTable.hpp.

◆ append() [3/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::append	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		const Transaction &	txn )

inline

Appends data from a vector to the database using a provided transaction.

Parameters

container	Vector with content to be synchronized.
txn	Transaction wrapper.

Exceptions

MdbxException if a database error occurs.

Definition at line 308 of file KeyValueTable.hpp.

◆ append() [4/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::append	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		MDBX_txn *	txn = nullptr )

inline

Appends data from a vector to the database.

Parameters

container	Vector with content to be synchronized.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 298 of file KeyValueTable.hpp.

◆ at() [1/2]

template<class KeyT, class ValueT>

ValueT mdbxc::KeyValueTable< KeyT, ValueT >::at	(	const KeyT &	key,
		const Transaction &	txn ) const

inline

Retrieves value by key or throws.

Parameters

key	The key to look up.
txn	Transaction wrapper used for the lookup.

Returns: The value associated with the key.

Exceptions

std::out_of_range	if key not found.
MdbxException	if DB error occurs.

Definition at line 458 of file KeyValueTable.hpp.

◆ at() [2/2]

template<class KeyT, class ValueT>

ValueT mdbxc::KeyValueTable< KeyT, ValueT >::at	(	const KeyT &	key,
		MDBX_txn *	txn = nullptr ) const

inline

Retrieves value by key or throws.

Parameters

key	The key to look up.
txn	Active MDBX transaction.

Returns: The value associated with the key.

Exceptions

std::out_of_range	if key not found.
MdbxException	if DB error occurs.

Definition at line 442 of file KeyValueTable.hpp.

◆ clear() [1/2]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::clear ( const Transaction & txn )

inline

Clears all key-value pairs from the database.

Parameters

txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 657 of file KeyValueTable.hpp.

◆ clear() [2/2]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::clear ( MDBX_txn * txn = nullptr )

inline

Clears all key-value pairs from the database.

Parameters

txn	Active transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 648 of file KeyValueTable.hpp.

◆ contains() [1/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::contains	(	const KeyT &	key,
		const Transaction &	txn ) const

inline

Checks whether a key exists in the database.

Parameters

key	The key to look up.
txn	Transaction wrapper used for the lookup.

Returns: True if the key exists, false otherwise.

Exceptions

MdbxException if DB error occurs.

Definition at line 579 of file KeyValueTable.hpp.

◆ contains() [2/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::contains	(	const KeyT &	key,
		MDBX_txn *	txn = nullptr ) const

inline

Checks whether a key exists in the database.

Parameters

key	The key to look up.
txn	Active transaction.

Returns: True if the key exists, false otherwise.

Exceptions

MdbxException if DB error occurs.

Definition at line 566 of file KeyValueTable.hpp.

◆ count() [1/2]

template<class KeyT, class ValueT>

std::size_t mdbxc::KeyValueTable< KeyT, ValueT >::count ( const Transaction & txn ) const

inline

Returns the number of elements in the database.

Parameters

txn	Transaction wrapper used for the count operation.

Returns: The number of key-value pairs.

Exceptions

MdbxException if DB error occurs.

Definition at line 599 of file KeyValueTable.hpp.

◆ count() [2/2]

template<class KeyT, class ValueT>

std::size_t mdbxc::KeyValueTable< KeyT, ValueT >::count ( MDBX_txn * txn = nullptr ) const

inline

Returns the number of elements in the database.

Parameters

txn	Active transaction.

Returns: The number of key-value pairs.

Exceptions

MdbxException if DB error occurs.

Definition at line 587 of file KeyValueTable.hpp.

◆ db_append() [1/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_append	(	const ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn_handle )

inlineprivate

Appends the content of the container to the database.

Template Parameters

ContainerT Template for the container type (map or unordered_map).

Parameters

container	Container with content to append.
txn_handle	Active transaction handle.

Exceptions

MdbxException if a database error occurs.

Definition at line 781 of file KeyValueTable.hpp.

◆ db_append() [2/2]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_append	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		MDBX_txn *	txn_handle )

inlineprivate

Appends the content of the vector to the database.

Parameters

container	Vector with key-value pairs to append.
txn_handle	Active transaction handle.

Exceptions

MdbxException if a database error occurs.

Definition at line 799 of file KeyValueTable.hpp.

◆ db_clear()

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_clear ( MDBX_txn * txn_handle )

inlineprivate

Clears all key-value pairs from the database.

Exceptions

MdbxException if an MDBX error occurs.

Definition at line 961 of file KeyValueTable.hpp.

◆ db_contains()

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::db_contains	(	const KeyT &	key,
		MDBX_txn *	txn_handle ) const

inlineprivate

Checks whether a key exists in the database.

Parameters

key	The key to check.
txn_handle	The active transaction.

Returns: True if key exists, false otherwise.

Exceptions

MdbxException if a database error occurs.

Definition at line 755 of file KeyValueTable.hpp.

◆ db_count()

template<class KeyT, class ValueT>

std::size_t mdbxc::KeyValueTable< KeyT, ValueT >::db_count ( MDBX_txn * txn_handle ) const

inlineprivate

Returns the number of elements in the database.

Parameters

txn_handle Active transaction handle.

Returns: The number of key-value pairs in the database.

Exceptions

MdbxException if a database error occurs.

Definition at line 769 of file KeyValueTable.hpp.

◆ db_erase()

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::db_erase	(	const KeyT &	key,
		MDBX_txn *	txn_handle )

inlineprivate

Removes a key from the database.

Parameters

key	The key of the pair to be removed.
txn_handle	The active MDBX transaction.

Returns: True if the key was found and deleted, false if the key was not found.

Exceptions

MdbxException if deletion fails for other reasons.

Definition at line 949 of file KeyValueTable.hpp.

◆ db_get()

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::db_get	(	const KeyT &	key,
		ValueT &	value,
		MDBX_txn *	txn_handle ) const

inlineprivate

Gets a value by key from the database.

Parameters

key	The key to search for.
value	Reference to store the retrieved value.
txn_handle	The active transaction.

Returns: True if found, false otherwise.

Exceptions

MdbxException if a database error occurs.

Definition at line 739 of file KeyValueTable.hpp.

◆ db_insert_if_absent()

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::db_insert_if_absent	(	const KeyT &	key,
		const ValueT &	value,
		MDBX_txn *	txn_handle )

inlineprivate

Inserts a key-value pair only if the key does not already exist.

Parameters

key	The key to insert.
value	The value to insert.
txn_handle	The active MDBX transaction.

Returns: true if the key-value pair was inserted, false if the key already existed.

Exceptions

MdbxException if the insert fails for reasons other than key existence.

Definition at line 912 of file KeyValueTable.hpp.

◆ db_insert_or_assign()

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_insert_or_assign	(	const KeyT &	key,
		const ValueT &	value,
		MDBX_txn *	txn_handle )

inlineprivate

Inserts or replaces the key-value pair.

Parameters

key	The key to insert or replace.
value	The value to set.
txn_handle	The active MDBX transaction.

Exceptions

MdbxException if the operation fails.

Definition at line 933 of file KeyValueTable.hpp.

◆ db_load() [1/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_load	(	ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn_handle )

inlineprivate

Loads data from the database into the container.

Template Parameters

ContainerT Template for the container type.

Parameters

container	Container to be synchronized with database content.
txn_handle	Active transaction handle.

Exceptions

MdbxException if a database error occurs.

Definition at line 701 of file KeyValueTable.hpp.

◆ db_load() [2/2]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_load	(	std::vector< std::pair< KeyT, ValueT > > &	out_vector,
		MDBX_txn *	txn )

inlineprivate

Loads all key-value pairs into a std::vector of pairs.

Parameters

out_vector	The output vector to fill.
txn	Optional transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 719 of file KeyValueTable.hpp.

◆ db_reconcile() [1/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_reconcile	(	const ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn_handle )

inlineprivate

Reconciles the content of the database with the container.

Synchronizes the main table with the content of the container by using a temporary table. Clears old data, inserts new data, and updates existing records in the main table.

Template Parameters

ContainerT Template for the container type (map or unordered_map).

Parameters

container	Container with key-value pairs to be reconciled with the database.
txn_handle	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 835 of file KeyValueTable.hpp.

◆ db_reconcile() [2/2]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_reconcile	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		MDBX_txn *	txn_handle )

inlineprivate

Reconciles the content of the database with the given vector of key-value pairs.

Clears existing records not present in the vector, and upserts all from the vector.

Parameters

container	Vector of key-value pairs to reconcile with the database.
txn_handle	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 871 of file KeyValueTable.hpp.

◆ empty() [1/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::empty ( const Transaction & txn ) const

inline

Checks if the database is empty.

Parameters

txn	Transaction wrapper used for the check.

Returns: True if the database is empty, false otherwise.

Exceptions

MdbxException if a database error occurs.

Definition at line 619 of file KeyValueTable.hpp.

◆ empty() [2/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::empty ( MDBX_txn * txn = nullptr ) const

inline

Checks if the database is empty.

Parameters

txn	Optional transaction handle.

Returns: True if the database is empty, false otherwise.

Exceptions

MdbxException if a database error occurs.

Definition at line 607 of file KeyValueTable.hpp.

◆ erase() [1/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::erase	(	const KeyT &	key,
		const Transaction &	txn )

inline

Removes key from DB.

Parameters

key	The key of the pair to be removed.
txn	Transaction wrapper used for the operation.

Returns: True if the key was found and deleted, false if the key was not found.

Exceptions

MdbxException if deletion fails.

Definition at line 641 of file KeyValueTable.hpp.

◆ erase() [2/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::erase	(	const KeyT &	key,
		MDBX_txn *	txn = nullptr )

inline

Removes key from DB.

Parameters

key	The key of the pair to be removed.
txn	Active transaction.

Returns: True if the key was found and deleted, false if the key was not found.

Exceptions

MdbxException if deletion fails.

Definition at line 628 of file KeyValueTable.hpp.

◆ find() [1/2]

template<class KeyT, class ValueT>

std::pair< bool, ValueT > mdbxc::KeyValueTable< KeyT, ValueT >::find	(	const KeyT &	key,
		const Transaction &	txn ) const

inline

Finds value by key.

Parameters

key	Key to search for.
txn	Transaction wrapper used for the lookup.

Returns: Pair of success flag and value.

Exceptions

MdbxException on DB error.

Definition at line 532 of file KeyValueTable.hpp.

◆ find() [2/2]

template<class KeyT, class ValueT>

std::pair< bool, ValueT > mdbxc::KeyValueTable< KeyT, ValueT >::find	(	const KeyT &	key,
		MDBX_txn *	txn = nullptr ) const

inline

Finds value by key.

Parameters

key	Key to search for.
txn	Optional active MDBX transaction.

Returns: Pair of success flag and value.

Exceptions

MdbxException on DB error.

Definition at line 517 of file KeyValueTable.hpp.

◆ find_compat() [1/2]

template<class KeyT, class ValueT>

std::pair< bool, ValueT > mdbxc::KeyValueTable< KeyT, ValueT >::find_compat	(	const KeyT &	key,
		const Transaction &	txn ) const

inline

Finds value by key.

Parameters

key	Key to search for.
txn	Transaction wrapper used for the lookup.

Returns: Pair of success flag and value.

Exceptions

MdbxException on DB error.

Definition at line 557 of file KeyValueTable.hpp.

◆ find_compat() [2/2]

template<class KeyT, class ValueT>

std::pair< bool, ValueT > mdbxc::KeyValueTable< KeyT, ValueT >::find_compat	(	const KeyT &	key,
		MDBX_txn *	txn = nullptr ) const

inline

Finds value by key.

Parameters

key	Key to search for.
txn	Optional active MDBX transaction.

Returns: Pair of success flag and value.

Exceptions

MdbxException on DB error.

Definition at line 542 of file KeyValueTable.hpp.

◆ insert() [1/4]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::insert	(	const KeyT &	key,
		const ValueT &	value,
		const Transaction &	txn )

inline

Inserts key-value only if key is absent.

Parameters

key	The key to be inserted.
value	The value to be inserted.
txn	Transaction wrapper used for the insertion.

Returns: true if the pair was inserted, false when the key already exists.

Exceptions

MdbxException if a database error occurs.

Definition at line 372 of file KeyValueTable.hpp.

◆ insert() [2/4]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::insert	(	const KeyT &	key,
		const ValueT &	value,
		MDBX_txn *	txn = nullptr )

inline

Inserts key-value only if key is absent.

Parameters

key	The key to be inserted.
value	The value to be inserted.
txn	Active MDBX transaction.

Returns: true if the pair was inserted, false when the key already exists.

Exceptions

MdbxException if a database error occurs.

Definition at line 358 of file KeyValueTable.hpp.

◆ insert() [3/4]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::insert	(	const std::pair< KeyT, ValueT > &	pair,
		const Transaction &	txn )

inline

Inserts key-value only if key is absent.

Parameters

pair	The key-value pair to be inserted.
txn	Transaction wrapper used for the operation.

Returns: true if the pair was inserted, false when the key already exists.

Exceptions

MdbxException if a database error occurs.

Definition at line 394 of file KeyValueTable.hpp.

◆ insert() [4/4]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::insert	(	const std::pair< KeyT, ValueT > &	pair,
		MDBX_txn *	txn = nullptr )

inline

Inserts key-value only if key is absent.

Parameters

pair	The key-value pair to be inserted.
txn	Active MDBX transaction.

Returns: true if the pair was inserted, false when the key already exists.

Exceptions

MdbxException if a database error occurs.

Definition at line 381 of file KeyValueTable.hpp.

◆ insert_or_assign() [1/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::insert_or_assign	(	const KeyT &	key,
		const ValueT &	value,
		const Transaction &	txn )

inline

Inserts or replaces key-value pair.

Parameters

key	The key to be inserted.
value	The value to be inserted.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 414 of file KeyValueTable.hpp.

◆ insert_or_assign() [2/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::insert_or_assign	(	const KeyT &	key,
		const ValueT &	value,
		MDBX_txn *	txn = nullptr )

inline

Inserts or replaces key-value pair.

Parameters

key	The key to be inserted.
value	The value to be inserted.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 403 of file KeyValueTable.hpp.

◆ insert_or_assign() [3/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::insert_or_assign	(	const std::pair< KeyT, ValueT > &	pair,
		const Transaction &	txn )

inline

Inserts or replaces key-value pair.

Parameters

pair	The key-value pair to be inserted.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 432 of file KeyValueTable.hpp.

◆ insert_or_assign() [4/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::insert_or_assign	(	const std::pair< KeyT, ValueT > &	pair,
		MDBX_txn *	txn = nullptr )

inline

Inserts or replaces key-value pair.

Parameters

pair	The key-value pair to be inserted.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 422 of file KeyValueTable.hpp.

◆ load() [1/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::load	(	ContainerT< KeyT, ValueT > &	container,
		const Transaction &	txn )

inline

Loads data from the database into the container using provided transaction.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container to be synchronized with database content.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 185 of file KeyValueTable.hpp.

◆ load() [2/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::load	(	ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn = nullptr )

inline

Loads data from the database into the container.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container to be synchronized with database content.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 173 of file KeyValueTable.hpp.

◆ load() [3/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::load	(	std::vector< std::pair< KeyT, ValueT > > &	container,
		const Transaction &	txn )

inline

Loads all key-value pairs into a std::vector of pairs.

Parameters

container	Container to be synchronized with database content.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 203 of file KeyValueTable.hpp.

◆ load() [4/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::load	(	std::vector< std::pair< KeyT, ValueT > > &	container,
		MDBX_txn *	txn = nullptr )

inline

Loads all key-value pairs into a std::vector of pairs.

Parameters

container	Container to be synchronized with database content.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 193 of file KeyValueTable.hpp.

◆ operator()()

template<class KeyT, class ValueT>

template<template< class... > class ContainerT = std::map>

std::conditional< std::is_same< ContainerT< KeyT, ValueT >, std::vector< std::pair< KeyT, ValueT > > >::value, std::vector< std::pair< KeyT, ValueT > >, ContainerT< KeyT, ValueT > >::type mdbxc::KeyValueTable< KeyT, ValueT >::operator() ( )

inline

Loads all key-value pairs from the database into a container.

Template Parameters

ContainerT Container type (e.g., std::map, std::unordered_map, std::vector).

Returns: Filled container.

Exceptions

MdbxException if a database error occurs.

Definition at line 106 of file KeyValueTable.hpp.

◆ operator=() [1/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

KeyValueTable & mdbxc::KeyValueTable< KeyT, ValueT >::operator= ( const ContainerT< KeyT, ValueT > & container )

inline

Assigns a container (e.g., std::map or std::unordered_map) to the database.

Parameters

container The container with key-value pairs.

Returns: Reference to this KeyValueTable.

Exceptions

MdbxException if a database error occurs.

Note: The transaction mode is taken from the database configuration.

Definition at line 63 of file KeyValueTable.hpp.

◆ operator=() [2/2]

template<class KeyT, class ValueT>

KeyValueTable & mdbxc::KeyValueTable< KeyT, ValueT >::operator= ( const std::vector< std::pair< KeyT, ValueT > > & container )

inline

Assigns a vector of key-value pairs to the database.

Parameters

container The vector with key-value pairs.

Returns: Reference to this KeyValueTable.

Exceptions

MdbxException if a database error occurs.

Note: The transaction mode is taken from the database configuration.

Definition at line 75 of file KeyValueTable.hpp.

◆ operator[]()

template<class KeyT, class ValueT>

AssignmentProxy mdbxc::KeyValueTable< KeyT, ValueT >::operator[] ( const KeyT & key )

inline

Provides convenient access to insert or read a value by key.

Parameters

key	Key to access.

Returns: Proxy object used for assignment or implicit read.

Definition at line 161 of file KeyValueTable.hpp.

◆ reconcile() [1/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::reconcile	(	const ContainerT< KeyT, ValueT > &	container,
		const Transaction &	txn )

inline

Reconciles the database with the container.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container to be reconciled with the database.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 330 of file KeyValueTable.hpp.

◆ reconcile() [2/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::reconcile	(	const ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn = nullptr )

inline

Reconciles the database with the container.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container to be reconciled with the database.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 318 of file KeyValueTable.hpp.

◆ reconcile() [3/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::reconcile	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		const Transaction &	txn )

inline

Reconciles the database with the vector of key-value pairs using provided transaction.

Parameters

container	Vector to be reconciled with the database.
txn	Transaction wrapper.

Exceptions

MdbxException if a database error occurs.

Definition at line 348 of file KeyValueTable.hpp.

◆ reconcile() [4/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::reconcile	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		MDBX_txn *	txn = nullptr )

inline

Reconciles the database with the vector of key-value pairs.

Parameters

container	Vector to be reconciled with the database.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 338 of file KeyValueTable.hpp.

◆ retrieve_all() [1/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT = std::map>

std::conditional< std::is_same< ContainerT< KeyT, ValueT >, std::vector< std::pair< KeyT, ValueT > > >::value, std::vector< std::pair< KeyT, ValueT > >, ContainerT< KeyT, ValueT > >::type mdbxc::KeyValueTable< KeyT, ValueT >::retrieve_all ( const Transaction & txn )

inline

Retrieves all key-value pairs into the specified container type.

Template Parameters

ContainerT Container type (e.g., std::map, std::unordered_map, std::vector).

Parameters

txn	Transaction wrapper used for the retrieval.

Returns: Filled container.

Exceptions

MdbxException if a database error occurs.

Definition at line 266 of file KeyValueTable.hpp.

◆ retrieve_all() [2/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT = std::map>

std::conditional< std::is_same< ContainerT< KeyT, ValueT >, std::vector< std::pair< KeyT, ValueT > > >::value, std::vector< std::pair< KeyT, ValueT > >, ContainerT< KeyT, ValueT > >::type mdbxc::KeyValueTable< KeyT, ValueT >::retrieve_all ( MDBX_txn * txn = nullptr )

inline

Retrieves all key-value pairs into the specified container type.

Template Parameters

ContainerT Container type (e.g., std::map, std::unordered_map, std::vector).

Parameters

txn	Optional transaction handle.

Returns: Filled container.

Exceptions

MdbxException if a database error occurs.

Definition at line 242 of file KeyValueTable.hpp.

◆ try_get() [1/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::try_get	(	const KeyT &	key,
		ValueT &	out,
		const Transaction &	txn ) const

inline

Tries to find value by key.

Parameters

key	The key to look up.
out	Reference to output value.
txn	Transaction wrapper used for the lookup.

Returns: True if key exists, false otherwise.

Exceptions

MdbxException if DB error occurs.

Definition at line 482 of file KeyValueTable.hpp.

◆ try_get() [2/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::try_get	(	const KeyT &	key,
		ValueT &	out,
		MDBX_txn *	txn ) const

inline

Tries to find value by key.

Parameters

key	The key to look up.
out	Reference to output value.
txn	Active MDBX transaction.

Returns: True if key exists, false otherwise.

Exceptions

MdbxException if DB error occurs.

Definition at line 468 of file KeyValueTable.hpp.

◆ with_transaction()

template<class KeyT, class ValueT>

template<typename F>

void mdbxc::KeyValueTable< KeyT, ValueT >::with_transaction	(	F &&	action,
		TransactionMode	mode = TransactionMode::WRITABLE,
		MDBX_txn *	txn = nullptr ) const

inlineprivate

Executes a functor within a transaction context.

Template Parameters

F	Callable type accepting `MDBX_txn*`.

Parameters

action	Functor to execute.
mode	Transaction mode used when a new transaction is created.
txn	Optional existing transaction handle.

Definition at line 669 of file KeyValueTable.hpp.

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

include/mdbx_containers/KeyValueTable.hpp

Classes

Public Member Functions

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ KeyValueTable() [1/2]

◆ KeyValueTable() [2/2]

◆ ~KeyValueTable()

Member Function Documentation

◆ append() [1/4]

◆ append() [2/4]

◆ append() [3/4]

◆ append() [4/4]

◆ at() [1/2]

◆ at() [2/2]

◆ clear() [1/2]

◆ clear() [2/2]

◆ contains() [1/2]

◆ contains() [2/2]

◆ count() [1/2]

◆ count() [2/2]

◆ db_append() [1/2]

◆ db_append() [2/2]

◆ db_clear()

◆ db_contains()

◆ db_count()

◆ db_erase()

◆ db_get()

◆ db_insert_if_absent()

◆ db_insert_or_assign()

◆ db_load() [1/2]

◆ db_load() [2/2]

◆ db_reconcile() [1/2]

◆ db_reconcile() [2/2]

◆ empty() [1/2]

◆ empty() [2/2]

◆ erase() [1/2]

◆ erase() [2/2]

◆ find() [1/2]

◆ find() [2/2]

◆ find_compat() [1/2]

◆ find_compat() [2/2]

◆ insert() [1/4]

◆ insert() [2/4]

◆ insert() [3/4]

◆ insert() [4/4]

◆ insert_or_assign() [1/4]

◆ insert_or_assign() [2/4]

◆ insert_or_assign() [3/4]

◆ insert_or_assign() [4/4]

◆ load() [1/4]

◆ load() [2/4]

◆ load() [3/4]

◆ load() [4/4]

◆ operator()()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]()

◆ reconcile() [1/4]

◆ reconcile() [2/4]

◆ reconcile() [3/4]

◆ reconcile() [4/4]

◆ retrieve_all() [1/2]

◆ retrieve_all() [2/2]

◆ try_get() [1/2]

◆ try_get() [2/2]

◆ with_transaction()