liblzma

https://docs.rs/liblzma/0.4.6
Admin
liblzma is a Rust binding to liblzma that provides LZMA and XZ encoding/decoding streams for...
Tokens:67,148
Snippets:545
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example: Configure DELTA filter with properties

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Shows how to add a DELTA filter to a chain using a pre-defined properties slice.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let mut filters = Filters::new();
filters.delta_properties(&[0x00]).unwrap();
```

--------------------------------

### Example: Configure x86 and LZMA2 filters

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Illustrates setting up a filter chain with an x86 filter for binary optimization, followed by an LZMA2 filter with custom options.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let dict_size = 0x40000;
let mut opts = LzmaOptions::new_preset(6).unwrap();
opts.dict_size(dict_size);
let mut filters = Filters::new();
filters.x86();
filters.lzma2(&opts);
```

--------------------------------

### Example: Configure ARM filter with properties

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Demonstrates adding an ARM filter to a filter chain using a provided properties byte slice.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let mut filters = Filters::new();
filters.arm_properties(&[0x00, 0x00, 0x00, 0x00]).unwrap();
```

--------------------------------

### Example: Configure PowerPC filter with properties

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Illustrates adding a PowerPC filter to a filter chain using a provided properties byte slice.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let mut filters = Filters::new();
filters.powerpc_properties(&[0x00, 0x00, 0x00, 0x00]).unwrap();
```

--------------------------------

### Example: Configure IA-64 and LZMA2 filters

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Demonstrates building a filter chain with an IA-64 filter for binary compression, followed by an LZMA2 filter with specified options.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let dict_size = 0x40000;
let mut opts = LzmaOptions::new_preset(6).unwrap();
opts.dict_size(dict_size);
let mut filters = Filters::new();
filters.ia64();
filters.lzma2(&opts);
```

--------------------------------

### Example: Configure IA-64 filter with properties

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Shows how to add an IA-64 filter to a filter chain using a specific properties byte slice.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let mut filters = Filters::new();
filters.ia64_properties(&[0x00, 0x00, 0x00, 0x00]).unwrap();
```

--------------------------------

### Example: Configure x86 filter with properties

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Demonstrates adding an x86 filter to a filter chain using a specific properties byte slice.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let mut filters = Filters::new();
filters.x86_properties(&[0x00, 0x00, 0x00, 0x00]).unwrap();
```

--------------------------------

### Example: Configure PowerPC and LZMA2 filters

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Shows how to create a filter chain including a PowerPC filter for binary compression, combined with an LZMA2 filter configured with specific options.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let dict_size = 0x40000;
let mut opts = LzmaOptions::new_preset(6).unwrap();
opts.dict_size(dict_size);
let mut filters = Filters::new();
filters.powerpc();
filters.lzma2(&opts);
```

--------------------------------

### liblzma Crate Overview

Source: https://docs.rs/liblzma/0.4.6/liblzma/index.html

Provides an overview of the liblzma crate, its purpose, and basic usage examples.

```APIDOC
## Crate liblzma

### Summary

LZMA/XZ encoding and decoding streams.

This library is a binding to liblzma currently to provide LZMA and xz encoding/decoding streams. I/O streams are provided in the `read`, `write`, and `bufread` modules (same types, different bounds). Raw in-memory compression/decompression is provided via the `stream` module and contains many of the raw APIs in liblzma.

### Examples

```rust
use liblzma::read::{XzDecoder, XzEncoder};
use std::io::prelude::*;

// Round trip some bytes from a byte source, into a compressor, into a
// decompressor, and finally into a vector.
let data = "Hello, World!".as_bytes();
let compressor = XzEncoder::new(data, 9);
let mut decompressor = XzDecoder::new(compressor);

let mut contents = String::new();
decompressor.read_to_string(&mut contents).unwrap();
assert_eq!(contents, "Hello, World!");
```
```

--------------------------------

### Example: Configure ARM and LZMA2 filters

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Illustrates creating a filter chain with an ARM filter for binary compression, combined with an LZMA2 filter configured with custom options.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let dict_size = 0x40000;
let mut opts = LzmaOptions::new_preset(6).unwrap();
opts.dict_size(dict_size);
let mut filters = Filters::new();
filters.arm();
filters.lzma2(&opts);
```

--------------------------------

### Example: Configure DELTA and LZMA2 filters

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Demonstrates creating a filter chain with a DELTA filter followed by an LZMA2 filter, configuring LZMA2 options like dictionary size.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let dict_size = 0x40000;
let mut opts = LzmaOptions::new_preset(6).unwrap();
opts.dict_size(dict_size);
let mut filters = Filters::new();
filters.delta();
filters.lzma2(&opts);
```

--------------------------------

### Configure liblzma features in Cargo.toml

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/lib.rs.html

Examples of enabling optional features like static linking, multithreading, or async I/O support.

```toml
liblzma = { version = "0.4", features = ["static"] }
```

```toml
liblzma = { version = "0.4", features = ["parallel"] }
```

```toml
async-compression = { version = "0.4", features = ["lzma"] }
```

--------------------------------

### Create New Filter Chain

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/stream.rs.html

Initializes a new filter chain with no filters. This is the starting point for building a sequence of compression filters.

```rust
pub fn new() -> Filters {
        Filters {
            inner: vec![liblzma_sys::lzma_filter {
                id: liblzma_sys::LZMA_VLI_UNKNOWN,
                options: std::ptr::null_mut(),
            }],
            lzma_opts: LinkedList::new(),
        }
    }
```

--------------------------------

