Struct BucketedAxis 

pub struct BucketedAxis<const N: usize, const B: usize> { /* private fields */ }

An axis of N stored knots with a static index of B buckets.

The index turns an irregular axis into a bounded local problem: one division selects a bucket, the bucket names the first knot that can hold the answer, and a short scan finishes the job. It is the strategy to reach for when an axis is long and unevenly spaced and a few index bytes are worth a smaller search bound; UniformAxis is better when the spacing is regular, and BinaryAxis when no extra bytes are wanted.

The index is built at compile time by bucket_index and re-derived by BucketedAxis::new, so a stale or hand-written table fails to compile. Nothing is constructed, cached, or mutated at runtime.

Cost

2*N stored knot bytes plus 2*B index bytes. After the endpoint checks, the strategy reads one bucket and then performs at most max_local_comparisons knot comparisons — a figure exact for these knots, which never grows when B is raised to a multiple of itself.

Examples

use ph_surfaces::{BilinearSurface, BinaryAxis, BucketedAxis, bucket_index, max_local_comparisons};

// Tightly clustered at the bottom, then a long tail.
static X: [u16; 6] = [0, 1, 2, 3, 400, 1_000];
static X_INDEX: [u16; 8] = bucket_index(&X);
static Y: [u16; 2] = [0, 10];
static VALUES: [[i32; 6]; 2] = [[0, 1, 2, 3, 400, 1_000], [10, 11, 12, 13, 410, 1_010]];

static SURFACE: BilinearSurface<6, 2, BucketedAxis<6, 8>, BinaryAxis<2>> =
    BilinearSurface::from_axes(BucketedAxis::new(&X, &X_INDEX), BinaryAxis::new(&Y), &VALUES);

// The same answers as the default binary surface over the same tables.
static DEFAULT: BilinearSurface<6, 2> = BilinearSurface::new(&X, &Y, &VALUES);
assert_eq!(SURFACE.evaluate(700, 5), DEFAULT.evaluate(700, 5));

// Three comparisons at worst, on an axis a plain scan could take five to
// walk: the index paid two bytes a bucket to bound the walk.
assert_eq!(max_local_comparisons(&X, &X_INDEX), 3);

A bucket table that does not match its knots does not compile:

use ph_surfaces::BucketedAxis;

static X: [u16; 6] = [0, 1, 2, 3, 400, 1_000];
static WRONG: [u16; 4] = [0, 0, 0, 0];
static AXIS: BucketedAxis<6, 4> = BucketedAxis::new(&X, &WRONG);

Implementations

impl<const N: usize, const B: usize> BucketedAxis<N, B>

pub const fn new(knots: &'static [u16; N], index: &'static [u16; B]) -> Self

Declares a bucketed axis over static knots and a static bucket index.

Panics

Panics unless the axis declares at least two strictly increasing knots, N <= 65_536 so every knot index is representable in the table, 1 <= B <= 65_536, and every entry of index equals the entry bucket_index derives for the same knots. In a constant or static definition that panic is a compile error, so an axis cannot reach runtime with an index that disagrees with its knots.

Examples found in repository

examples/firmware_cost_budget.rs (line 97)

    static MIXED: Mixed =
        BilinearSurface::from_axes(BucketedAxis::new(&X, &X_INDEX), UniformAxis::new(), &VALUES);

examples/mixed_calibration_map.rs (line 32)

static MIXED: Mixed = BilinearSurface::from_axes(
    BucketedAxis::new(&X, &X_INDEX_8),
    UniformAxis::new(),
    &VALUES,
);

pub const fn knots(&self) -> &'static [u16; N]

Returns the declared knots.

The same array as KnotArray::knots, available in a constant context.

pub const fn index(&self) -> &'static [u16; B]

Returns the declared bucket index.

pub const fn max_local_comparisons(&self) -> u32

Returns the exact worst-case local scan for this axis, in knot comparisons: max_local_comparisons over its knots and index.

Trait Implementations

impl<const N: usize, const B: usize> AxisLookup<N> for BucketedAxis<N, B>

const KNOT_BYTES: usize

Bytes of stored knots or descriptor this strategy references.

const INDEX_BYTES: usize

Bytes of auxiliary index this strategy references.

const MAX_SEARCH_COMPARISONS: u32

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

fn first(&self) -> u16

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

fn last(&self) -> u16

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

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

Returns the knot at index.

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.

impl<const N: usize, const B: usize> Clone for BucketedAxis<N, B>

fn clone(&self) -> BucketedAxis<N, B>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const N: usize, const B: usize> Copy for BucketedAxis<N, B>

impl<const N: usize, const B: usize> Debug for BucketedAxis<N, B>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const N: usize, const B: usize> Eq for BucketedAxis<N, B>

impl<const N: usize, const B: usize> Hash for BucketedAxis<N, B>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<const N: usize, const B: usize> KnotArray<N> for BucketedAxis<N, B>

fn knots(&self) -> &'static [u16; N]

Returns the declared knots, strictly increasing and at least two long.

impl<const N: usize, const B: usize> PartialEq for BucketedAxis<N, B>

fn eq(&self, other: &BucketedAxis<N, B>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<const N: usize, const B: usize> StructuralPartialEq for BucketedAxis<N, B>