Crate brotlic

Brotlic

Brotlic (or BrotliC) is a thin wrapper around brotli. It provides Rust bindings to all compression and decompression APIs. On the fly compression and decompression is supported for both BufRead and Write via [CompressorReader<R>, CompressorWriter<W>, DecompressorReader<R> and DecompressorWriter<W>. For low-level instances, see BrotliEncoder and BrotliDecoder. These can be configured via BrotliEncoderOptions and BrotliDecoderOptions respectively.

High level abstractions

When dealing with BufRead:

• DecompressorReader<R> - Reads a brotli compressed input stream and decompresses it.
• CompressorReader<R> - Reads a stream and compresses it while reading.

When dealing with Write:

• CompressorWriter<W> - Writes brotli compressed data to the underlying writer.
• DecompressorWriter<W> - Writes brotli decompressed data to the underlying writer.

To simplify this decision, the following table outlines all the differences:

	Input	Output	Wraps
CompressorReader<R>	Uncompressed	Compressed	BufRead
DecompressorReader<R>	Compressed	Uncompressed	BufRead
CompressorWriter<W>	Uncompressed	Compressed	Write
DecompressorWriter<W>	Compressed	Uncompressed	Write

To compress a file with brotli:

use std::fs::File;
use std::io::{self, Write};

use brotlic::CompressorWriter;

let mut input = File::open("test.txt")?; // uncompressed text file
let mut output = File::create("test.brotli")?; // compressed text output file
let mut output_compressed = CompressorWriter::new(output);

output_compressed.write_all(b"test")?;

To decompress that same file:

use std::fs::File;
use std::io::{self, BufReader, Read};

use brotlic::DecompressorReader;

let mut input = BufReader::new(File::open("test.brotli")?); // uncompressed text file
let mut input_decompressed = DecompressorReader::new(input); // requires BufRead

let mut text = String::new();
input_decompressed.read_to_string(&mut text)?;

assert_eq!(text, "test");

To compress and decompress in memory:

use std::io::{self, Read, Write};

use brotlic::{CompressorWriter, DecompressorReader};

let input = vec![0; 1024];

// create a wrapper around Write that supports on the fly brotli compression.
let mut compressor = CompressorWriter::new(Vec::new()); // Vec implements Write
compressor.write_all(input.as_slice());
let compressed_input = compressor.into_inner()?; // read to vec

// create a wrapper around BufRead that supports on the fly brotli decompression.
let mut decompressor = DecompressorReader::new(compressed_input.as_slice()); // slice is BufRead
let mut decompressed_input = Vec::new();

decompressor.read_to_end(&mut decompressed_input)?;

assert_eq!(input, decompressed_input);

Customizing compression quality

Sometimes it can be desirable to trade run-time costs for an even better compression ratio:

use brotlic::{BlockSize, BrotliEncoderOptions, CompressorWriter, Quality, WindowSize};

let encoder = BrotliEncoderOptions::new()
    .quality(Quality::best())
    .window_size(WindowSize::best())
    .block_size(BlockSize::best())
    .build()?;

let compressed_writer = CompressorWriter::with_encoder(encoder, Vec::new());

It is recommended to not use the encoder directly but instead pass it onto the higher level abstractions like CompressorWriter<W> or DecompressorReader<R>.

Re-exports

pub use decode::BrotliDecoder;

pub use decode::BrotliDecoderOptions;

pub use decode::DecompressorReader;

pub use decode::DecompressorWriter;

pub use encode::BrotliEncoder;

pub use encode::BrotliEncoderOptions;

pub use encode::CompressorReader;

pub use encode::CompressorWriter;

Modules

decode

Module that contains the brotli decoder instances

encode

Module that contains the brotli encoder instances

Structs

BlockSize

The recommended input block size (in bits) to use for compression.

CompressError

An error returned by compress.

DecompressError

An error returned by decompress.

IntoInnerError

An error returned by into_inner.

LargeWindowSize

The large sliding window size (in bits) to use for compression.

Quality

Quality level of the brotli compression

WindowSize

The sliding window size (in bits) to use for compression.

Enums

CompressionMode

Allows to tune a brotli compressor for a specific type of input.

SetParameterError

An error returned by BrotliEncoderOptions::build and BrotliDecoderOptions::build

Functions

compress

Read all bytes from input and compress them into output, returning how many bytes were written.

compress_bound

Returns an upper bound for compression.

compress_estimate_max_mem_usage

Returns peak memory usage for a given quality and window size

decompress

Read all bytes from input and decompress them into output, returning how many bytes were written.