qbsdiff

https://docs.rs/qbsdiff
Admin
qbsdiff is a fast and memory-efficient bsdiff 4.x compatible delta compressor and patcher for...
Tokens:16,481
Snippets:184
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install qbsdiff Command

Source: https://docs.rs/qbsdiff

Install the qbsdiff command-line tool to your Cargo bin directory for easy access.

```bash
$ cargo install qbsdiff --features cmd
```

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

### Install qbsdiff command-line tool

Source: https://docs.rs/qbsdiff/latest/index.html

Install the qbsdiff command-line tool to your Cargo bin directory using 'cargo install'. This command also requires the 'cmd' feature flag.

```bash
$ cargo install qbsdiff --features cmd

```

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

### Example: Produce Bsdiff Patch Data

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Demonstrates how to produce patch data with custom buffer size, compression level, and disabled parallel searching.

```rust
use std::io;
use qbsdiff::{Bsdiff, ParallelScheme};

fn bsdiff(source: &[u8], target: &[u8]) -> io::Result<Vec<u8>> {
    let mut patch = Vec::new();
    Bsdiff::new(source, target)
        .buffer_size(65536)
        .compression_level(1)
        .parallel_scheme(ParallelScheme::Never)
        .compare(io::Cursor::new(&mut patch)?);
    Ok(patch)
}
```

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

### Convert Range to Extent

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Converts a `Range<usize>` to a tuple of (start, length). The length is calculated using saturating_sub to prevent underflow.

```rust
/// Converts Range<usize> to extent (i, n).
#[inline]
fn range_to_extent(range: Range<usize>) -> (usize, usize) {
    let Range { start, end } = range;
    (start, end.saturating_sub(start))
}
```

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

### Get Previous State

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Retrieves the previous state (i0, j0, n0, b0) from the SaDiff context. This is useful for backtracking or resuming operations.

```rust
    #[inline]
    fn previous_state(&self) -> (usize, usize, usize, usize) {
        (self.i0, self.j0, self.n0, self.b0)
    }
```

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

### Build qbsdiff and qbspatch Commands

Source: https://docs.rs/qbsdiff

Build the qbsdiff and qbspatch command-line tools using Cargo. These commands are useful for applying and creating patches.

```bash
$ cargo build --release --bins --features cmd
$ cd target/release
$ ./qbsdiff --help
$ ./qbspatch --help
```

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

### Build qbsdiff and qbspatch commands

Source: https://docs.rs/qbsdiff/latest/index.html

Build the qbsdiff and qbspatch command-line tools using Cargo. These commands require the 'cmd' feature flag.

```bash
$ cargo build --release --bins --features cmd
$ cd target/release
$ ./qbsdiff --help
$ ./qbspatch --help

```

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

### Add qbsdiff Dependency

Source: https://docs.rs/qbsdiff

Add the qbsdiff crate to your Cargo.toml file to include it in your project.

```toml
[dependencies]
qbsdiff = "1.4"
```

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

### Bspatch::new

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/struct.Bspatch.html

Parses the patch file and creates a new patcher configuration. Returns an error if the patch header fails to parse.

```APIDOC
## pub fn new(patch: &'p [u8]) -> Result<Self>

### Description
Parse the patch file and create new patcher configuration.
Return error if failed to parse the patch header.

### Parameters
* `patch`: A byte slice representing the patch data.

### Returns
A `Result` containing a new `Bspatch` instance on success, or an error on failure.
```

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

### Create Bsdiff Delta Compressor Configuration

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Initializes a new Bsdiff configuration with default settings. Panics if the source data exceeds MAX_LENGTH.

```rust
pub fn new(source: &'s [u8], target: &'t [u8]) -> Self {
        if source.len() > MAX_LENGTH {
            panic!("source data is too large to be indexed");
        }

        Bsdiff {
            source,
            target,
            parallel_scheme: ParallelScheme::Auto,
            small_match: SMALL_MATCH,
            mismatch_count: MISMATCH_COUNT,
            long_suffix: LONG_SUFFIX,
            compression_level: Compression::new(COMPRESSION_LEVEL),
            buffer_size: BUFFER_SIZE,
        }
    }
```

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

### Bspatch::new

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Parses the patch file and creates a new Bspatch configuration. Returns an error if the patch header is invalid.

