wasm_bitpack/lib.rs
1//! `wasm-bitpack` is a SIMD-accelerated integer bit-packing and unpacking library with a
2//! hand-written WebAssembly SIMD128 decode fast path.
3//!
4//! Every popular Rust integer-compression crate gets its speed from x86 AVX2/SSE
5//! intrinsics and silently falls back to scalar code when compiled to `wasm32`. This crate
6//! implements the missing `wasm32` + `simd128` decode fast path instead.
7//!
8//! See the [project README](https://github.com/udaybhangare/wasm-bitpack) for the full
9//! pitch, benchmark methodology, and usage examples.
10
11#![deny(clippy::all)]
12#![warn(clippy::pedantic)]
13#![deny(missing_docs)]
14#![deny(unsafe_code)]
15#![deny(unsafe_op_in_unsafe_fn)]
16#![allow(clippy::module_name_repetitions)]
17#![allow(clippy::must_use_candidate)]
18// `test` is exempted so `#[cfg(test)]` modules (which use `std`/`Vec` throughout) keep
19// compiling unmodified under `--no-default-features`; doctests are unaffected either way
20// since they're always compiled as a separate, ordinary std-linked crate.
21#![cfg_attr(not(any(feature = "std", test)), no_std)]
22// `doc_cfg` is nightly-only; docs.rs builds with a pinned nightly and passes `--cfg docsrs`
23// automatically, so this has no effect on a normal stable build.
24#![cfg_attr(docsrs, feature(doc_cfg))]
25
26mod dispatch;
27mod pack;
28mod scalar;
29mod sorted;
30mod testing;
31mod traits;
32mod unpack;
33mod wasm128;
34
35pub use dispatch::best_available;
36pub use pack::pack;
37pub use scalar::Scalar;
38pub use sorted::{
39 compress_sorted, compress_strictly_sorted, decompress_sorted, decompress_strictly_sorted,
40 num_bits_sorted, num_bits_strictly_sorted,
41};
42pub use traits::BitPacker;
43pub use unpack::unpack;
44pub use wasm128::Wasm128;
45
46/// Benchmark input generation, mirroring exactly what the correctness suite proves against —
47/// see `plans/04-testing-strategy.md` §9. **Not part of the locked v0.1 public API**
48/// (`plans/02-api-design-rules.md` §2) and not covered by semver: this exists solely so this
49/// crate's own `benches/` targets (a separate compilation unit that can only see `pub` items)
50/// can reuse the exact generation logic the correctness suite is checked against, instead of
51/// a second, potentially-drifting copy. Gated behind the `bench-support` feature, which is
52/// off by default and is not meant to be enabled outside this crate's own benchmark targets.
53#[cfg(feature = "bench-support")]
54#[doc(hidden)]
55pub mod bench_support {
56 pub use crate::testing::bench_gen::{
57 max_value_for_num_bits, random_values, sorted_ascending_values, BenchPattern,
58 BENCH_BIT_WIDTHS, BENCH_SEED, BENCH_SIZES,
59 };
60}
61
62#[cfg(test)]
63mod scaffold_smoke_test {
64 // Phase -1 validation test: confirms `cargo test --target wasm32-wasip1` genuinely
65 // executes under wasmtime via the `.cargo/config.toml` runner, not a silent no-op.
66 #[test]
67 fn arithmetic_sanity() {
68 assert_eq!(2 + 2, 4);
69 }
70}