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