Utilities

Purpose

Time, math, numeric parsing and file helpers supply local value operations. Their namespaces describe responsibility; they do not imply a shared service, singleton manager or engine-wide initialization/shutdown phase.

Interface

Types below are in CE unless another namespace is shown.

Types and operations

API and purpose
Time::DeltaTime and duration helpers Measure local wall-clock intervals and convert duration units. Timing helpers.
Math::BitArray Own packed bits with borrowed proxies/native word spans. Packed bit representation.
CE::Math::overlaps() Test two axis-aligned rectangles from positions, dimensions and optional anchors. Rectangle overlap.
CE::Text::Numbers parsing functions Parse floating/signed/unsigned numeric text with explicit syntax and range failures. Numeric parsing; declarations.
Files::FileIndex Own normalized file-discovery results without automatic refresh. File index.
CE::Memory::Pointers and fit/byte helpers Calculate addresses/alignment, growth and byte formatting without owning storage. Address preconditions; fit arithmetic.

Values and selection rules

Choice	Purpose and details
Duration aliases / casts	Standard duration truncation and representability rules; no scheduling policy. Time units.
Memory::FitPolicy	exact, larger, greedy choose length adjustment independently of managed allocation. Growth rules.
Rendering::Geometry::AnchorType, Rendering::Geometry::Pivot	Choose named CPU quad placement or a normalized pivot; texture dimensions have explicit preconditions. Anchor geometry; coordinate conventions.
Local timer / runtime delta	Measure CPU work with DeltaTime; advance game simulation with the tick’s selected delta. Local timing; simulation time.

Usage

Pick a helper for the local value operation you need. A loading tool can use file discovery and elapsed-time measurement without creating a runtime or a graphics context; a game update still uses the runtime’s selected simulation delta for gameplay progression.

        ---
config:
  theme: base
  themeVariables:
    fontFamily: system-ui, sans-serif
    fontSize: 14px
  flowchart:
    htmlLabels: true
    curve: linear
    nodeSpacing: 22
    rankSpacing: 38
    padding: 12
---
flowchart TB
    accTitle: Utilities · application-local helpers
    accDescr: Arrows point toward the API or type used, not call order or data flow. Methods beneath type names are selected application entry points; Implement hooks marks engine-invoked overrides. Dashed arrows mark optional choices.
    k0(["Application<br/>loading tool"]):::app
    k1["<b>Files::<br/>FileIndex</b><br/><br/>FileIndex(Files::Path)<br/><br/>get_files_of_type(Files::Extension): Files::Path[]<br/><br/>search_directory(Files::Path)"]:::focal
    k2["<b>Time::<br/>DeltaTime</b><br/><br/>operator()()<br/><br/>elapsed(): Time::DeltaTime&lt;ClockType&gt;::Duration"]:::focal
    k3(["Application<br/>bit bookkeeping"]):::app
    k4["<b>Math::<br/>BitArray</b><br/><br/>operator[](index): Math::BitArray&lt;Bits&gt;::Reference<br/><br/>words(): Math::BitArray&lt;Bits&gt;::word_type[]"]:::focal
    k5(["Application<br/>geometry preparation"]):::app
    k6["<b>Rendering::Geometry::<br/>Anchor</b><br/><br/>MakeQuad(<br/>Rendering::Geometry::Pivot,<br/>texture_width,<br/>texture_height,<br/>width,<br/>height,<br/>x0,<br/>y0):<br/>Rendering::Geometry::Quad<br/><br/>MakeQuadStrip(<br/>Rendering::Geometry::Pivot,<br/>texture_width,<br/>texture_height,<br/>width,<br/>height,<br/>x0,<br/>y0):<br/>Rendering::Geometry::QuadTriangleStrip"]:::focal
    k7["Rendering::Geometry::<br/>Pivot"]:::focal
    k8(["Application<br/>storage owner"]):::app
    k9("Memory::adjust_length(length, Memory::FitPolicy, gb, gf)"):::focal
    k10["Memory::<br/>FitPolicy"]:::focal
    k11(["Application<br/>configuration parsing"]):::app
    k12("Text::Numbers::parse_integers&lt;is_unsigned&gt;(str):<br/>Text::Numbers::NumberVariant"):::focal
    k13("Text::Numbers::parse_floats(str)"):::focal
    k0 --> k1
    k0 --> k2
    k3 --> k4
    k8 --> k9
    k9 --> k10
    k5 --> k6
    k6 --> k7
    k11 --> k12
    k11 --> k13
    classDef focal fill:#e7f3ef,stroke:#387d6b,color:#153d33,stroke-width:1.2px
    classDef neighbor fill:#f0f3f8,stroke:#8c9bb1,color:#35445b,stroke-width:1px
    classDef app fill:#fff2df,stroke:#c09452,color:#674515,stroke-dasharray:5 3
    classDef system fill:#eaf0fc,stroke:#617fab,color:#263f69,stroke-width:1.2px
    linkStyle default stroke:#7e8fa7,stroke-width:1.2px

    

