ludus::foundation¶

Namespace

Enumerations¶

NumberParseStatus¶

enum class NumberParseStatus : uint8

Result of a bounded, locale-independent decimal conversion.

Related types: uint8

Success¶

Success

The complete input was converted.

InvalidSyntax¶

InvalidSyntax

Input does not match the documented grammar.

OutOfRange¶

OutOfRange

The rounded result overflows or a nonzero input rounds to zero.

TooLong¶

TooLong

Input exceeds the supported 1024-byte bound.

Declared in modules/foundation/base/include/ludus/foundation/base/parse_number.hpp

TargetOs¶

enum class TargetOs : uint8

Related types: uint8

Web¶

Web = LUDUS_OS_WEB

Windows¶

Windows = LUDUS_OS_WINDOWS

MacOS¶

MacOS = LUDUS_OS_MACOS

Linux¶

Linux = LUDUS_OS_LINUX

Android¶

Android = LUDUS_OS_ANDROID

IOS¶

IOS = LUDUS_OS_IOS

Declared in modules/foundation/base/include/ludus/foundation/base/target.hpp

TargetArch¶

enum class TargetArch : uint8

Related types: uint8

Wasm32¶

Wasm32 = LUDUS_CPU_WASM32

Wasm64¶

Wasm64 = LUDUS_CPU_WASM64

X86_64¶

X86_64 = LUDUS_CPU_X86_64

Arm64¶

Arm64 = LUDUS_CPU_ARM64

Declared in modules/foundation/base/include/ludus/foundation/base/target.hpp

TargetCompiler¶

enum class TargetCompiler : uint8

Related types: uint8

Clang¶

Clang = LUDUS_CXX_CLANG

Gcc¶

Gcc = LUDUS_CXX_GCC

Msvc¶

Msvc = LUDUS_CXX_MSVC

Declared in modules/foundation/base/include/ludus/foundation/base/target.hpp

TargetEndian¶

enum class TargetEndian : uint8

Related types: uint8

Little¶

Little = LUDUS_ENDIAN_LITTLE

Big¶

Big = LUDUS_ENDIAN_BIG

Declared in modules/foundation/base/include/ludus/foundation/base/target.hpp

AccountingValidity¶

enum class AccountingValidity : uint8

Whether a domain's counters still describe its requested-byte history exactly.

Both invalid states are sticky: later arithmetic cannot restore accuracy.

Related types: uint8

Valid¶

Valid

Every update stayed in range.

Saturated¶

Saturated

A counter overflowed its width; values are no longer exact.

AccountingError¶

AccountingError

A free exceeded live bytes/blocks or had an invalid layout.

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

AllocationDomainRegistrationStatus¶

enum class AllocationDomainRegistrationStatus : uint8

Outcome of TryRegisterAllocationDomain.

Related types: uint8

Ok¶

Ok

Registered, or the identical definition was already registered.

InvalidName¶

InvalidName

Empty, too long, or not made of ASCII letters, digits, '.', '_' and '-'.

NameCollision¶

NameCollision

Another domain already uses the name.

DomainAlreadyRegistered¶

DomainAlreadyRegistered

The domain is already registered under another name.

RegistryFull¶

RegistryFull

MAX_ALLOCATION_DOMAINS definitions already exist.

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

OwnershipStatus¶

enum class OwnershipStatus : uint8

Result of a fallible ownership factory.

Every value other than Ok means the output owner was left unchanged and no ownership was acquired.

Related types: uint8

Ok¶

Ok

The output owner now holds the newly constructed object.

InvalidState¶

InvalidState

The output owner was not empty, or the layout is not an object layout.

TooLarge¶

TooLarge

The object layout cannot be represented as an allocation request.

OutOfMemory¶

OutOfMemory

The allocation domain could not provide the storage.

Declared in modules/foundation/memory/include/ludus/foundation/memory/owned_object.hpp

StringStatus¶

enum class StringStatus : uint8

Explicit result of FoundationStrings operations.

Each operation documents which values it returns and what it leaves unchanged on failure. Values are not stable serialized codes.

Related types: uint8

Ok¶

Ok

The operation succeeded and wrote its documented outputs.

OutOfMemory¶

OutOfMemory

The allocation domain could not supply the requested storage.

TooLarge¶

TooLarge

A length or size computation exceeds a representable or configured maximum, such as a table's spelling-length limit.

CapacityExceeded¶

CapacityExceeded

A fixed capacity or configured budget (entries, allocated bytes or bounded storage) has no room for the request.

