pith-digest 0.1.0

pith foundation: digest (zero-dep Rust)
Documentation
  • Coverage
  • 100%
    80 out of 80 items documented17 out of 33 items with examples
  • Size
  • Source code size: 441.9 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 1.2 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 2s Average build duration of successful builds.
  • all releases: 2s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • crates.io
  • Dependencies
    • —
  • Versions
  • Owners
  • n24q02m

The pith suite contract

pith-digest is part of the pith suite (pith-hash). Every suite repository follows the same rules; CI enforces them mechanically:

  • Naming: a library is always pith-<domain> (pith-image, pith-audio, pith-zip, ...). The curator/repository of repositories is the bare pith-hash. Never invent a second naming scheme inside the suite.
  • Version pinning: cross-library dependencies pin ~0.1 (e.g. pith-image = { version = "~0.1", path = "../pith-image" }). The whole suite moves together inside 0.1.x; breaking changes require a suite-wide version bump, never a silent minor drift.
  • Zero third-party dependencies: every crate depends only on other pith-* crates plus std. scripts/check-zero-deps.py (run in CI) fails the build on any other crate, for normal, build and dev dependencies alike.
  • No unsafe: every crate root carries #![forbid(unsafe_code)].
  • Hex-exact vectors: reference.json at the repo root is the cross-language source of truth. The gen-reference binary regenerates it; CI verifies the committed copy is current (gen-reference verify), and CD ships the regenerated file with every SDK artifact. Python, Node and Go SDKs MUST test against the same bytes.

Repository layout

crates/            one published crate per suite lib (pith-<domain>)
tools/gen-reference  the vector generator binary (bin name: gen-reference)
sdk/python         ctypes wheel; build backend reads PITH_CDYLIB_DIR
sdk/node           koffi-based package; prebuilds/<os-arch>/ carry the cdylib
sdk/go             cgo binding; go.mod carries the module's cgo flags
fuzz/corpus        fuzz inputs, replayed by tests/fuzz_corpus.rs (parser crates)
reference.json     hex-exact cross-SDK test vectors

Install

Rust (the core library):

cargo add pith-digest

Python / Node / Go SDKs are published from the same cdylib on every release; see the release assets or the package registries for the matching version.

Quick start

Rust:

use pith_digest::{Digest, crc32, sha256};

// SHA-256 (FIPS 180-2): fixed-width `Digest<32>`, hex output without
// allocation — written into a caller-owned buffer.
let digest = sha256(b"pith").unwrap();
let mut hex = [0u8; Digest::<32>::HEX_LEN];
digest.to_hex_into(&mut hex).unwrap();
assert_eq!(&hex[..], b"158b993c2b8d4c22e5640dc7b2910dd9b4a70cee21eebd82b2eeecc06f7266e6");
assert_eq!(digest.to_string(), "158b993c2b8d4c22e5640dc7b2910dd9b4a70cee21eebd82b2eeecc06f7266e6");

// Checksums: CRC-32 (PNG/zlib), Adler-32 (RFC 1950), FNV-1a 64.
assert_eq!(crc32(b"123456789"), 0xCBF4_3926);
assert_eq!(pith_digest::adler32(b"Wikipedia"), 0x11E6_0398);
assert_eq!(pith_digest::fnv1a64(b"foobar"), 0x8594_4171_f739_67e8);

// Bit-level fields, MSB-first (the ISO media convention), never panicking.
let mut reader = pith_digest::BitReader::new(&[0b1010_0110]);
assert_eq!(reader.bits(3).unwrap(), 0b101);
assert_eq!(reader.bits(5).unwrap(), 0b0_0110);

The crate is core-only (#![no_std]): no allocator, no filesystem, no environment — every result depends on its arguments alone. The committed reference.json carries the hex-exact test vectors; regenerate with cargo run --bin gen-reference -- gen and verify with cargo run --bin gen-reference -- verify.

Python / Node / Go SDKs are published from the same cdylib on every release; see the release assets or the package registries for the matching version.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT © pith-hash