diff options
Diffstat (limited to 'libbutl/lz4.hxx')
-rw-r--r-- | libbutl/lz4.hxx | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/libbutl/lz4.hxx b/libbutl/lz4.hxx new file mode 100644 index 0000000..bf679c5 --- /dev/null +++ b/libbutl/lz4.hxx @@ -0,0 +1,76 @@ +// file : libbutl/lz4.hxx -*- C++ -*- +// license : MIT; see accompanying LICENSE file + +#pragma once + +#include <cstdint> + +#include <libbutl/optional.mxx> +#include <libbutl/fdstream.mxx> + +#include <libbutl/export.hxx> + +namespace butl +{ + namespace lz4 + { + //@@ TODO: allow (re-)using external buffers, contexts? + + // Read the content from the input stream, compress it using the specified + // compression level and block size, and write the compressed content to + // the output stream. If content size is specified, then include it into + // the compressed content header. Return the compressed content size. + // + // This function may throw std::bad_alloc as well as exceptions thrown by + // fdstream read/write functions. It may also throw invalid_argument in + // case of argument inconsistencies (e.g., content size does not match + // actual) with what() returning the error description. The input stream + // is expected to throw on badbit (but not failbit). The output stream is + // expected to throw on badbit or failbit. + // + // The output and most likely the input streams must be in the binary + // mode. + // + // Valid values for the compressions level are between 1 (fastest) and + // 12 (best compression level). + // + // Valid block sizes and their IDs: + // + // 4: 64KB + // 5: 256KB + // 6: 1MB + // 7: 4MB + // + // This function produces compressed content identical to: + // + // lz4 -z -<compression_level> -B<block_size_id> -BD [--content-size] + // + LIBBUTL_SYMEXPORT std::uint64_t + compress (ofdstream&, + ifdstream&, + int compression_level, + int block_size_id, + optional<std::uint64_t> content_size); + + + // Read the compressed content from the input stream, decompress it, and + // write the decompressed content to the output stream. Return the + // decompressed content size. + // + // This function may throw std::bad_alloc as well as exceptions thrown by + // fdstream read/write functions. It may also throw invalid_argument if + // the compressed content is invalid with what() returning the error + // description. The input stream is expected to throw on badbit (but not + // failbit). The output stream is expected to throw on badbit or failbit. + // + // The input and most likely the output streams must be in the binary + // mode. + // + // Note that this function does not require the input stream to reach EOF + // at the end of compressed content. So if you have this a requirement, + // you will need to enforce it yourself. + // + LIBBUTL_SYMEXPORT std::uint64_t + decompress (ofdstream&, ifdstream&); + } +} |