Explore this diagram and its other views →

The engine consumer view shows where these helpers participate in loading, allocation and CPU geometry.

Choose the operation

Task	Start with	Boundary to keep explicit
Measure a CPU preparation interval	Time::DeltaTime	operator() returns seconds and starts the next interval; elapsed() only observes. This is independent of tick.delta_seconds.
Index files by extension	Files::FileIndex	Own the index, serialize access and construct a fresh one to rescan visited directories. Results borrow the index’s containers.
Parse a known numeric syntax	Text::Numbers::parse_floats() or parse_integers()	Floating and decimal integer syntax differ. Use an explicit parser when format is known; the compatibility selector chooses floats by ., e or E.
Keep compact flags	Math::BitArray	Valid indices and synchronization are caller responsibilities, including different bits sharing a word. Proxies/spans borrow the array.
Calculate capacity/alignment	Memory::adjust_length(), Memory::FitPolicy and pointer helpers	Results describe arithmetic; they do not allocate storage or establish a live object’s bounds/lifetime.
Build CPU quad geometry	Rendering::Geometry::Pivot and Rendering::Geometry::Anchor operations	Supply valid normalized placement and nonzero texture dimensions. Resource upload/rendering is a later owner-bound operation.

The utility contract guide owns syntax, range, borrowing and failure rules for these choices.

Uses

Helper	Input/dependency	What it retains or returns
Time::DeltaTime<Clock>	Selected clock; steady by default	Retains its last sample and returns local elapsed values; no scheduler or runtime service.
Files::FileIndex	Filesystem root	Owns discovery results; no automatic freshness or worker scheduling.
Numeric parsers and capacity helpers	Borrowed text or supplied numeric values/policy	Return parsed/adjusted values; no service lifetime is created.
Math::BitArray and address/geometry helpers	Owned bit words or caller-provided values/storage	Borrowed proxies/ranges stay within their owner; address helpers never own the pointees.

These helpers use standard clocks, filesystem and value machinery internally. Their engine-facing dependencies are local values and caller-owned storage, rather than a common Utilities manager.

Used by

Consumer	Utility	Relationship
Assets::Loading::Loader	Files::FileIndex	Automatic preparation creates a fresh discovery index before preparing file/manifest metadata. Assets::Loading::FileRegistry retains registered paths; it does not own the index. File discovery.
Memory::Manager	Memory::adjust_length() and pointer/alignment helpers	Calculates growth and valid aligned request ranges before storage transactions. Memory.
Assets::Grids::make_geometry() and Assets::Graphics::Asset	Rendering::Geometry::Anchor / Rendering::Geometry::Pivot	Builds CPU vertices from source rectangles and placement. Asset coordinates.
Text::Legacy::BitmapFont preparation	Rendering::Geometry::Anchor	Builds the fixed bitmap font’s CPU glyph quads before upload. Text.
Application tools/components	Timers, parsers, indices and packed bits	Own local preparation/bookkeeping; choose when blocking discovery runs and how results reach another owner.

Keep timing and work ownership separate

Use Time::DeltaTime to observe how long preparation took. Use tick.delta_seconds to advance runtime simulation; the runtime may select a fixed step, clamp elapsed time or discard accumulated lag according to its timing policy.

Filesystem discovery can block. If the application moves it to Workers, the job owns its inputs/results and transfers a completed result to the appropriate consumer. A helper’s local nature does not make its borrowed results safe to share or extend them past owner destruction.

Contracts

Duration conversions follow standard truncation/representability rules. Pointer helpers do not allocate or prove storage bounds/object lifetime; supply valid alignment and representable addresses. Packed bit access requires valid indices and synchronization, even for different bits sharing a word. Native word layout is not a portable serialized format.

Numeric parsing has distinct floating/integer syntax and failure rules. File index references borrow its container storage and do not refresh automatically. Use each helper’s actual contract rather than assuming a universal checked-value or service-lifecycle guarantee.

Lifecycle

Construct timers, indices and bit arrays as application-owned values. Keep their borrowed references/spans within the owner’s lifetime and invalidation rules. Caller-supplied pointer ranges and pointees remain the caller’s responsibility. There is no runtime shutdown hook for a stateless conversion function.

Execution

These local values generally require caller synchronization. A custom timer clock defines backward-jump behavior; the default steady clock is monotonic. Filesystem discovery may block and should run at a loading boundary or on an appropriate worker, with owned results transferred to consumers.

Integration

A standalone loading tool can measure one CPU preparation interval:

CE::Time::DeltaTime timer;
auto prepared = loader.prepare();
const double seconds = timer();

The returned prepared value owns its CPU input; the loader retains its root configuration and any previously published metadata. The timer owns only its last clock sample. In a game update, use tick.delta_seconds for runtime-selected simulation time instead of substituting this independent wall-clock measurement.

Limits and further reading

Helpers do not provide scheduling, automatic thread safety, portable pointer identity or transactional behavior for arbitrary template types. Read the complete state/time/math/file contracts, file discovery guide and DeltaTime header.