Struct UniformAxis 

pub struct UniformAxis<const N: usize, const ORIGIN: u16, const STEP: u16>(/* private fields */);

An axis of N evenly spaced knots, described by ORIGIN and STEP rather than stored.

Knot i is ORIGIN + i * STEP, so the whole axis is ORIGIN, STEP, and N — all three in the type. The value is zero-sized: an evenly spaced axis costs no static bytes, adds nothing to the surface handle, and needs no knot array to walk or probe. Because the descriptor is a compile-time constant, the division that locates a cell is a division by a constant in every instantiation.

This is the one strategy that cannot describe an arbitrary axis. If the spacing is irregular, use BinaryAxis, or BucketedAxis when a smaller search bound is worth index bytes.

Cost

No stored bytes, no index, and no strategy-specific knot comparison after the endpoint checks: one subtraction and one division locate the cell regardless of N.

Examples

use ph_surfaces::{BilinearSurface, BinaryAxis, UniformAxis};

// Five knots at 0, 25, 50, 75, 100 — declared, not stored.
static Y: [u16; 2] = [0, 10];
static VALUES: [[i32; 5]; 2] = [[0, 25, 50, 75, 100], [10, 35, 60, 85, 110]];

static SURFACE: BilinearSurface<5, 2, UniformAxis<5, 0, 25>, BinaryAxis<2>> =
    BilinearSurface::from_axes(UniformAxis::new(), BinaryAxis::new(&Y), &VALUES);

assert_eq!(SURFACE.x_knot(3), 75);
assert_eq!(SURFACE.evaluate(60, 0), Ok(60));
assert_eq!(SURFACE.evaluate(100, 10), Ok(110));

The same surface with the knots spelled out and located binarily returns the same values:

use ph_surfaces::{BilinearSurface, BinaryAxis, UniformAxis};

static X: [u16; 5] = [0, 25, 50, 75, 100];
static Y: [u16; 2] = [0, 10];
static VALUES: [[i32; 5]; 2] = [[0, 25, 50, 75, 100], [10, 35, 60, 85, 110]];

static UNIFORM: BilinearSurface<5, 2, UniformAxis<5, 0, 25>, BinaryAxis<2>> =
    BilinearSurface::from_axes(UniformAxis::new(), BinaryAxis::new(&Y), &VALUES);
static STORED: BilinearSurface<5, 2> = BilinearSurface::new(&X, &Y, &VALUES);

for x in [0u16, 1, 37, 50, 99, 100] {
    assert_eq!(UNIFORM.evaluate(x, 5), STORED.evaluate(x, 5));
}

A single-knot axis does not compile:

use ph_surfaces::UniformAxis;

static AXIS: UniformAxis<1, 0, 25> = UniformAxis::new();

Nor does a zero step, which would declare N copies of one knot:

use ph_surfaces::UniformAxis;

static AXIS: UniformAxis<5, 0, 0> = UniformAxis::new();

Nor does a descriptor whose last knot leaves u16:

use ph_surfaces::UniformAxis;

static AXIS: UniformAxis<5, 60_000, 2_000> = UniformAxis::new();

The descriptor cannot bypass UniformAxis::new; its zero-sized field is private:

use ph_surfaces::UniformAxis;

static AXIS: UniformAxis<5, 0, 25> = UniformAxis(());

Implementations

impl<const N: usize, const ORIGIN: u16, const STEP: u16> UniformAxis<N, ORIGIN, STEP>

pub const fn new() -> Self

Declares an evenly spaced axis.

Panics

Panics unless the descriptor names at least two strictly increasing knots that are all representable: N >= 2, STEP >= 1, and N <= 65_536, and ORIGIN + (N - 1) * STEP <= u16::MAX. In a constant or static definition that panic is a compile error, so an unrepresentable axis cannot be declared.

Examples found in repository

examples/uniform_sensor_compensation.rs (line 21)

static SURFACE: Compensation =
    BilinearSurface::from_axes(UniformAxis::new(), UniformAxis::new(), &VALUES);