### Create a new filter chain

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Initializes a new filter chain with no filters. Use this as a starting point for building custom filter configurations.

```rust
pub fn new() -> Filters
```

--------------------------------

### GET /memlimit

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Stream.html

Retrieves the current memory usage limit configured for the stream.

```APIDOC
## GET /memlimit

### Description
Returns the current memory usage limit as a 64-bit unsigned integer. This is only supported if the underlying stream supports memory limiting.

### Method
GET

### Response
#### Success Response (200)
- **limit** (u64) - The current memory limit in bytes.
```

--------------------------------

### Get Multithreaded Block Size

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Retrieves the recommended block size for multithreaded encoding.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let dict_size = 0x40000;
let mut opts = LzmaOptions::new_preset(6).unwrap();
opts.dict_size(dict_size);
let mut filters = Filters::new();
filters.lzma2(&opts);
assert_eq!(filters.mt_block_size(), 1 << 20);
```

--------------------------------

### Get a reference to the underlying stream

Source: https://docs.rs/liblzma/0.4.6/liblzma/bufread/struct.XzEncoder.html

Acquires an immutable reference to the reader that the XzEncoder is operating on.

```rust
pub fn get_ref(&self) -> &R
```

--------------------------------

### Get Total Output Bytes Produced

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/stream.rs.html

Returns the total number of bytes that have been produced by this stream.

```rust
pub fn total_out(&self) -> u64 {
        self.raw.total_out
    }
```

--------------------------------

### Type ID Implementation

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.AutoFinishXzEncoder.html

Implements the `Any` trait, providing a `type_id` method to get the `TypeId` of the instance.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Get Total Input Bytes Consumed

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/stream.rs.html

Returns the total number of input bytes that have been consumed by this stream.

```rust
pub fn total_in(&self) -> u64 {
        self.raw.total_in
    }
```

--------------------------------

### Get reference to underlying stream

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/bufread.rs.html

Acquires an immutable reference to the underlying `BufRead` stream that the `XzEncoder` is operating on.

```rust
pub fn get_ref(&self) -> &R {
    &self.obj
}
```

--------------------------------

### Get Reference to Underlying Writer in XzDecoder

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write.rs.html

Acquires an immutable reference to the underlying writer object used by the `XzDecoder`.

```rust
pub fn get_ref(&self) -> &W {
    self.obj.as_ref().unwrap()
}
```

--------------------------------

### Get total bytes consumed by compressor

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/bufread.rs.html

Returns the total number of uncompressed bytes read from the underlying stream and processed by the encoder.

```rust
pub fn total_in(&self) -> u64 {
    self.data.total_in()
}
```

--------------------------------

### XzEncoder Initialization

Source: https://docs.rs/liblzma/0.4.6/liblzma/read/struct.XzEncoder.html

Methods for creating new XzEncoder instances for compression.

```APIDOC
## XzEncoder::new

### Description
Create a new compression stream which will compress at the given level to read compressed output from the given output stream.

### Parameters
- **r** (R: Read) - The underlying stream to read from.
- **level** (u32) - Compression level (typically 0-9, 6 is default). Use bitwise-OR with `crate::stream::PRESET_EXTREME` for extreme presets.

## XzEncoder::new_parallel

### Description
Create a new parallel compression stream which will compress at the given level.

### Parameters
- **r** (R: Read) - The underlying stream to read from.
- **level** (u32) - Compression level.

## XzEncoder::new_stream

### Description
Creates a new encoder with a custom `Stream` configuration.

### Parameters
- **r** (R: Read) - The underlying stream to read from.
- **stream** (Stream) - A pre-configured stream for multithreaded encoding or custom tuning.
```

--------------------------------

### XzDecoder Initialization

Source: https://docs.rs/liblzma/0.4.6/liblzma/bufread/struct.XzDecoder.html

Methods to create and configure a new XzDecoder instance.

```APIDOC
## XzDecoder::new(r: R)

### Description
Creates a new decoder which will decompress data read from the given stream.

### Parameters
#### Request Body
- **r** (BufRead) - Required - The input stream to decompress.

## XzDecoder::new_parallel(r: R)

### Description
Creates a new parallel decoder which will decompress data read from the given stream.

## XzDecoder::new_multi_decoder(r: R)

### Description
Creates a new decoder which will decompress data read from the given input, consuming all concatenated xz streams.

## XzDecoder::new_stream(r: R, stream: Stream)

### Description
Creates a new decoder with a custom Stream configuration.
```

--------------------------------

### Get Reference to Underlying Stream

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/read.rs.html

Provides immutable access to the underlying reader `R`. Useful for inspecting the stream without consuming it.

```rust
#[inline]
    pub fn get_ref(&self) -> &R {
        self.inner.get_ref().get_ref()
    }
