Skip to content

Commit 50c500e

Browse files
onethumbonethumb
committed
Improve docs
1 parent de88e02 commit 50c500e

File tree

2 files changed

+229
-4
lines changed

2 files changed

+229
-4
lines changed

‎README.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,111 @@ let checksum = checksum_file(Crc32IsoHdlc, file_on_disk, None);
142142
assert_eq!(checksum.unwrap(), 0xcbf43926);
143143
```
144144

145+
## Custom CRC Parameters
146+
147+
For cases where you need to use CRC variants not included in the predefined algorithms, you can define custom CRC parameters and use the `*_with_params` functions.
148+
149+
### Digest with custom parameters
150+
151+
Creates a `Digest` with custom CRC parameters for stream processing.
152+
153+
```rust
154+
use crc_fast::{Digest, CrcParams};
155+
156+
// Define custom CRC-32 parameters (equivalent to CRC-32/ISO-HDLC)
157+
let custom_params = CrcParams::new(
158+
"CRC-32/CUSTOM",
159+
32,
160+
0x04c11db7,
161+
0xffffffff,
162+
true,
163+
0xffffffff,
164+
0xcbf43926,
165+
);
166+
167+
let mut digest = Digest::new_with_params(custom_params);
168+
digest.update(b"123456789");
169+
let checksum = digest.finalize();
170+
171+
assert_eq!(checksum, 0xcbf43926);
172+
```
173+
174+
### checksum_with_params
175+
176+
Checksums data using custom CRC parameters.
177+
178+
```rust
179+
use crc_fast::{checksum_with_params, CrcParams};
180+
181+
// Define custom CRC-32 parameters (equivalent to CRC-32/ISO-HDLC)
182+
let custom_params = CrcParams::new(
183+
"CRC-32/CUSTOM",
184+
32,
185+
0x04c11db7,
186+
0xffffffff,
187+
true,
188+
0xffffffff,
189+
0xcbf43926,
190+
);
191+
192+
let checksum = checksum_with_params(custom_params, b"123456789");
193+
194+
assert_eq!(checksum, 0xcbf43926);
195+
```
196+
197+
### checksum_combine_with_params
198+
199+
Combines checksums from two different sources using custom CRC parameters.
200+
201+
```rust
202+
use crc_fast::{checksum_with_params, checksum_combine_with_params, CrcParams};
203+
204+
// Define custom CRC-32 parameters (equivalent to CRC-32/ISO-HDLC)
205+
let custom_params = CrcParams::new(
206+
"CRC-32/CUSTOM",
207+
32,
208+
0x04c11db7,
209+
0xffffffff,
210+
true,
211+
0xffffffff,
212+
0xcbf43926,
213+
);
214+
215+
let checksum_1 = checksum_with_params(custom_params, b"1234");
216+
let checksum_2 = checksum_with_params(custom_params, b"56789");
217+
let checksum = checksum_combine_with_params(custom_params, checksum_1, checksum_2, 5);
218+
219+
assert_eq!(checksum, 0xcbf43926);
220+
```
221+
222+
### checksum_file_with_params
223+
224+
Checksums a file using custom CRC parameters, chunking through the file optimally.
225+
226+
```rust
227+
use std::env;
228+
use crc_fast::{checksum_file_with_params, CrcParams};
229+
230+
// for example/test purposes only, use your own file path
231+
let binding = env::current_dir().expect("missing working dir").join("crc-check.txt");
232+
let file_on_disk = binding.to_str().unwrap();
233+
234+
// Define custom CRC-32 parameters (equivalent to CRC-32/ISO-HDLC)
235+
let custom_params = CrcParams::new(
236+
"CRC-32/CUSTOM",
237+
32,
238+
0x04c11db7,
239+
0xffffffff,
240+
true,
241+
0xffffffff,
242+
0xcbf43926,
243+
);
244+
245+
let checksum = checksum_file_with_params(custom_params, file_on_disk, None);
246+
247+
assert_eq!(checksum.unwrap(), 0xcbf43926);
248+
```
249+
145250
## C/C++ compatible shared library
146251

147252
`cargo build` will produce a shared library target (`.so` on Linux, `.dll` on Windows, `.dylib` on macOS, etc) and an

‎src/lib.rs

Lines changed: 124 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,31 @@
104104
//!
105105
//! assert_eq!(checksum.unwrap(), 0xcbf43926);
106106
//! ```
107+
//!
108+
//! ## Custom CRC Parameters
109+
//!
110+
//! For cases where you need to use CRC variants not included in the predefined algorithms,
111+
//! you can define custom CRC parameters using `CrcParams::new()` and use the `*_with_params` functions.
112+
//!
113+
//! ## checksum_with_params
114+
//!```rust
115+
//! use crc_fast::{checksum_with_params, CrcParams};
116+
//!
117+
//! // Define custom CRC-32 parameters (equivalent to CRC-32/ISO-HDLC)
118+
//! let custom_params = CrcParams::new(
119+
//! "CRC-32/CUSTOM",
120+
//! 32,
121+
//! 0x04c11db7,
122+
//! 0xffffffff,
123+
//! true,
124+
//! 0xffffffff,
125+
//! 0xcbf43926,
126+
//! );
127+
//!
128+
//! let checksum = checksum_with_params(custom_params, b"123456789");
129+
//!
130+
//! assert_eq!(checksum, 0xcbf43926);
131+
//! ```
107132
108133
use crate::crc32::consts::{
109134
CRC32_AIXM, CRC32_AUTOSAR, CRC32_BASE91_D, CRC32_BZIP2, CRC32_CD_ROM_EDC, CRC32_CKSUM,
@@ -363,7 +388,30 @@ impl Digest {
363388
}
364389
}
365390