examples/firmware_cost_budget.rs (line 64)

    static SURFACE: UniformPair =
        BilinearSurface::from_axes(UniformAxis::new(), UniformAxis::new(), &VALUES);

    assert_eq!(SURFACE.evaluate(100, 200), Ok(0));
    assert_eq!(SURFACE.x_knot(16), 1_600);
    assert_eq!(SURFACE.y_knot(8), 1_600);

    assert_eq!(UniformPair::VALUE_BYTES, 612);
    assert_eq!(UniformPair::PAYLOAD_BYTES, 612);
    assert_eq!(AllBinary::PAYLOAD_BYTES, 664);
    assert_eq!(UniformPair::PAYLOAD_BYTES + 52, AllBinary::PAYLOAD_BYTES);
    assert_eq!(<UniformAxis<17, 0, 100>>::KNOT_BYTES, 0);
    assert_eq!(<UniformAxis<17, 0, 100>>::MAX_SEARCH_COMPARISONS, 0);
    assert_eq!(<UniformAxis<9, 0, 200>>::MAX_SEARCH_COMPARISONS, 0);
    assert_eq!(UniformPair::SUCCESS_INTERPOLATIONS, 3);
    assert_eq!(UniformPair::SUCCESS_GRID_READS, 4);
    assert_eq!(
        UniformPair::HANDLE_BYTES,
        core::mem::size_of::<UniformPair>()
    );
}

fn mixed_bucketed_uniform_17x9() {
    static X: [u16; 17] = [
        0, 100, 210, 300, 405, 500, 610, 700, 805, 900, 1_010, 1_100, 1_205, 1_300, 1_410, 1_500,
        1_600,
    ];
    static X_INDEX: [u16; 8] = bucket_index(&X);
    static VALUES: [[i32; 17]; 9] = [[0; 17]; 9];

    type Mixed = BilinearSurface<17, 9, BucketedAxis<17, 8>, UniformAxis<9, 0, 200>>;
    type AllBinary = BilinearSurface<17, 9>;

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

examples/mixed_calibration_map.rs (line 33)

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

pub const fn origin(&self) -> u16

Returns the first knot, ORIGIN.

The same value as AxisLookup::first, available in a constant context.

pub const fn step(&self) -> u16

Returns the spacing between consecutive knots, STEP.

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

Returns the knot at index, computed from the descriptor.

The same value as AxisLookup::knot, available in a constant context.

Panics

Panics if index >= N.

pub const fn last(&self) -> u16

Returns the last knot, ORIGIN + (N - 1) * STEP.

The same value as AxisLookup::last, available in a constant context. inline(always) because the body folds to one constant; an outlined copy would be all call overhead.

Trait Implementations

impl<const N: usize, const ORIGIN: u16, const STEP: u16> AxisLookup<N> for UniformAxis<N, ORIGIN, STEP>

const KNOT_BYTES: usize = 0

Bytes of stored knots or descriptor this strategy references.

const INDEX_BYTES: usize = 0

Bytes of auxiliary index this strategy references.

const MAX_SEARCH_COMPARISONS: u32 = 0

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 ORIGIN: u16, const STEP: u16> Clone for UniformAxis<N, ORIGIN, STEP>

fn clone(&self) -> UniformAxis<N, ORIGIN, STEP>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const N: usize, const ORIGIN: u16, const STEP: u16> Copy for UniformAxis<N, ORIGIN, STEP>

impl<const N: usize, const ORIGIN: u16, const STEP: u16> Debug for UniformAxis<N, ORIGIN, STEP>

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

Formats the value using the given formatter.

impl<const N: usize, const ORIGIN: u16, const STEP: u16> Default for UniformAxis<N, ORIGIN, STEP>

fn default() -> Self

Returns UniformAxis::new, validating the descriptor.

It is written out rather than derived on purpose: a derived Default would hand back an axis whose descriptor had never been checked, and the rest of the crate relies on every axis having been.

impl<const N: usize, const ORIGIN: u16, const STEP: u16> Eq for UniformAxis<N, ORIGIN, STEP>

impl<const N: usize, const ORIGIN: u16, const STEP: u16> Hash for UniformAxis<N, ORIGIN, STEP>

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 ORIGIN: u16, const STEP: u16> PartialEq for UniformAxis<N, ORIGIN, STEP>

fn eq(&self, other: &UniformAxis<N, ORIGIN, STEP>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<const N: usize, const ORIGIN: u16, const STEP: u16> StructuralPartialEq for UniformAxis<N, ORIGIN, STEP>