Reference/SDK support

SDK support

database/CVarTable_

A schema-driven row table whose records and query descriptions are dynamic values.

C++23 mc/database/CVarTable_.h
#include <mc/database/CVarTable_.h>

Obtain a CVarTable<RI> from CDatabase with a schema and table name. RI is uint32_t or uint64_t and must match the table’s row-ID width.

The database must outlive its table handles. Writes are staged; commit() applies them and rollback() discards them. Query callbacks return false to stop traversal.

Jump to a declaration · 29
CVarTable CVarTable::commit CVarTable::count CVarTable::dump CVarTable::erase CVarTable::get CVarTable::getMax CVarTable::getMin CVarTable::getRows CVarTable::has CVarTable::insert CVarTable::query CVarTable::QueryFunc CVarTable::QueryFunc_ CVarTable::reserve CVarTable::rollback CVarTable::RowId CVarTable::RowSet CVarTable::RowVector CVarTable::setQuery CVarTable::toHashMap CVarTable::toMap CVarTable::toMultimap CVarTable::traverseBackward CVarTable::traverseForward CVarTable::update CVarTable::UpdateMap_ CVarTable::vectorQuery CVarTable::~CVarTable

CVarTable

template<class RI> class CVarTable

Types, constants & data

using RowId = RI;
using RowSet = CHashSet<RowId>;
using RowVector = CVector<RowId>;
using QueryFunc_ = std::function<bool(RowId rowId, cvec& r)>;
using UpdateMap_ = CHashMap<RowId, RowId>;
using QueryFunc = std::function<bool(cvec& r)>;

Methods

~CVarTable

~CVarTable();

Releases this dynamic table handle and its staged state. It does not implicitly commit pending edits; the parent database owns persistent table storage.

dump

void dump();

Writes diagnostic table contents to the implementation’s output stream. This is an inspection aid rather than an export format.

reserve

void reserve(size_t numRows);

Reserves space for the specified number of staged rows on this table handle. It does not insert rows or preallocate persistent row IDs.

insert

void insert(cvec& row) noexcept;
void insert(cvec&& row) noexcept;

Stages a row for insertion; it becomes committed through commit(). The lvalue overload copies the row, while the rvalue overload may consume its fields.

erase

void erase(RowId rowId) noexcept;
void erase(cvec& row) noexcept;

Stages deletion of a row by its persistent ID or row object. Call commit() to publish the deletion, or rollback() to discard it.

update

void update(cvec& row);
void update(cvec&& row);

Stages replacement of a row that already has a nonzero row ID. Commit can assign a new physical row ID; callers must not assume the replacement retains the original ID.

commit

void commit();

Applies staged row and index changes; commit validation can fail, for example on a unique-key conflict.

rollback

void rollback() noexcept;

Discards staged changes.

get

bool get(const CFields& fs, cvec& row, RowId rowId) noexcept;
bool get(cvec& row, RowId rowId) noexcept;
void get(const CFields& fs, const RowSet& rs, QueryFunc qf) noexcept;
void get(const RowSet& rs, QueryFunc qf) noexcept;
void get(const CFields& fs, const RowVector& rs, QueryFunc qf) noexcept;
void get(const RowVector& rs, QueryFunc qf) noexcept;
bool get(const CFields& fs, const cstr& index, cvec& row, const cvar& value) noexcept;
bool get(const cstr& index, cvec& row, const cvar& value) noexcept;
template<class... Args> bool get(const CFields& fs, const cstr& index, cvec& row, const cvar& value, Args&&... args);
template<class... Args> bool get(const cstr& index, cvec& row, const cvar& value, Args&&... args);
bool get(const CFields& fs, const cstr& index, const cvec& keys, cvec& row, const cvar& value);
bool get(const cstr& index, const cvec& keys, cvec& row, const cvar& value);

Fetches rows by ID or index. Boolean overloads report whether a row was found; callbacks return false to stop.

has

bool has(const cstr& index, const cvar& value) noexcept;
template<class... Args> bool has(const cstr& index, const cvar& value, Args&&... args);
bool has(const cstr& index, const cvec& keys, const cvar& value);

Tests whether an indexed value exists in committed table data. Composite-index overloads also constrain the remaining key fields.

query

void query(const CFields& fs, const cstr& index, QueryFunc func, const cvar& start, const cvar& end);
void query(const cstr& index, QueryFunc func, const cvar& start, const cvar& end);
void query(const CFields& fs, const cstr& index, QueryFunc func, const cvar& value);
void query(const cstr& index, QueryFunc func, const cvar& value);
template<class... Args> void query(const CFields& fs, const cstr& index, QueryFunc func, const cvar& start, const cvar& end, Args&&... args);
template<class... Args> void query(const cstr& index, QueryFunc func, const cvar& start, const cvar& end, Args&&... args);
void query(const CFields& fs, const cstr& index, const cvec& keys, QueryFunc func, const cvar& start, const cvar& end);
void query(const cstr& index, const cvec& keys, QueryFunc func, const cvar& start, const cvar& end);

