Struct Decoder 

pub struct Decoder<'a, S> { /* private fields */ }

Decompresses data from a seekable source.

A decoder reads compressed data from a seekable source. By default, it decompresses everything, from the first to the last frame. This can be changed via DecodeOptions or by setting the offset after initialization.

Implementations

impl<'a, S: Seekable> Decoder<'a, S>

pub fn new(src: S) -> Result<Self>

Creates a new Decoder with default parameters and src as source.

This is equivalent to calling DecodeOptions::new(src).into_decoder().

Errors

Fails if the decoder could not be created.

pub fn with_opts(opts: DecodeOptions<'a, S>) -> Result<Self>

Creates a new Decoder with the given DecodeOptions.

Errors

Fails if the decoder cannot be created.

pub fn decompress_with_prefix<'b: 'a>( &mut self, buf: &mut [u8], prefix: Option<&'b [u8]>, ) -> Result<usize>

Decompresses data from the internal source.

Call this repetetively to fill buf with decompressed data. Returns the number of bytes written to buf. Decompression is finished when no more bytes are written to buf.

If a prefix is passed, it will be referenced at the beginning of every frame. Referencing a raw content prefix has almost no CPU nor memory cost.

Errors

If decompression fails or any parameter is invalid.

impl<S: Seekable> Decoder<'_, S>

pub fn decompress(&mut self, buf: &mut [u8]) -> Result<usize>

Decompresses data from the internal source.

Call this repetetively to fill buf with decompressed data. Returns the number of bytes written to buf. Decompression is finished when no more bytes are written to buf.

Errors

If decompression fails or any parameter is invalid.

Examples

use zeekstd::Decoder;

let mut decoder = Decoder::new(seekable)?;
// Make sure `buf` is big enough to hold all decompressed data
let mut buf = [0u8; 128];
let mut progress = 0;

// Decompress in a loop until no more bytes are written to `buf`
loop {
    let n = decoder.decompress(&mut buf[progress..])?;
    if n == 0 {
        break;
    }
    progress += n;
}

pub fn reset(&mut self)

Resets the current decompresion status.

This resets the internal decompression context as well as decompression offset and limit. The next decompression operation after this function will start from the beginning of the seekable source.

Examples

use zeekstd::Decoder;

let mut decoder = Decoder::new(seekable)?;
decoder.reset();

assert_eq!(decoder.read_compressed(), 0);
assert_eq!(decoder.offset(), 0);
assert_eq!(decoder.offset_limit(), decoder.seek_table().size_decomp());

pub fn set_lower_frame(&mut self, index: u32) -> Result<u64>

Sets the decompression offset to the beginning of the frame at index.

This has the same effect as calling Self::set_offset with the decompressed start position of the frame at index.

Errors

When the the passed frame index is out of range.

pub fn set_upper_frame(&mut self, index: u32) -> Result<u64>

Sets the limit for the decompression offset to the end of the frame at index.

This has the same effect as calling Self::set_offset_limit with the decompressed end position of the frame at index. The current decompression state will not be reset, it is possible to change the upper frame in the middle of a decompression operation.

Errors

When the the passed frame index is out of range.

pub fn set_offset(&mut self, offset: u64) -> Result<()>

Sets the decompression offset.

The offset is the position in the decompressed data of the seekable source from which decompression starts. If possible, the decoder will continue decompression from the current internal state.

Note: If the passed offset is not the beginning of a frame, the decoder will perform a dummy decompression from the beginning of the frame up to the offset position.

Errors

When the passed offset is out of range.

pub fn set_offset_limit(&mut self, limit: u64) -> Result<()>

Sets a limit for the decompression offset.

The limit is the position in the decompressed data of the seekable source at which decompression stops. This does not reset the current decompression state, the limit can be changed in the middle of a decompression operation without interrupting the ongoing operation. It is possible to set a limit that is lower than the current decompression offset, however, it will lead to any decompression operation making no progress, i.e. it will produce zero decompressed bytes.

Note: The decoder will immediately stop decompression at the specified limit. The frame checksum of the last decompressed frame will not be verified, if the limit isn’t at the end of a frame.

Errors

When the passed limit is out of range.

pub fn read_compressed(&self) -> u64

Gets the total number of compressed bytes read since the last reset.

pub fn seek_table(&self) -> &SeekTable

Gets a reference to the internal SeekTable.

pub fn offset(&self) -> u64

Gets the current offset of this decoder.

pub fn offset_limit(&self) -> u64

Gets the offset limit of this decoder.

Trait Implementations

impl<S: Seekable> Read for Decoder<'_, S>

Available on crate feature std only.

Allows to read decompressed data from a Decoder.

Examples

use std::{fs::File, io};
use zeekstd::Decoder;

let seekable = File::open("seekable.zst")?;
let mut output = File::create("output")?;
let mut decoder = Decoder::new(seekable)?;
io::copy(&mut decoder, &mut output)?;

Similar to regular decompression, this supports frame limits.

decoder.set_lower_frame(2)?;
decoder.set_upper_frame(3)?;
io::copy(&mut decoder, &mut io::stdout())?;

And also arbitrary byte offsets.

decoder.set_offset(123)?;
decoder.set_offset_limit(456)?;
io::copy(&mut decoder, &mut io::stdout())?;

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

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

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

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

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

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

🔬This is a nightly-only experimental API. (read_array)

Read and return a fixed array of bytes from this source.

impl<S: Seekable> Seek for Decoder<'_, S>

Available on crate feature std only.

Allows to set the offset of a Decoder via seeking.

Examples

use std::io::{Seek, SeekFrom};
use zeekstd::Decoder;

let mut decoder = Decoder::new(seekable)?;
decoder.seek(SeekFrom::Start(7))?;

assert_eq!(decoder.offset(), 7);

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬This is a nightly-only experimental API. (seek_stream_len)

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

Returns the current seek position from the start of the stream.

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

Seeks relative to the current position.