366-
/// Creates a new `Digest` instance with custom parameters.
391+
/// Creates a new `Digest` instance with custom CRC parameters.
392+
///
393+
/// # Examples
394+
///
395+
/// ```rust
396+
/// use crc_fast::{Digest, CrcParams};
397+
///
398+
/// // Define custom CRC-32 parameters (equivalent to CRC-32/ISO-HDLC)
399+
/// let custom_params = CrcParams::new(
400+
/// "CRC-32/CUSTOM",
401+
/// 32,
402+
/// 0x04c11db7,
403+
/// 0xffffffff,
404+
/// true,
405+
/// 0xffffffff,
406+
/// 0xcbf43926,
407+
/// );
408+
///
409+
/// let mut digest = Digest::new_with_params(custom_params);
410+
/// digest.update(b"123456789");
411+
/// let checksum = digest.finalize();
412+
///
413+
/// assert_eq!(checksum, 0xcbf43926);
414+
/// ```
367415
#[inline(always)]
368416
pub fn new_with_params(params: CrcParams) -> Self {
369417
let calculator = Calculator::calculate as CalculatorFn;
@@ -476,7 +524,28 @@ pub fn checksum(algorithm: CrcAlgorithm, buf: &[u8]) -> u64 {
476524
calculator(params.init, buf, params) ^ params.xorout
477525
}
478526

479-
/// Computes the CRC checksum for the given data using the custom specified parameters.
527+
/// Computes the CRC checksum for the given data using custom CRC parameters.
528+
///
529+
/// # Examples
530+
///
531+
/// ```rust
532+
/// use crc_fast::{checksum_with_params, CrcParams};
533+
///
534+
/// // Define custom CRC-32 parameters (equivalent to CRC-32/ISO-HDLC)
535+
/// let custom_params = CrcParams::new(
536+
/// "CRC-32/CUSTOM",
537+
/// 32,
538+
/// 0x04c11db7,
539+
/// 0xffffffff,
540+
/// true,
541+
/// 0xffffffff,
542+
/// 0xcbf43926,
543+
/// );
544+
///
545+
/// let checksum = checksum_with_params(custom_params, b"123456789");
546+
///
547+
/// assert_eq!(checksum, 0xcbf43926);
548+
/// ```
480549
pub fn checksum_with_params(params: CrcParams, buf: &[u8]) -> u64 {
481550
let calculator = Calculator::calculate as CalculatorFn;
482551

@@ -514,11 +583,39 @@ pub fn checksum_file(
514583
checksum_file_with_digest(Digest::new(algorithm), path, chunk_size)
515584
}
516585

517-
/// Computes the CRC checksum for the given file using the custom specified parameters.
586+
/// Computes the CRC checksum for the given file using custom CRC parameters.
587+
///
588+
/// Appears to be much faster (~2X) than using Writer and io::*, at least on Apple M2 Ultra
518589
///
519590
/// # Errors
520591
///
521592
/// This function will return an error if the file cannot be read.
593+
///
594+
/// # Examples
595+
///
596+
/// ```rust
597+
/// use std::env;
598+
/// use crc_fast::{checksum_file_with_params, CrcParams};
599+
///
600+
/// // for example/test purposes only, use your own file path
601+
/// let file_path = env::current_dir().expect("missing working dir").join("crc-check.txt");
602+
/// let file_on_disk = file_path.to_str().unwrap();
603+
///
604+
/// // Define custom CRC-32 parameters (equivalent to CRC-32/ISO-HDLC)
605+
/// let custom_params = CrcParams::new(
606+
/// "CRC-32/CUSTOM",
607+
/// 32,
608+
/// 0x04c11db7,
609+
/// 0xffffffff,
610+
/// true,
611+
/// 0xffffffff,
612+
/// 0xcbf43926,
613+
/// );
614+
///
615+
/// let checksum = checksum_file_with_params(custom_params, file_on_disk, None);
616+
///
617+
/// assert_eq!(checksum.unwrap(), 0xcbf43926);
618+
/// ```
522619
pub fn checksum_file_with_params(
523620
params: CrcParams,
524621
path: &str,
@@ -582,7 +679,30 @@ pub fn checksum_combine(
582679
combine::checksums(checksum1, checksum2, checksum2_len, params)
583680
}
584681

585-
/// Combines two CRC checksums using the custom specified parameters.
682+
/// Combines two CRC checksums using custom CRC parameters.
683+
///
684+
/// # Examples
685+
///
686+
/// ```rust
687+
/// use crc_fast::{checksum_with_params, checksum_combine_with_params, CrcParams};
688+
///
689+
/// // Define custom CRC-32 parameters (equivalent to CRC-32/ISO-HDLC)
690+
/// let custom_params = CrcParams::new(
691+
/// "CRC-32/CUSTOM",
692+
/// 32,
693+
/// 0x04c11db7,
694+
/// 0xffffffff,
695+
/// true,
696+
/// 0xffffffff,
697+
/// 0xcbf43926,
698+
/// );
699+
///
700+
/// let checksum_1 = checksum_with_params(custom_params, b"1234");
701+
/// let checksum_2 = checksum_with_params(custom_params, b"56789");
702+
/// let checksum = checksum_combine_with_params(custom_params, checksum_1, checksum_2, 5);
703+
///
704+
/// assert_eq!(checksum, 0xcbf43926);
705+
/// ```
586706
pub fn checksum_combine_with_params(
587707
params: CrcParams,
588708
checksum1: u64,

0 commit comments

Comments
 (0)