Skip to content

Commit

Permalink
update readme with a section about the encoder
Browse files Browse the repository at this point in the history
  • Loading branch information
KillingSpark committed Dec 14, 2024
1 parent 8b86e4b commit 12c8cf5
Showing 1 changed file with 22 additions and 4 deletions.
26 changes: 22 additions & 4 deletions Readme.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Ruzstd (a pure rust zstd decoder)
# Ruzstd (a pure rust zstd format implementation)

[![Released API docs](https://docs.rs/ruzstd/badge.svg)](https://docs.rs/ruzstd)
[![CI](https://github.com/killingspark/zstd-rs/workflows/CI/badge.svg)](https://github.com/killingspark/zstd-rs/actions?query=workflow%3ACI)
Expand Down Expand Up @@ -74,9 +74,27 @@ This will tell you where the decoder panics exactly. If you are able to fix the

# How can you use it?

## Compression

The easiest is to use the provided `compress`/`compress_to_vec` functions

```rust
use ruzstd::encoding::{compress, compress_to_vec, frame_compressor::CompressionLevel};
let data: &[u8] = todo!();
// Either
let mut compressed = Vec::new();
compress(data, &mut compressed, CompressionLevel::Fastest);
// or
let compressed = compress_to_vec(data, CompressionLevel::Fastest);
```

Or you can use the `FrameDecoder` manually to compress data. This allows you to process encoded data while it is being encoded instead of collecting into a big vector.

## Decompression

Additionally to the descriptions and the docs you can have a look at the zstd / zstd_streaming binaries. They showcase how this library can be used.

## Easy
### Easy

The easiest is to wrap the io::Read into a StreamingDecoder which itself implements io::Read. It will decode blocks as necessary to fulfill the read requests

Expand All @@ -91,7 +109,7 @@ decoder.read_to_end(&mut result).unwrap();
This might be a problem if you are accepting user provided data. Frames can be REALLY big when decoded. If this is the case you should either check how big the frame
actually is or use the memory efficient approach described below.

## Memory efficient
### Memory efficient

If memory is a concern you can decode frames partially. There are two ways to do this:

Expand All @@ -107,4 +125,4 @@ given block count has been decoded or the decodebuffer has reached a certain siz

# Contributing

Contributions will be published under the same MIT license as this project. Please make an entry in the Changelog.md file when you make a PR.
Contributions will be published under the same MIT license as this project. Please make an entry in the Changelog.md file when you make a PR.

0 comments on commit 12c8cf5

Please sign in to comment.