compression.hpp

Go to the documentation of this file.

#ifndef RPNX_COMPRESSION_COMPRESSION_HPP
#define RPNX_COMPRESSION_COMPRESSION_HPP
 
#include <cstddef>
#include <cstdint>
#include <exception>
#include <iterator>
#include <optional>
#include <span>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
 
/**
 * @file
 * @brief Compression formats, options, errors, and buffer or iterator APIs.
 */
 
/**
 * @brief 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.
 */
namespace rpnx::compression
{
 
    /** @brief Wire formats recognized by the library. */
    enum class format : std::uint8_t
    {
        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().
    };
 
    /** @brief Stable machine-readable categories reported by compression_error. */
    enum class error_code : std::uint8_t
    {
        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.
    };
 
    /** @brief Options shared by compression operations. */
    struct compression_options
    {
        /**
         * @brief Optional format-specific compression level.
         *
         * The accepted ranges are 0--9 for DEFLATE, zlib, and gzip; 1--9 for
         * bzip2; 0--9 for xz; 0--22 for Zstandard; and 0--12 for LZ4. An empty
         * value selects the codec's default level.
         */
        std::optional< std::int32_t > level;
    };
 
    /** @brief Resource and stream-validation policy for decompression operations. */
    struct decompression_options
    {
        /**
         * @brief Maximum total number of bytes the operation may emit.
         *
         * Decoding stops with error_code::output_limit_exceeded before the
         * returned output grows beyond this value. The default is one GiB.
         */
        std::size_t maximum_output_size = 1024U * 1024U * 1024U;
 
        /**
         * @brief Whether to decode adjacent members for formats that define concatenation.
         *
         * When false, bytes following the first complete stream are rejected.
         * When true, the decoder treats adjacent input as additional members of
         * the selected format.
         */
        bool allow_concatenated_streams = false;
    };
 
    /**
     * @brief Exception raised for malformed streams, invalid options, and codec failures.
     *
     * The error category and stream format are stable programmatic context. The
     * diagnostic returned by what() is intended for humans and is not a stable API.
     */
    class compression_error final : public std::exception
    {
      public:
        /**
         * @brief Constructs a compression exception.
         * @param code Stable category for the failure.
         * @param stream_format Wire format being processed when the failure occurred.
         * @param message Human-readable diagnostic retained by the exception.
         */
        compression_error(error_code code, format stream_format, std::string message);
 
        /**
         * @brief Returns the human-readable diagnostic.
         * @return A null-terminated string valid until the exception is destroyed.
         */
        [[nodiscard]] char const* what() const noexcept override;
 
        /**
         * @brief Returns the stable error category.
         * @return The category supplied at construction.
         */
        [[nodiscard]] error_code code() const noexcept;
 
        /**
         * @brief Returns the stream format involved in the error.
         * @return The format supplied at construction.
         */
        [[nodiscard]] format stream_format() const noexcept;
 
      private:
        error_code m_code;
        format m_stream_format;
        std::string m_message;
    };
 
    /**
     * @brief Compresses a contiguous byte buffer into an owning result.
     * @param stream_format Wire format to produce. format::zip is not accepted.
     * @param input Uncompressed bytes. The span is only borrowed for this call.
     * @param options Format-specific compression settings.
     * @return The complete encoded stream.
     * @throws compression_error If the format or options are invalid or encoding fails.
     */
    [[nodiscard]] std::vector< std::byte > compress(format stream_format, std::span< std::byte const > input, compression_options const& options = {});
 
    /**
     * @brief Decompresses a contiguous byte buffer into an owning result.
     * @param stream_format Wire format of @p input. format::zip is not accepted.
     * @param input Complete compressed stream. The span is only borrowed for this call.
     * @param options Output limits and concatenated-stream policy.
     * @return The complete uncompressed data.
     * @throws compression_error If input is invalid, unsupported, or exceeds a limit.
     */
    [[nodiscard]] std::vector< std::byte > decompress(format stream_format, std::span< std::byte const > input, decompression_options const& options = {});
 