InvalidArgument¶

InvalidArgument

The arguments or configuration violate a documented requirement, such as a nonempty output owner.

InvalidUtf8¶

InvalidUtf8

The bytes are not well-formed UTF-8.

EmbeddedZero¶

EmbeddedZero

The bytes contain a zero byte where the operation forbids one.

InvalidHandle¶

InvalidHandle

The owner is empty, or the ID is invalid or outside its table's entries.

WrongTable¶

WrongTable

The ID belongs to a different table than the one asked to resolve it.

NotFound¶

NotFound

A lookup did not find the requested spelling. Nothing was inserted.

TokenExhausted¶

TokenExhausted

The process has issued every table token; no further table can be created.

ProbeExhausted¶

ProbeExhausted

A table lookup visited every lookup slot without reaching the requested spelling or an empty slot. The load-factor invariant makes this unreachable for intact metadata, so it reports corrupted table state; the lookup leaves the table and the caller's output unchanged.

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

StringHashPolicy¶

enum class StringHashPolicy : uint8

Selects the lookup hash a StringTable applies to counted spelling bytes.

Either policy compares full bytes on lookup; the policy affects only collision resistance.

Related types: uint8

Trusted¶

Trusted

Unkeyed XXH3 (TableHash64) for engine-controlled input. StringTableConfig::Key is ignored.

Untrusted¶

Untrusted

SipHash-2-4 keyed by StringTableConfig::Key (KeyedTableHash64) for hostile input. Requires StringTableConfig::HasSecretKey; it resists hash flooding but does not bound admitted volume.

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

Aliases¶

UniquePtr¶

template <typename ElementType, typename DeleterType = core::DefaultDeleter<ElementType>>
using ludus::foundation::UniquePtr = core::UniquePtr<ElementType, DeleterType>

Public spelling of core::UniquePtr, including its deleter parameter.

Related types: core::UniquePtr

Declared in modules/foundation/base/include/ludus/foundation/base/pointer.hpp

Array¶

template <typename ElementType>
using ludus::foundation::Array = core::Array<ElementType>

Engine-namespace alias for core::Array.

Related types: core::Array

Declared in modules/foundation/containers/include/ludus/foundation/containers/array.hpp

FixedArray¶

template <typename ElementType, core::usize Count>
using ludus::foundation::FixedArray = core::FixedArray<ElementType, Count>

Engine-namespace alias for core::FixedArray.

Related types: core::FixedArray

Declared in modules/foundation/containers/include/ludus/foundation/containers/fixed_array.hpp

RingBuffer¶

template <typename ElementType, core::usize Count>
using ludus::foundation::RingBuffer = core::RingBuffer<ElementType, Count>

Engine-namespace alias for core::RingBuffer.

Related types: core::RingBuffer

Declared in modules/foundation/containers/include/ludus/foundation/containers/ring_buffer.hpp

SortedMap¶

template <typename KeyType, typename ValueType, typename Compare = KeyLess>
using ludus::foundation::SortedMap = core::SortedMap<KeyType, ValueType, Compare>

Engine-namespace alias for core::SortedMap.

Related types: core::SortedMap

Declared in modules/foundation/containers/include/ludus/foundation/containers/sorted_map.hpp

StaticArray¶

template <typename ElementType, core::usize Count>
using ludus::foundation::StaticArray = core::StaticArray<ElementType, Count>

Engine-namespace alias for core::StaticArray.

Related types: core::StaticArray

Declared in modules/foundation/containers/include/ludus/foundation/containers/static_array.hpp

StaticBitSet¶

template <core::usize BitCount>
using ludus::foundation::StaticBitSet = core::StaticBitSet<BitCount>

Engine-namespace alias for core::StaticBitSet.

Related types: core::StaticBitSet

Declared in modules/foundation/containers/include/ludus/foundation/containers/static_bit_set.hpp

AllocationDomainId¶

using ludus::foundation::AllocationDomainId = uint32

Numeric identity of a registered domain, stable for the process lifetime. Zero is never assigned.

Related types: uint32

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

nullptr_t¶

using ludus::foundation::core::nullptr_t = decltype(nullptr)

nullptr_t: the Ludus-scoped spelling of the null pointer literal's type.

Declared in modules/foundation/base/include/ludus/foundation/base/core.h

float32¶

using ludus::foundation::core::float32 = float

IEEE binary32 scalar; does not select rounding, trap or denormal policy.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

float64¶