Applies an indexed query to a row-ID set.

getRows

void getRows(const CFields& fs, const cstr& index, cvec& rows, const cvar& value);
void getRows(const cstr& index, cvec& rows, const cvar& value);
template<class... Args> void getRows(const CFields& fs, const cstr& index, cvec& rows, const cvar& value, Args&&... args);
template<class... Args> void getRows(const cstr& index, cvec& rows, const cvar& value, Args&&... args);

Appends matching rows to the supplied output vector without clearing it. A field selection limits which fields are materialized.

setQuery

void setQuery(const CFields& fs, const cstr& index, RowSet& rs, const cvar& start, const cvar& end);
void setQuery(const cstr& index, RowSet& rs, const cvar& start, const cvar& end);
void setQuery(const CFields& fs, const cstr& index, RowSet& rs, const cvar& value);
void setQuery(const cstr& index, RowSet& rs, const cvar& value);
template<class... Args> void setQuery(const CFields& fs, const cstr& index, RowSet& rs, const cvar& start, const cvar& end, Args&&... args);
template<class... Args> void setQuery(const cstr& index, RowSet& rs, const cvar& start, const cvar& end, Args&&... args);

Adds matching row IDs to the supplied set, preserving existing members and suppressing duplicate IDs. Use get() afterwards when row contents are needed.

vectorQuery

void vectorQuery(const CFields& fs, const cstr& index, RowVector& rs, const cvar& start, const cvar& end);
void vectorQuery(const cstr& index, RowVector& rs, const cvar& start, const cvar& end);
void vectorQuery(const CFields& fs, const cstr& index, RowVector& rs, const cvar& value);
void vectorQuery(const cstr& index, RowVector& rs, const cvar& value);
template<class... Args> void vectorQuery(const CFields& fs, const cstr& index, RowVector& rs, const cvar& start, const cvar& end, Args&&... args);
template<class... Args> void vectorQuery(const cstr& index, RowVector& rs, const cvar& start, const cvar& end, Args&&... args);

Appends matching row IDs to the supplied vector without clearing it. A separate get() can retrieve selected fields for those IDs.

traverseForward

void traverseForward(const CFields& fs, QueryFunc func);
void traverseForward(QueryFunc func);
void traverseForward(const CFields& fs, const cstr& index, QueryFunc func);
void traverseForward(const cstr& index, QueryFunc func);
template<class... Args> void traverseForward(const CFields& fs, const cstr& index, QueryFunc func, Args&&... args);
template<class... Args> void traverseForward(const cstr& index, QueryFunc func, Args&&... args);
void traverseForward(const CFields& fs, const cstr& index, const cvec& keys, QueryFunc func);
void traverseForward(const cstr& index, const cvec& keys, QueryFunc func);

Visits rows in forward index order; false from the callback stops traversal.

traverseBackward

void traverseBackward(const CFields& fs, QueryFunc func);
void traverseBackward(QueryFunc func);
void traverseBackward(const CFields& fs, const cstr& index, QueryFunc func);
void traverseBackward(const cstr& index, QueryFunc func);
template<class... Args> void traverseBackward(const CFields& fs, const cstr& index, QueryFunc func, Args&&... args);
template<class... Args> void traverseBackward(const cstr& index, QueryFunc func, Args&&... args);
void traverseBackward(const CFields& fs, const cstr& index, const cvec& keys, QueryFunc func);
void traverseBackward(const cstr& index, const cvec& keys, QueryFunc func);

Visits rows in reverse index order; false from the callback stops traversal.

getMin

template<class... Args> bool getMin(const cstr& index, cvar& ret, Args&&... args);

Retrieves the first matching row in forward index order.

getMax

template<class... Args> bool getMax(const cstr& index, cvar& ret, Args&&... args);

Retrieves the first matching row in reverse index order.

toMap

template<class K, class V> auto toMap(uint32_t k, uint32_t v);

Builds an ordered map from the selected key and value fields. Duplicate keys retain the first value encountered during forward traversal.

toHashMap

template<class K, class V> auto toHashMap(uint32_t k, uint32_t v);

Builds a hash map from the selected key and value fields. Duplicate keys retain the first value encountered during forward traversal.

toMultimap

template<class K, class V> auto toMultimap(uint32_t k, uint32_t v);

Builds an ordered multimap from the selected fields, retaining repeated keys and all corresponding values.

count

size_t count() noexcept;

Returns the committed row count. Pending insertions and deletions on this handle are reflected only after commit.