ludus::foundation::unicode

Ludus Wiki · API overview · Browse API

Namespace

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

Related declarations

• ludus::foundation::unicode::UnicodeAllocationStatistics

Enumerations

UnicodeStatus

enum class UnicodeStatus : uint8

Outcome of the Unicode host lifecycle operations.

Related types: uint8

Ok

Ok

The operation completed.

AlreadyInitialized

AlreadyInitialized

InitializeUnicodeHost was called while the host was running; nothing changed.

NotInitialized

NotInitialized

The host is not running; nothing changed.

DataMismatch

DataMismatch

The runtime ICU, CLDR or Unicode version differs from the pinned build; ICU was cleaned up.

BackendFailure

BackendFailure

ICU rejected its memory hooks, embedded data or warm-up; ICU was cleaned up.

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

Functions

InitializeUnicodeHost

UnicodeStatus ludus::foundation::unicode::InitializeUnicodeHost(const AllocationDomain &domain) noexcept

Starts ICU for this process: memory hooks, embedded data and singleton warm-up.

In order: installs ICU memory functions backed by domain before any other ICU call, registers the immutable embedded data package (ICU never opens files), warms the static locale cache, UnifiedCache and number-skeleton tables, then compares the runtime ICU/CLDR/Unicode versions with the pinned build. ICU4C 78.3 is unsafe under allocation failure (L0 findings), so from the hook installation onward any allocation failure terminates through FoundationBase's emergency path (LUDUS_FATAL) instead of reporting.

Parameter	Description
domain	Backing storage for every ICU allocation. Borrowed; it must outlive ShutdownUnicodeHost and be thread safe.

Returns

Ok; AlreadyInitialized; DataMismatch or BackendFailure after which ICU has been cleaned up and initialization may be retried.

Precondition

Called on the host thread before any ICU user exists, never from a catalog, editor project or live-reloaded module.

Related types: AllocationDomain · UnicodeStatus

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

ShutdownUnicodeHost

UnicodeStatus ludus::foundation::unicode::ShutdownUnicodeHost() noexcept

Releases every ICU allocation with u_cleanup at host teardown.

Also clears ICU's memory hooks and data registration; the host may be initialized again afterwards.

Returns

Ok, or NotInitialized when the host is not running.

Precondition

Every ICU user (for example each Localization formatter context) is destroyed. A live user terminates through LUDUS_FATAL, because u_cleanup would invalidate its objects.

Related types: UnicodeStatus

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

IsUnicodeHostInitialized

bool ludus::foundation::unicode::IsUnicodeHostInitialized() noexcept

Reports whether InitializeUnicodeHost succeeded and ShutdownUnicodeHost has not run since.

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

GetLinguisticDataLabel

std::string_view ludus::foundation::unicode::GetLinguisticDataLabel() noexcept

Linguistic data identity reported by the running ICU.

Spelled like a cooked catalog's label, for example icu4c-78.3/cldr-48/unicode-17.0. Static storage; empty when the host is not running.

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

GetUnicodeAllocationStatistics

UnicodeAllocationStatistics ludus::foundation::unicode::GetUnicodeAllocationStatistics() noexcept

Snapshot of ICU allocation diagnostics; zeros before the first initialization.

Thread safe; counters are read independently, so a snapshot taken while other threads format may be momentarily inconsistent between fields.

Related types: UnicodeAllocationStatistics

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