diff --git a/README.md b/README.md index bfd1061..c933dbd 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,7 @@ fn main() { } ``` +See the [examples](https://github.com/adumbidiot/lz-str-rs/tree/master/examples) directory for more examples. ## Testing ```bash diff --git a/examples/binary-data.rs b/examples/binary-data.rs new file mode 100644 index 0000000..04e4b72 --- /dev/null +++ b/examples/binary-data.rs @@ -0,0 +1,55 @@ +use std::convert::TryInto; + +// Sometimes, you may need to compress or decompress binary data. +// This shows a way to handle that. +fn main() { + let data = b"The quick brown fox jumps over the lazy dog"; + + // We pad every byte to make it a `u16`. + let wide_data: Vec = data.iter().copied().map(u16::from).collect(); + + let compressed_data = lz_str::compress(wide_data); + + // Let's turn the output into bytes + // so we can show how to decompress from bytes. + // We make the data native endian. + let compressed_bytes: Vec = compressed_data + .iter() + .copied() + .flat_map(u16::to_ne_bytes) + .collect(); + + // We cannot decompress from an arbitrary string of bytes; + // those byte must be encoded wide characters (u16). + + // First, let's ensure those bytes are a multiple of two, + // since two u8s form one u16. + // Make this a check instead of an `assert` in an actual application. + assert!(compressed_bytes.len() % 2 == 0); + + // Now, let's form a `Vec` from the bytes. + // Here, we use u16::from_ne_bytes, + // since we made this byte array with native endian data. + // Make sure to use the correct function for your data. + // As an example, if you get your bytes from a network connection, + // you likely want to use `u16::from_be_bytes`. + let compressed_data: Vec = compressed_bytes + .chunks(2) + .map(|slice| { + // slice is always guaranteed to be 2 long here. + u16::from_ne_bytes(slice.try_into().unwrap()) + }) + .collect(); + + // Finally, call the decompress function. + // Again, make sure to do proper error checking in a real application. + let decompressed_data = + lz_str::decompress(compressed_data).expect("`compressed_bytes` is invalid"); + + // Remap the u16 to u8 via truncation. + // We do this in this example only to prove we get the same bytes back from the beginning. + let decompressed_data: Vec = decompressed_data.iter().copied().map(|v| v as u8).collect(); + + // We get the same bytes from the beginning. + assert!(decompressed_data == data); +}