using ludus::foundation::core::float64 = double

IEEE binary64 scalar; does not select rounding, trap or denormal policy.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

int16¶

using ludus::foundation::core::int16 = std::int16_t

Exact 16-bit signed integer for explicit-width values.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

int32¶

using ludus::foundation::core::int32 = std::int32_t

Exact 32-bit signed integer for explicit-width values.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

int64¶

using ludus::foundation::core::int64 = std::int64_t

Exact 64-bit signed integer for explicit-width values.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

int8¶

using ludus::foundation::core::int8 = std::int8_t

Exact 8-bit signed integer for explicit-width values.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

isize¶

using ludus::foundation::core::isize = std::ptrdiff_t

Native signed pointer-difference type; width follows the target ABI.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

uint16¶

using ludus::foundation::core::uint16 = std::uint16_t

Exact 16-bit unsigned integer for explicit-width values.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

uint32¶

using ludus::foundation::core::uint32 = std::uint32_t

Exact 32-bit unsigned integer for explicit-width values.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

uint64¶

using ludus::foundation::core::uint64 = std::uint64_t

Exact 64-bit unsigned integer for explicit-width values.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

uint8¶

using ludus::foundation::core::uint8 = std::uint8_t

Exact 8-bit unsigned integer for explicit-width values.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

usize¶

using ludus::foundation::core::usize = std::size_t

Native unsigned size/index type; matches sizeof and container sizes, not a wire format.

Declared in modules/foundation/base/include/ludus/foundation/base/types.h

Constants and variables¶

kTarget¶

constexpr TargetInfo ludus::foundation::kTarget {
    .Os = static_cast<TargetOs>(LUDUS_TARGET_OS),
    .Arch = static_cast<TargetArch>(LUDUS_TARGET_ARCH),
    .Compiler = static_cast<TargetCompiler>(LUDUS_TARGET_COMPILER),
    .Endian = static_cast<TargetEndian>(LUDUS_TARGET_ENDIAN),
    .PointerBits = LUDUS_POINTER_BITS,
}

Related types: TargetInfo

Declared in modules/foundation/base/include/ludus/foundation/base/target.hpp

SYSTEM_ALLOCATION_DOMAIN_ID¶

constexpr AllocationDomainId ludus::foundation::SYSTEM_ALLOCATION_DOMAIN_ID = 1

Identity of the built-in System domain returned by GetSystemAllocationDomain.

Related types: AllocationDomainId

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

CONTAINERS_ALLOCATION_DOMAIN_ID¶

constexpr AllocationDomainId ludus::foundation::CONTAINERS_ALLOCATION_DOMAIN_ID = 2

Identity of the built-in Containers domain returned by GetContainerAllocationDomain.

Related types: AllocationDomainId

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

MAX_ALLOCATION_DOMAINS¶

constexpr usize ludus::foundation::MAX_ALLOCATION_DOMAINS = 32

Maximum registered domains, built-in domains included.

Related types: usize

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

MAX_ALLOCATION_DOMAIN_NAME_BYTES¶

constexpr usize ludus::foundation::MAX_ALLOCATION_DOMAIN_NAME_BYTES = 47

Maximum bytes of a registered domain name, excluding its terminator.

Related types: usize

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

IsTriviallyRelocatable¶

template <typename ElementType>
constexpr bool ludus::foundation::core::IsTriviallyRelocatable

True when containers may relocate ElementType by copying bytes and skipping destruction of the source.

Defaults to trivially copyable; extend only with LUDUS_TRIVIALLY_RELOCATABLE.

Declared in modules/foundation/containers/include/ludus/foundation/containers/relocation.hpp

Functions¶

ParseFloat32¶

NumberParseStatus ludus::foundation::ParseFloat32(const char *text, usize size, float32 &output) noexcept

Parse ASCII JSON number syntax into binary32, rounding to nearest, ties to even.

Parameter	Description
`text`	Input bytes; may be null only when size is zero. No whitespace, leading plus, leading zeroes, hexadecimal, NaN or infinity is accepted.
`size`	Number of bytes, at most 1024; the complete input must match.
`output`	Updated only on success. Negative zero and subnormals are preserved.

Returns

Explicit syntax, length or range status; no allocations or exceptions.

Note

Available on native and browser targets; independent of locale and the floating-point environment. Uses bounded integer arithmetic, with no shared state.

Related types: NumberParseStatus · float32 · usize

Declared in modules/foundation/base/include/ludus/foundation/base/parse_number.hpp

