ccrush.h File Reference

Compress and decompress byte arrays easily using wrapper functions around Zlib. More...

#include <stdio.h>
#include <stdint.h>
#include <stddef.h>

Include dependency graph for ccrush.h:

Go to the source code of this file.

Macros
#define	CCRUSH_API
#define	CCRUSH_VERSION   210
#define	CCRUSH_VERSION_STR   "2.1.0"
#define	CCRUSH_MAX_BUFFER_SIZE_KiB   (1024 * 256)
#define	CCRUSH_DEFAULT_CHUNKSIZE   (1024 * 256)
#define	CCRUSH_ERROR_INVALID_ARGS   1000
#define	CCRUSH_ERROR_BUFFERSIZE_TOO_LARGE   1001
#define	CCRUSH_ERROR_FILE_ACCESS_FAILED   1002
#define	CCRUSH_ERROR_OUT_OF_MEMORY   2000
#define	CCRUSH_MIN(x, y)   (((x) < (y)) ? (x) : (y))
#define	CCRUSH_MAX(x, y)   (((x) > (y)) ? (x) : (y))
#define	CCRUSH_MAX_WIN_FILEPATH_LENGTH   (1024 * 32)

Functions
CCRUSH_API int	ccrush_compress (const uint8_t *data, size_t data_length, uint32_t buffer_size_kib, int level, uint8_t **out, size_t *out_length)
CCRUSH_API int	ccrush_compress_file (const char *input_file_path, const char *output_file_path, uint32_t buffer_size_kib, int level)
CCRUSH_API int	ccrush_compress_file_raw (FILE *input_file, FILE *output_file, uint32_t buffer_size_kib, int level, int close_input_file, int close_output_file)
CCRUSH_API int	ccrush_decompress (const uint8_t *data, size_t data_length, uint32_t buffer_size_kib, uint8_t **out, size_t *out_length)
CCRUSH_API int	ccrush_decompress_file (const char *input_file_path, const char *output_file_path, uint32_t buffer_size_kib)
CCRUSH_API int	ccrush_decompress_file_raw (FILE *input_file, FILE *output_file, uint32_t buffer_size_kib, int close_input_file, int close_output_file)
CCRUSH_API void	ccrush_free (void *mem)
CCRUSH_API uint32_t	ccrush_get_version_nr ()
CCRUSH_API char *	ccrush_get_version_nr_string ()
static uint64_t	ccrush_nextpow2 (uint64_t n)

Detailed Description

Compress and decompress byte arrays easily using wrapper functions around Zlib.

Author

Raphael Beck

Macro Definition Documentation

CCRUSH_DEFAULT_CHUNKSIZE

#define CCRUSH_DEFAULT_CHUNKSIZE   (1024 * 256)

Default chunksize to use for compression/decompression buffers.

CCRUSH_ERROR_BUFFERSIZE_TOO_LARGE

#define CCRUSH_ERROR_BUFFERSIZE_TOO_LARGE   1001

Error code for exaggerated buffer size arguments...

CCRUSH_ERROR_FILE_ACCESS_FAILED

#define CCRUSH_ERROR_FILE_ACCESS_FAILED   1002

Error code for when you compress/decompress a FILE* and either the input or output FILE* couldn't be opened/written to.

CCRUSH_ERROR_INVALID_ARGS

#define CCRUSH_ERROR_INVALID_ARGS   1000

Error code for NULL, invalid, out-of-range or simply just wrong arguments.

CCRUSH_ERROR_OUT_OF_MEMORY

#define CCRUSH_ERROR_OUT_OF_MEMORY   2000

Error code for OOM scenarios. Uh oh...

CCRUSH_MAX

#define CCRUSH_MAX	(		x,
			y )   (((x) > (y)) ? (x) : (y))

Pick the higher of two numbers.

CCRUSH_MAX_BUFFER_SIZE_KiB

#define CCRUSH_MAX_BUFFER_SIZE_KiB   (1024 * 256)

Maximum size of the input and output buffers to be used by ccrush.

CCRUSH_MAX_WIN_FILEPATH_LENGTH

#define CCRUSH_MAX_WIN_FILEPATH_LENGTH   (1024 * 32)

Maximum file path length on NTFS.

CCRUSH_MIN

#define CCRUSH_MIN	(		x,
			y )   (((x) < (y)) ? (x) : (y))

Pick the lower of two numbers.

CCRUSH_VERSION

#define CCRUSH_VERSION   210

Ccrush version number.

CCRUSH_VERSION_STR

#define CCRUSH_VERSION_STR   "2.1.0"

Ccrush version number (as a human-readable string).

Function Documentation

ccrush_compress()

CCRUSH_API int ccrush_compress	(	const uint8_t *	data,
		size_t	data_length,
		uint32_t	buffer_size_kib,
		int	level,
		uint8_t **	out,
		size_t *	out_length )

Compresses an array of bytes using deflate.

Parameters

data	The data to compress.
data_length	Length of the data array (how many bytes to compress).
buffer_size_kib	The underlying buffer size to use (in KiB). Pass 0 to use the default value CCRUSH_DEFAULT_CHUNKSIZE. Especially inflate() profits from a relatively large buffer a.k.a. "chunk" size. A 256KiB buffer works great :)
level	The level of compression [0-9]. Lower means faster, higher level means better compression (but slower). Default is 6. If you pass a value that is out of the allowed range of [0-9], 6 will be used! 0 does not compress at all...
out	Pointer to an output buffer. This will be allocated on the heap ONLY on success: if something failed, this is left untouched! Needs to be freed manually by the caller.
out_length	Where to write the output array's length into.

Returns

0 on success; non-zero error codes if something fails.

