perf: contiguous slice fast path for binary-search kernels

[samukweku]

Summary

Part 3 (final) of issue #24. The issue's own framing: "Evaluate a slice-based fast path for C-contiguous one-dimensional arrays while retaining the current strided-array behavior as a fallback... but should be adopted only if benchmarks and float semantics support them." This PR is that evaluation plus the resulting rollout, since the benchmark came back clearly positive.

• All ten src/bin_search/*.rs files shared the same manual bisection over an ArrayView1<T> index (right[mid_idx as usize]). ArrayView1::as_slice() returns Some(&[T]) only when the view is contiguous in standard order; each kernel now branches once per call: when contiguous, std::slice::partition_point runs against the same [start, end) sub-range with a predicate matching the fallback's; when not, the original while loop is untouched as the fallback. Every existing post-loop check (sentinel/inverted-range rejection, defensive equality checks) is preserved exactly.
• Public Python export names and signatures are unchanged — pure internal-implementation change.

Performance (decision gate)

Prototyped on binary_search_lt_core first (bench_bin_search_lt, extended with a strided fixture), benchmarked against the pre-change baseline before touching the other nine files:

	old baseline	new contiguous (fast path)	new strided (fallback)
n=100	646.97 ns	473.67 ns (−26.8%)	649.71 ns (parity)
n=100,000	2.3530 ms	1.0374 ms (−55.9%)	2.4289 ms (parity)

Clear win, zero regression for non-contiguous input, so the same two-branch pattern was rolled out to the other nine kernels (bin_search_ge/gt/le, their _first siblings, and _ge_regions/_gt_regions) rather than adopting on bin_search_lt alone.

Correctness: what "fast path matches fallback" actually guarantees (updated after review)

An earlier version of this PR claimed fast-path/fallback parity unconditionally, including for a right containing NaN, and had a test using NaN embedded in right that happened to pass with that specific layout. That claim was wrong, caught in review, and is now corrected:

• The predicate itself. ge's and gt's fast-path predicates were originally the algebraically-equivalent-for-ordered-values rewrite (<=/<) of the fallback's actual condition (!(current > left)/!(current >= left)). Those two forms agree for any totally-ordered comparison but diverge whenever either compared value is NaN. Fixed by writing the fast-path predicate as the literal negation of the fallback's condition instead of the algebraic rewrite, so a NaN query against an otherwise-sorted right now agrees between paths (in-contract input). lt/le never had this bug — their fallback conditions were already stated in the direction the fast path needs.
• The search algorithm itself. Independent of the predicate, slice::partition_point is std's "branchless" binary search: it shrinks the search width by a fixed size / 2 every step regardless of the comparison outcome, unlike the fallback's comparison-driven width shrink. For a genuinely sorted right both converge on the same unique partition point regardless of which width-shrinking strategy got them there. For a right that itself contains NaN (which has no valid position in "sorted ascending" to begin with), the two can probe different elements and land on genuinely different, but never out-of-bounds, answers — confirmed with a standalone repro (right=[-1, NaN, 0, 1, 2, 3, 4], left=0: lt's fast path returns 3, its fallback returns 1) and affects all ten fast paths, not just ge/gt.
• Considered and rejected: replacing partition_point with a manual loop over the &[T] slice, which would guarantee exact parity for any input. Benchmarked it: ~2.4x slower than partition_point at n=100,000 (954µs vs 2.26ms for lt's kernel) — most of the fast path's value comes from the branchless algorithm itself, not just slice bounds-check elision. Rewriting it away would give up most of what this PR is for, to guarantee a case already outside the documented precondition.

The corrected, accurate contract: right must be sorted ascending, which in particular means NaN-free. Within that precondition, fast path and fallback are guaranteed to agree (including for a NaN query against an otherwise-sorted right). Outside it (a right that itself contains NaN), neither path panics, but they are not guaranteed to agree with each other. This is now stated explicitly in the /// doc comment directly above every one of the 10 exported #[pyfunction]s (verified via __doc__/help() on a built wheel, not just the internal _core Rust functions — an earlier revision of this fix only documented the internal functions, invisible to Python callers).

Test plan

• cargo test --no-default-features — 270 passed, 0 failed. Each of the 10 kernels gets:
  • A differential test proving fast path and fallback agree on ordinary contiguous-vs-strided input.
  • A differential test proving they agree when the query is NaN and right stays sorted (the in-contract NaN case).
  • A test using a right that itself contains NaN, asserting neither path panics and both return a valid (in-bounds-or-sentinel) result — explicitly not asserting parity, since that's exactly the guarantee this out-of-contract input doesn't have.
  • The 5 core-extracted kernels (bin_search_lt, and the four _first siblings) compare directly in pure Rust; the 5 wrapper-only kernels (ge/gt/le, the two _regions files) are compared via the actual #[pyfunction] through an embedded Python interpreter, building a non-contiguous PyReadonlyArray1 by slicing a Python-side numpy array with a step of 2.
• cargo clippy --all-targets --all-features -- -D warnings — clean (including neg_cmp_op_on_partial_ord, deliberately suppressed at the 6 ge/gt sites where the negation is the fix, not the anti-pattern the lint normally flags)
• cargo fmt --check — clean
• cargo doc --no-default-features --no-deps — builds without warnings
• Built the wheel via maturin develop --release and verified end-to-end: all 10 dtype-representative Python-facing functions return identical results for contiguous vs. strided input on ordinary data; the NaN-in-right repro reproduces the documented (no-panic, no-parity-guarantee) behavior through Python, not just the Rust core; every one of the 10 exported functions' __doc__/help() states the sorted-ascending/NaN-free precondition

Addresses the last of #24's three opportunities (one-pass *_first output, #46, merged; shared/validated comparison operator, #51, merged; this one). The "only rejects the exact -1 sentinel, not any negative value" bug class found along the way (same as what #52 fixed in comp.rs) was filed and fixed separately in #57/#60, then rebased in here rather than left for a follow-up.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S1gZKDRiZoBLZnXXXjW3gt