Struct ipworkszip::Zstd

Properties   Methods   Events   Config Settings   Errors  

The Zstd struct implements a Zstandard (zstd) compressor and decompressor.

Syntax

ipworkszip::Zstd

Remarks

The Zstd struct is compliant with RFC 8878, the Zstandard Compression Format specification. Data compressed by the struct can be decompressed by any standard zstd-compatible tool or library, and the struct can in turn decompress data produced by any standard zstd encoder.

The compression_level property selects the compression level to use, from 1 (fastest) to 22 (most compact). The struct favors speed and simplicity over maximum compression, so at very high levels it may not reach the same compression ratio as the reference zstd encoder; however, the resulting data is still fully standard and can be decompressed by any zstd decoder.

Data may be operated on in multiple ways as discussed below.

Compression and Decompression Streams

The get_decompression_stream and get_compression_stream methods are used to retrieve streams that read or write compressed data, as appropriate. The underlying stream should be passed to either method as a parameter.

CompressBlock and DecompressBlock

The compress_block and decompress_block methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the output_data property is not applicable. Instead, data are made available via the on_compressed_data and on_decompressed_data events.

If all data is available ahead of time, the compress_data and decompress_data methods may be called instead.

Compress Data

The input_data property should be set to the current block to be compressed. Next, the compress_block method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to true. For all other blocks, it must remain false.

During compression, the on_compressed_data event will fire with the compressed data. Note that this event may not fire for every call to compress_block due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the on_compressed_data event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when compressing block data.

Decompress Data

The input_data property should be set to the current block to be decompressed. Next, the decompress_block method should be called to decompress the current block.

During decompression, the on_decompressed_data event will fire with the decompressed data. Note that this event may not fire for every call to decompress_block due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the on_decompressed_data event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when decompressing block data.

CompressData and DecompressData

The compress_data and decompress_data methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the input_data property before calling either method.

To compress and decompress data in blocks (chunks), refer to the compress_block and decompress_block methods.

Compress Data

The input_data property should be set to the decompressed data. This should be the entire data to be compressed. Next, the compress_data method should be called, after which the output_data property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to output_data, the compressed data may also be accumulated within the on_compressed_data event.

Decompress Data

The input_data property should be set to the compressed data. This should be the entire data to be decompressed. Next, the decompress_data method should be called, after which the output_data property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to output_data, the decompressed data may also be accumulated within the on_decompressed_data event.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksZip. Due to this, the Zstd struct cannot be disposed of automatically. Please, call the dispose(&self) method of Zstd when you have finished using the instance.

Property List

---

The following is the full list of the properties of the struct with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the struct with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the struct with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the struct with short descriptions. Click on the links for further details.

close_base_stream property (Zstd Struct)

Whether or not to close the underlying stream.

Syntax

fn close_base_stream(&self) -> Result<bool, IPWorksZipError> 
fn set_close_base_stream(&self, value : bool) ->  Option<IPWorksZipError> 

Default Value

true

Remarks

This property controls whether streams created via the get_compression_stream and get_decompression_stream methods will close their underlying streams when their Close method is invoked.

When enabled, the underlying streams are closed; otherwise, they will remain open.

Data Type

bool

compression_level property (Zstd Struct)

The compression level to use.

Syntax

fn compression_level(&self) -> Result<i32, IPWorksZipError> 
fn set_compression_level(&self, value : i32) ->  Option<IPWorksZipError> 

Default Value

4

Remarks

This property dictates the compression level to use, from 1 to 22. Higher values will cause the struct to compress better; lower values will cause the struct to compress faster.

Note that some levels may produce functionally identical results to a neighboring level. A higher level will never compress worse than a lower one, but it is not guaranteed to compress better at every step.

Data Type

i32

input_data property (Zstd Struct)

The data to compress or decompress.

Syntax