    /**
     * @brief Compresses into caller-owned storage.
     * @param stream_format Wire format to produce. format::zip is not accepted.
     * @param input Uncompressed bytes. The span is only borrowed for this call.
     * @param output Destination storage.
     * @param options Format-specific compression settings.
     * @return Number of initialized bytes at the beginning of @p output.
     * @throws compression_error With error_code::insufficient_output_space if the
     * destination is exhausted, or with another category for a codec failure.
     */
    [[nodiscard]] std::size_t compress(format stream_format, std::span< std::byte const > input, std::span< std::byte > output, compression_options const& options = {});
 
    /**
     * @brief Decompresses into caller-owned storage.
     * @param stream_format Wire format of @p input. format::zip is not accepted.
     * @param input Complete compressed stream. The span is only borrowed for this call.
     * @param output Destination storage.
     * @param options Output limits and concatenated-stream policy.
     * @return Number of initialized bytes at the beginning of @p output.
     * @throws compression_error With error_code::insufficient_output_space if the
     * destination is exhausted, or with another category for invalid input or limits.
     */
    [[nodiscard]] std::size_t decompress(format stream_format, std::span< std::byte const > input, std::span< std::byte > output, decompression_options const& options = {});
 
} // namespace rpnx::compression
 
#include <rpnx/compression/implementation/bzip2.hpp>
#include <rpnx/compression/implementation/deflate.hpp>
#include <rpnx/compression/implementation/lz4.hpp>
#include <rpnx/compression/implementation/xz.hpp>
#include <rpnx/compression/implementation/zstandard.hpp>
 
namespace rpnx::compression
{
 
