rpnx::compression Namespace Reference

Facilities for creating and decoding supported compressed streams. More...

Namespaces
namespace	bzip2_codec
	Internal implementation of bzip2 compression and decompression.
namespace	deflate_codec
	Internal implementation shared by raw DEFLATE, zlib, gzip, and ZIP.
namespace	implementation
	Internal primitives shared by the format-specific codecs.
namespace	lz4_codec
	Internal implementation of LZ4 frame compression and decompression.
namespace	xz_codec
	Internal implementation of xz and its LZMA2 payload format.
namespace	zip_detail
	Internal ZIP32 parsing and output-iterator support.
namespace	zstandard_codec
	Internal implementation of Zstandard compression and decompression.

Classes
class	compression_error
	Exception raised for malformed streams, invalid options, and codec failures. More...
struct	compression_options
	Options shared by compression operations. More...
struct	decompression_options
	Resource and stream-validation policy for decompression operations. More...
struct	zip_entry
	An owning ZIP archive member. More...
struct	zip_extraction_options
	Resource limits applied while parsing a ZIP archive. More...

Enumerations
enum class	format : std::uint8_t {   deflate , zlib , gzip , bzip2 ,   xz , zstandard , lz4_frame , zip }
	Wire formats recognized by the library. More...
enum class	error_code : std::uint8_t {   invalid_data , invalid_option , output_limit_exceeded , trailing_data ,   unsupported_feature , backend_failure , insufficient_output_space }
	Stable machine-readable categories reported by compression_error. More...
enum class	zip_compression : std::uint8_t { stored , deflate }
	Compression methods supported for individual ZIP members. More...

Functions
std::vector< std::byte >	compress (format stream_format, std::span< std::byte const > input, compression_options const &options={})
	Compresses a contiguous byte buffer into an owning result.
std::vector< std::byte >	decompress (format stream_format, std::span< std::byte const > input, decompression_options const &options={})
	Decompresses a contiguous byte buffer into an owning result.
std::size_t	compress (format stream_format, std::span< std::byte const > input, std::span< std::byte > output, compression_options const &options={})
	Compresses into caller-owned storage.
std::size_t	decompress (format stream_format, std::span< std::byte const > input, std::span< std::byte > output, decompression_options const &options={})
	Decompresses into caller-owned storage.
template<std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>
output_iterator	compress (format stream_format, input_iterator first, sentinel last, output_iterator output, compression_options const &options={})
	Compresses an iterator range into an STL output iterator.
template<format stream_format, std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>
output_iterator	compress (input_iterator first, sentinel last, output_iterator output, compression_options const &options={})
	Compresses an iterator range with compile-time format dispatch.
template<std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>
output_iterator	decompress (format stream_format, input_iterator first, sentinel last, output_iterator output, decompression_options const &options={})
	Decompresses an iterator range into an STL output iterator.
template<format stream_format, std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>
output_iterator	decompress (input_iterator first, sentinel last, output_iterator output, decompression_options const &options={})
	Decompresses an iterator range with compile-time format dispatch.
std::vector< std::byte >	create_zip (std::span< zip_entry const > entries)
	Creates a deterministic ZIP32 archive from contiguous entries.
std::vector< zip_entry >	extract_zip (std::span< std::byte const > archive, zip_extraction_options const &options={})
	Extracts a contiguous ZIP32 archive into owning entries.
template<std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>
output_iterator	create_zip (input_iterator first, sentinel last, output_iterator output)
	Creates a deterministic ZIP32 archive from an iterator range.
template<std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>
output_iterator	extract_zip (input_iterator first, sentinel last, output_iterator output, zip_extraction_options const &options={})
	Extracts validated ZIP members through an STL output iterator.

Detailed Description

Facilities for creating and decoding supported compressed streams.

The namespace exposes allocating and caller-owned span overloads for ABI-stable use, plus iterator overloads for single-pass streaming. All implementations are self-contained and report format-specific failures through compression_error.

Enumeration Type Documentation

error_code

enum class rpnx::compression::error_code : std::uint8_t

strong

Stable machine-readable categories reported by compression_error.

Enumerator
invalid_data	The input does not conform to the selected format.
invalid_option	An option or format value is outside its accepted range.
output_limit_exceeded	Decoding would exceed a configured resource limit.
trailing_data	Bytes remain after the permitted stream members.
unsupported_feature	Valid input requires a format feature not implemented by the library.
backend_failure	A codec encountered an internal failure not covered by another category.
insufficient_output_space	A caller-owned output span cannot hold the complete result.

Definition at line 44 of file compression.hpp.

format

enum class rpnx::compression::format : std::uint8_t

strong

Wire formats recognized by the library.

Enumerator
deflate	Raw RFC 1951 DEFLATE stream.
zlib	RFC 1950 zlib wrapper around DEFLATE.
gzip	RFC 1952 gzip member or concatenated members.
bzip2	bzip2 stream.
xz	xz container containing LZMA2 data.
zstandard	Zstandard frame.
lz4_frame	LZ4 frame.
zip	ZIP32 archive; use create_zip() and extract_zip().