fn input_data(&self) -> Result<Vec<u8>, IPWorksZipError> 
fn set_input_data(&self, value : Vec<u8>) ->  Option<IPWorksZipError> 
fn set_input_data_ref(&self, value : &[u8]) ->  Option<IPWorksZipError> 

Default Value

""

Remarks

This property specifies the data to compress or decompress.

When decompressing, this should be set to the compressed data before the decompress_data or decompress_block methods are called.

When compressing, this should be set to the decompressed data before the compress_data or compress_block methods are called.

Note that this property is not automatically cleared after each operation when performing operations on multiple chunks of data.

Data Type

Vec<u8>

output_data property (Zstd Struct)

The output data after compression or decompression.

Syntax

fn output_data(&self) -> Result<Vec<u8>, IPWorksZipError> 

Default Value

""

Remarks

This property holds the compressed or decompressed data after the compress_data or decompress_data methods are called.

This property is not applicable when calling the compress_block or decompress_block methods.

This property is read-only.

Data Type

Vec<u8>

compress_block method (Zstd Struct)

Compresses a block of data.

Syntax

fn compress_block(&self, last_block : bool) -> Result<(), IPWorksZipError>

Remarks

This method compresses the block of data specified by the input_data property.

The compress_block and decompress_block methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the output_data property is not applicable. Instead, data are made available via the on_compressed_data and on_decompressed_data events.

If all data is available ahead of time, the compress_data and decompress_data methods may be called instead.

Compress Data

The input_data property should be set to the current block to be compressed. Next, the compress_block method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to true. For all other blocks, it must remain false.

During compression, the on_compressed_data event will fire with the compressed data. Note that this event may not fire for every call to compress_block due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the on_compressed_data event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when compressing block data.

Decompress Data

The input_data property should be set to the current block to be decompressed. Next, the decompress_block method should be called to decompress the current block.

During decompression, the on_decompressed_data event will fire with the decompressed data. Note that this event may not fire for every call to decompress_block due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the on_decompressed_data event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when decompressing block data.

compress_data method (Zstd Struct)

Compresses the specified data.

Syntax

fn compress_data(&self) -> Result<(), IPWorksZipError>

Remarks

This method compresses the data specified by the input_data property. After calling this method, the output_data property holds the compressed data.

The compress_data and decompress_data methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the input_data property before calling either method.

To compress and decompress data in blocks (chunks), refer to the compress_block and decompress_block methods.

Compress Data

The input_data property should be set to the decompressed data. This should be the entire data to be compressed. Next, the compress_data method should be called, after which the output_data property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to output_data, the compressed data may also be accumulated within the on_compressed_data event.

Decompress Data

The input_data property should be set to the compressed data. This should be the entire data to be decompressed. Next, the decompress_data method should be called, after which the output_data property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to output_data, the decompressed data may also be accumulated within the on_decompressed_data event.

config method (Zstd Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) -> Result<String, IPWorksZipError>

Remarks

config is a generic method available in every struct. It is used to set and retrieve configuration settings for the struct.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

decompress_block method (Zstd Struct)

Decompresses a block of data.

Syntax

fn decompress_block(&self) -> Result<(), IPWorksZipError>

Remarks

This method decompresses the block of data specified by the input_data property.

The compress_block and decompress_block methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the output_data property is not applicable. Instead, data are made available via the on_compressed_data and on_decompressed_data events.

If all data is available ahead of time, the compress_data and decompress_data methods may be called instead.

Compress Data

The input_data property should be set to the current block to be compressed. Next, the compress_block method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to true. For all other blocks, it must remain false.

During compression, the on_compressed_data event will fire with the compressed data. Note that this event may not fire for every call to compress_block due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the on_compressed_data event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when compressing block data.

Decompress Data

The input_data property should be set to the current block to be decompressed. Next, the decompress_block method should be called to decompress the current block.

During decompression, the on_decompressed_data event will fire with the decompressed data. Note that this event may not fire for every call to decompress_block due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the on_decompressed_data event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when decompressing block data.

