Classes
struct	clod_compressor
struct	clod_decompressor

Enumerations
enum	clod_compression_method { CLOD_UNCOMPRESSED = 1 , CLOD_GZIP = 2 , CLOD_ZLIB = 3 , CLOD_DEFLATE = 4 , CLOD_LZ4F = 5 , CLOD_XZ = 6 , CLOD_ZSTD = 7 , CLOD_BZIP2 = 8 , CLOD_MINECRAFT_LZ4 = 10 }
enum	clod_compression_level { CLOD_COMPRESSION_LOWEST = 0 , CLOD_COMPRESSION_LOW = 1 , CLOD_COMPRESSION_NORMAL = 2 , CLOD_COMPRESSION_HIGH = 3 , CLOD_COMPRESSION_HIGHEST = 4 , CLOD_COMPRESSION_LEVELS }
enum	clod_compression_result { CLOD_COMPRESSION_SUCCESS = 0 , CLOD_COMPRESSION_UNSUPPORTED = 1 , CLOD_COMPRESSION_MALFORMED = 2 , CLOD_COMPRESSION_SHORT_BUFFER = 3 , CLOD_COMPRESSION_SHORT_OUTPUT = 4 , CLOD_COMPRESSION_ALLOC_FAILED = 5 }

Functions
bool	clod_compression_support (enum clod_compression_method method)
struct clod_compressor *	clod_compressor_init ()
void	clod_compressor_free (struct clod_compressor *ctx)
enum clod_compression_result	clod_compress (struct clod_compressor ctx, void dst, size_t dst_max_size, const void src, size_t src_size, size_t actual_size, enum clod_compression_method method, enum clod_compression_level level)
struct clod_decompressor *	clod_decompressor_init ()
void	clod_decompressor_free (struct clod_decompressor *ctx)
enum clod_compression_result	clod_decompress (struct clod_decompressor ctx, void dst, size_t dst_size, const void src, size_t src_size, size_t actual_size, enum clod_compression_method method)

Detailed Description

These compression methods provide a generic interface for compressing data using a variety of compression algorithms. Support for compression algorithms can be configured at compile time through enabling or disabling the libraries that provide them.

Each compressed output is independent of the last, and no external state (i.e. dictionaries) exists. Some algorithms are only well optimised for small data sizes when used in a way which breaks one of those two properties. As such, compressing many small blobs of data can result in bad compression ratios and static overheads making relative performance worse.

Enumeration Type Documentation

◆ clod_compression_method

enum clod_compression_method

Compression methods.

Support for compression libraries and hence methods can be configured at compile time and can be checked with clod_compression_support. Currently, the library compiles with support for all compression methods by default.

Naming follows CLOD_<CONTAINER>_<ALGORITHM>, with algorithm being omitted if it is abundantly obvious (i.e. container only supports one compression algorithm).

Enumerator
CLOD_UNCOMPRESSED	No compression, provided by memcpy lol.
CLOD_GZIP	GZip container with deflate compression, provided by libdeflate. Uncompressed size is not known on failure.
CLOD_ZLIB	ZLib container with deflate compression, provided by libdeflate. Uncompressed size is not known on failure.
CLOD_DEFLATE	Deflate compression, provided by libdeflate. Uncompressed size is not known on failure.
CLOD_LZ4F	LZ4F container with LZ4 compression, provided by liblz4. Uncompressed size might be known on failure.
CLOD_XZ	XZ container with LZMA2 compression, provided by liblzma. Uncompressed size is not known on failure.
CLOD_ZSTD	ZSTD compression, provided by libzstd. Uncompressed size might be known on failure. This is probably the best choice for most use cases.
CLOD_BZIP2	BZIP2 compression, provided by libbz2. Uncompressed size is not known on failure.
CLOD_MINECRAFT_LZ4	Custom minecraft container with LZ4 compression. Some very unfortunate design decisions must have been made to land us with this. Uncompressed size might be known on failure.

Definition at line 32 of file compression.h.

◆ clod_compression_level

enum clod_compression_level

The compression level to use. These are mapped to each compression algorithm's useful range.

Enumerator
CLOD_COMPRESSION_LOWEST	Lowest compression level. Fastest with the largest compressed sizes.
CLOD_COMPRESSION_LOW	Low compression level. Faster with larger compressed sizes.
CLOD_COMPRESSION_NORMAL	Normal compression level. Uses uses algorithm default values.
CLOD_COMPRESSION_HIGH	High compression level. Slower with smaller compressed sizes.
CLOD_COMPRESSION_HIGHEST	Highest compression level. Slowest with the smallest compressed sizes.
CLOD_COMPRESSION_LEVELS	Number of compression levels.

Definition at line 74 of file compression.h.

◆ clod_compression_result

enum clod_compression_result

Result of a compression operation.

Enumerator
CLOD_COMPRESSION_SUCCESS	The operation was successful.
CLOD_COMPRESSION_UNSUPPORTED	The specified algorithm isn't supported.
CLOD_COMPRESSION_MALFORMED	The compressed data is malformed.
CLOD_COMPRESSION_SHORT_BUFFER	The provided buffer is too short to hold the output.
CLOD_COMPRESSION_SHORT_OUTPUT	The output buffer is larger than the output, and actual_size was null.
CLOD_COMPRESSION_ALLOC_FAILED	Allocation failed.