    /**
     * @brief Compresses an iterator range into an STL output iterator.
     * @tparam input_iterator Single-pass iterator whose value type is std::byte or a one-byte integral type.
     * @tparam sentinel Sentinel for @p first.
     * @tparam output_iterator Output iterator accepting std::byte or std::uint8_t assignments.
     * @param stream_format Wire format to produce. format::zip is not accepted.
     * @param first Iterator to the first uncompressed byte.
     * @param last Sentinel past the final uncompressed byte.
     * @param output Destination iterator, taken and returned by value.
     * @param options Format-specific compression settings.
     * @return The destination iterator advanced past the final encoded byte.
     * @throws compression_error If the format or options are invalid or encoding fails.
     */
    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 = {})
    {
        using input_value = std::remove_cv_t< std::iter_value_t< input_iterator > >;
        static_assert(std::is_same_v< input_value, std::byte > || (std::is_integral_v< input_value > && sizeof(input_value) == 1U), "compression input iterators must contain byte-sized values");
 
        if (stream_format == format::deflate || stream_format == format::zlib || stream_format == format::gzip)
        {
            return deflate_codec::compress(stream_format, first, last, output, options);
        }
        if (stream_format == format::lz4_frame)
        {
            return lz4_codec::compress(first, last, output, options);
        }
        if (stream_format == format::zstandard)
        {
            return zstandard_codec::compress(first, last, output, options);
        }
        if (stream_format == format::bzip2)
        {
            return bzip2_codec::compress(first, last, output, options);
        }
        if (stream_format == format::xz)
        {
            return xz_codec::compress(first, last, output, options);
        }
        if (stream_format == format::zip)
        {
            throw compression_error(error_code::unsupported_feature, stream_format, "use create_zip for ZIP archives");
        }
        throw compression_error(error_code::invalid_option, stream_format, "unknown compression format");
    }
 
    /**
     * @brief Compresses an iterator range with compile-time format dispatch.
     * @tparam stream_format Wire format to produce. format::zip is not accepted.
     * @tparam input_iterator Single-pass iterator whose value type is std::byte or a one-byte integral type.
     * @tparam sentinel Sentinel for @p first.
     * @tparam output_iterator Output iterator accepting std::byte or std::uint8_t assignments.
     * @param first Iterator to the first uncompressed byte.
     * @param last Sentinel past the final uncompressed byte.
     * @param output Destination iterator, taken and returned by value.
     * @param options Format-specific compression settings.
     * @return The destination iterator advanced past the final encoded byte.
     * @throws compression_error If the options are invalid or encoding fails.
     */
    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 = {})
    {
        if constexpr (stream_format == format::deflate || stream_format == format::zlib || stream_format == format::gzip)
        {
            return deflate_codec::compress(stream_format, first, last, output, options);
        }
        else if constexpr (stream_format == format::lz4_frame)
        {
            return lz4_codec::compress(first, last, output, options);
        }
        else if constexpr (stream_format == format::zstandard)
        {
            return zstandard_codec::compress(first, last, output, options);
        }
        else if constexpr (stream_format == format::bzip2)
        {
            return bzip2_codec::compress(first, last, output, options);
        }
        else if constexpr (stream_format == format::xz)
        {
            return xz_codec::compress(first, last, output, options);
        }
        else
        {
            return compress(stream_format, first, last, output, options);
        }
    }
 
    /**
     * @brief Decompresses an iterator range into an STL output iterator.
     * @tparam input_iterator Single-pass iterator whose value type is std::byte or a one-byte integral type.
     * @tparam sentinel Sentinel for @p first.
     * @tparam output_iterator Output iterator accepting std::byte or std::uint8_t assignments.
     * @param stream_format Wire format of the input. format::zip is not accepted.
     * @param first Iterator to the first compressed byte.
     * @param last Sentinel past the final compressed byte.
     * @param output Destination iterator, taken and returned by value.
     * @param options Output limits and concatenated-stream policy.
     * @return The destination iterator advanced past the final uncompressed byte.
     * @throws compression_error If input is invalid, unsupported, or exceeds a limit.
     */
    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 = {})
    {
        using input_value = std::remove_cv_t< std::iter_value_t< input_iterator > >;
        static_assert(std::is_same_v< input_value, std::byte > || (std::is_integral_v< input_value > && sizeof(input_value) == 1U), "decompression input iterators must contain byte-sized values");
 
        if (stream_format == format::deflate || stream_format == format::zlib || stream_format == format::gzip)
        {
            return deflate_codec::decompress(stream_format, first, last, output, options);
        }
        if (stream_format == format::lz4_frame)
        {
            return lz4_codec::decompress(first, last, output, options);
        }
        if (stream_format == format::zstandard)
        {
            return zstandard_codec::decompress(first, last, output, options);
        }
        if (stream_format == format::bzip2)
        {
            return bzip2_codec::decompress(first, last, output, options);
        }
        if (stream_format == format::xz)
        {
            return xz_codec::decompress(first, last, output, options);
        }
        if (stream_format == format::zip)
        {
            throw compression_error(error_code::unsupported_feature, stream_format, "use extract_zip for ZIP archives");
        }
        throw compression_error(error_code::invalid_option, stream_format, "unknown compression format");
    }
 
    /**
     * @brief Decompresses an iterator range with compile-time format dispatch.
     * @tparam stream_format Wire format of the input. format::zip is not accepted.
     * @tparam input_iterator Single-pass iterator whose value type is std::byte or a one-byte integral type.
     * @tparam sentinel Sentinel for @p first.
     * @tparam output_iterator Output iterator accepting std::byte or std::uint8_t assignments.
     * @param first Iterator to the first compressed byte.
     * @param last Sentinel past the final compressed byte.
     * @param output Destination iterator, taken and returned by value.
     * @param options Output limits and concatenated-stream policy.
     * @return The destination iterator advanced past the final uncompressed byte.
     * @throws compression_error If input is invalid, unsupported, or exceeds a limit.
     */
    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 = {})
    {
        if constexpr (stream_format == format::deflate || stream_format == format::zlib || stream_format == format::gzip)
        {
            return deflate_codec::decompress(stream_format, first, last, output, options);
        }
        else if constexpr (stream_format == format::lz4_frame)
        {
            return lz4_codec::decompress(first, last, output, options);
        }
        else if constexpr (stream_format == format::zstandard)
        {
            return zstandard_codec::decompress(first, last, output, options);
        }
        else if constexpr (stream_format == format::bzip2)
        {
            return bzip2_codec::decompress(first, last, output, options);
        }
        else if constexpr (stream_format == format::xz)
        {
            return xz_codec::decompress(first, last, output, options);
        }
        else
        {
            return decompress(stream_format, first, last, output, options);
        }
    }
 
} // namespace rpnx::compression
 
#endif