Struct Decoder 

pub struct Decoder { /* private fields */ }

Immutable, reusable decompressor configuration.

Implementations

impl Decoder

pub fn builder() -> DecoderBuilder

Creates a builder initialized with the DecoderBuilder defaults.

pub fn decode<R, W>( &self, source: &R, output: &mut W, ) -> Result<DecodeReport, DecodeError>

where R: ReadAt + ?Sized, W: Write,

Decodes the selected container into output and performs all available integrity checks.

The writer is used only by the calling thread and need not implement Send.

The compressed source must keep its length and contents stable for the duration of this call. On error, output can contain a verified prefix; writes are not rolled back.

pub fn analyze<R>(&self, source: &R) -> Result<Analysis, DecodeError>

where R: ReadAt + ?Sized,

Analyzes every DEFLATE block using bounded default retention limits.

The walk is sequential because each block depends on its predecessor history. It validates the same container headers, checksums, sizes, and trailing-data rules as decoding while retaining only one 32 KiB output window. Use Self::analyze_with_options to change result limits or retain individual predecessor-window references.

Errors

Returns DecodeError for input, framing, DEFLATE, integrity, output expectation, or typed analysis-budget failures.

pub fn analyze_with_options<R>( &self, source: &R, options: AnalyzeOptions, ) -> Result<Analysis, DecodeError>

where R: ReadAt + ?Sized,

Analyzes every DEFLATE block with explicit retention limits.

Detailed back-reference retention is input-wide. Exact summaries remain available when that budget is exhausted, and each block records its omitted detail count.

Errors

Returns DecodeError for input, framing, DEFLATE, integrity, output expectation, or typed analysis-budget failures.

pub fn analyze_stream<R>(&self, source: R) -> Result<Analysis, DecodeError>

where R: Read,

Analyzes a non-seekable compressed stream with default limits.

Input and decompressed history remain bounded; unlike positional analysis, a stream cannot be re-read if the caller later requests more retained detail.

Errors

Returns DecodeError for input, framing, DEFLATE, integrity, output expectation, or typed analysis-budget failures.

pub fn analyze_stream_with_options<R>( &self, source: R, options: AnalyzeOptions, ) -> Result<Analysis, DecodeError>

where R: Read,

Analyzes a non-seekable compressed stream with explicit limits.

Errors

Returns DecodeError for input, framing, DEFLATE, integrity, output expectation, or typed analysis-budget failures.

pub fn decode_with_index<R, W>( &self, source: &R, output: &mut W, options: IndexOptions, ) -> Result<IndexedDecodeReport, IndexingError>

where R: ReadAt + ?Sized, W: Write,

Decodes the selected container while collecting a random-access index.

Index construction is explicit per operation. Ordinary Self::decode calls therefore retain their small Copy report and perform no checkpoint-window work. On error, output can contain a verified prefix; writes are not rolled back.

Errors

Returns IndexingError::Decode for source, framing, DEFLATE, verification, output, or limit failures, and IndexingError::Index when a checkpoint window cannot be stored or the final index is invalid.

pub fn decode_from_index<R, W>( &self, source: &R, output: &mut W, index: &DeflateIndex, ) -> Result<DecodeReport, IndexDecodeError>

where R: ReadAt + ?Sized, W: Write,

Decodes through a caller-supplied random-access index.

Every indexed span runs plain zlib-rs inflation from an authoritative checkpoint. The index is validated against the selected format and source before workers start; each worker must then reach the next checkpoint’s exact compressed-bit and decompressed-byte offsets. Invalid or mismatched indexes are errors and never silently select an unindexed fallback.

Worker output is handed off in bounded chunks, so a sparse index does not cause an entire decompressed span to be allocated. Empty gzip members remain explicit spans and are fully verified.

When DecoderBuilder::count_lines is enabled, imported per-checkpoint and total line counters are recomputed from final ordered output and a mismatch is rejected. Without line counting, line metadata remains caller-supplied navigation data and is not authenticated.