Definition at line 31 of file compression.hpp.

zip_compression

enum class rpnx::compression::zip_compression : std::uint8_t

strong

Compression methods supported for individual ZIP members.

Enumerator
stored	Store the member without compression.
deflate	Encode the member as raw DEFLATE.

Definition at line 30 of file zip.hpp.

Function Documentation

compress() [1/4]

template<std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>

output_iterator rpnx::compression::compress	(	format	stream_format,
		input_iterator	first,
		sentinel	last,
		output_iterator	output,
		compression_options const &	options = {} )

Compresses an iterator range into an STL output iterator.

Template Parameters

input_iterator	Single-pass iterator whose value type is std::byte or a one-byte integral type.
sentinel	Sentinel for first.
output_iterator	Output iterator accepting std::byte or std::uint8_t assignments.

Parameters

stream_format	Wire format to produce. format::zip is not accepted.
first	Iterator to the first uncompressed byte.
last	Sentinel past the final uncompressed byte.
output	Destination iterator, taken and returned by value.
options	Format-specific compression settings.

Returns

The destination iterator advanced past the final encoded byte.

Exceptions

compression_error

If the format or options are invalid or encoding fails.

Definition at line 199 of file compression.hpp.

compress() [2/4]

std::vector< std::byte > rpnx::compression::compress ( format stream_format, std::span< std::byte const > input, compression_options const & options = {} )

nodiscard

Compresses a contiguous byte buffer into an owning result.

Parameters

stream_format	Wire format to produce. format::zip is not accepted.
input	Uncompressed bytes. The span is only borrowed for this call.
options	Format-specific compression settings.

Returns

The complete encoded stream.

Exceptions

compression_error

If the format or options are invalid or encoding fails.

References compress().

Referenced by compress(), and create_zip().

compress() [3/4]

std::size_t rpnx::compression::compress ( format stream_format, std::span< std::byte const > input, std::span< std::byte > output, compression_options const & options = {} )

nodiscard

Compresses into caller-owned storage.

Parameters

stream_format	Wire format to produce. format::zip is not accepted.
input	Uncompressed bytes. The span is only borrowed for this call.
output	Destination storage.
options	Format-specific compression settings.

Returns

Number of initialized bytes at the beginning of output.

Exceptions

compression_error

With error_code::insufficient_output_space if the destination is exhausted, or with another category for a codec failure.

compress() [4/4]

template<format stream_format, std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>

output_iterator rpnx::compression::compress	(	input_iterator	first,
		sentinel	last,
		output_iterator	output,
		compression_options const &	options = {} )

Compresses an iterator range with compile-time format dispatch.

Template Parameters

stream_format	Wire format to produce. format::zip is not accepted.
input_iterator	Single-pass iterator whose value type is std::byte or a one-byte integral type.
sentinel	Sentinel for first.
output_iterator	Output iterator accepting std::byte or std::uint8_t assignments.

Parameters

first	Iterator to the first uncompressed byte.
last	Sentinel past the final uncompressed byte.
output	Destination iterator, taken and returned by value.
options	Format-specific compression settings.

Returns

The destination iterator advanced past the final encoded byte.

Exceptions

compression_error

If the options are invalid or encoding fails.

Definition at line 245 of file compression.hpp.

create_zip() [1/2]

template<std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>

output_iterator rpnx::compression::create_zip	(	input_iterator	first,
		sentinel	last,
		output_iterator	output )

Creates a deterministic ZIP32 archive from an iterator range.

Template Parameters

input_iterator	Single-pass iterator whose value type is zip_entry.
sentinel	Sentinel for first.
output_iterator	Output iterator accepting std::byte or std::uint8_t assignments.

Parameters

first	Iterator to the first member.
last	Sentinel past the final member.
output	Destination iterator, taken and returned by value.

Returns

The destination iterator advanced past the end-of-central-directory record.

Exceptions

compression_error

If a member is invalid or ZIP64 would be required.

Only central-directory metadata is retained; member data is consumed and emitted in archive order.

Definition at line 452 of file zip.hpp.

References compress(), rpnx::compression::zip_entry::compression, rpnx::compression::deflate_codec::crc32(), rpnx::compression::zip_entry::data, deflate, invalid_option, rpnx::compression::zip_entry::path, rpnx::compression::zip_detail::path_is_safe(), rpnx::compression::zip_detail::counting_output_iterator< output_iterator >::size(), stored, rpnx::compression::zip_detail::counting_output_iterator< output_iterator >::take_output(), unsupported_feature, rpnx::compression::implementation::write_byte(), and zip.

create_zip() [2/2]

std::vector< std::byte > rpnx::compression::create_zip ( std::span< zip_entry const > entries )

nodiscard

Creates a deterministic ZIP32 archive from contiguous entries.

Parameters

entries

Members to write in archive order. The span is only borrowed for this call.

