Struct zstd::stream::write::Encoder

source ·
pub struct Encoder<'a, W: Write> { /* private fields */ }
Expand description

An encoder that compress and forward data to another writer.

This allows to compress a stream of data (good for files or heavy network stream).

Don’t forget to call finish() before dropping it!

Alternatively, you can call auto_finish() to use an AutoFinishEncoder that will finish on drop.

Note: The zstd library has its own internal input buffer (~128kb).

Implementations§

source§

impl<W: Write> Encoder<'static, W>

source

pub fn new(writer: W, level: i32) -> Result<Self>

Creates a new encoder.

level: compression level (1-22).

A level of 0 uses zstd’s default (currently 3).

source

pub fn with_dictionary(writer: W, level: i32, dictionary: &[u8]) -> Result<Self>

Creates a new encoder, using an existing dictionary.

(Provides better compression ratio for small files, but requires the dictionary to be present during decompression.)

A level of 0 uses zstd’s default (currently 3).

source§

impl<'a, W: Write> Encoder<'a, W>

source

pub fn with_context(writer: W, context: &'a mut CCtx<'static>) -> Self

Creates an encoder that uses the provided context to compress a stream.

source

pub fn with_prepared_dictionary<'b>( writer: W, dictionary: &EncoderDictionary<'b>, ) -> Result<Self>
where 'b: 'a,

Creates a new encoder, using an existing prepared EncoderDictionary.

(Provides better compression ratio for small files, but requires the dictionary to be present during decompression.)

source

pub fn with_ref_prefix<'b>( writer: W, level: i32, ref_prefix: &'b [u8], ) -> Result<Self>
where 'b: 'a,

Creates a new encoder, using a ref prefix

source

pub fn auto_finish(self) -> AutoFinishEncoder<'a, W>

Returns a wrapper around self that will finish the stream on drop.

source

pub fn on_finish<F: FnMut(Result<W>)>(self, f: F) -> AutoFinishEncoder<'a, W, F>

Returns an encoder that will finish the stream on drop.

Calls the given callback with the result from finish(). This runs during drop so it’s important that the provided callback doesn’t panic.

source

pub fn get_ref(&self) -> &W

Acquires a reference to the underlying writer.

source

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

Acquires a mutable reference to the underlying writer.

Note that mutation of the writer may result in surprising results if this encoder is continued to be used.

source

pub fn finish(self) -> Result<W>

Required: Finishes the stream.

You need to finish the stream when you’re done writing, either with this method or with try_finish(self).

This returns the inner writer in case you need it.

To get back self in case an error happened, use try_finish.

Note: If you don’t want (or can’t) call finish() manually after writing your data, consider using auto_finish() to get an AutoFinishEncoder.

source

pub fn try_finish(self) -> Result<W, (Self, Error)>

Required: Attempts to finish the stream.

You need to finish the stream when you’re done writing, either with this method or with finish(self).

This returns the inner writer if the finish was successful, or the object plus an error if it wasn’t.

write on this object will panic after try_finish has been called, even if it fails.

source

pub fn do_finish(&mut self) -> Result<()>

Attempts to finish the stream.

You need to finish the stream when you’re done writing, either with this method or with finish(self).

source

pub fn recommended_input_size() -> usize

Return a recommendation for the size of data to write at once.

source

pub fn set_parameter(&mut self, parameter: CParameter) -> Result<()>

Sets the given zstd compression parameter.

source

pub fn set_pledged_src_size(&mut self, size: Option<u64>) -> Result<()>

Sets the expected size of the input.

This affects the compression effectiveness.

It is an error to give an incorrect size (an error will be returned when closing the stream if the size does not match what was pledged).

Giving a None size means the size is unknown (this is the default).

source

pub fn include_checksum(&mut self, include_checksum: bool) -> Result<()>

Controls whether zstd should include a content checksum at the end of each frame.

source

pub fn include_dictid(&mut self, include_dictid: bool) -> Result<()>

Enables or disables storing of the dict id.

Defaults to true. If false, the behaviour of decoding with a wrong dictionary is undefined.

source

pub fn include_contentsize(&mut self, include_contentsize: bool) -> Result<()>

Enables or disabled storing of the contentsize.

Note that this only has an effect if the size is given with set_pledged_src_size.

source

pub fn long_distance_matching( &mut self, long_distance_matching: bool, ) -> Result<()>

Enables or disables long-distance matching

source

pub fn set_target_cblock_size(&mut self, target_size: Option<u32>) -> Result<()>

Sets the target size for compressed blocks.

A lower block size may result in slightly lower speed (~2%) and compression ratio (~0.1%), but may decrease end-to-end latency in low-bandwidth environments (time to first decompressed byte).

No value, or a value of zero, results in no contraint for the block sizes.

source

pub fn window_log(&mut self, log_distance: u32) -> Result<()>

Sets the maximum back-reference distance.

The actual maximum distance is going to be 2^log_distance.

Note that decompression will need to use at least the same setting.

Trait Implementations§

source§

impl<'a, W: Write> Write for Encoder<'a, W>

source§

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

Write a buffer into this writer, returning how many bytes were written. Read more
source§

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
1.36.0 · source§

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

Like write, except that it writes from a slice of buffers. Read more
source§

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)
Determines if this Writer has an efficient write_vectored implementation. Read more
1.0.0 · source§

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

Attempts to write an entire buffer into this writer. Read more
source§

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

🔬This is a nightly-only experimental API. (write_all_vectored)
Attempts to write multiple buffers into this writer. Read more
1.0.0 · source§

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

Writes a formatted string into this writer, returning any error encountered. Read more
1.0.0 · source§

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

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

Auto Trait Implementations§

§

impl<'a, W> Freeze for Encoder<'a, W>
where W: Freeze,

§

impl<'a, W> RefUnwindSafe for Encoder<'a, W>
where W: RefUnwindSafe,

§

impl<'a, W> Send for Encoder<'a, W>
where W: Send,

§

impl<'a, W> Sync for Encoder<'a, W>
where W: Sync,

§

impl<'a, W> Unpin for Encoder<'a, W>
where W: Unpin,

§

impl<'a, W> !UnwindSafe for Encoder<'a, W>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

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.
source§

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

Performs the conversion.