Definition at line 100 of file compression.h.

Function Documentation

◆ clod_compression_support()

bool clod_compression_support ( enum clod_compression_method method )

Check if support for a given compression algorithm exists.

Parameters

[in] method Compression algorithm to check.

Returns: True if the compression algorithm is supported.

Definition at line 4 of file compression.c.

◆ clod_compressor_init()

struct clod_compressor * clod_compressor_init ( )

Create a new compressor. The compressor holds memory and tables that are reused between invocations of clod_compress. It is not a streaming interface, but an optimisation.

Returns: Newly allocated compressor, or nullptr on allocation failure.

Definition at line 64 of file compress.c.

◆ clod_compressor_free()

void clod_compressor_free ( struct clod_compressor * ctx )

Releases resources associated with the compressor.

Parameters

ctx	Compressor to free.

Definition at line 73 of file compress.c.

◆ clod_compress()

enum clod_compression_result clod_compress	(	struct clod_compressor *	ctx,
		void *	dst,
		size_t	dst_max_size,
		const void *	src,
		size_t	src_size,
		size_t *	actual_size,
		enum clod_compression_method	method,
		enum clod_compression_level	level )

Compress data with a given compression method.

Parameters

[in]	ctx	Compressor.
[out]	dst	Where compressed data is written.
[in]	dst_max_size	Size of `dst`.
[in]	src	Where data to be compressed is read from.
[in]	src_size	Size of data to compress in `src`.
[out]	actual_size	The actual size of the compressed output.
[in]	method	The compression method to use.
[in]	level	Compression level to use.

Returns: Result of compression.

Exceptions

CLOD_COMPRESSION_SUCCESS	On successful compression.
CLOD_COMPRESSION_UNSUPPORTED	If the compression method is unsupported.
CLOD_COMPRESSION_SHORT_BUFFER	If `dst` is too small to hold the compressed output.
CLOD_COMPRESSION_ALLOC_FAILED	If memory allocation failed.

Definition at line 89 of file compress.c.

◆ clod_decompressor_init()

struct clod_decompressor * clod_decompressor_init ( )

Create a new decompressor. The decompressor holds memory and tables that are reused between invocations of clod_decompress. It is not a streaming interface, but an optimisation.

Returns: Newly allocated decompressor, or nullptr on allocation failure.

Definition at line 43 of file decompress.c.

◆ clod_decompressor_free()

void clod_decompressor_free ( struct clod_decompressor * ctx )

Release resources associated with the decompressor.

Parameters

ctx	Decompressor to free.

Definition at line 52 of file decompress.c.

◆ clod_decompress()

enum clod_compression_result clod_decompress	(	struct clod_decompressor *	ctx,
		void *	dst,
		size_t	dst_size,
		const void *	src,
		size_t	src_size,
		size_t *	actual_size,
		enum clod_compression_method	method )

Decompress some data with the given method.

The nullability of actual_size informs clod_decompress if the size of the uncompressed output is known. If the size is known, actual_size should be null, and the size passed to dst_size. If the size is unknown, actual_size must be non-null and returns the size of the uncompressed output. It is strongly recommended to know the uncompressed size ahead of time.

When CLOD_COMPRESSION_SHORT_BUFFER is returned, it is sometimes possible to know the uncompressed size even without successfully decompressing the whole buffer. In that case, actual_size might be set to the true uncompressed size.

Parameters

[in]	ctx	Decompressor.
[out]	dst	Where decompressed data is written.
[in]	dst_size	Size of `dst`.
[in]	src	Where compressed data is read from.
[in]	src_size	Size of compressed data in `src`. Decompression will probably work as expected if you supply a value larger than the compressed size. It's method-dependent, and I'm not giving you any more than that in the public API.
[out]	actual_size	The actual size of the decompressed output. If CLOD_COMPRESSION_SHORT_BUFFER is returned and the uncompressed size can be discerned, `actual_size` might be set to the size of uncompressed data that would have been returned.
[in]	method	The compression method to use.

Returns: The result of the decompression.

Exceptions

CLOD_COMPRESSION_SUCCESS	On successful decompression.
CLOD_COMPRESSION_UNSUPPORTED	If the compression method is unsupported.
CLOD_COMPRESSION_MALFORMED	If the compressed data is malformed. THIS IS NOT AN INTEGRITY CHECK.
CLOD_COMPRESSION_SHORT_BUFFER	If `dst` is too small to hold the decompressed output.
CLOD_COMPRESSION_SHORT_OUTPUT	If `dst` is larger than the decompressed output and bytes_written is null.
CLOD_COMPRESSION_ALLOC_FAILED	If memory allocation failed.

Definition at line 95 of file decompress.c.

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ clod_compression_method

◆ clod_compression_level

◆ clod_compression_result

Function Documentation

◆ clod_compression_support()

◆ clod_compressor_init()

◆ clod_compressor_free()

◆ clod_compress()

◆ clod_decompressor_init()

◆ clod_decompressor_free()

◆ clod_decompress()