ParseUint64¶

NumberParseStatus ludus::foundation::ParseUint64(const char *text, usize size, uint64 &output) noexcept

Parse a complete ASCII unsigned decimal integer into uint64.

Parameter	Description
`text`	Input bytes; may be null only when size is zero. Digits only; leading zeroes are accepted, signs and whitespace are rejected.
`size`	Number of bytes, at most 1024.
`output`	Updated only on success.

Returns

Explicit syntax, length or overflow status. No allocation or exceptions.

Related types: NumberParseStatus · uint64 · usize

Declared in modules/foundation/base/include/ludus/foundation/base/parse_number.hpp

TargetOsName¶

constexpr const char * ludus::foundation::TargetOsName(TargetOs value) noexcept

Related types: TargetOs

Declared in modules/foundation/base/include/ludus/foundation/base/target.hpp

TargetArchName¶

constexpr const char * ludus::foundation::TargetArchName(TargetArch value) noexcept

Related types: TargetArch

Declared in modules/foundation/base/include/ludus/foundation/base/target.hpp

version¶

Version ludus::foundation::version() noexcept

Related types: Version

Declared in modules/foundation/base/include/ludus/foundation/base/version.hpp

version_string¶

std::string_view ludus::foundation::version_string() noexcept

Declared in modules/foundation/base/include/ludus/foundation/base/version.hpp

git_revision¶

std::string_view ludus::foundation::git_revision() noexcept

Declared in modules/foundation/base/include/ludus/foundation/base/version.hpp

compiler_identity¶

std::string_view ludus::foundation::compiler_identity() noexcept

Declared in modules/foundation/base/include/ludus/foundation/base/version.hpp

Sort¶

template <typename T, typename Compare>
void ludus::foundation::Sort(T *values, usize count, const Compare &less) noexcept

Sorts initialized contiguous elements in place using O(count log count) comparisons and O(1) extra storage. Equivalent elements may be reordered. No allocation occurs; existing element addresses remain valid.

Parameter	Description
`values`	Array of at least count initialized elements; may be null when count is zero.
`count`	Number of elements to sort.
`less`	Nonthrowing strict weak ordering over elements.

Precondition

Element move construction/assignment and the comparator cannot throw. Values is nonnull for nonzero count.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/sort.hpp

StableSort¶

template <typename T, typename Compare>
bool ludus::foundation::StableSort(T *values, T *scratch, usize count, const Compare &less) noexcept

Stable O(count log count) merge sort with no allocation.

Parameter	Description
`values`	Mutable array of count initialized elements.
`scratch`	Separate array of at least count initialized elements; contents may be overwritten.
`count`	Element count; zero permits null arrays.
`less`	Nonthrowing strict weak order; equivalent values retain their input order.

Returns

False for a null nonempty array or identical arrays, preserving values; otherwise true.

Precondition

Arrays do not partially overlap and have sufficient capacity. Copy assignment is nonthrowing.

Related types: usize

Declared in modules/foundation/containers/include/ludus/foundation/containers/stable_sort.hpp

SymbolFingerprint64¶

constexpr uint64 ludus::foundation::SymbolFingerprint64(std::string_view bytes) noexcept

Related types: uint64

Declared in modules/foundation/hash/include/ludus/foundation/hash/hash.hpp

TableHash64¶

uint64 ludus::foundation::TableHash64(std::span< const uint8 > bytes) noexcept

Non-cryptographic XXH3, pinned 0.8.3; no public vendor headers or hash cache.

Related types: uint64 · uint8

Declared in modules/foundation/hash/include/ludus/foundation/hash/hash.hpp

StableFingerprint128¶

Fingerprint128 ludus::foundation::StableFingerprint128(std::span< const uint8 > bytes) noexcept

XXH3-128 seed zero/default secret.

Persistent format v1: Low then High, each little endian, over caller-defined canonical bytes. Not an identity.

Related types: uint8 · Fingerprint128

Declared in modules/foundation/hash/include/ludus/foundation/hash/hash.hpp

KeyedTableHash64¶

uint64 ludus::foundation::KeyedTableHash64(std::span< const uint8 > bytes, SipHashKey key) noexcept

SipHash-2-4.

Caller supplies a platform-generated secret key for hostile input; this module performs no entropy acquisition and provides no fixed fallback.

Related types: uint64 · uint8 · SipHashKey

Declared in modules/foundation/hash/include/ludus/foundation/hash/hash.hpp