Returns

The complete ZIP32 archive.

Exceptions

compression_error

If a path is unsafe or duplicated, compression fails, or ZIP64 would be required.

The writer emits UTF-8 path flags, fixed timestamps, data descriptors, and no extra fields or archive comment. Identical entries therefore produce identical bytes.

decompress() [1/4]

template<std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>

output_iterator rpnx::compression::decompress	(	format	stream_format,
		input_iterator	first,
		sentinel	last,
		output_iterator	output,
		decompression_options const &	options = {} )

Decompresses an iterator range into an STL output iterator.

Template Parameters

input_iterator	Single-pass iterator whose value type is std::byte or a one-byte integral type.
sentinel	Sentinel for first.
output_iterator	Output iterator accepting std::byte or std::uint8_t assignments.

Parameters

stream_format	Wire format of the input. format::zip is not accepted.
first	Iterator to the first compressed byte.
last	Sentinel past the final compressed byte.
output	Destination iterator, taken and returned by value.
options	Output limits and concatenated-stream policy.

Returns

The destination iterator advanced past the final uncompressed byte.

Exceptions

compression_error

If input is invalid, unsupported, or exceeds a limit.

Definition at line 287 of file compression.hpp.

decompress() [2/4]

std::vector< std::byte > rpnx::compression::decompress ( format stream_format, std::span< std::byte const > input, decompression_options const & options = {} )

nodiscard

Decompresses a contiguous byte buffer into an owning result.

Parameters

stream_format	Wire format of input. format::zip is not accepted.
input	Complete compressed stream. The span is only borrowed for this call.
options	Output limits and concatenated-stream policy.

Returns

The complete uncompressed data.

Exceptions

compression_error

If input is invalid, unsupported, or exceeds a limit.

Referenced by rpnx::compression::zip_detail::extract_archive().

decompress() [3/4]

std::size_t rpnx::compression::decompress ( format stream_format, std::span< std::byte const > input, std::span< std::byte > output, decompression_options const & options = {} )

nodiscard

Decompresses into caller-owned storage.

Parameters

stream_format	Wire format of input. format::zip is not accepted.
input	Complete compressed stream. The span is only borrowed for this call.
output	Destination storage.
options	Output limits and concatenated-stream policy.

Returns

Number of initialized bytes at the beginning of output.

Exceptions

compression_error

With error_code::insufficient_output_space if the destination is exhausted, or with another category for invalid input or limits.

decompress() [4/4]

template<format stream_format, std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>

output_iterator rpnx::compression::decompress	(	input_iterator	first,
		sentinel	last,
		output_iterator	output,
		decompression_options const &	options = {} )

Decompresses an iterator range with compile-time format dispatch.

Template Parameters

stream_format	Wire format of the input. format::zip is not accepted.
input_iterator	Single-pass iterator whose value type is std::byte or a one-byte integral type.
sentinel	Sentinel for first.
output_iterator	Output iterator accepting std::byte or std::uint8_t assignments.

Parameters

first	Iterator to the first compressed byte.
last	Sentinel past the final compressed byte.
output	Destination iterator, taken and returned by value.
options	Output limits and concatenated-stream policy.

Returns

The destination iterator advanced past the final uncompressed byte.

Exceptions

compression_error

If input is invalid, unsupported, or exceeds a limit.

Definition at line 333 of file compression.hpp.

extract_zip() [1/2]

template<std::input_iterator input_iterator, std::sentinel_for< input_iterator > sentinel, typename output_iterator>

output_iterator rpnx::compression::extract_zip	(	input_iterator	first,
		sentinel	last,
		output_iterator	output,
		zip_extraction_options const &	options = {} )

Extracts validated ZIP members through an STL output iterator.

Template Parameters

input_iterator	Single-pass iterator whose value type is std::byte or a one-byte integral type.
sentinel	Sentinel for first.
output_iterator	Output iterator accepting zip_entry values.

Parameters

first	Iterator to the first archive byte.
last	Sentinel past the final archive byte.
output	Destination iterator, taken and returned by value.
options	Member-count and uncompressed-size limits.

Returns

The destination iterator advanced past the final extracted member.

Exceptions

compression_error

If the archive is malformed, unsupported, unsafe, duplicated, fails checksum validation, or exceeds a configured limit.

ZIP extraction materializes the archive because its trailing central directory points backward to local headers.

Definition at line 597 of file zip.hpp.

extract_zip() [2/2]

std::vector< zip_entry > rpnx::compression::extract_zip ( std::span< std::byte const > archive, zip_extraction_options const & options = {} )

nodiscard

Extracts a contiguous ZIP32 archive into owning entries.

Parameters

archive	Complete ZIP archive. The span is only borrowed for this call.
options	Member-count and uncompressed-size limits.

Returns

Owning entries in central-directory order. Extracted entries record the method declared by the archive.

Exceptions

compression_error

If the archive is malformed, unsupported, unsafe, duplicated, fails checksum validation, or exceeds a configured limit.