ZlibCompression Class Reference

Compresses and uncompresses arbitrary byte buffers using zlib. More...

#include <OpenMS/FORMAT/ZlibCompression.h>

Static Public Member Functions
static void	compressString (std::string &raw_data, std::string &compressed_data)
	Compress raw_data into compressed_data using zlib.
static void	compressData (const void *raw_data, const size_t in_length, std::string &compressed_data)
	Compress the in_length bytes pointed to by raw_data into compressed_data using zlib.
static void	uncompressData (const void *compressed_data, size_t nr_bytes, std::string &out, size_t output_size=0)
	Uncompress compressed_data using zlib.
static void	uncompressString (const std::string &in, std::string &out, size_t output_size=0)
	Convenience wrapper around uncompressData that takes a String input.

Detailed Description

Compresses and uncompresses arbitrary byte buffers using zlib.

Static utility class. All methods treat the std::string / String arguments as raw byte containers; the data is not assumed to be NUL- terminated and may contain embedded zeros.

Note

Only the raw zlib format is supported on the decompression side; gzip-framed streams are rejected.

Member Function Documentation

compressData()

static void compressData ( const void *  raw_data, const size_t  in_length, std::string &  compressed_data  )

static

Compress the in_length bytes pointed to by raw_data into compressed_data using zlib.

Parameters

[in]	raw_data	Pointer to the bytes to compress.
[in]	in_length	Length of raw_data in bytes.
[out]	compressed_data	Receives the compressed payload; any previous contents are replaced.

Exceptions

Exception::OutOfMemory	if zlib cannot allocate an output buffer of the worst-case size.
Exception::InvalidValue	if the destination buffer turns out to be too small for the compressed output.
Exception::ConversionError	if zlib reports any other failure during compression.

Referenced by Base64::encode(), and Base64::encodeIntegers().

compressString()

static void compressString ( std::string &  raw_data, std::string &  compressed_data  )

static

Compress raw_data into compressed_data using zlib.

Parameters

[in]	raw_data	Data to compress (treated as a raw byte buffer; the reference is read-only despite the non-const type).
[out]	compressed_data	Receives the compressed payload; any previous contents are replaced.

Exceptions

Exception::OutOfMemory	if zlib cannot allocate an output buffer of the worst-case size.
Exception::InvalidValue	if the destination buffer turns out to be too small for the compressed output.
Exception::ConversionError	if zlib reports any other failure during compression.

uncompressData()

static void uncompressData ( const void *  compressed_data, size_t  nr_bytes, std::string &  out, size_t  output_size = 0  )

static

Uncompress compressed_data using zlib.

When the uncompressed size is known up front, pass it as output_size to skip the iterative chunked path and decompress straight into a single preallocated buffer. Pass 0 (the default) when the size is not known; decompression then proceeds chunk by chunk.

Note

Only zlib-format data is accepted; gzip-framed streams are rejected with Exception::InternalToolError.

Parameters

[in]	compressed_data	Pointer to the zlib-compressed bytes.
[in]	nr_bytes	Length of compressed_data in bytes; passing 0 with a non-zero output_size results in an empty out.
[out]	out	Receives the decompressed bytes; any previous contents are replaced.
[in]	output_size	Expected uncompressed size (optional). When 0, an iterative path is taken; when positive, out is sized to output_size up front. If the actual decompressed size turns out to be smaller, out is shrunk to match and an informational message is logged.

Exceptions

Exception::InvalidValue	if output_size was specified (>0) but is smaller than the actual uncompressed size.
Exception::InternalToolError	if zlib cannot decompress the data (corrupted input, unsupported gzip framing, or any other zlib failure).

uncompressString()

static void uncompressString ( const std::string &  in, std::string &  out, size_t  output_size = 0  )

static

Convenience wrapper around uncompressData that takes a String input.

Parameters

[in]	in	Compressed input.
[out]	out	Receives the decompressed bytes; any previous contents are replaced.
[in]	output_size	Expected uncompressed size; see uncompressData.

Exceptions

Exception::InvalidValue	see uncompressData.
Exception::InternalToolError	see uncompressData.