ludus::foundation::String

Ludus Wiki · API overview · Browse API

Class

Unique, move-only, zero-terminated byte storage.

Contents are counted bytes: sizes, capacities and offsets count bytes, not Unicode scalars, and no operation validates UTF-8 or rejects embedded zero bytes (see ValidateUtf8 and ValidateCString). Up to kInlineCapacity bytes are held without allocation; a longer value occupies one heap allocation of capacity + 1 bytes from the owner's AllocationDomain. The domain is recorded even while the value is inline and must outlive this owner.

Copies are explicit through CloneTo, so deep-copy allocation and failure stay visible. Moves carry the source's domain; TryAssign and TryAppend keep the destination's domain. A failed operation leaves bytes, size, capacity and domain unchanged. An owner is not internally synchronized: concurrent const calls are safe, and any non-const call needs exclusive access.

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

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

class ludus::foundation::String final

Static fields

kInlineCapacity

static constexpr usize ludus::foundation::String::kInlineCapacity = 23

Bytes held inline before an operation must allocate.

A capacity equal to this value selects inline storage; heap capacities are always larger. The value is the current layout baseline, not a stable ABI.

Related types: usize

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

Methods

String

explicit ludus::foundation::String::String(const AllocationDomain &domain=GetSystemAllocationDomain()) noexcept

Creates an empty inline owner that allocates from domain; does not allocate.

Parameter	Description
domain	Allocation domain for later growth. It is borrowed and must outlive this owner.

Related types: AllocationDomain

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

~String

ludus::foundation::String::~String() noexcept

Frees heap storage through the owner's domain; inline storage needs no domain call.

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

String

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

Takes other's bytes, storage and domain without allocating.

other becomes empty and inline and keeps its domain, so it remains usable.

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

operator=

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

Releases this owner's storage, then takes other's bytes, storage and domain.

Does not allocate. other becomes empty and inline and keeps its domain. Self-move does nothing.

Related types: String

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

String

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

Deleted: a deep copy can fail, so it is spelled CloneTo.

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

operator=

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

Deleted: a deep copy can fail, so it is spelled CloneTo, and TryAssign copies bytes.

Related types: String

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

GetSize

usize ludus::foundation::String::GetSize() const noexcept

Number of stored bytes, excluding the terminating zero.

Related types: usize

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

GetCapacity

usize ludus::foundation::String::GetCapacity() const noexcept

Bytes the current storage holds without reallocating, excluding the terminating zero.

kInlineCapacity while inline. Growth may reserve more than requested; do not depend on the exact value. Capacity never shrinks while the owner keeps its storage.

Related types: usize

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

IsEmpty

bool ludus::foundation::String::IsEmpty() const noexcept

True when GetSize is zero.

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

GetDomain

const AllocationDomain & ludus::foundation::String::GetDomain() const noexcept

Domain that allocates and frees this owner's heap storage; borrowed, never null.

Related types: AllocationDomain

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

GetView

std::string_view ludus::foundation::String::GetView() const &noexcept

Borrowed counted view of the stored bytes, which may contain zero bytes.

Valid until the next non-const call on this owner, a move from it, or its destruction.

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

GetView

std::string_view ludus::foundation::String::GetView() const &&=delete

Deleted so a view cannot outlive a temporary owner that is destroyed at the end of the expression.

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

GetData

const char * ludus::foundation::String::GetData() const &noexcept

Borrowed pointer to the stored bytes; never null.

GetData()[GetSize()] is always zero, including for an empty owner, but embedded zero bytes may end a C-string reading early. Valid until the next non-const call on this owner, a move from it, or its destruction.

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

GetData

const char * ludus::foundation::String::GetData() const &&=delete

Deleted so a pointer cannot outlive a temporary owner that is destroyed at the end of the expression.

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

TryAssign

StringStatus ludus::foundation::String::TryAssign(std::string_view value) noexcept

Replaces the contents with a copy of value.

Copies in place, overlap-safe, when value fits the current capacity. Otherwise allocates grown storage (the larger of the request and twice the current capacity, clamped to the maximum), copies value into it and only then frees the old storage. value may therefore borrow this owner's own bytes.

Parameter	Description
value	Bytes to copy; it may alias this owner's contents.

Returns

Ok; TooLarge when value exceeds the maximum capacity (just under half the address space); OutOfMemory when the domain cannot supply the storage. Failure leaves the owner unchanged.

Related types: StringStatus

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

TryAppend

StringStatus ludus::foundation::String::TryAppend(std::string_view value) noexcept

Appends a copy of value; equivalent to TryAppendMany with one view.

Parameter	Description
value	Bytes to append; it may alias this owner's contents.

Returns

Ok, TooLarge or OutOfMemory as for TryAppendMany. Failure leaves the owner unchanged.

Related types: StringStatus

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

TryAppendMany

StringStatus ludus::foundation::String::TryAppendMany(std::span< const std::string_view > values) noexcept

Appends every view in order, with one reserve and one commit for the batch.

The checked total size is computed before anything changes, and the call allocates at most once. When it grows, all views are read while the old storage is still live, so slices of this owner's own bytes are valid input. Views into unused capacity beyond GetSize are not valid input.

Parameter	Description
values	Views to append; each may alias this owner's contents.

Returns

Ok; TooLarge when the total size overflows or exceeds the maximum capacity; OutOfMemory when the domain cannot supply the storage. Failure leaves the owner unchanged.

Related types: StringStatus

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

TryEnsureCapacity

StringStatus ludus::foundation::String::TryEnsureCapacity(usize capacity) noexcept

Ensures room for at least capacity bytes, excluding the terminating zero.

Does nothing when the current capacity suffices. Otherwise moves the contents to grown storage (the larger of the request and twice the current capacity), so later appends up to that capacity do not allocate.

Parameter	Description
capacity	Requested capacity in bytes.

Returns

Ok; TooLarge when capacity exceeds the maximum capacity; OutOfMemory when the domain cannot supply the storage. Failure leaves the owner unchanged.

Related types: StringStatus · usize

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

CloneTo

StringStatus ludus::foundation::String::CloneTo(const AllocationDomain &domain, String &output) const noexcept

Deep-copies these bytes into a new owner that allocates from domain, then moves it into output.

On success output's previous storage is released and output takes domain. output may be this owner.

Parameter	Description
domain	Domain for the copy; borrowed and must outlive output.
output	Receives the copy.

Returns

Ok; OutOfMemory when domain cannot supply the storage. Failure leaves output unchanged.

Related types: AllocationDomain · String · StringStatus

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

Clear

void ludus::foundation::String::Clear() noexcept

Sets the size to zero and keeps the current storage and capacity; never allocates or frees.

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