```

--------------------------------

### XzDecoder Initialization Methods

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/read.rs.html

Methods for creating new XzDecoder instances, including parallel, multi-decoder, and custom stream configurations.

```rust
#[cfg(feature = "parallel")]
#[inline]
pub fn new_parallel(r: R) -> XzDecoder<R> {
    XzDecoder {
        inner: bufread::XzDecoder::new_parallel(BufReader::new(r)),
    }
}
```

```rust
#[inline]
pub fn new_multi_decoder(r: R) -> XzDecoder<R> {
    XzDecoder {
        inner: bufread::XzDecoder::new_multi_decoder(BufReader::new(r)),
    }
}
```

```rust
#[inline]
pub fn new_stream(r: R, stream: Stream) -> XzDecoder<R> {
    XzDecoder {
        inner: bufread::XzDecoder::new_stream(BufReader::new(r), stream),
    }
}
```

--------------------------------

### Get total input bytes consumed by compressor

Source: https://docs.rs/liblzma/0.4.6/liblzma/bufread/struct.XzEncoder.html

Returns the total number of bytes that have been read from the underlying stream and processed by the compressor.

```rust
pub fn total_in(&self) -> u64
```

--------------------------------

### Initialize XzEncoder and XzDecoder

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write.rs.html

Defines the structures for compression and decompression streams. Note that manual finalization via finish or auto_finish is required.

```rust
pub struct XzEncoder<W: Write> {
    data: Stream,
    obj: Option<W>,
    buf: Vec<u8>,
}
```

```rust
pub struct XzDecoder<W: Write> {
    data: Stream,
    obj: Option<W>,
    buf: Vec<u8>,
}
```

--------------------------------

### XzDecoder Initialization and Methods

Source: https://docs.rs/liblzma/0.4.6/liblzma/read/struct.XzDecoder.html

Methods for creating and interacting with the XzDecoder decompression stream.

```APIDOC
## XzDecoder Initialization

### Description
Methods to initialize an XzDecoder instance to decompress data from an underlying reader.

### Methods
- **new(r: R)**: Creates a new decompression stream to decompress one xz stream.
- **new_parallel(r: R)**: Creates a new parallel decompression stream for one xz stream.
- **new_multi_decoder(r: R)**: Creates a new decompression stream to decompress all xz streams contained in the input.
- **new_stream(r: R, stream: Stream)**: Creates a new decoder with a custom Stream configuration.

## XzDecoder Utility Methods

### Description
Methods to inspect the state of the decoder and the underlying stream.

### Methods
- **get_ref()**: Acquires a reference to the underlying stream.
- **get_mut()**: Acquires a mutable reference to the underlying stream.
- **into_inner()**: Consumes the decoder and returns the underlying reader.
- **total_out()**: Returns the total number of bytes produced by the decompressor.
- **total_in()**: Returns the total number of bytes consumed by the decompressor.
```

--------------------------------

### Initialize .lzma Encoder (Legacy)

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Stream.html

Use this only if you need to create files compatible with legacy LZMA tools. The .lzma format does not support integrity checks. Moving to the .xz format is recommended.

```rust
pub fn new_lzma_encoder(options: &LzmaOptions) -> Result<Stream, Error>
```

--------------------------------

### Get Reference to Underlying Writer

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.AutoFinishXzEncoder.html

Acquires an immutable reference to the underlying writer. Use with care to avoid corrupting the stream's state.

```rust
pub fn get_ref(&self) -> &W
```

--------------------------------

### Get uncompressed size of xz file

Source: https://docs.rs/liblzma/0.4.6/liblzma/fn.uncompressed_size.html

Calculates the uncompressed size of an xz file. Requires a source that implements both Read and Seek traits.

```rust
pub fn uncompressed_size<R: Read + Seek>(source: R) -> Result<u64>
```

--------------------------------

### Write All Implementation

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.AutoFinishXzEncoder.html

Implements `write_all` for `AutoFinishXzEncoder`, attempting to write an entire buffer.

```rust
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
```

--------------------------------

### Create a new XzEncoder

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.XzEncoder.html

Initializes a new XzEncoder for sequential compression. Use levels 0-9 (default 6) or OR with `crate::stream::PRESET_EXTREME` for slower, higher compression.

```rust
pub fn new(obj: W, level: u32) -> XzEncoder<W>
```

--------------------------------

### XzDecoder Creation Methods

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/read.rs.html

Provides methods for initializing an XzDecoder with different configurations.

```APIDOC
## XzDecoder Creation

### Description
Methods for creating an `XzDecoder` instance.

### Methods

#### `new_parallel(r: R) -> XzDecoder<R>`

Creates a new decompression stream that can process a mix of xz and non-xz data in parallel.

- **`r`**: The input reader.

#### `new_multi_decoder(r: R) -> XzDecoder<R>`

Creates a new decompression stream that reads compressed data from the given input and decompresses all the xz streams it contains.

- **`r`**: The input reader.

#### `new_stream(r: R, stream: Stream) -> XzDecoder<R>`

Creates a new decoder with a custom `Stream` configuration. The `Stream` can be pre-configured for various checks, different decompression options/tuning, etc.

- **`r`**: The input reader.
- **`stream`**: A `Stream` object for custom configuration.
```

--------------------------------

### Integrate liblzma with Async I/O using async-compression

Source: https://docs.rs/liblzma/0.4.6/index.html

Configures the `async-compression` crate to use LZMA compression/decompression by enabling the `lzma` feature flag. Note that direct `tokio` support was dropped in liblzma 0.4.0.

```toml
async-compression = { version = "0.4", features = ["lzma"] }
```

--------------------------------

### Create XzEncoder with default settings

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/bufread.rs.html

Use this to create a new encoder that reads uncompressed data from a `BufRead` stream and outputs compressed data. The `level` argument controls compression ratio, with 6 being a good default. Higher levels increase compression but take longer.

```rust
pub fn new(r: R, level: u32) -> XzEncoder<R> {
    let stream = Stream::new_easy_encoder(level, Check::Crc64).unwrap();
    XzEncoder::new_stream(r, stream)
}
```

--------------------------------

### Get Mutable Reference to Underlying Writer

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.AutoFinishXzEncoder.html

Acquires a mutable reference to the underlying writer. Mutating the stream's state directly can lead to corruption.

```rust
pub fn get_mut(&mut self) -> &mut W
```

--------------------------------

### TryInto Conversion

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/enum.Error.html

Demonstrates the `try_into` method for performing conversions.

```APIDOC
## fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Description
Performs the conversion.