GetSystemAllocationDomain¶

const AllocationDomain & ludus::foundation::GetSystemAllocationDomain() noexcept

Returns the process-lifetime system allocation domain.

Registered as System (SYSTEM_ALLOCATION_DOMAIN_ID); the general domain for engine-owned storage without a more specific domain.

Returns

Stable system backend, available before dynamic initialization and through static and thread-local teardown.

Related types: AllocationDomain

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_domain.hpp

GetContainerAllocationDomain¶

const AllocationDomain & ludus::foundation::GetContainerAllocationDomain() noexcept

Returns the process-lifetime domain that backs Array storage.

Registered as Containers (CONTAINERS_ALLOCATION_DOMAIN_ID). It uses the same system backend as GetSystemAllocationDomain, so its blocks are interchangeable at the backend level, but it is a separate accounting origin: free its blocks only through this domain.

Returns

Stable domain, available before dynamic initialization and through static and thread-local teardown.

Related types: AllocationDomain

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_domain.hpp

GetAllocationStatistics¶

AllocationStatistics ludus::foundation::GetAllocationStatistics(const AllocationDomain &domain) noexcept

Samples a domain's counters.

Parameter	Description
`domain`	Any domain, registered or not.

Returns

Relaxed per-field loads. While other threads allocate or free in domain, fields may come from different moments; at a quiescent boundary LiveRequestedBytes == AllocatedBytes - FreedBytes and LiveBlocks == AllocationCount - FreeCount while Validity is Valid.

Note

Thread safe and allocation free.

Related types: AllocationDomain · AllocationStatistics

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

TryRegisterAllocationDomain¶

AllocationDomainRegistrationStatus ludus::foundation::TryRegisterAllocationDomain(const AllocationDomain &domain, const char *name, AllocationDomainId &outId) noexcept

Registers a process-lifetime domain under a stable name for enumeration and export.

Registration is a cold, serialized operation; do not call it from an allocation callback. The name is copied into bounded registry storage. Registering the identical domain and name again returns the existing ID. Registration never affects allocation: unregistered domains still count, and a failed registration only reduces attribution.

Parameter	Description
`domain`	Domain with static storage duration. Registered domains are never removed, so a shorter-lived domain must not be registered.
`name`	Null-terminated name of 1 to MAX_ALLOCATION_DOMAIN_NAME_BYTES ASCII letters, digits, '.', '_' or '-'.
`outId`	Receives the domain's ID on `Ok`; unchanged otherwise.

Returns

Registration outcome.

Note

Thread safe. Allocation free.

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

GetRegisteredAllocationDomainCount¶

usize ludus::foundation::GetRegisteredAllocationDomainCount() noexcept

Returns how many domains are registered, built-in domains included.

Returns

Published entry count; entries below it never change.

Note

Thread safe; a concurrent registration may publish more entries afterwards.

Related types: usize

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

TryGetRegisteredAllocationDomain¶

bool ludus::foundation::TryGetRegisteredAllocationDomain(usize index, RegisteredAllocationDomain &outEntry) noexcept

Reads one published registry entry.

Parameter	Description
`index`	Entry index, below `GetRegisteredAllocationDomainCount()`.
`outEntry`	Receives the entry on success; unchanged otherwise.

Returns

False when index is not published.

Note

Thread safe and allocation free.

Related types: usize · RegisteredAllocationDomain

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

GetAllocationCoverageExclusionCount¶

usize ludus::foundation::GetAllocationCoverageExclusionCount() noexcept

Returns how many coverage exclusions are listed.

Returns

Number of entries in the static exclusion manifest.

Related types: usize

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

GetAllocationCoverageExclusion¶

const AllocationCoverageExclusion & ludus::foundation::GetAllocationCoverageExclusion(usize index) noexcept

Reads one entry of the static coverage exclusion manifest.

Domain totals cover only allocations made through registered domains. This manifest names the known paths outside them, so a report never presents covered totals as whole-process memory. It is not a measured denominator.

Parameter	Description
`index`	Entry index, below `GetAllocationCoverageExclusionCount()`.

Returns

Process-lifetime entry.

Precondition

index < GetAllocationCoverageExclusionCount(); violations terminate through LUDUS_REQUIRE.

Related types: usize · AllocationCoverageExclusion

Declared in modules/foundation/memory/include/ludus/foundation/memory/allocation_statistics.hpp

TryCreateOwned¶