Examples

use rapidgzip_core::{Decoder, DeflateIndex};
use std::fs::File;
use std::io;

let mut serialized = File::open("reads.fastq.gz.rgzidx")?;
let index = DeflateIndex::read_native(&mut serialized)?;
let source = File::open("reads.fastq.gz")?;
let report = Decoder::default().decode_from_index(
    &source,
    &mut io::sink(),
    &index,
)?;
assert!(report.member_count >= 1);

Errors

Returns IndexDecodeError::Index for invalid or source-mismatched metadata, IndexDecodeError::FormatMismatch when the builder and index select different containers, or IndexDecodeError::Decode for input, DEFLATE, verification, output, limit, or worker failures.

pub fn reader<R>(&self, source: R) -> Result<DecoderReader, DecodeError>

where R: ReadAt + 'static,

Starts decoding an owned positional source and returns Read + Send decompressed output.

Initial selected framing is validated before the background coordinator is spawned. Later decoding failures are returned as std::io::Error values by std::io::Read, or as DecodeError by DecoderReader::finish.

pub fn reader_with_index<R>( &self, source: R, options: IndexOptions, ) -> Result<IndexingDecoderReader, DecodeError>

where R: ReadAt + 'static,

Starts positional decoding with index construction and returns owned Read + Send decompressed output.

The returned IndexingDecoderReader exposes the same telemetry and dynamic worker controls as DecoderReader. Its index becomes available only after verified EOF, either through IndexingDecoderReader::report or IndexingDecoderReader::finish.

Errors

Returns an initial source or framing failure. Later decode and index failures are reported by Read::read and preserved in typed form by IndexingDecoderReader::finish.

pub fn reader_from_index<R>( &self, source: R, index: Arc<DeflateIndex>, ) -> Result<DecoderReader, IndexDecodeError>

where R: ReadAt + 'static,

Starts full-stream decoding through an existing index and returns owned Read + Send output.

The Arc permits a large index and its stored windows to be shared with the background coordinator without cloning them. Validation is completed before any thread is spawned. Later failures are returned by Read::read and preserved by DecoderReader::finish. The reader’s crate::DecoderHandle exposes the same telemetry and dynamic worker ceiling as every other positional parallel path.

Examples

use rapidgzip_core::{Decoder, DeflateIndex};
use std::fs::File;
use std::io;
use std::sync::Arc;

let mut serialized = File::open("reads.fastq.gz.rgzidx")?;
let index = Arc::new(DeflateIndex::read_native(&mut serialized)?);
let mut reader = Decoder::default().reader_from_index(
    File::open("reads.fastq.gz")?,
    index,
)?;
io::copy(&mut reader, &mut io::sink())?;
reader.finish()?;

Errors

Returns a strict index, format, or initial source validation error, or a coordinator-thread creation failure.

pub fn decode_stream<R, W>( &self, source: R, output: &mut W, ) -> Result<DecodeReport, DecodeError>

where R: Read, W: Write,

Decodes the selected format from a non-seekable source.

This is the push interface for input that cannot be read positionally, such as standard input, a FIFO, a process substitution, or a socket. It mirrors Decoder::decode, including the writer being used only by the calling thread.

Validation is identical to Decoder::decode, including gzip CRC32 and ISIZE, zlib Adler-32, raw-DEFLATE structural completion, trailing-data rejection, and configured output bounds. The source is read once in order, so decoding uses one calling thread regardless of DecoderBuilder::decoder_threads. The returned report retains the configured worker budget, just like Decoder::decode.

Input memory is bounded by one DecoderBuilder::input_page_size window; nothing is spooled.

Examples

use rapidgzip_core::Decoder;
use std::io;

let decoder = Decoder::default();
let report = decoder.decode_stream(io::stdin(), &mut io::sink())?;
println!("completed {} framing units", report.member_count);

Errors