```APIDOC
## Bspatch::new

### Description
Parses the patch file and creates a new patcher configuration. Returns an error if failed to parse the patch header.

### Signature
`pub fn new(patch: &'p [u8]) -> Result<Self>`

### Parameters
* `patch` (&'p [u8]): A byte slice representing the patch file content.

### Returns
`Result<Self>`: A `Bspatch` instance if successful, otherwise an `io::Error`.
```

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

### Bsdiff::compare

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/struct.Bsdiff.html

Initiates the delta compression process, searching for matches and constructing the patch file. Returns the size of the generated patch file.

```APIDOC
## pub fn compare<P: Write>(&self, patch: P) -> Result<u64>

### Description
Start searching matches in target and constructing the patch file.

The size of patch file would be returned if no error occurs.

### Parameters

* **patch** (P: Write) - A writer to which the patch data will be written.

### Returns

* Result<u64> - The size of the patch file if successful, or an error.
```

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

### Add qbsdiff dependency to Cargo.toml

Source: https://docs.rs/qbsdiff/latest/index.html

To use the qbsdiff crate, add the following dependency to your Cargo.toml file.

```toml
[dependencies]
qbsdiff = "1.4"

```

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

### Initialize Bspatch Patcher

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Creates a new Bspatch instance by parsing the patch data. Returns an error if the patch header is invalid.

```rust
pub fn new(patch: &'p [u8]) -> Result<Self> {
    Ok(Bspatch {
        patch: parse(patch)?,
        buffer_size: BUFFER_SIZE,
        delta_min: DELTA_MIN,
    })
}
```

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

### Create BSPatch Context

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Initializes a new `Context` for applying a patch. Requires a `PatchFile` structure, the source data, a target writer, and buffer sizes for control and delta data.

```rust
pub fn new(patch: PatchFile<'p>, source: &'s [u8], target: T, bsize: usize, dsize: usize) -> Self {
        Context {
            source: Cursor::new(source),
            target,
            patch,
            n: 0,
            buf: vec![0; bsize],
            dlt: vec![0; dsize],
            ctl: [0; 24],
            total: 0,
        }
    }
```

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

### Bsdiff::new

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/struct.Bsdiff.html

Creates a new configuration for bsdiff delta compression. Panics if the source data length exceeds MAX_LENGTH.

```APIDOC
## pub fn new(source: &'s [u8], target: &'t [u8]) -> Self

### Description
Create new configuration for bsdiff delta compression.

Panics if the length of source data is greater than MAX_LENGTH.

### Parameters

* **source** (&'s [u8]) - The source data slice.
* **target** (&'t [u8]) - The target data slice.

### Returns

* Self - A new Bsdiff configuration instance.
```

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

### Context Creation

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Creates a new BSPatch context with the provided patch file, source data, target writer, and buffer sizes.

```APIDOC
## fn new<'s, 'p, T: Write>(
    patch: PatchFile<'p>,
    source: &'s [u8],
    target: T,
    bsize: usize,
    dsize: usize
) -> Context<'s, 'p, T>
```

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

### Create Bsdiff Patch with Custom Settings

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/struct.Bsdiff.html

Produces patch data with a limited delta calculation buffer and disabled parallel searching, using the fastest bzip2 compression level. Ensure necessary imports are included.

```rust
use std::io;
use qbsdiff::{Bsdiff, ParallelScheme};

fn bsdiff(source: &[u8], target: &[u8]) -> io::Result<Vec<u8>> {
    let mut patch = Vec::new();
    Bsdiff::new(source, target)
        .buffer_size(65536)
        .compression_level(1)
        .parallel_scheme(ParallelScheme::Never)
        .compare(io::Cursor::new(&mut patch))?;
    Ok(patch)
}
```

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

### Apply Patch to File with Pre-allocation

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/struct.Bspatch.html

Applies a patch to source data, writing the output to a file. It hints the target file size for pre-allocation before applying the patch.

```rust
use std::io;
use std::fs::File;
use std::path::Path;
use qbsdiff::Bspatch;

fn file_allocate(file: &mut File, size: u64) -> io::Result<()> {
    unimplemented!()
}

fn bspatch<P: AsRef<Path>>(source: &[u8], target: P, patch: &[u8]) -> io::Result<u64> {
    let patcher = Bspatch::new(patch)?;
    let mut target_file = File::create(target)?;
    file_allocate(&mut target_file, patcher.hint_target_size())?;
    patcher.apply(source, &mut target_file)
}
```

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

### Hint Target File Size

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Returns the hinted size of the target file based on the patch information.

```rust
pub fn hint_target_size(&self) -> u64 {
    self.patch.tsize
}
```

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

### Generate a patch by comparing source and target using Bsdiff

Source: https://docs.rs/qbsdiff/latest/index.html

This function generates a patch file by comparing a source byte slice with a target byte slice. It uses the Bsdiff struct from the qbsdiff crate and writes the resulting patch data to a mutable byte vector via an io::Cursor.

```rust
use std::io;
use qbsdiff::Bsdiff;

fn bsdiff(source: &[u8], target: &[u8]) -> io::Result<Vec<u8>> {
    let mut patch = Vec::new();
    Bsdiff::new(source, target)
        .compare(io::Cursor::new(&mut patch))?;
    Ok(patch)
}

```

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

### Apply a patch to a source using Bspatch

Source: https://docs.rs/qbsdiff/latest/index.html

This function applies a given patch to a source byte slice to produce a target byte vector. It utilizes the Bspatch struct from the qbsdiff crate. The target vector can be preallocated using a hint from the patcher.

```rust
use std::io;
use qbsdiff::Bspatch;

fn bspatch(source: &[u8], patch: &[u8]) -> io::Result<Vec<u8>> {
    let patcher = Bspatch::new(patch)?;
    let mut target = Vec::new();
    // To preallocate target:
    //Vec::with_capacity(patcher.hint_target_size() as usize);
    patcher.apply(source, io::Cursor::new(&mut target)?);
    Ok(target)
}

```

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

### Configure bzip2 Compression Level

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Sets the bzip2 compression level for patch files, ranging from 0 to 9. The default level is usually sufficient.

```rust
pub fn compression_level(mut self, compression_level: u32) -> Self {
        self.compression_level = Compression::new(u32::min(u32::max(compression_level, 0), 9));
        self
    }
```

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

### Apply BSPatch File

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Applies the patch by iterating through control instructions, adding new data, copying existing data, and seeking within the source. Flushes the target writer upon completion.

```rust
pub fn apply(mut self) -> Result<u64> {
        while let Some(result) = self.next() {
            match result {
                Ok(Control { add, copy, seek }) => {
                    self.add(add)?;
                    self.copy(copy)?;
                    self.seek(seek)?;
                }
                Err(e) => return Err(e),
            }
        }
        if self.n > 0 {
            self.target.write_all(&self.buf[..self.n])?;
        }
        self.target.flush()?;
        Ok(self.total)
    }
```

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

### Buffer Size Configuration

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Sets the buffer size used for delta calculation during patch generation. The minimum buffer size is 128 bytes.

```APIDOC
## buffer_size(buffer_size: usize) -> Self

### Description
Set the buffer size for delta calculation (`buffer_size >= 128`, default is `BUFFER_SIZE`).

### Parameters
* **buffer_size** (usize) - The buffer size for delta calculation (must be >= 128).
```

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

### Bspatch::hint_target_size

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/struct.Bspatch.html

Provides a hint for the expected final size of the target file after the patch is applied.

```APIDOC
## pub fn hint_target_size(&self) -> u64

### Description
Hint the final target file size.

### Returns
A `u64` representing the estimated target file size.
```

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

### TryFrom<U> for Bspatch

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/struct.Bspatch.html

Implementation of the TryFrom trait allowing conversion from a type U into Bspatch, provided U implements Into<Bspatch>.

```APIDOC
## impl<T, U> TryFrom<U> for T
where U: Into<T>

### Associated Types
#### type Error = Infallible

### Methods
#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

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

### Create New SaDiff Search Context

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Creates a new search context for the SaDiff algorithm. Initializes the struct with source and target data, suffix array, and various matching parameters.

```rust
    pub fn new(
        s: &'s [u8],
        t: &'t [u8],
        sa: &'s SuffixArray<'s>,
        small_match: usize,
        mismatch_count: usize,
        long_suffix: usize,
    ) -> Self {
        SaDiff {
            s,
            t,
            sa,
            small_match,
            mismatch_count,
            long_suffix,
            i0: 0,
            j0: 0,
            n0: 0,
            b0: 0,
        }
```

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

### Bspatch::apply

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Applies the patch to the source data and writes the resulting target data to the provided writer. It returns the total size of the target data written.

```APIDOC
## Bspatch::apply

### Description
Applies the patch to the source data and outputs the stream of target data. The `source` parameter is expected to be a byte slice. For lazy loading of source files, using `memmap` is recommended. The function returns the total size of the target data written if no error occurs.

### Signature
`pub fn apply<T: Write>(self, source: &[u8], target: T) -> Result<u64>`

### Parameters
* `source` (&[u8]): The original data as a byte slice.
* `target` (T: Write): A writer where the patched data will be written.

### Returns
`Result<u64>`: The total size of the target data written, or an `io::Error` if the patching process fails.
```

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

### Configure Buffer Size for Delta Calculation

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Sets the buffer size used during delta calculation. Ensures the buffer size is at least 128.

```rust
pub fn buffer_size(mut self, mut buffer_size: usize) -> Self {
        if buffer_size < 128 {
            buffer_size = 128;
        }
        self.buffer_size = buffer_size;
        self
    }
```

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

### Bspatch::delta_min

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/struct.Bspatch.html

Sets the initial delta cache size. The delta cache is dynamic and can grow as needed, but will not exceed the main copy buffer size. This setting might be deprecated in future versions.

```APIDOC
## pub fn delta_min(self, dm: usize) -> Self

### Description
Sets the initial delta cache size, (`dm > 128`, default is `DELTA_MIN`).
The delta cache is dynamic and can grow up when needed (but keeps not greater than the size of main copy buffer).
This might be deprecated in later version.

### Parameters
* `dm`: The initial delta cache size in bytes. Must be greater than 128.

### Returns
Returns `self` to allow chaining configuration.
```

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

### Create New Paralleled bsdiff Search Context

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Creates a new parallelized bsdiff search context by dividing the target data into chunks and initializing `SaDiff` jobs for each chunk.

```rust
    pub fn new(
        s: &'s [u8],
        t: &'t [u8],
        sa: &'s SuffixArray<'s>,
        chunk: usize,
        small_match: usize,
        mismatch_count: usize,
        long_suffix: usize,
    ) -> Self {
        let jobs = t
            .chunks(chunk)
            .map(|ti| SaDiff::new(s, ti, sa, small_match, mismatch_count, long_suffix))
            .collect();
        ParSaDiff { jobs }
```

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

### Set Buffer Size

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Configures the main copy buffer size for the patcher. Ensures the buffer size is at least 128 bytes.

```rust
pub fn buffer_size(mut self, mut bs: usize) -> Self {
    if bs < 128 {
        bs = 128;
    }
    self.buffer_size = bs;
    self
}
```

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

### Write Compressed Controls, Delta, and Extra Data

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Writes the compressed control data, delta data, and extra data to the patch file. This completes the patch file construction.

```rust
    // Write compressed controls, delta data and extra data.
    patch.write_all(&bz_ctrls[..])?;
    patch.write_all(&bz_delta[..])?;
    patch.write_all(&bz_extra[..])?;
    patch.flush()?;
```

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

### TryInto<U> for Bspatch

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/struct.Bspatch.html

Implementation of the TryInto trait allowing conversion from Bspatch into a type U, provided U implements TryFrom<Bspatch>.

```APIDOC
## impl<T, U> TryInto<U> for T
where U: TryFrom<T>

### Associated Types
#### type Error = <U as TryFrom<T>>::Error

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

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

### Apply Patch with Bspatch

Source: https://docs.rs/qbsdiff

Use the Bspatch struct to apply a patch to a source byte slice, producing a target byte vector. Preallocation of the target vector can be done using the hint provided by patcher.hint_target_size().

```rust
use std::io;
use qbsdiff::Bspatch;

fn bspatch(source: &[u8], patch: &[u8]) -> io::Result<Vec<u8>> {
    let patcher = Bspatch::new(patch)?;
    let mut target = Vec::new();
    // To preallocate target:
    //Vec::with_capacity(patcher.hint_target_size() as usize);
    patcher.apply(source, io::Cursor::new(&mut target)?);
    Ok(target)
}
```

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

### Bspatch::apply

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/struct.Bspatch.html

Applies the patch to the source data and outputs the resulting stream to the target. The source data is expected as a byte slice. The target can be any type implementing `std::io::Write`. Returns the size of the target data upon successful completion.

```APIDOC
## pub fn apply<T: Write>(self, source: &[u8], target: T) -> Result<u64>

### Description
Apply patch to the source data and output the stream of target.
Parameter `source` is designed to be a low-level `&[u8]` binary, rather than a `Seek + Read` random accessing data. See #8, allowing random accessible source file might be misleading, which could result in unwanted performance loss due to heavy syscall overheads of `seek` + `read` (by the way, `pread`/`read_at` is not cross-platform).
For those who in search of loading the source file lazily, simply memmap source file to memory is recommended.

### Parameters
* `source`: A byte slice representing the original data.
* `target`: A mutable reference to a type implementing `std::io::Write` where the patched data will be written.

### Returns
A `Result` containing the size of the target data in bytes on success, or an error on failure.
```

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

### Apply Patch

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Applies the patch file to the source data and writes the result to the target. Returns the total number of bytes written.

```APIDOC
## fn apply(mut self) -> Result<u64>
```

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

### Compare and Generate Patch

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Initiates the process of comparing source and target data to generate a patch file. It handles both single-threaded and parallel execution based on chunk size.

```APIDOC
## compare<P: Write>(&self, patch: P) -> Result<u64>

### Description
Start searching matches in target and constructing the patch file.

The size of patch file would be returned if no error occurs.

### Parameters
* **patch** (P: Write) - A writer to which the generated patch data will be written.

### Response
* **Result<u64>** - The size of the generated patch file in bytes, or an error if the process fails.
```

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

### Read Next Control Instruction

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Reads the next control instruction (add, copy, seek) from the patch file's control data. Returns `None` if the end of the control data is reached.

```rust
fn next(&mut self) -> Option<Result<Control>> {
        match read_exact_or_eof(&mut self.patch.ctrls, &mut self.ctl[..]) {
            Ok(0) => return None,
            Err(e) => return Some(Err(e)),
            _ => (),
        }

        let add = decode_int(&self.ctl[0..]) as u64;
        let copy = decode_int(&self.ctl[8..]) as u64;
        let seek = decode_int(&self.ctl[16..]);
        Some(Ok(Control { add, copy, seek }))
    }
```

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

### Compression Level Configuration

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Sets the compression level for bzip2 compression used in patch files. The level ranges from 0 (fastest, default) to 9 (best compression).

```APIDOC
## compression_level(compression_level: u32) -> Self

### Description
Set the compression level of bzip2 (in range `0..=9`, default is `COMPRESSION_LEVEL`).

The fastest/default compression level is usually good enough. In contrast, patch files produced with the best level appeared slightly bigger in many test cases.

### Parameters
* **compression_level** (u32) - The desired bzip2 compression level (0-9).
```

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

### Compute bsdiff Controls in Parallel

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Computes all bsdiff controls in parallel by iterating over the `SaDiff` jobs, searching each chunk, and collecting the control structures.

```rust
    /// Compute all the bsdiff controls in parallel.
    pub fn compute(mut self) -> Vec<Control> {
        self.jobs
            .par_iter_mut()
            .map(|diff| {
                // Search current chunk.
                let mut pos = 0u64;
                let mut ctrls = Vec::new();
                for ctl in diff {
                    pos += ctl.add;
                    pos = pos.wrapping_add(ctl.seek as u64);
                    ctrls.push(ctl);
                }

                // Reset source cursor (`pos <= MAX_LENGTH` would not overflow).
                debug_assert!(pos <= i64::MAX as u64);
                ctrls.push(Control {
                    add: 0,
                    copy: 0,
                    seek: -(pos as i64),
                });

                ctrls
            })
            .flatten()
            .collect()
```

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

### Configure Bsdiff Parallel Search Scheme

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Sets the parallel searching scheme for bsdiff. If a chunk size or number of jobs is set to zero, it defaults to Auto. Small chunk sizes are internally adjusted to a minimum of 256 KiB to maintain patch quality.

```rust
pub fn parallel_scheme(mut self, mut parallel_scheme: ParallelScheme) -> Self {
        use ParallelScheme::*;
        if parallel_scheme == ChunkSize(0) || parallel_scheme == NumJobs(0) {
            parallel_scheme = Auto;
        }
        self.parallel_scheme = parallel_scheme;
        self
    }
```

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

### Apply a Patch to Source Data

Source: https://docs.rs/qbsdiff/latest/qbsdiff

Use the Bspatch struct to apply a patch file to source data, producing the target data. This function is useful for updating files with minimal data transfer.

```rust
use std::io;
use qbsdiff::Bspatch;

fn bspatch(source: &[u8], patch: &[u8]) -> io::Result<Vec<u8>> {
    let patcher = Bspatch::new(patch)?;
    let mut target = Vec::new();
    // To preallocate target:
    //Vec::with_capacity(patcher.hint_target_size() as usize);
    patcher.apply(source, io::Cursor::new(&mut target))?;
    Ok(target)
}

```

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

### Apply Patch with Configurable Buffers

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/struct.Bspatch.html

Applies a patch to source data using a specified copy buffer size and delta cache size. The target is written to a mutable Vec<u8>.

```rust
use std::io;
use qbsdiff::Bspatch;

fn bspatch(source: &[u8], patch: &[u8]) -> io::Result<Vec<u8>> {
    let mut target = Vec::new();
    Bspatch::new(patch)?
        .buffer_size(4096)
        .delta_min(1024)
        .apply(source, io::Cursor::new(&mut target))?;
    Ok(target)
}
```

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

### Generate bsdiff Patch File

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Initiates the patch file generation process by comparing source and target data. Determines parallel chunk size based on the configured parallel scheme.

```rust
pub fn compare<P: Write>(&self, patch: P) -> Result<u64> {
        // Determine parallel chunk size.
        use ParallelScheme::*;
        let mut chunk = match self.parallel_scheme {
            Never => self.target.len(),
            ChunkSize(chunk) => chunk,
            NumJobs(jobs) => div_ceil(self.target.len(), jobs),
            Auto => DEFAULT_CHUNK,
        };
        chunk = Ord::max(chunk, MIN_CHUNK);

        let mut suffix_array = SuffixArray::new(self.source);
        suffix_array.enable_buckets();
        if chunk >= self.target.len() {
            // Single thread is fine.
            let diff = SaDiff::new(
                self.source,
                self.target,
                &suffix_array,
                self.small_match,
                self.mismatch_count,
                self.long_suffix,
            );
            pack(
                self.source,
                self.target,
                diff,
                patch,
                self.compression_level,
                self.buffer_size,
            )
        } else {
            // Go parallel.
            let par_diff = ParSaDiff::new(
                self.source,
                self.target,
                &suffix_array,
                chunk,
                self.small_match,
                self.mismatch_count,
                self.long_suffix,
            );
            let ctrls = par_diff.compute();
            pack(
                self.source,
                self.target,
                ctrls.into_iter(),
                patch,
                self.compression_level,
                self.buffer_size,
            )
        }
    }
```

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

### Configure Bsdiff Small Match Threshold

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Sets the threshold for determining small matches. If set to zero, no matches are skipped.

```rust
pub fn small_match(mut self, small_match: usize) -> Self {
        self.small_match = small_match;
        self
    }
```

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

### Rust: Search for Next Match in bsdiff

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Implements the logic to find the next potential match between two byte sequences. It handles end-of-file conditions and optimizes searching by considering small matches and potential similar bytes.

```rust
fn search_next(&mut self) -> Option<(usize, usize, usize)> {
        // EOF is already scanned.
        if self.j0 == self.t.len() && self.b0 == 0 {
            return None;
        }

        let mut j = self.j0 + self.n0;
        let mut k = j;
        let mut m = 0;
        while j < self.t.len().saturating_sub(self.small_match) {
            // Finds out a possible exact match.
            let (i, n) = range_to_extent(self.sa.search_lcp(&self.t[j..]));

            // Counts the matched bytes, and determine whether these bytes
            // should be treated as possible similar bytes, or simply as the
            // next exact match.
            while k < j + n {
                let i = self.i0.saturating_add(k - self.j0);
                if i < self.s.len() && self.s[i] == self.t[k] {
                    m += 1;
                }
                k += 1;
            }

            if n == 0 {
                // Match nothing.
                j += 1;
                m = 0;
            } else if m == n || n <= self.small_match {
                // Skip small matches and non-empty exact matches to speed up
                // searching and improve patch quality.
                j += n;
                m = 0;
            } else if n <= m + self.mismatch_count {
                // Bytes with insufficient mismatches were treated as possible
                // suffixing similar data.
                //
                // The entire match is s[i0-b0..i0+n0+a0] ~= t[j0-b0..j0+n0+a0],
                // where
                //     n0 is the exact match (s[i0..i0+n0] == t[j0..j0+n0]),
                //     b0 is the prefixing similar bytes,
                //     a0 is the suffixing similar bytes.
                //
                // Use binary search to approximately find out a proper skip
                // length for long suffixing similar bytes.
                // Do linear search instead when length is not long enough.
                let next = if n <= self.long_suffix {
                    j + 1
                } else {
                    let mut x = 0;
                    let mut y = n;
                    while x < y {
                        let z = x + (y - x) / 2;
                        let (iz, nz) = range_to_extent(self.sa.search_lcp(&self.t[j + z..]));
                        if i + n == iz + nz && j + n == j + z + nz {
                            x = z + 1;
                        } else {
                            y = z;
                        }
                    }
                    j + Ord::max(x, 1)
                };
                let mut i = self.i0.saturating_add(j - self.j0);
                while j < next {
                    if i < self.s.len() && self.s[i] == self.t[j] {
                        m -= 1;
                    }
                    i += 1;
                    j += 1;
                }
            } else {
                // The count of mismatches is sufficient.
                return Some((i, j, n));
            }
        }

        // EOF should be treated as the last exact match.
        Some((self.s.len(), self.t.len(), 0))
    }
```

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

### Pack bsdiff 4.x Patch File

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Constructs the bsdiff 4.x patch file from computed differences. It compresses control, delta, and extra data using bzip2.

```rust
fn pack<D, P>(source: &[u8], target: &[u8], diff: D, mut patch: P, level: Compression, bsize: usize) -> Result<u64>
where
    D: Iterator<Item = Control>,
    P: Write,
{
    let mut bz_ctrls = Vec::new();
    let mut bz_delta = Vec::new();
    let mut bz_extra = Vec::new();

    {
        let mut ctrls = BzEncoder::new(Cursor::new(&mut bz_ctrls), level);
        let mut delta = BzEncoder::new(Cursor::new(&mut bz_delta), level);
        let mut extra = BzEncoder::new(Cursor::new(&mut bz_extra), level);

        let mut spos = 0;
        let mut tpos = 0;
        let mut cbuf = [0; 24];

        let mut dat = Vec::with_capacity(bsize);

        for ctrl in diff {
            // Write control data.
            encode_int(ctrl.add as i64, &mut cbuf[0..8]);
            encode_int(ctrl.copy as i64, &mut cbuf[8..16]);
            encode_int(ctrl.seek, &mut cbuf[16..24]);
            ctrls.write_all(&cbuf[..])?;

```

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

### Set Delta Minimum Size

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Sets the initial size for the delta cache buffer. Ensures the size is at least 128 bytes. This setting might be deprecated in future versions.

```rust
pub fn delta_min(mut self, mut dm: usize) -> Self {
    if dm < 128 {
        dm = 128;
    }
    self.delta_min = dm;
    self
}
```

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

### Create Patch with Bsdiff

Source: https://docs.rs/qbsdiff

Use the Bsdiff struct to compare a source byte slice with a target byte slice and generate a patch byte vector. The generated patch file format is compatible with bsdiff 4.x, but the patch data itself may differ.

```rust
use std::io;
use qbsdiff::Bsdiff;

fn bsdiff(source: &[u8], target: &[u8]) -> io::Result<Vec<u8>> {
    let mut patch = Vec::new();
    Bsdiff::new(source, target)
        .compare(io::Cursor::new(&mut patch))?;
    Ok(patch)
}
```

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

### SMALL_MATCH Constant

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/constant.SMALL_MATCH.html

Defines the default threshold for determining small exact matches.

```APIDOC
## Constant SMALL_MATCH

### Summary
```rust
pub const SMALL_MATCH: usize = 12;
```

### Description
Default threshold to determine small exact match.
```

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

### Bsdiff::source

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/struct.Bsdiff.html

Sets the source data for the bsdiff operation.

```APIDOC
## pub fn source(self, source: &'s [u8]) -> Self

### Description
Set the source data.

### Parameters

* **source** (&'s [u8]) - The source data slice.

### Returns

* Self - The modified Bsdiff configuration instance.
```

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

### Apply Patch

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Applies the patch to the source data and writes the result to the target stream. The source is treated as a flat byte slice, and random access is discouraged due to potential performance issues.

```rust
pub fn apply<T: Write>(self, source: &[u8], target: T) -> Result<u64> {
    let delta_min = Ord::min(self.delta_min, self.buffer_size);
    let ctx = Context::new(self.patch, source, target, self.buffer_size, delta_min);
    ctx.apply()
}
```

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

### Control Struct

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/utils.rs.html

Represents a single bsdiff control instruction, detailing the number of bytes to add, copy, and the seek offset.

```APIDOC
/// Single bsdiff control instruction.
#[derive(Debug)]
pub struct Control {
    pub add: u64,
    pub copy: u64,
    pub seek: i64,
}
```

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

### Apply a Patch to Source Data

Source: https://docs.rs/qbsdiff/latest/qbsdiff/index.html

Applies a given patch to a source byte slice to produce the target byte vector. This function uses Bspatch for the patching process.

```rust
use std::io;
use qbsdiff::Bspatch;

fn bspatch(source: &[u8], patch: &[u8]) -> io::Result<Vec<u8>> {
    let patcher = Bspatch::new(patch)?;
    let mut target = Vec::new();
    // To preallocate target:
    //Vec::with_capacity(patcher.hint_target_size() as usize);
    patcher.apply(source, io::Cursor::new(&mut target))?;
    Ok(target)
}
```

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

### Default bzip2 Compression Level

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/constant.COMPRESSION_LEVEL.html

This constant specifies the default compression level for bzip2 when used by the qbsdiff library. It is set to 6.

```rust
pub const COMPRESSION_LEVEL: u32 = 6;
```

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

### Seek Source Cursor

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Moves the cursor position within the source data by a specified offset.

```APIDOC
## fn seek(&mut self, offset: i64) -> Result<()>
```

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

### BUFFER_SIZE Constant

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/constant.BUFFER_SIZE.html

This constant represents the default buffer size used in the bspatch operations. It is defined as a public constant within the qbsdiff::bspatch module.

```APIDOC
## Constant BUFFER_SIZE

### Description
Default buffer size.

### Value
`pub const BUFFER_SIZE: usize = 131072;`
```

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

### Read Exact or EOF Utility

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

A helper function to read exactly `buf.len()` bytes from a reader or until EOF is encountered. Returns the number of bytes read. Handles interrupted reads.

```rust
fn read_exact_or_eof<R: Read>(r: &mut R, buf: &mut [u8]) -> Result<usize> {
    let mut cnt = 0;
    while cnt < buf.len() {
        match r.read(&mut buf[cnt..]) {
            Ok(0) => break,
            Ok(n) => cnt += n,
            Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
            Err(e) => return Err(e),
        }
    }
    if cnt != 0 && cnt != buf.len() {
        Err(Error::new(ErrorKind::UnexpectedEof, "failed to fill whole buffer"))
    } else {
        Ok(cnt)
    }
}
```

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

### Bsdiff::parallel_scheme

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/struct.Bsdiff.html

Configures the parallel searching scheme for delta compression. The default is `ParallelScheme::Never`.

```APIDOC
## pub fn parallel_scheme(self, parallel_scheme: ParallelScheme) -> Self

### Description
Set parallel searching scheme (default is `ParallelScheme::Never`). Chunk size or thread number should not be zero, or it would automatically choose a proper number instead.

Considering that small chunk size of each parallel job may lead to bad patch quality, the chunk size is forced to be no less than 256 KiB internally.

### Parameters

* **parallel_scheme** (ParallelScheme) - The parallel searching scheme to use.

### Returns

* Self - The modified Bsdiff configuration instance.
```

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

### TryInto Trait

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/struct.Bsdiff.html

The TryInto trait provides a convenient way to perform fallible conversions using the `try_into` method. It is typically implemented when TryFrom is implemented.

```APIDOC
## impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

## type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

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

Performs the conversion.
```

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

### Bspatch::buffer_size

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/struct.Bspatch.html

Sets the main copy buffer size, which also serves as the write buffer to the target stream. A larger buffer can improve writing performance for unbuffered streams.

```APIDOC
## pub fn buffer_size(self, bs: usize) -> Self

### Description
Set the main copy buffer size, (`bs > 128`, default is `BUFFER_SIZE`).
This is also the write buffer to target stream. A relative big buffer (usually 128k) will speed up writing process if the target stream is unbuffered (e.g. `std::fs::File`).

### Parameters
* `bs`: The desired buffer size in bytes. Must be greater than 128.

### Returns
Returns `self` to allow chaining configuration.
```

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

### Seek in Source Data

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Moves the cursor within the source data by a specified offset. This is used to position the source for copying data.

```rust
fn seek(&mut self, offset: i64) -> Result<()> {
        self.source.seek(SeekFrom::Current(offset)).map(drop)
    }
```

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

### Define Default Buffer Size

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/constant.BUFFER_SIZE.html

This constant specifies the default buffer size used for patch operations. It is a public constant accessible for use or reference.

```rust
pub const BUFFER_SIZE: usize = 131072;
```

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

### Copy Extra Data

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Copies extra data from the patch file to the target. Handles buffering and writing in chunks.

```APIDOC
## fn copy(&mut self, count: u64) -> Result<()>
```

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

### COMPRESSION_LEVEL

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/constant.COMPRESSION_LEVEL.html

This constant represents the default bzip2 compression level. It is set to 6.

```APIDOC
## Constant COMPRESSION_LEVEL

### Summary
```
pub const COMPRESSION_LEVEL: u32 = 6;
```

### Description
Default bzip2 compression level.
```

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

### BUFFER_SIZE Constant

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/constant.BUFFER_SIZE.html

This constant represents the default buffer size used during delta calculations. It is set to 4096.

```APIDOC
## Constant BUFFER_SIZE

### Summary
```rust
pub const BUFFER_SIZE: usize = 4096;
```

### Description
Default buffer size for delta calculation.
```

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

### Write Patch Header

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Writes the header information for the bsdiff patch file. This includes magic bytes, control data size, delta data size, and target size.

```rust
    // Write header (BSDIFF4_MAGIC, control size, delta size, target size).
    let mut header = [0; 32];
    let csize = bz_ctrls.len() as u64;
    let dsize = bz_delta.len() as u64;
    let esize = bz_extra.len() as u64;
    let tsize = target.len() as u64;
    header[0..8].copy_from_slice(BSDIFF4_MAGIC);
    encode_int(csize as i64, &mut header[8..16]);
    encode_int(dsize as i64, &mut header[16..24]);
    encode_int(tsize as i64, &mut header[24..32]);
    patch.write_all(&header[..])?;
```

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

### DELTA_MIN Constant Definition

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bspatch/constant.DELTA_MIN.html

This constant specifies the default initial size for the delta calculation buffer. It is used internally by the bspatch algorithm.

```rust
pub const DELTA_MIN: usize = 32768;
```

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

### Bsdiff::target

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/struct.Bsdiff.html

Sets the target data for the bsdiff operation.

```APIDOC
## pub fn target(self, target: &'t [u8]) -> Self

### Description
Set the target data.

### Parameters

* **target** (&'t [u8]) - The target data slice.

### Returns

* Self - The modified Bsdiff configuration instance.
```

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

### Calculate Ceiling Division

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Helper function to calculate the ceiling of a division. Used for determining parallel chunk sizes.

```rust
#[inline]
fn div_ceil(x: usize, y: usize) -> usize {
    if x % y == 0 {
        x / y
    } else {
        x / y + 1
    }
}
```

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

### Read Control Data

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bspatch.rs.html

Reads the next control information (add, copy, seek) from the patch file. Returns None if the end of the patch file is reached.

```APIDOC
## fn next(&mut self) -> Option<Result<Control>>
```

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

### Configure Mismatch Count in bsdiff

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Sets the minimum number of mismatches to consider for a match. Ensures the value is at least 1.

```rust
fn mismatch_count(mut self, mut mismatch_count: usize) -> Self {
        if mismatch_count < 1 {
            mismatch_count = 1;
        }
        self.mismatch_count = mismatch_count;
        self
    }
```

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

### Encode Integer to Byte Slice

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/utils.rs.html

Encodes a signed 64-bit integer into a mutable byte slice using little-endian byte order. Supports the bsdiff format for representing negative numbers.

```rust
use byteorder::{ByteOrder, LE};

/// Encodes integer.
#[inline]
pub fn encode_int(x: i64, b: &mut [u8]) {
    if x < 0 {
        LE::write_u64(b, x.wrapping_neg() as u64 | (1 << 63));
    } else {
        LE::write_u64(b, x as u64);
    }
}
```

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

### BUFFER_SIZE Constant Definition

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/constant.BUFFER_SIZE.html

This constant specifies the default buffer size for delta calculations. It is set to 4096 bytes.

```rust
pub const BUFFER_SIZE: usize = 4096;
```

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

### Bsdiff::compression_level

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/struct.Bsdiff.html

Sets the bzip2 compression level, ranging from 0 to 9. The default is `COMPRESSION_LEVEL`.

```APIDOC
## pub fn compression_level(self, compression_level: u32) -> Self

### Description
Set the compression level of bzip2 (in range `0..=9`, default is `COMPRESSION_LEVEL`).

The fastest/default compression level is usually good enough. In contrast, patch files produced with the best level appeared slightly bigger in many test cases.

### Parameters

* **compression_level** (u32) - The bzip2 compression level (0-9).

### Returns

* Self - The modified Bsdiff configuration instance.
```

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

### Bsdiff::buffer_size

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/struct.Bsdiff.html

Sets the buffer size for delta calculation. Must be at least 128, with a default of `BUFFER_SIZE`.

```APIDOC
## pub fn buffer_size(self, buffer_size: usize) -> Self

### Description
Set the buffer size for delta calculation (`buffer_size >= 128`, default is `BUFFER_SIZE`).

### Parameters

* **buffer_size** (usize) - The buffer size for delta calculation.

### Returns

* Self - The modified Bsdiff configuration instance.
```

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

### Bsdiff::parallel_scheme

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Configures the parallel searching scheme for bsdiff. Automatically adjusts if zero values are provided for ChunkSize or NumJobs.

```APIDOC
## Bsdiff::parallel_scheme

### Description
Configures the parallel searching scheme for bsdiff. If `ChunkSize` or `NumJobs` is set to zero, it defaults to `ParallelScheme::Auto`. The chunk size is internally enforced to be at least 256 KiB to maintain patch quality.

### Signature
```rust
pub fn parallel_scheme(mut self, parallel_scheme: ParallelScheme) -> Self
```

### Parameters
- **parallel_scheme** (`ParallelScheme`): The desired parallel processing scheme (`Never`, `Auto`, `ChunkSize(usize)`, `NumJobs(usize)`).

### Returns
- `Self`: The modified `Bsdiff` instance.
```

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

### Configure Long Suffix Threshold in bsdiff

Source: https://docs.rs/qbsdiff/latest/src/qbsdiff/bsdiff.rs.html

Sets the threshold for scanning long suffixes in target data. Ensures the value is at least 64 to control linear scanning versus skimming.

```rust
fn long_suffix(mut self, mut long_suffix: usize) -> Self {
        if long_suffix < 64 {
            long_suffix = 64;
        }
        self.long_suffix = long_suffix;
        self
    }
```

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

### TryFrom Trait

Source: https://docs.rs/qbsdiff/latest/qbsdiff/bsdiff/struct.Bsdiff.html

The TryFrom trait allows for fallible conversions from one type to another. The `try_from` function attempts the conversion and returns a Result.

```APIDOC
## type Error = Infallible

The type returned in the event of a conversion error.

## fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
```
Tokens:
Raw