template <typename ElementType, typename... ArgumentTypes>
OwnershipStatus ludus::foundation::TryCreateOwned(const AllocationDomain &domain, UniquePtr< ElementType, DomainDeleter< ElementType > > &inoutOwner, ArgumentTypes &&... arguments) noexcept
requires (std::is_object_v<ElementType> && std::is_array_v<ElementType> == false && std::is_same_v<ElementType, std::remove_cv_t<ElementType>> && std::is_nothrow_constructible_v<ElementType, ArgumentTypes&&...> && std::is_nothrow_destructible_v<ElementType>)

Allocates one exact object through domain and writes its owner.

The sequence is: reject a nonempty output, validate the layout with checked usize arithmetic, request exactly sizeof(ElementType) bytes at alignof(ElementType) (including over-aligned types), and only then forward arguments to the constructor. Allocation failure therefore never consumes move arguments. The resulting owner frees through domain with that same layout.

Construction must not fail. A type with fallible setup uses a nothrow inert constructor and an explicit status operation; its factory creates a private candidate here, runs setup, lets the candidate roll back on failure, and moves only a complete object into its own output.

Template parameter	Description
`ElementType`	Exact, non-array, non-cv object type, nothrow constructible from `ArgumentTypes` and nothrow destructible. Convert the owner to a `const` view afterwards through the explicit adapter if needed.

Parameter	Description
`domain`	Allocation domain for the object. Borrowed; it must outlive the returned owner.
`inoutOwner`	Output owner. Must be empty on entry. Written only on `Ok`; every other status leaves it unchanged.
`arguments`	Constructor arguments, forwarded only after allocation succeeds.

Returns

Ok with inoutOwner holding the object; InvalidState if inoutOwner was not empty; TooLarge if the layout cannot be requested; OutOfMemory if domain returned no storage.

Note

Thread affinity: thread safe as far as domain's callbacks are; the output owner itself is not synchronized.

Related types: AllocationDomain · DomainDeleter · UniquePtr · OwnershipStatus

Declared in modules/foundation/memory/include/ludus/foundation/memory/owned_object.hpp

TryMakeShared¶

template <typename ElementType, typename... ArgumentTypes>
OwnershipStatus ludus::foundation::TryMakeShared(const AllocationDomain &domain, SharedPtr< ElementType > &inoutOwner, ArgumentTypes &&... arguments) noexcept
requires (std::is_object_v<ElementType> && std::is_array_v<ElementType> == false && std::is_same_v<ElementType, std::remove_cv_t<ElementType>> && std::is_nothrow_constructible_v<ElementType, ArgumentTypes&&...> && std::is_nothrow_destructible_v<ElementType>)

Allocates one object with its shared controller through domain and writes its owner.

The sequence is: reject a nonempty output, validate the combined controller/object layout with checked usize arithmetic, request one allocation aligned for both the controller and ElementType (including over-aligned types), and only then forward arguments to the constructor. Allocation failure therefore never consumes move arguments. The object is destroyed by its exact type when the last strong owner releases it, and the block is freed through domain with its original layout when the last weak hold releases it.

Construction must not fail. A type with fallible setup uses a nothrow inert constructor and an explicit status operation, completes setup through a private candidate, and publishes only a complete object.

Template parameter	Description
`ElementType`	Exact, non-array, non-cv object type, nothrow constructible from `ArgumentTypes` and nothrow destructible. Convert the owner to a `const` or base view afterwards if needed.

Parameter	Description
`domain`	Allocation domain for the combined block. Borrowed; it, its callback context and this code must outlive every strong owner and weak observer of the result.
`inoutOwner`	Output owner. Must be empty on entry. Written only on `Ok`; every other status leaves it unchanged.
`arguments`	Constructor arguments, forwarded only after allocation succeeds.

Returns

Ok with inoutOwner holding the object; InvalidState if inoutOwner was not empty; TooLarge if the combined layout cannot be requested; OutOfMemory if domain returned no storage.

Note

Thread affinity: thread safe as far as domain's callbacks are; the output owner itself is not synchronized.

Related types: AllocationDomain · SharedPtr · OwnershipStatus

Declared in modules/foundation/memory/include/ludus/foundation/memory/shared_ptr.hpp

CreateShared¶

StringStatus ludus::foundation::CreateShared(std::string_view value, const AllocationDomain &domain, SharedString &output)

Copies value once into a new shared block allocated from domain and stores it in output.

An empty value makes output empty without allocating or recording domain. Otherwise the header and bytes are one allocation. On success output releases its previous block. Output unchanged on failure, even when source borrows the old output.