ccrush_compress_file()

CCRUSH_API int ccrush_compress_file	(	const char *	input_file_path,
		const char *	output_file_path,
		uint32_t	buffer_size_kib,
		int	level )

Compresses a given file and writes it into the passed output file path.

Parameters

input_file_path	The file to compress. Must be UTF-8 encoded! Must be NUL-terminated!
output_file_path	The output file path where the compressed file should be written to. Must be UTF-8 encoded! Must be NUL-terminated!
buffer_size_kib	The underlying buffer size to use (in KiB). Pass 0 to use the default value CCRUSH_DEFAULT_CHUNKSIZE. Especially inflate() profits from a relatively large buffer a.k.a. "chunk" size. A 256KiB buffer works great :)
level	The level of compression [0-9]. Lower means faster, higher level means better compression (but slower). Default is 6. If you pass a value that is out of the allowed range of [0-9], 6 will be used! 0 does not compress at all...

Returns

0 on success; non-zero error codes if something fails.

ccrush_compress_file_raw()

CCRUSH_API int ccrush_compress_file_raw	(	FILE *	input_file,
		FILE *	output_file,
		uint32_t	buffer_size_kib,
		int	level,
		int	close_input_file,
		int	close_output_file )

Compresses a given file and writes it into the passed output file.

Parameters

input_file	The file to compress. Standard IO file handle (FILE*)
output_file	The output file handle into which to write the compressed file. Standard IO file handle (FILE*)
buffer_size_kib	The underlying buffer size to use (in KiB). Pass 0 to use the default value CCRUSH_DEFAULT_CHUNKSIZE. Especially inflate() profits from a relatively large buffer a.k.a. "chunk" size. A 256KiB buffer works great :)
level	The level of compression [0-9]. Lower means faster, higher level means better compression (but slower). Default is 6. If you pass a value that is out of the allowed range of [0-9], 6 will be used! 0 does not compress at all...
close_input_file	Should the input file handle be fclose'd after usage? Pass 0 for "false" and anything else for "true".
close_output_file	Should the output file handle be fclose'd after usage? Pass 0 for "false" and anything else for "true".

Returns

ccrush_decompress()

CCRUSH_API int ccrush_decompress	(	const uint8_t *	data,
		size_t	data_length,
		uint32_t	buffer_size_kib,
		uint8_t **	out,
		size_t *	out_length )

Decompresses a given set of deflated data using inflate.

Parameters

data	The compressed bytes to decompress.
data_length	Length of the data array.
buffer_size_kib	The underlying buffer size to use (in KiB). If available, a buffer size of 256KiB or more is recommended. Pass 0 to use the default value CCRUSH_DEFAULT_CHUNKSIZE.
out	Output buffer pointer: this will be allocated and filled with the decompressed data. In case of a failure it's left alone, so you only need to free it if decompression succeeds!
out_length	Where to write the output array's length into.

Returns

0 on success; non-zero error codes if something fails.

ccrush_decompress_file()

CCRUSH_API int ccrush_decompress_file	(	const char *	input_file_path,
		const char *	output_file_path,
		uint32_t	buffer_size_kib )

Decompresses a given file and writes it into the passed output file path.

Parameters

input_file_path	The file to decompress. Must be UTF-8 encoded! Must be NUL-terminated!
output_file_path	The output file path where the decompressed file should be written to. Must be UTF-8 encoded! Must be NUL-terminated!
buffer_size_kib	The underlying buffer size to use (in KiB). Pass 0 to use the default value CCRUSH_DEFAULT_CHUNKSIZE. Especially inflate() profits from a relatively large buffer a.k.a. "chunk" size. A 256KiB buffer works great :)

Returns

0 on success; non-zero error codes if something fails.

ccrush_decompress_file_raw()

CCRUSH_API int ccrush_decompress_file_raw	(	FILE *	input_file,
		FILE *	output_file,
		uint32_t	buffer_size_kib,
		int	close_input_file,
		int	close_output_file )

Decompresses a given file and writes it into the passed output file.

Parameters

input_file	The file to decompress. Standard IO file handle (FILE*)
output_file	The output file handle into which to write the decompressed file. Standard IO file handle (FILE*)
buffer_size_kib	The underlying buffer size to use (in KiB). Pass 0 to use the default value CCRUSH_DEFAULT_CHUNKSIZE. Especially inflate() profits from a relatively large buffer a.k.a. "chunk" size. A 256KiB buffer works great :)
close_input_file	Should the input file handle be fclose'd after usage? Pass 0 for "false" and anything else for "true".
close_output_file	Should the output file handle be fclose'd after usage? Pass 0 for "false" and anything else for "true".

Returns

ccrush_free()

CCRUSH_API void ccrush_free

(

void *

mem

)

Wrapper around free() (mostly useful for C# interop).

Parameters

mem	The pointer to the memory to free.

ccrush_get_version_nr()

CCRUSH_API uint32_t ccrush_get_version_nr

(

)

Get the current ccrush version number (as an unsigned integer).

Returns

The current ccrush version number (as an unsigned integer).

ccrush_get_version_nr_string()

CCRUSH_API char * ccrush_get_version_nr_string

(

)

Get the current ccrush version number (as a nicely formatted, human-readable string).

Returns

The current ccrush version number (as a nicely formatted, human-readable string).

ccrush_nextpow2()

static uint64_t ccrush_nextpow2 ( uint64_t n )

inlinestatic

Calculates a number's next upper power of 2.

Source: http://graphics.stanford.edu/~seander/bithacks.html#RoundUpPowerOf2

Parameters

n	The number to round to the next upper power of 2.

Returns

The upper next power of 2.