### Method
N/A (This is a trait method, not a direct API endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response
- **U** (type) - The target type after successful conversion.
- **Result** (type) - A Result enum indicating success or failure.

#### Response Example
N/A
```

--------------------------------

### Initialize .xz Stream Encoder (Easy)

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Stream.html

Use this for most encoding tasks. The `preset` argument is a level (0-9), and `check` specifies the integrity check. `PRESET_EXTREME` can be bitwise-ORed with the level for slower, more effective compression.

```rust
pub fn new_easy_encoder(preset: u32, check: Check) -> Result<Stream, Error>
```

--------------------------------

### Get LZMA Memory Usage Limit

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/stream.rs.html

Retrieves the current memory usage limit for an LZMA stream. This is only supported if the underlying stream supports a memory limit.

```rust
/// Get the current memory usage limit.
///
/// This is only supported if the underlying stream supports a memlimit.
#[inline]
pub fn memlimit(&self) -> u64 {
    unsafe { liblzma_sys::lzma_memlimit_get(&self.raw) }
}
```

--------------------------------

### Get total uncompressed bytes consumed by AutoFinishXzEncoder

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write/auto_finish.rs.html

Returns the total number of uncompressed bytes consumed by the `AutoFinishXzEncoder`. This is equivalent to the number of bytes written to the stream.

```rust
pub fn total_in(&self) -> u64 {
        self.0.total_out()
    }
```

--------------------------------

### AutoFinishXzDecoder Methods

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write/auto_finish.rs.html

Provides details on the methods available for the AutoFinishXzDecoder, including `try_finish`, `finish`, `total_out`, and `total_in`.

```APIDOC
## AutoFinishXzDecoder Methods

### `try_finish()`

- **Description**: Attempts to finish the decoding process, flushing the output stream. Returns an `io::Result<()>`. This method is suitable for asynchronous I/O streams.
- **Method**: `pub fn try_finish(&mut self) -> io::Result<()>`

### `finish()`

- **Description**: Consumes the decoder, flushing the output stream and returning the contained writer if successful. This method may not be suitable for asynchronous I/O streams. It can be safely called after `try_finish` has returned `Ok` to re-acquire ownership of the stream.
- **Method**: `pub fn finish(mut self) -> io::Result<W>`

### `total_out()`

- **Description**: Returns the number of bytes produced by the decompressor. Note that this value is only accurate relative to `total_in()` after a call to `flush()`.
- **Method**: `pub fn total_out(&self) -> u64`

### `total_in()`

- **Description**: Returns the number of bytes consumed by the decompressor (e.g., the number of bytes written to this stream).
- **Method**: `pub fn total_in(&self) -> u64`
```

--------------------------------

### Create a new parallel XzEncoder

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.XzEncoder.html

Initializes a new XzEncoder for parallel compression. Use levels 0-9 (default 6) or OR with `crate::stream::PRESET_EXTREME` for slower, higher compression.

```rust
pub fn new_parallel(obj: W, level: u32) -> XzEncoder<W>
```

--------------------------------

### Get reference to underlying writer in AutoFinishXzEncoder

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write/auto_finish.rs.html

Acquires a reference to the underlying writer of the `AutoFinishXzEncoder`. Use this to inspect the writer without modifying the encoder's state.

```rust
pub fn get_ref(&self) -> &W {
        self.0.get_ref()
    }
```

--------------------------------

### Decoder Initialization Methods

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Stream.html

Methods for initializing various types of LZMA decoders.

```APIDOC
## POST /new_auto_decoder

### Description
Initialize a decoder which will choose a stream/lzma formats depending on the input stream.

### Parameters
#### Request Body
- **memlimit** (u64) - Required - Maximum memory usage.
- **flags** (u32) - Required - Decoder flags.

## POST /new_stream_decoder

### Description
Initialize a .xz stream decoder.

### Parameters
#### Request Body
- **memlimit** (u64) - Required - Maximum memory usage.
- **flags** (u32) - Required - Decoder flags (e.g., TELL_ANY_CHECK, CONCATENATED).
```

--------------------------------

### AutoFinishXzEncoder Methods

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.AutoFinishXzEncoder.html

Methods available for interacting with the AutoFinishXzEncoder compression stream.

```APIDOC
## get_ref

### Description
Acquires a reference to the underlying writer.

### Method
fn get_ref(&self) -> &W

## get_mut

### Description
Acquires a mutable reference to the underlying writer. Note that mutating the output/input state of the stream may corrupt this object.

### Method
fn get_mut(&mut self) -> &mut W

## try_finish

### Description
Attempt to finish this output stream, writing out final chunks of data. This function can only be used once data has finished being written.

### Method
fn try_finish(&mut self) -> Result<()>

## finish

### Description
Consumes this encoder, flushing the output stream and returning the contained writer.

### Method
fn finish(self) -> Result<W>

## total_out

### Description
Returns the number of bytes produced by the compressor.

### Method
fn total_out(&self) -> u64

## total_in

### Description
Returns the number of bytes consumed by the compressor.

### Method
fn total_in(&self) -> u64
```

--------------------------------

### Get total compressed bytes produced by AutoFinishXzEncoder

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write/auto_finish.rs.html

Returns the total number of compressed bytes produced by the `AutoFinishXzEncoder`. This value is only meaningful in relation to `total_in()` after a `flush()` operation.

```rust
pub fn total_out(&self) -> u64 {
        self.0.total_out()
    }
```

--------------------------------

### Get a mutable reference to the underlying stream

Source: https://docs.rs/liblzma/0.4.6/liblzma/bufread/struct.XzEncoder.html

Acquires a mutable reference to the reader. Note that mutating the underlying stream while the encoder is in use may lead to unexpected behavior.

```rust
pub fn get_mut(&mut self) -> &mut R
```

--------------------------------

### Create New XzEncoder

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/read.rs.html

Constructs a new compression stream with a specified compression level. The level typically ranges from 0-9, with 6 as a default. Use `crate::stream::PRESET_EXTREME` for slower, more effective compression.

```rust
pub fn new(r: R, level: u32) -> XzEncoder<R> {
        XzEncoder {
            inner: bufread::XzEncoder::new(BufReader::new(r), level),
        }
    }
```

--------------------------------

### Initialize .xz Stream Encoder (Custom Filters)

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Stream.html

Similar to `new_easy_encoder`, but allows specifying a custom filter chain for advanced control over the encoding process.

```rust
pub fn new_stream_encoder( filters: &Filters, check: Check, ) -> Result<Stream, Error>
```

--------------------------------

### Get Mutable Reference to Underlying Writer in XzDecoder

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write.rs.html

Acquires a mutable reference to the underlying writer object. Use with caution, as mutating the stream's state can corrupt the decoder.

```rust
pub fn get_mut(&mut self) -> &mut W {
    self.obj.as_mut().unwrap()
}
```

--------------------------------

### XzDecoder Constructors

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write.rs.html

Constructors for creating `XzDecoder` instances with different configurations.

```APIDOC
## XzDecoder Constructors

### `new()`

Creates a new decoding stream that decodes a single xz stream into the provided writer.

### `new_parallel()`

Creates a new parallel decoding stream using multiple threads for decompression.

### `new_multi_decoder()`

Creates a new decoding stream that decodes all concatenated xz streams from the input into the provided writer.

### `new_stream()`

Creates a new decoding stream with a custom `Stream` configuration.
```

--------------------------------

### Write Formatted String Implementation

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.AutoFinishXzEncoder.html

Implements `write_fmt` for `AutoFinishXzEncoder`, writing a formatted string and returning any encountered error.

```rust
fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>
```

--------------------------------

### Get mutable reference to underlying writer in AutoFinishXzEncoder

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write/auto_finish.rs.html

Acquires a mutable reference to the underlying writer of the `AutoFinishXzEncoder`. Use with caution as mutating the writer's state can corrupt the stream.

```rust
pub fn get_mut(&mut self) -> &mut W {
        self.0.get_mut()
    }
```

--------------------------------

### Get total output bytes from compressor

Source: https://docs.rs/liblzma/0.4.6/liblzma/bufread/struct.XzEncoder.html

Returns the total number of bytes produced by the compressor. This value is most meaningful when the compressor flushes data, allowing calculation of the compression ratio.

```rust
pub fn total_out(&self) -> u64
```

--------------------------------

### MtStreamBuilder - Initialization

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.MtStreamBuilder.html

Provides methods for creating and configuring a new MtStreamBuilder.

```APIDOC
## MtStreamBuilder

Builder to create a multithreaded stream encoder.

### `new()`

Creates a new blank builder to create a multithreaded encoding `Stream`.

### Method

`new()`

### Endpoint

N/A (Struct method)

### Parameters

None

### Request Example

```rust
let builder = MtStreamBuilder::new();
```

### Response

#### Success Response (Self)

- `Self` (MtStreamBuilder) - A new instance of MtStreamBuilder.

#### Response Example

```rust
// Returns an instance of MtStreamBuilder
```
```

--------------------------------

### Standard property-based testing

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write.rs.html

General quickcheck test for standard XZ compression round-trips.

```rust
#[test]
    fn qc() {
        quickcheck(test as fn(_) -> _);

        fn test(v: Vec<u8>) -> bool {
            let w = XzDecoder::new(Vec::new());
            let mut w = XzEncoder::new(w, 6);
            w.write_all(&v).unwrap();
            v == w.finish().unwrap().finish().unwrap()
        }
    }
```

--------------------------------

### Stream Encoder Initialization

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/stream.rs.html

Methods for creating new encoder instances for .xz and .lzma formats.

```APIDOC
## new_easy_encoder

### Description
Initialize .xz stream encoder using a preset number. This is the recommended method for most encoding tasks.

### Parameters
- **preset** (u32) - Required - Compression level (0-9), optionally bitwise-ORed with PRESET_EXTREME.
- **check** (Check) - Required - The integrity check to insert at the end of the stream.

## new_lzma_encoder

### Description
Initialize .lzma encoder (legacy file format). Use only for compatibility with legacy tools like LZMA Utils 4.32.x.

### Parameters
- **options** (&LzmaOptions) - Required - Configuration options for the LZMA1 filter.

## new_stream_encoder

### Description
Initialize .xz Stream encoder using a custom filter chain.

### Parameters
- **filters** (&Filters) - Required - Custom filter chain configuration.
- **check** (Check) - Required - The integrity check to insert at the end of the stream.

## new_raw_encoder

### Description
Initialize an encoder stream using a custom filter chain.

### Parameters
- **filters** (&Filters) - Required - Custom filter chain configuration.
```

--------------------------------

### XzDecoder Initialization

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.XzDecoder.html

Methods for creating new instances of XzDecoder for various decompression scenarios.

```APIDOC
## XzDecoder Initialization

### Description
Methods to initialize an XzDecoder stream with different configurations.

### Methods
- **new(obj: W)**: Creates a new decoding stream for one xz stream.
- **new_parallel(obj: W)**: Creates a new parallel decoding stream for one xz stream.
- **new_multi_decoder(obj: W)**: Creates a new decoding stream for all xz streams in the input.
- **new_stream(obj: W, stream: Stream)**: Creates a new decoding stream with custom configuration.
```

--------------------------------

### Get mutable reference to underlying stream

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/bufread.rs.html

Acquires a mutable reference to the underlying `BufRead` stream. Be cautious, as mutating the stream directly might lead to unexpected behavior if the encoder is still in use.

```rust
pub fn get_mut(&mut self) -> &mut R {
    &mut self.obj
}
```

--------------------------------

### Create a new XzEncoder

Source: https://docs.rs/liblzma/0.4.6/liblzma/bufread/struct.XzEncoder.html

Creates a new XzEncoder that reads uncompressed data from a stream and emits compressed data. The level argument typically ranges from 0-9, with 6 as a default. Use `crate::stream::PRESET_EXTREME` for slower, more effective compression.

```rust
pub fn new(r: R, level: u32) -> XzEncoder<R>
```

--------------------------------

### Get total bytes produced by compressor

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/bufread.rs.html

Returns the total number of compressed bytes emitted by the encoder. Note that this value might not be perfectly accurate until the stream is flushed, as internal buffering can affect the count.

```rust
pub fn total_out(&self) -> u64 {
    self.data.total_out()
}
```

--------------------------------

### Encoder Initialization Methods

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Stream.html

Methods for initializing various types of LZMA encoders.

```APIDOC
## POST /new_easy_encoder

### Description
Initialize .xz stream encoder using a preset number.

### Parameters
#### Request Body
- **preset** (u32) - Required - Compression level (0-9), optionally ORed with PRESET_EXTREME.
- **check** (Check) - Required - Integrity check to insert at the end of the stream.

## POST /new_lzma_encoder

### Description
Initialize .lzma encoder (legacy file format).

### Parameters
#### Request Body
- **options** (LzmaOptions) - Required - Configuration options for the legacy encoder.

## POST /new_stream_encoder

### Description
Initialize .xz Stream encoder using a custom filter chain.

### Parameters
#### Request Body
- **filters** (Filters) - Required - Custom filter chain configuration.
- **check** (Check) - Required - Integrity check type.
```

--------------------------------

### Create XzEncoder instances

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write.rs.html

Methods for creating new encoder instances, including standard and parallel compression configurations.

```rust
pub fn new(obj: W, level: u32) -> XzEncoder<W> {
        let stream = Stream::new_easy_encoder(level, Check::Crc64).unwrap();
        XzEncoder::new_stream(obj, stream)
    }
```

```rust
#[cfg(feature = "parallel")]
    pub fn new_parallel(obj: W, level: u32) -> XzEncoder<W> {
        let stream = MtStreamBuilder::new()
            .preset(level)
            .check(Check::Crc64)
            .threads(num_cpus::get() as u32)
            .encoder()
            .unwrap();
        Self::new_stream(obj, stream)
    }
```

--------------------------------

### Create LZMA Options with Preset

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/stream.rs.html

Creates a new set of LZMA options using a preset compression level. Presets typically range from 0-9, and can be combined with `PRESET_EXTREME` for slower, higher compression.

```rust
/// Creates a new blank set of options for encoding.
///
/// The `preset` argument is usually a level in the range 0-9. You may also
/// bitwise-OR a level with [`PRESET_EXTREME`] to use the slower extreme
/// variant, for example `6 | PRESET_EXTREME`.
#[inline]
pub fn new_preset(preset: u32) -> Result<LzmaOptions, Error> {
    unsafe {
        let mut options = Self::new();
        let ret = liblzma_sys::lzma_lzma_preset(&mut options.raw, preset);
        if ret != 0 {
            Err(Error::Program)
        } else {
            Ok(options)
        }
    }
}
```

--------------------------------

### Create a new parallel XzEncoder

Source: https://docs.rs/liblzma/0.4.6/liblzma/bufread/struct.XzEncoder.html

Creates a new parallel XzEncoder for concurrent compression. Similar to `new`, the level argument controls compression strength, and `crate::stream::PRESET_EXTREME` can be used for enhanced compression.

```rust
pub fn new_parallel(r: R, level: u32) -> XzEncoder<R>
```

--------------------------------

### Property-based testing for LZMA1

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write.rs.html

Uses quickcheck to verify LZMA1 stream encoding and decoding consistency.

```rust
#[test]
    fn qc_lzma1() {
        quickcheck(test as fn(_) -> _);

        fn test(v: Vec<u8>) -> bool {
            let stream = Stream::new_lzma_decoder(u64::MAX).unwrap();
            let w = XzDecoder::new_stream(Vec::new(), stream);
            let options = LzmaOptions::new_preset(6).unwrap();
            let stream = Stream::new_lzma_encoder(&options).unwrap();
            let mut w = XzEncoder::new_stream(w, stream);
            w.write_all(&v).unwrap();
            v == w.finish().unwrap().finish().unwrap()
        }
    }
```

--------------------------------

### AutoFinishXzDecoder Write Trait Implementation

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write/auto_finish.rs.html

Details the implementation of the `Write` trait for `AutoFinishXzDecoder`, specifically the `write` and `flush` methods.

```APIDOC
## AutoFinishXzDecoder Write Trait Implementation

### `write()`

- **Description**: Writes a buffer to the decoder. Delegates to the underlying decoder's `write` method.
- **Method**: `fn write(&mut self, buf: &[u8]) -> io::Result<usize>`

### `flush()`

- **Description**: Flushes the underlying data stream. Delegates to the underlying decoder's `flush` method.
- **Method**: `fn flush(&mut self) -> io::Result<()>`
```

--------------------------------

### Reference Adapter

Source: https://docs.rs/liblzma/0.4.6/liblzma/read/struct.XzEncoder.html

Creates a reference adapter for the writer instance.

```APIDOC
## POST /api/users

### Description
Creates a “by reference” adapter for this instance of `Write`.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user to retrieve.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Body
- **username** (string) - Required - The username for the new user.
- **email** (string) - Required - The email address for the new user.

### Request Example
```json
{
  "username": "johndoe",
  "email": "john.doe@example.com"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created user.
- **username** (string) - The username of the created user.
- **email** (string) - The email address of the created user.

#### Response Example
```json
{
  "id": "user123",
  "username": "johndoe",
  "email": "john.doe@example.com"
}
```
```

--------------------------------

### Create a by-reference adapter for Read

Source: https://docs.rs/liblzma/0.4.6/liblzma/bufread/struct.XzEncoder.html

Creates an adapter that allows treating a `Read` instance as a reference, useful for borrowing operations.

```rust
fn by_ref(&mut self) -> &mut Self
```

--------------------------------

### Stream Decoder Initialization

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/stream.rs.html

Methods for creating decoder instances.

```APIDOC
## new_auto_decoder

### Description
Initialize a decoder which will choose a stream/lzma format depending on the input stream.

### Parameters
- **memlimit** (u64) - Required - Maximum memory usage allowed for the decoder.
- **flags** (u32) - Required - Flags such as TELL_NO_CHECK, TELL_UNSUPPORTED_CHECK, IGNORE_CHECK, or CONCATENATED.
```

--------------------------------

### Functions in liblzma-0.4.6

Source: https://docs.rs/liblzma/0.4.6/liblzma/all.html

Lists the available free functions within the liblzma-0.4.6 crate.

```APIDOC
## Functions

- `copy_decode`
- `copy_encode`
- `decode_all`
- `encode_all`
- `uncompressed_size`
```

--------------------------------

### XzEncoder

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write.rs.html

The XzEncoder struct provides a writer interface for compressing data. It can be initialized with a compression level and an output writer. The `try_finish` method should be called to finalize the compressed stream, and `auto_finish` can be used for automatic finalization.

```APIDOC
## XzEncoder

### Description
A compression stream which will have uncompressed data written to it and will write compressed data to an output stream.

### Methods

#### `new(obj: W, level: u32) -> XzEncoder<W>`
Creates a new compression stream with the specified compression level.

- **obj** (W): The output writer to write compressed data to.
- **level** (u32): The compression level (0-9). Bitwise OR with `crate::stream::PRESET_EXTREME` for extreme compression.

#### `new_parallel(obj: W, level: u32) -> XzEncoder<W>` (Requires `parallel` feature)
Creates a new parallel compression stream.

- **obj** (W): The output writer to write compressed data to.
- **level** (u32): The compression level (0-9).

#### `new_stream(obj: W, stream: Stream) -> XzEncoder<W>`
Creates a new encoder using a pre-configured `Stream`.

- **obj** (W): The output writer.
- **stream** (Stream): The stream configuration.

#### `get_ref(&self) -> &W`
Acquires a reference to the underlying writer.

#### `get_mut(&mut self) -> &mut W`
Acquires a mutable reference to the underlying writer.

#### `try_finish(&mut self) -> io::Result<()>`
Attempts to finish the output stream, writing final chunks of data. This should be called once writing is complete. Further writes after this may panic.

#### `finish(self) -> io::Result<W>`
Consumes the encoder, finishing the compression stream and returning the underlying writer if successful.

### Example
```rust
use std::io::Write;
use liblzma::writer::XzEncoder;

let mut compressed_data = Vec::new();
let mut encoder = XzEncoder::new(&mut compressed_data, 6);
encoder.write_all(b"some data to compress").unwrap();
encoder.finish().unwrap();
// compressed_data now contains the compressed output
```
```

--------------------------------

### XzEncoder Creation

Source: https://docs.rs/liblzma/0.4.6/liblzma/bufread/struct.XzEncoder.html

Methods for creating new XzEncoder instances with different configurations.

```APIDOC
## XzEncoder
liblzma::bufread

# Struct XzEncoder Copy item path

A xz encoder, or compressor. This structure implements a `BufRead` interface and will read uncompressed data from an underlying stream and emit a stream of compressed data.

### impl<R: BufRead> XzEncoder<R>

#### pub fn new(r: R, level: u32) -> XzEncoder<R>
Creates a new encoder which will read uncompressed data from the given stream and emit the compressed stream. The `level` argument here is typically 0-9 with 6 being a good default. To use the slower `xz --extreme`-style preset, bitwise-OR a level with `crate::stream::PRESET_EXTREME` (for example, `6 | crate::stream::PRESET_EXTREME`).

#### pub fn new_parallel(r: R, level: u32) -> XzEncoder<R>
Creates a new parallel encoder which will read uncompressed data from the given stream and emit the compressed stream. The `level` argument here is typically 0-9 with 6 being a good default. To use the slower `xz --extreme`-style preset, bitwise-OR a level with `crate::stream::PRESET_EXTREME` (for example, `6 | crate::stream::PRESET_EXTREME`).

#### pub fn new_stream(r: R, stream: Stream) -> XzEncoder<R>
Creates a new encoder with a custom `Stream`. The `Stream` can be pre-configured for multithreaded encoding, different compression options/tuning, etc.
```

--------------------------------

### By Reference Adapter

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.AutoFinishXzEncoder.html

Creates a "by reference" adapter for an instance of `Write`.

```rust
fn by_ref(&mut self) -> &mut Self
where Self: Sized,
```

--------------------------------

### Configure ARM-Thumb Filter

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/struct.Filters.html

Adds an ARM-Thumb filter to the compression chain.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let dict_size = 0x40000;
let mut opts = LzmaOptions::new_preset(6).unwrap();
opts.dict_size(dict_size);
let mut filters = Filters::new();
filters.arm_thumb();
filters.lzma2(&opts);
```

```rust
use liblzma::stream::{Filters, LzmaOptions};

let mut filters = Filters::new();
filters.arm_thumb_properties(&[0x00, 0x00, 0x00, 0x00]).unwrap();
```

--------------------------------

### Initialize .xz Stream Encoder

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/stream.rs.html

Initializes an encoder using a preset level and integrity check.

```rust
pub fn new_easy_encoder(preset: u32, check: Check) -> Result<Stream, Error> {
    let mut init = unsafe { Stream::zeroed() };
    cvt(unsafe {
        liblzma_sys::lzma_easy_encoder(&mut init.raw, preset, check as liblzma_sys::lzma_check)
    })?;
    Ok(init)
}
```

--------------------------------

### XzDecoder Constructors

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/bufread.rs.html

Various methods to initialize an XzDecoder, including standard, parallel, and multi-stream decoders.

```rust
impl<R: BufRead> XzDecoder<R> {
    /// Creates a new decoder which will decompress data read from the given
    /// stream.
    #[inline]
    pub fn new(r: R) -> XzDecoder<R> {
        let stream = Stream::new_stream_decoder(u64::MAX, 0).unwrap();
        XzDecoder::new_stream(r, stream)
    }

    /// Creates a new parallel decoder which will decompress data read from the given
    /// stream.
    #[cfg(feature = "parallel")]
    pub fn new_parallel(r: R) -> Self {
        let stream = MtStreamBuilder::new()
            .memlimit_stop(u64::MAX)
            .threads(num_cpus::get() as u32)
            .decoder()
            .unwrap();
        Self::new_stream(r, stream)
    }

    /// Creates a new decoder which will decompress data read from the given
    /// input. All the concatenated xz streams from input will be consumed.
    #[inline]
    pub fn new_multi_decoder(r: R) -> XzDecoder<R> {
        let stream = Stream::new_auto_decoder(u64::MAX, liblzma_sys::LZMA_CONCATENATED).unwrap();
        XzDecoder::new_stream(r, stream)
    }

    /// Creates a new decoder with a custom `Stream`.
    ///
    /// The `Stream` can be pre-configured for various checks, different
    /// decompression options/tuning, etc.
    #[inline]
    pub fn new_stream(r: R, stream: Stream) -> XzDecoder<R> {
        XzDecoder {
            obj: r,
            data: stream,
        }
    }
}
```

--------------------------------

### XzDecoder Implementations

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/write.rs.html

Details the implementation of `Write`, `Read`, and `Drop` traits for the `XzDecoder`.

```APIDOC
## XzDecoder Implementations

### `impl Write for XzDecoder<W>`

#### `write` Method

##### Description
Writes a byte slice to the `XzDecoder`. The loop continues processing data until a portion is written, the input data is empty, or the stream ends.

##### Signature
`fn write(&mut self, data: &[u8]) -> io::Result<usize>`

#### `flush` Method

##### Description
Flushes the `XzDecoder`, ensuring all buffered data is processed and then flushing the underlying writer.

##### Signature
`fn flush(&mut self) -> io::Result<()>`

### `impl Read for XzDecoder<W>`

#### `read` Method

##### Description
Reads decompressed data into a buffer by delegating to the underlying writer's `read` method.

##### Signature
`fn read(&mut self, buf: &mut [u8]) -> io::Result<usize>`

### `impl Drop for XzDecoder<W>`

#### `drop` Method

##### Description
When the `XzDecoder` goes out of scope, this method is called. If the underlying writer is still present, it attempts to finish the stream by calling `try_finish`.

##### Signature
`fn drop(&mut self)`
```

--------------------------------

### From Implementation for Action

Source: https://docs.rs/liblzma/0.4.6/liblzma/stream/enum.Action.html

Allows creating an Action value from itself.

```rust
fn from(t: T) -> T
```

--------------------------------

### Write All Vectored Implementation

Source: https://docs.rs/liblzma/0.4.6/liblzma/write/struct.AutoFinishXzEncoder.html

Implements `write_all_vectored` for `AutoFinishXzEncoder`, attempting to write multiple buffers. This is a nightly-only experimental API.

```rust
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
```

--------------------------------

### Add ARM-Thumb Filter

Source: https://docs.rs/liblzma/0.4.6/src/liblzma/stream.rs.html

Configures an ARM-Thumb filter for binary compression.

```rust
use liblzma::stream::{Filters, LzmaOptions};

let dict_size = 0x40000;
let mut opts = LzmaOptions::new_preset(6).unwrap();
opts.dict_size(dict_size);
let mut filters = Filters::new();
filters.arm_thumb();
filters.lzma2(&opts);
```
Tokens:
Raw