Skip to main content

AxisLookup

ph_surfaces

Trait AxisLookup 

Source 
pub trait AxisLookup<const N: usize>: Sealed<N> + Copy {
    const KNOT_BYTES: usize;
    const INDEX_BYTES: usize;
    const MAX_SEARCH_COMPARISONS: u32;

    // Required methods
    fn first(&self) -> u16;
    fn last(&self) -> u16;
    fn knot(&self, index: usize) -> u16;

    // Provided method
    fn search(&self, coordinate: u16) -> (usize, u32) { ... }
}
Expand description

One axis of N knots, together with the strategy that locates a coordinate in it.

This trait is sealed: LinearAxis, BinaryAxis, UniformAxis, and BucketedAxis are the only implementations, and each validates its own invariants in a const fn constructor. An invalid axis therefore fails to compile rather than reaching search.

N is a parameter of the trait rather than an associated constant so that an axis and the value grid it addresses cannot drift apart: a BilinearSurface requires X: AxisLookup<NX>, so pairing a 5-knot axis with a grid of 4 columns is a type error at the declaration.

§Invariants

Every implementation guarantees that N >= 2 and that knot(0) < knot(1) < .. < knot(N - 1), all of them representable in u16.

Required Associated Constants§

Source

const KNOT_BYTES: usize

Bytes of stored knots or descriptor this strategy references.

This is the axis’s own static payload. It excludes the value grid, the auxiliary index counted by INDEX_BYTES, the surface handle, alignment, code, and stack. It is exact and target-independent, and it is not a total memory figure.

Source

const INDEX_BYTES: usize

Bytes of auxiliary index this strategy references.

Zero for every strategy except BucketedAxis, which is the only one that buys a smaller search bound with static data.

Source

const MAX_SEARCH_COMPARISONS: u32

The most strategy-specific knot comparisons needed to locate an in-domain coordinate, after the inclusive endpoint checks.

This counts comparisons against stored knots, not machine instructions, and it excludes the two endpoint comparisons performed before the strategy-specific search. The public search wrapper routes through the lookup module that owns those checks; surface evaluation reuses the endpoint classification it already needs for boundary handling. It is a work bound, never a cycle count.

Required Methods§

Source

fn first(&self) -> u16

Returns the first knot: the inclusive lower bound of the axis domain.

Source

fn last(&self) -> u16

Returns the last knot: the inclusive upper bound of the axis domain.

Source

fn knot(&self, index: usize) -> u16

Returns the knot at index.

§Panics

Panics if index >= N. Every index this crate passes comes from a located cell, whose lower knot is at most N - 2 and whose upper knot is therefore at most N - 1.

Provided Methods§

Source

fn search(&self, coordinate: u16) -> (usize, u32)

Returns the greatest index whose knot is at or below coordinate, together with the number of knot comparisons it took.

The returned count covers only the strategy-specific work and is bounded by MAX_SEARCH_COMPARISONS. It is the observable half of that declared bound: because the count is public, a consumer — and this crate’s own black-box conformance suite — can verify the bound instead of taking it on faith. Callers that only want the index discard it, and an optimising build removes the counting.

§Panics

Panics in every build profile unless first() <= coordinate <= last(). This makes the answer set non-empty and the returned index well defined.

§Cost

A direct public call performs one or two endpoint comparisons before the strategy-specific work (two for an in-domain coordinate). The surface evaluator does not duplicate those comparisons: its private locator performs the same endpoint checks for boundary handling, then enters the sealed in-domain search directly.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§