alice_zip/lib.rs
1//! ALICE-Zip — Compression primitives + procedural signal generators
2//!
3//! LZ77 sliding window / dictionary coding / Shannon entropy / byte-pair
4//! encoding, plus the generator laws (polynomial / Fourier / Perlin) that let
5//! downstream crates store *how to regenerate* a signal instead of its samples
6//! ("send the law, not the data").
7//!
8//! The crate is `no_std + alloc` by default-features-off; the `std` feature
9//! (on by default) adds the zlib wrappers and `std::error::Error`.
10//!
11//! # Quick start
12//!
13//! ```
14//! use alice_zip::prelude::*;
15//!
16//! // Compression primitives (no_std)
17//! let tokens = lz77_encode(b"abcabcabcabc", 256, 32);
18//! assert_eq!(lz77_decode(&tokens)?, b"abcabcabcabc");
19//! assert_eq!(shannon_entropy(&(0..=255u8).collect::<Vec<_>>()), 8.0);
20//!
21//! // Generator laws: fit a series, keep the coefficients, regenerate
22//! let series: Vec<f32> = (0..64).map(|i| 3.0 + 2.0 * i as f32).collect();
23//! let (coeffs, degree, err) = fit_polynomial(&series, 4, 1e-6).unwrap();
24//! assert_eq!((degree, generate_polynomial(64, &coeffs) == series), (1, true));
25//!
26//! let (bins, dc) = analyze_signal(&generate_sine_wave(32, 1.0, 2.0, 0.0, 0.5), 4, 0.99);
27//! let regenerated = generate_from_coefficients(32, &bins, dc);
28//! # assert_eq!(regenerated.len(), 32);
29//! # Ok::<(), alice_zip::ZipError>(())
30//! ```
31//!
32//! # Module 構成
33//!
34//! | Module | 内容 | feature |
35//! |--------|------|---------|
36//! | [`lz77`] | LZ77 sliding-window encode / decode + [`lz77::LzToken`] | — |
37//! | [`dictionary`] | phrase → index 辞書 [`dictionary::Dictionary`] (FIFO eviction) | — |
38//! | [`entropy`] | Shannon entropy + 理論最小サイズ | — |
39//! | [`bpe`] | Byte-pair encoding (最頻ペア検出 + 置換) | — |
40//! | [`generators`] | polynomial / Fourier / Perlin generator laws | `fft` / `parallel` で加速 path 追加 |
41//! | [`law`] | fitted law + residual + valid range + provenance + oracle cases, verdict on new evidence | — |
42//! | [`quantize`] | 8 / 16-bit min-max quantisation of `f32` samples | — |
43//! | [`compression`] | zlib wrappers ([`flate2`]); LZMA + `.alice` residual containers | `std`; `lzma` |
44//! | [`error`] | 共通 [`error::ZipError`] | — |
45//! | [`prelude`] | 主要 API 一括 re-export | — |
46//!
47//! # no_std
48//!
49//! `--no-default-features` で `core + alloc` のみに依存する float の超越関数は
50//! [`libm`] に委譲するため、`std` build と最終 ulp が異なることがある (法則は同一)
51//! 64-bit atomics 等の前提は無く、`thumbv7em-none-eabihf` で CI が rlib build を検証する
52//!
53//! # backward compatibility
54//!
55//! v0.1.0 まで crate ルート直下に定義していた項目は module 移動後も
56//! ルートから `pub use` で公開している
57
58#![cfg_attr(not(feature = "std"), no_std)]
59#![forbid(unsafe_code)]
60
61extern crate alloc;
62
63pub mod bpe;
64#[cfg(feature = "std")]
65pub mod compression;
66pub mod container;
67pub mod dictionary;
68pub mod entropy;
69pub mod error;
70pub mod generators;
71pub mod law;
72pub mod lz77;
73pub(crate) mod math;
74pub mod prelude;
75pub mod quantize;
76
77#[cfg(test)]
78mod integration_tests;
79
80// Backward-compatible re-exports (= v0.1.0 まで crate root で提供していた API)
81pub use crate::bpe::{bpe_replace, find_most_frequent_pair};
82pub use crate::dictionary::Dictionary;
83pub use crate::entropy::{shannon_entropy, theoretical_min_size};
84pub use crate::error::ZipError;
85pub use crate::lz77::{lz77_decode, lz77_encode, LzToken};