decompress_data method (Zstd Struct)

Decompresses the specified data.

Syntax

fn decompress_data(&self) -> Result<(), IPWorksZipError>

Remarks

This method decompresses the data specified by the input_data property. After calling this method, the output_data property holds the decompressed data.

The compress_data and decompress_data methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the input_data property before calling either method.

To compress and decompress data in blocks (chunks), refer to the compress_block and decompress_block methods.

Compress Data

The input_data property should be set to the decompressed data. This should be the entire data to be compressed. Next, the compress_data method should be called, after which the output_data property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to output_data, the compressed data may also be accumulated within the on_compressed_data event.

Decompress Data

The input_data property should be set to the compressed data. This should be the entire data to be decompressed. Next, the decompress_data method should be called, after which the output_data property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to output_data, the decompressed data may also be accumulated within the on_decompressed_data event.

reset method (Zstd Struct)

Resets the struct.

Syntax

fn reset(&self) -> Result<(), IPWorksZipError>

Remarks

This method is used to reset the state of the struct. All properties are set to their default values, and any open files are closed.

on_compressed_data event (Zstd Struct)

Fires with compressed data.

Syntax

// ZstdCompressedDataEventArgs carries the Zstd CompressedData event's parameters.
pub struct ZstdCompressedDataEventArgs {
  fn data(&self) -> &[u8]
}

// ZstdCompressedDataEvent defines the signature of the Zstd CompressedData event's handler function.
pub trait ZstdCompressedDataEvent {
  fn on_compressed_data(&self, sender : Zstd, e : &mut ZstdCompressedDataEventArgs);
}

impl <'a> Zstd<'a> {
  pub fn on_compressed_data(&self) -> &'a dyn ZstdCompressedDataEvent;
  pub fn set_on_compressed_data(&mut self, value : &'a dyn ZstdCompressedDataEvent);
  ...
}

Remarks

This event is fired one or more times as compressed data become available when the compress_data or compress_block methods are called.

Data holds the current block of compressed data.

on_decompressed_data event (Zstd Struct)

Fires with decompressed data.

Syntax

// ZstdDecompressedDataEventArgs carries the Zstd DecompressedData event's parameters.
pub struct ZstdDecompressedDataEventArgs {
  fn data(&self) -> &[u8]
}

// ZstdDecompressedDataEvent defines the signature of the Zstd DecompressedData event's handler function.
pub trait ZstdDecompressedDataEvent {
  fn on_decompressed_data(&self, sender : Zstd, e : &mut ZstdDecompressedDataEventArgs);
}

impl <'a> Zstd<'a> {
  pub fn on_decompressed_data(&self) -> &'a dyn ZstdDecompressedDataEvent;
  pub fn set_on_decompressed_data(&mut self, value : &'a dyn ZstdDecompressedDataEvent);
  ...
}

Remarks

This event is fired one or more times as decompressed data become available when the decompress_data or decompress_block methods are called.

Data holds the current block of decompressed data.

on_error event (Zstd Struct)

Fires with information about errors during data delivery.

Syntax

// ZstdErrorEventArgs carries the Zstd Error event's parameters.
pub struct ZstdErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// ZstdErrorEvent defines the signature of the Zstd Error event's handler function.
pub trait ZstdErrorEvent {
  fn on_error(&self, sender : Zstd, e : &mut ZstdErrorEventArgs);
}

impl <'a> Zstd<'a> {
  pub fn on_error(&self) -> &'a dyn ZstdErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn ZstdErrorEvent);
  ...
}

Remarks

This event is fired in case of exceptional conditions during message processing. Normally, the struct fails with an error.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Config Settings (Zstd Struct)

The struct accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

No configuration settings defined.

Base Config Settings

Trappable Errors (Zstd Struct)

Note that the streams returned by get_compression_stream and get_decompression_stream will throw standard IOExceptions in case of error.

ZipStream Errors