Returns the first framing, DEFLATE, verification, input, or output-limit failure. On error, output can contain a verified prefix; writes are not rolled back.

pub fn decode_stream_with_index<R, W>( &self, source: R, output: &mut W, options: IndexOptions, ) -> Result<IndexedDecodeReport, IndexingError>

where R: Read, W: Write,

Decodes non-seekable input while collecting a coarse but valid index.

A forward-only source does not expose independently discoverable interior block boundaries, so the resulting index records gzip member starts or the single zlib/raw stream start. It can later seek a stable positional copy of the same compressed bytes.

Errors

Returns IndexingError for the same decode failures as Self::decode_stream or for index construction and validation errors.

pub fn stream_reader<R>(&self, source: R) -> Result<DecoderReader, DecodeError>

where R: Read + Send + 'static,

Starts decoding an owned non-seekable source and returns Read + Send decompressed output.

This is the pull counterpart to Decoder::decode_stream and mirrors Decoder::reader, returning the same DecoderReader so it can still be handed to a parser as Box<dyn Read + Send>.

One initial source read is used for best-effort fail-fast header validation. A short read can defer validation until std::io::Read; later failures are returned as std::io::Error values by that method, or as DecodeError by DecoderReader::finish.

DecoderReader::stats reports crate::DecoderPath::Sequential, the builder-supplied configured worker budget, an effective target of one, and zero spawned decoder or auxiliary threads. Decoding occurs in the caller’s read, so dropping the reader immediately drops the source and cannot strand a coordinator blocked on input.

Examples

use rapidgzip_core::Decoder;
use std::io::{self, Read};

let decoder = Decoder::default();
let reader = decoder.stream_reader(io::stdin())?;

// Still Read + Send, so a parser can own it.
let mut parser_input: Box<dyn Read + Send> = Box::new(reader);
io::copy(&mut parser_input, &mut io::sink())?;

Errors

Returns an input failure, or a framing failure detectable from the best-effort initial read. A short read can defer a framing failure until the returned reader is consumed.

pub fn stream_reader_with_index<R>( &self, source: R, options: IndexOptions, ) -> Result<IndexingDecoderReader, DecodeError>

where R: Read + Send + 'static,

Starts pull-driven decoding of a non-seekable source while collecting a framing-start index.

Like Self::stream_reader, this runs synchronously in the caller’s read calls and spawns no coordinator or decoder worker. The returned reader remains Read + Send and publishes the index only at verified EOF.

Errors

Returns an input failure or an initial framing failure. Later failures are returned by Read::read or IndexingDecoderReader::finish.

pub fn decode_path<P, W>( &self, path: P, output: &mut W, ) -> Result<DecodeReport, DecodeError>

where P: AsRef<Path>, W: Write,

Opens and decodes the selected format from a filesystem path.

This is the push counterpart to Decoder::open. A regular file uses positional decoding; a non-regular path accepted by File::open, such as a FIFO or character device, uses Decoder::decode_stream. The writer remains on the calling thread in both cases and need not implement Send.

Errors

Returns the first open, framing, DEFLATE, verification, input, output, or output-limit failure. On error, output can contain a verified prefix; writes are not rolled back.

pub fn open<P: AsRef<Path>>( &self, path: P, ) -> Result<DecoderReader, DecodeError>

Opens a compressed file and returns a Read + Send decompressed stream.

A regular file is owned by the returned reader and accessed positionally through every decode path. A non-regular path accepted by File::open, such as a FIFO or character device, is routed to Decoder::stream_reader instead and decoded sequentially with the same verification. Such a path previously failed, so no successful call changes behaviour.

Errors

Returns an input failure, or a framing failure detected while opening the reader. Further decoding and verification failures are returned by std::io::Read or DecoderReader::finish.

Trait Implementations

impl Clone for Decoder

fn clone(&self) -> Decoder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Decoder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Decoder

fn default() -> Self

Returns the “default value” for a type.