README.md
1# crc
2
3Rust implementation of CRC.
4
5[](https://github.com/mrhooray/crc-rs/actions/workflows/ci.yaml)
6[](https://crates.io/crates/crc)
7[](https://docs.rs/crc)
8[](https://github.com/mrhooray/crc-rs#license)
9
10### Usage
11
12Add `crc` to `Cargo.toml`
13```toml
14[dependencies]
15crc = "3.2.1"
16```
17
18### Examples
19
20Using a well-known algorithm:
21```rust
22const X25: crc::Crc<u16> = crc::Crc::<u16>::new(&crc::CRC_16_IBM_SDLC);
23assert_eq!(X25.checksum(b"123456789"), 0x906e);
24```
25
26Using a custom algorithm:
27```rust
28const CUSTOM_ALG: crc::Algorithm<u16> = crc::Algorithm {
29 width: 16,
30 poly: 0x8005,
31 init: 0xffff,
32 refin: false,
33 refout: false,
34 xorout: 0x0000,
35 check: 0xaee7,
36 residue: 0x0000
37};
38let crc = crc::Crc::<u16>::new(&CUSTOM_ALG);
39let mut digest = crc.digest();
40digest.update(b"123456789");
41assert_eq!(digest.finalize(), 0xaee7);
42```
43
44### Minimum supported Rust version (MSRV)
45
46This crate's MSRV is 1.65.
47
48At a minimum, the MSRV will be <= the oldest stable release in the last 12 months. MSRV may be bumped in minor version releases.
49
50### Implementations
51
52This crate has several pluggable implementations:
53
541. `NoTable` doesn't use a lookup table, and thus minimizes binary size and memory usage.
552. `Table<1>` uses a lookup table with 256 entries (e.g. for u32 thats 256 * 4 bytes).
563. `Table<16>` uses a lookup table with 16 * 256 entries (e.g. for u32 thats 16 * 256 * 4 bytes).
57
58`Table<1>` is the default implementation, but this can be overridden by specifying `I` in `Crc<W, I>`. E.g.: `Crc<u32, NoTable>`, `Crc<u64, Table<16>>`, ...
59
60NOTE: Lookup tables will increase binary size if they're generated at compile-time. Wrapping `Crc` initialization in a `std::cell::OnceCell` may be preferable if binary size is a concern.
61
62### Benchmark
63
64`cargo bench` with AMD Ryzen 7 3800X ([comparison](http://create.stephan-brumme.com/crc32/)).
65
66#### Throughput (GiB/s)
67
68| Width | NoTable | Bytewise | Slice16 |
69|-------|---------|----------|---------|
70| 8 | 0.113 | 0.585 | 3.11 |
71| 16 | 0.105 | 0.483 | 3.23 |
72| 32 | 0.111 | 0.516 | 3.30 |
73| 64 | 0.139 | 0.517 | 2.92 |
74| 82 | 0.091 | 0.438 | 0.623 |
75
76### License
77
78Licensed under either of
79
80 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
81 * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
82
83at your option.
84
85### Contribution
86
87Unless you explicitly state otherwise, any contribution intentionally submitted
88for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
89additional terms or conditions.
90
){kind=link}
){kind=link}
){kind=link}
){kind=link}