Parameter	Description
`value`	Bytes to copy; it may borrow `output`'s current bytes.
`domain`	Domain for the block; borrowed and must outlive every handle that shares it.
`output`	Receives the new handle.

Returns

Ok; TooLarge when the block size overflows or exceeds half the address space; OutOfMemory when domain cannot supply the block.

Related types: AllocationDomain · SharedString · StringStatus

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

CopyToString¶

StringStatus ludus::foundation::CopyToString(const SharedString &value, String &output) noexcept

Deep-copies the shared bytes into output, as String::TryAssign.

output keeps its own allocation domain, so the copy is independent of the shared block's domain.

Returns

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

Related types: SharedString · String · StringStatus

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

CreateTable¶

StringStatus ludus::foundation::CreateTable(const StringTableConfig &config, const AllocationDomain &domain, StringTable &outTable)

Empty outTable required; failure preserves it.

The runtime token issuer must be linked once into the host; plugins use the host's table API. It is a process-wide atomic counter, so concurrent calls are safe; each success takes a fresh nonzero token that is never reissued. The new table contains only the empty spelling at index zero. config is copied; domain is borrowed and must outlive the table and its frozen owner.

Parameter	Description
`config`	Budgets, hash policy and spelling rules.
`domain`	Allocation source for the table state, entries, lookup metadata and spelling bytes.
`outTable`	Receives the new table on success; must be empty.

Returns

Ok; InvalidArgument when outTable is not empty, MaxEntries is zero or StringIndex::INVALID_VALUE, MaxAllocatedBytes cannot hold the table state, MaxSpellingBytes reaches half the usize range, HashPolicy is not an enumerator, or Untrusted lacks HasSecretKey; OutOfMemory when the domain fails; CapacityExceeded when the byte budget cannot hold the empty entry; or TokenExhausted after the process has issued every token. Failure releases everything allocated.

Related types: AllocationDomain · StringTable · StringStatus · StringTableConfig

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

ValidateUtf8¶

StringStatus ludus::foundation::ValidateUtf8(std::string_view bytes, Utf8View &output, usize &errorOffset)

Checks that bytes is well-formed UTF-8 (Unicode Standard, section 3.9, table 3-7).

Rejects overlong encodings, surrogates, values above U+10FFFF and truncated sequences. Does not allocate. Failure preserves output and reports the first invalid sequence's byte offset.

U+0000 is valid Unicode. Success sets errorOffset to zero.

Parameter	Description
`bytes`	Bytes to validate; borrowed by `output` on success.
`output`	Receives the proof on success.
`errorOffset`	On failure, byte offset at which the first ill-formed sequence starts.

Returns

Ok or InvalidUtf8.

Related types: Utf8View · StringStatus · usize

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

ValidateCString¶

StringStatus ludus::foundation::ValidateCString(std::string_view bytes) noexcept

Checks that bytes contains no zero byte, so it can cross a C-string boundary intact.

The check is about bytes only: it does not validate UTF-8 and does not require or look for a terminator beyond bytes. Pass a separately terminated copy (such as String::GetData) to the C API.

Returns

Ok; EmbeddedZero when any byte in bytes is zero.

Related types: StringStatus

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

TryReadBigEndian¶

template <UnsignedInteger ValueType>
constexpr bool ludus::foundation::core::TryReadBigEndian(std::span< const uint8 > bytes, ValueType &out) noexcept

Read the first sizeof(ValueType) bytes as a big-endian unsigned integer. Unaligned input is supported; false preserves out when input is too short.

Related types: uint8

Declared in modules/foundation/base/include/ludus/foundation/base/byte_order.hpp

TryReadLittleEndian¶

template <UnsignedInteger ValueType>
constexpr bool ludus::foundation::core::TryReadLittleEndian(std::span< const uint8 > bytes, ValueType &out) noexcept

Read the first sizeof(ValueType) bytes as a little-endian unsigned integer. Unaligned input is supported; false preserves out when input is too short.

Related types: uint8

Declared in modules/foundation/base/include/ludus/foundation/base/byte_order.hpp

TryWriteBigEndian¶

template <UnsignedInteger ValueType>
constexpr bool ludus::foundation::core::TryWriteBigEndian(ValueType value, std::span< uint8 > bytes) noexcept

Write a big-endian unsigned integer into the first sizeof(ValueType) bytes. Unaligned output is supported; trailing bytes stay untouched. Short buffers return false without modifying any bytes.

