ludus::foundation::StringTable

Ludus Wiki · API overview · Browse API

Class

Mutable, append-only owner of deduplicated spellings and their table-qualified IDs.

Create one with CreateTable; a default-constructed table is empty and its operations return InvalidHandle. Spelling bytes, entries and lookup metadata are allocated from the creation domain within StringTableConfig::MaxAllocatedBytes; that domain must outlive this table and any FrozenStringTable it becomes. Entries are never removed or reused.

TryIntern, TryFind and TryResolve may be called concurrently from any thread; one internal mutex serializes them. Move, move assignment, destruction and TryFreeze are not synchronized: the caller must first quiesce every other operation on this object. A resolved view stays valid across later insertion, growth, moves and freezing, until the storage owner is destroyed or assigned over.

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

#include <ludus/foundation/strings/string_table.hpp>

class ludus::foundation::StringTable final

Methods

StringTable

ludus::foundation::StringTable::StringTable() noexcept=default

Constructs an empty table that owns no storage.

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

~StringTable

ludus::foundation::StringTable::~StringTable() noexcept

Releases all storage to the creation domain. Requires quiescence; outstanding views dangle.

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

StringTable

ludus::foundation::StringTable::StringTable(StringTable &&other) noexcept

Takes ownership of the storage and token of other, which becomes empty. Requires quiescence.

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

operator=

StringTable & ludus::foundation::StringTable::operator=(StringTable &&other) noexcept

Releases the current storage, then takes over other, which becomes empty.

Views into the previously owned storage dangle. Self-move does nothing. Requires quiescence of both tables.

Related types: StringTable

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

StringTable

ludus::foundation::StringTable::StringTable(const StringTable &)=delete

Not copyable: a table uniquely owns its storage and token.

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

operator=

StringTable & ludus::foundation::StringTable::operator=(const StringTable &)=delete

Not copyable: a table uniquely owns its storage and token.

Related types: StringTable

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

IsValid

bool ludus::foundation::StringTable::IsValid() const noexcept

Returns true when this object owns a table created by CreateTable and not moved or frozen away.

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

TryIntern

StringStatus ludus::foundation::StringTable::TryIntern(std::string_view value, NameId &outId) noexcept

Returns the ID of an exact spelling, inserting a copy when it is absent.

A duplicate succeeds without allocating, even at the entry or byte budget. A new spelling consumes the next index only on success. Serialized by the table mutex.

Parameter	Description
value	Counted bytes, checked against the configured length, UTF-8 and zero-byte rules.
outId	Receives the table-qualified ID on success; unchanged on failure.

Returns

Ok; InvalidHandle for an empty table; TooLarge, InvalidUtf8 or EmbeddedZero for a rejected spelling; CapacityExceeded, TooLarge or OutOfMemory when growth fails; or ProbeExhausted when corrupted lookup metadata has neither the spelling nor a free slot. Failure leaves the logical table unchanged; earlier successful reservations may remain.

Related types: StringStatus · NameId

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

TryFind

StringStatus ludus::foundation::StringTable::TryFind(std::string_view value, NameId &outId) const noexcept

Looks up an exact spelling without inserting or allocating.

Serialized by the table mutex.

Parameter	Description
value	Counted bytes, checked against the configured spelling rules.
outId	Receives the table-qualified ID on success; unchanged on failure.

Returns

Ok; NotFound when the spelling is absent; InvalidHandle for an empty table; TooLarge, InvalidUtf8 or EmbeddedZero for a rejected spelling; or ProbeExhausted when corrupted lookup metadata has neither the spelling nor a free slot.

Related types: StringStatus · NameId

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

TryResolve

StringStatus ludus::foundation::StringTable::TryResolve(NameId id, std::string_view &outSpelling) const &noexcept

Borrows the stored spelling of an ID issued by this table, without allocating.

Serialized by the table mutex. The view covers the stored bytes, which never change; see the class description for its lifetime.

Parameter	Description
id	ID to resolve.
outSpelling	Receives the spelling on success; unchanged on failure.

Returns

Ok; InvalidHandle for an empty table, a representation-invalid ID or an index beyond this table's entries; or WrongTable when the ID carries another table's token.

Related types: StringStatus · NameId

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

TryResolve

StringStatus ludus::foundation::StringTable::TryResolve(NameId, std::string_view &) const &&=delete

Deleted so a view cannot borrow from a temporary table that is about to be destroyed.

Related types: StringStatus · NameId

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp

TryFreeze

StringStatus ludus::foundation::StringTable::TryFreeze(FrozenStringTable &outTable) noexcept

Caller quiesces ALL concurrent operations.

Consumes this table and keeps every token/index stable; outTable must be empty. No allocation required.

Parameter	Description
outTable	Receives the table's storage on success; unchanged on failure.

Returns

Ok, leaving this table empty; InvalidHandle when this table is empty; or InvalidArgument when outTable already owns a table. Failure leaves both objects unchanged.

Related types: StringStatus

Declared in modules/foundation/strings/include/ludus/foundation/strings/string_table.hpp