1# rle-decode-fast 2 3**THE** fastest way to implement any kind of decoding for **R**un **L**ength **E**ncoded data in Rust. 4 5Writing a fast decoder that is also safe can be quite challenging, so this crate is here to save you the 6hassle of maintaining and testing your own implementation. 7 8## Usage 9 10Of course, you need to depend on this crate: 11```toml 12rle-decode-fast = "1.0" 13``` 14 15There is only a single function to use, `rle_decode<T>(&mut Vec<T>, lookbehind_size: usize, fill_length: usize)`. 16It takes : 17* a vector to modify, 18* the number of items to copy from said vector (basically `vector[(vector.len() - lookbehind)..])` 19* the number of items to append. 20Afterwards the vector will contain an extra `fill_length` items. 21```rust 22use rle_decode_fast::rle_decode; 23 24let mut decode_buffer = vec![0, 0, 1, 1, 0, 2, 3]; 25let lookbehind_length = 4; 26let output_length = 10; 27rle_decode(&mut decode_buffer, lookbehind_length, output_length); 28assert_eq!(decode_buffer, [0, 0, 1, 1, 0, 2, 3, 1, 0, 2, 3, 1, 0, 2, 3, 1, 0]); 29``` 30 31### Panics 32There are cases where the decode functions panics 33* The lookbehind length is 0 34* The lookbehind length is bigger than the Vec's length 35* The output length + Vec's length would overflow 36 37## Background 38The idea for this crate first originated from [this pre-RFC](https://internals.rust-lang.org/t/pre-rfc-fixed-capacity-view-of-vec/8413). 39It brought to attention a weak-point in the standard library, which lead some crates writing their own unsafe by-pass. 40 41During the exploration happening in the pre-RFC, some experimentation was conducted. For examples see [here](https://github.com/WanzenBug/rust-fixed-capacity-vec) and [here](https://docs.rs/buffer/0.1.8/buffer/). 42 43## Some Stats 44There is a benchmark comparing a naive (repeated push) implementation, a vulnerable implementation that might lead to 45uninitialized memory and this crate. 46 47The results for a very small fill length 48![lookbehind=333](docs/benchmark-big-lb-small-length.PNG) 49and for a bigger fill lengths 50![lookbehind=2](docs/benchmark-big-lb-big-length.PNG) 51 52## License 53 54Licensed under either of 55 56 * Apache License, Version 2.0 57 [LICENSE-APACHE](LICENSE-APACHE) 58 * MIT license 59 [LICENSE-MIT](LICENSE-MIT) 60 61at your option. 62 63## Contribution 64 65Unless you explicitly state otherwise, any contribution intentionally submitted 66for inclusion in the work by you, as defined in the Apache-2.0 license, shall be 67dual licensed as above, without any additional terms or conditions. 68