Related types: uint8

Declared in modules/foundation/base/include/ludus/foundation/base/byte_order.hpp

TryWriteLittleEndian¶

template <UnsignedInteger ValueType>
constexpr bool ludus::foundation::core::TryWriteLittleEndian(ValueType value, std::span< uint8 > bytes) noexcept

Write a little-endian unsigned integer into the first sizeof(ValueType) bytes. Unaligned output is supported; trailing bytes stay untouched. Short buffers return false without modifying any bytes.

Related types: uint8

Declared in modules/foundation/base/include/ludus/foundation/base/byte_order.hpp

TryAdd¶

template <Integer ValueType>
constexpr bool ludus::foundation::core::TryAdd(ValueType left, ValueType right, ValueType &outValue) noexcept

Add without wrapping or saturation; false preserves outValue, including aliased operands.

Declared in modules/foundation/base/include/ludus/foundation/base/checked_integer.hpp

TryIntegerCast¶

template <Integer DestinationType, Integer SourceType>
constexpr bool ludus::foundation::core::TryIntegerCast(SourceType value, DestinationType &outValue) noexcept

Convert an integer only when its value fits the destination range.

Returns

True on success; false preserves outValue. Output may alias the input. Bool, characters, enums, floats and qualified outputs are excluded; aliases cannot distinguish int32 from native int.

Declared in modules/foundation/base/include/ludus/foundation/base/checked_integer.hpp

TryMultiply¶

template <Integer ValueType>
constexpr bool ludus::foundation::core::TryMultiply(ValueType left, ValueType right, ValueType &outValue) noexcept

Multiply without wrapping or saturation; false preserves outValue, including aliased operands.

Declared in modules/foundation/base/include/ludus/foundation/base/checked_integer.hpp

TrySubtract¶

template <Integer ValueType>
constexpr bool ludus::foundation::core::TrySubtract(ValueType left, ValueType right, ValueType &outValue) noexcept

Subtract without wrapping or saturation; false preserves outValue, including aliased operands.

Declared in modules/foundation/base/include/ludus/foundation/base/checked_integer.hpp

Forward¶

template <typename ValueType>
constexpr ValueType && ludus::foundation::core::Forward(std::remove_reference_t< ValueType > &value) noexcept

Forward: perfect-forward a value while preserving its value category.

The two overloads mirror std::forward's contract (the rvalue overload must not be asked to forward as an lvalue).

Declared in modules/foundation/base/include/ludus/foundation/base/core.h

Move¶

template <typename ValueType>
constexpr std::remove_reference_t< ValueType > && ludus::foundation::core::Move(ValueType &&value) noexcept

Move: unconditional cast to an rvalue reference.

The Ludus-named, verb-first spelling of std::move; call sites read as engine vocabulary and never import the std name. Free and constexpr.

Declared in modules/foundation/base/include/ludus/foundation/base/core.h

ludus::foundation¶

Related declarations¶

Enumerations¶

NumberParseStatus¶

Success¶

InvalidSyntax¶

OutOfRange¶

TooLong¶

TargetOs¶

Web¶

Windows¶

MacOS¶

Linux¶

Android¶

IOS¶

TargetArch¶

Wasm32¶

Wasm64¶

X86_64¶

Arm64¶

TargetCompiler¶

Clang¶

Gcc¶

Msvc¶

TargetEndian¶

Little¶

Big¶

AccountingValidity¶

Valid¶

Saturated¶

AccountingError¶

AllocationDomainRegistrationStatus¶

Ok¶

InvalidName¶

NameCollision¶

DomainAlreadyRegistered¶

RegistryFull¶

OwnershipStatus¶

Ok¶

InvalidState¶

TooLarge¶

OutOfMemory¶

StringStatus¶

Ok¶

OutOfMemory¶

TooLarge¶

CapacityExceeded¶

InvalidArgument¶

InvalidUtf8¶

EmbeddedZero¶

InvalidHandle¶

WrongTable¶

NotFound¶

TokenExhausted¶

ProbeExhausted¶

StringHashPolicy¶

Trusted¶

Untrusted¶

Aliases¶

UniquePtr¶

Array¶

FixedArray¶

RingBuffer¶

SortedMap¶

StaticArray¶

StaticBitSet¶

AllocationDomainId¶

nullptr_t¶

float32¶

float64¶

int16¶

int32¶

int64¶

int8¶

isize¶

uint16¶

uint32¶

uint64¶

uint8¶

usize¶