ludus::content::string_dictionary::StringDictionaryWriter¶
Ludus Wiki · API overview · Browse API
Class
Collects spellings, deduplicates them, and encodes one canonical dictionary.
Lifecycle: create, TryAdd spellings in any order, TryFinish, then TryRemap record references and TryEncode. The encoded bytes depend only on the set of unique spellings, the byte policy and the revision, never on arrival order, worker scheduling or hash seeds.
TryAdd returns provisional indices in first-arrival order (the empty spelling is always 0). TryFinish sorts unique spellings by unsigned byte order; callers then rewrite every stored provisional index through TryRemap.
Move-only and not internally synchronized: callers serialize all calls on one writer. The allocation domain must outlive the writer. Spellings are copied, so callers may release their input immediately after TryAdd returns.
#include <ludus/content/string_dictionary/string_dictionary_writer.h>
class ludus::content::string_dictionary::StringDictionaryWriter final
Methods¶
StringDictionaryWriter¶
ludus::content::string_dictionary::StringDictionaryWriter::StringDictionaryWriter() noexcept=default
Constructs an empty writer; create one with CreateStringDictionaryWriter.
~StringDictionaryWriter¶
ludus::content::string_dictionary::StringDictionaryWriter::~StringDictionaryWriter() noexcept
Releases all working storage through the original domain.
StringDictionaryWriter¶
ludus::content::string_dictionary::StringDictionaryWriter::StringDictionaryWriter(StringDictionaryWriter &&other) noexcept
Transfers the writer and leaves other empty.
operator=¶
StringDictionaryWriter & ludus::content::string_dictionary::StringDictionaryWriter::operator=(StringDictionaryWriter &&other) noexcept
Releases this writer, then takes other's state and leaves other empty.
Related types: StringDictionaryWriter
StringDictionaryWriter¶
ludus::content::string_dictionary::StringDictionaryWriter::StringDictionaryWriter(const StringDictionaryWriter &)=delete
Writers own unique working storage and cannot be copied.
operator=¶
StringDictionaryWriter & ludus::content::string_dictionary::StringDictionaryWriter::operator=(const StringDictionaryWriter &)=delete
Writers own unique working storage and cannot be copy-assigned.
Related types: StringDictionaryWriter
IsValid¶
bool ludus::content::string_dictionary::StringDictionaryWriter::IsValid() const noexcept
Whether the writer was created and has not been moved from.
IsFinished¶
bool ludus::content::string_dictionary::StringDictionaryWriter::IsFinished() const noexcept
Whether TryFinish has succeeded.
GetEntryCount¶
uint32 ludus::content::string_dictionary::StringDictionaryWriter::GetEntryCount() const noexcept
Number of unique spellings including the empty entry; zero when empty.
Related types: uint32
TryAdd¶
StringDictionaryStatus ludus::content::string_dictionary::StringDictionaryWriter::TryAdd(std::string_view spelling, foundation::StringIndex &outProvisionalIndex) noexcept
Adds one spelling, or finds its existing entry.
A duplicate succeeds without allocating, even at the configured limits.
| Parameter | Description |
|---|---|
spelling |
Counted bytes, validated against the byte policy and limits.
|
outProvisionalIndex |
Receives the arrival-order index. Unchanged on failure.
|
Returns
Ok, InvalidHandle, InvalidState after TryFinish or for corrupted table metadata, LimitExceeded, InvalidUtf8, EmbeddedZero or OutOfMemory. Failure leaves the writer unchanged.
Related types: StringDictionaryStatus · foundation::StringIndex
TryFinish¶
StringDictionaryStatus ludus::content::string_dictionary::StringDictionaryWriter::TryFinish() noexcept
Sorts the unique spellings and fixes the final directory indices.
Returns
Ok, InvalidHandle, InvalidState if already finished, or OutOfMemory. On failure the writer remains unfinished and usable.
Related types: StringDictionaryStatus
TryRemap¶
StringDictionaryStatus ludus::content::string_dictionary::StringDictionaryWriter::TryRemap(foundation::StringIndex provisionalIndex, foundation::StringIndex &outIndex) const noexcept
Maps a provisional index from TryAdd to its final directory index.
| Parameter | Description |
|---|---|
provisionalIndex |
Index returned by this writer's TryAdd.
|
outIndex |
Receives the final index. Unchanged on failure.
|
Returns
Ok, InvalidState before TryFinish, or InvalidHandle for an empty writer or an index this writer never returned.
Related types: StringDictionaryStatus · foundation::StringIndex
GetEncodedSize¶
usize ludus::content::string_dictionary::StringDictionaryWriter::GetEncodedSize() const noexcept
Exact encoded size in bytes after TryFinish; zero before it.
Related types: usize
TryEncode¶
StringDictionaryStatus ludus::content::string_dictionary::StringDictionaryWriter::TryEncode(const RevisionDigest &revision, foundation::BorrowedView< uint8 > destination) const noexcept
Encodes the finished dictionary into caller storage, without allocating.
| Parameter | Description |
|---|---|
revision |
Content revision recorded in the header and checked by readers.
|
destination |
Writable storage of exactly GetEncodedSize() bytes; any alignment. Left untouched on failure.
|
Returns
Ok, InvalidHandle, InvalidState before TryFinish, or InvalidArgument for an invalid view or a size mismatch.
Related types: foundation::BorrowedView · StringDictionaryStatus · RevisionDigest · uint8