# crc32
`crc32` is a small, pure Gleam library for calculating CRC-32/ISO-HDLC
checksums.
It implements the conventional reflected CRC-32 variant commonly used by ZIP,
gzip, PNG, and Ethernet. The library supports both one-shot checksum
calculation and immutable incremental processing of data in chunks.
## Installation
```gleam
gleam add crc32
```
## Quick start
```gleam
import crc32
pub fn main() {
let checksum = crc32.checksum(<<"123456789":utf8>>)
assert checksum == 0xCBF43926
}
```
The returned value is the finalized CRC-32 checksum as a Gleam `Int`.
## Usage
### Calculate a checksum
```gleam
import crc32
pub fn main() {
let checksum = crc32.checksum(<<"hello":utf8>>)
assert checksum == 0x3610A686
}
```
### Incremental checksums
CRC-32 calculations can be built incrementally using an immutable, pipeline-friendly state.
```gleam
import crc32
pub fn main() {
let checksum =
crc32.new()
|> crc32.update(<<"hello ":utf8>>)
|> crc32.update(<<"world":utf8>>)
|> crc32.finalize()
}
```
Processing data incrementally produces the same checksum as processing the complete byte sequence at once:
```gleam
crc32.checksum(<<"hello world":utf8>>)
```
### Verify a checksum
An incremental CRC calculation can be verified directly against an expected checksum.
```gleam
import crc32
pub fn main() {
let valid =
crc32.new()
|> crc32.update(<<"hello ":utf8>>)
|> crc32.update(<<"world":utf8>>)
|> crc32.verify(expected_checksum)
}
```
`verify` returns `True` when the calculated CRC-32 checksum matches the expected value.
## Stability and versioning
This package starts at `0.1.0` and remains in the `0.x` series until its
public API has been exercised by at least one real consumer package.
During `0.x`:
- bug fixes increment the patch version, for example `0.1.0 -> 0.1.1`
- breaking public API changes increment the minor version, for example
`0.1.x -> 0.2.0`
## API
The library intentionally exposes a small API:
```gleam
pub type Crc32
pub fn checksum(data: BitArray) -> Int
pub fn new() -> Crc32
pub fn update(crc: Crc32, data: BitArray) -> Crc32
pub fn finalize(crc: Crc32) -> Int
pub fn verify(crc: Crc32, expected: Int) -> Bool
```
`Crc32` is an opaque value representing an incremental CRC-32 calculation in progress.
The internal accumulator is intentionally hidden so that intermediate CRC state cannot be confused with a finalized checksum.
## CRC-32 variant
This package implements CRC-32/ISO-HDLC, commonly referred to as CRC-32 or IEEE CRC-32.
The standard check value for the ASCII byte sequence `"123456789"` is:
```
0xCBF43926
```
## What CRC-32 is for
CRC-32 is designed to detect accidental changes or corruption in data.
Typical uses include:
- File and archive integrity checks
- Network and storage protocols
- Binary formats
- Structured identifiers and API keys
- Detecting transcription or transport errors
CRC-32 is **not** a cryptographic hash.
It must not be used for password hashing, authentication, digital signatures, or protection against intentional modification.
## Design
crc32 is intentionally small.
The package focuses on:
- CRC-32/ISO-HDLC only
- Pure Gleam
- Immutable incremental state
- Pipeline-friendly APIs
- BitArray input
- Predictable behavior across Gleam targets
- Minimal dependencies
It does not attempt to provide a generic framework for arbitrary CRC models.
## Development
```gleam
gleam test
```
Development validation and certification details are documented in
`CERTIFICATION.md`.
## License
MIT License - Copyright (c) 2026 Antonio Ognio
Made with ❤️ from 🇵🇪. El Perú es clave 🔑.