The library contains a compression routine, called LiZaRd. It is modified Lempel-Ziv 77 method with slightly worse compression ratio, but with faster compression and decompression (compression is few times faster than zlib, decompression is slightly slower than memcpy()).
The data format and inspiration for code comes from the LZO project (which couldn’t be used due to licence problems). They might be compatible, but no-one tested that.
Basic application
#define LIZARD_NEEDS_CHARS 8
The compression routine needs input buffer 8 characters longer, because it does not check the input bounds all the time.
#define LIZARD_MAX_LEN(LENGTH) ((LENGTH) * LIZARD_MAX_MULTIPLY + LIZARD_MAX_ADD)
The compressed data will not be longer than LIZARD_MAX_LEN(input_length). Note that LIZARD_MAX_LEN(length) > length (this is not a problem of the algorithm, every lossless compression algorithm must have an input for which it produces a larger output).
Use this to compute the size of out paramater of lizard_compress().
int lizard_compress(const byte *in, uint in_len, byte *out);
Compress data provided in in. The input buffer must be at last @in_len + <<def_LIZARD_NEEDS_CHARS,LIZARD_NEEDS_CHARS>> long (the compression algorithm does not check the bounds all the time).
The output will be stored in out. The out buffer must be at last LIZARD_LEN(@in_len) bytes long for the output to fit in for sure.
The function returns number of bytes actually needed (the size of output).
Use lizard_decompress() to get the original data.
int lizard_decompress(const byte *in, byte *out);
Decompress data previously compressed by lizard_compress(). Input is taken from in and the result stored in out. The size of output is returned.
Note that you need to know the maximal possible size of the output to allocate enough memory.
See also safe decompression.
Safe decompression
You can use safe decompression, when you want to make sure you got the length right and when you want to reuse the buffer for output.
struct lizard_buffer;
Type of the output buffer for lizard_decompress_safe().
struct lizard_buffer *lizard_alloc(void);
Get me a new lizard_buffer.
void lizard_free(struct lizard_buffer *buf);
Return memory used by a lizard_buffer. It frees even the data stored in it (the result of lizard_decompress_safe() call that used this buffer).
byte *lizard_decompress_safe(const byte *in, struct lizard_buffer *buf, uint expected_length);
This one acts much like lizard_decompress(). The difference is it checks the data to be of correct length (therefore it will not crash on invalid data).
It decompresses data provided by in. The buf is used to get the memory for output (you get one by lizard_alloc()).
The pointer to decompressed data is returned. To free it, free the buffer by lizard_free().
In the case of error, NULL is returned. In that case, errno is set either to EINVAL (expected_length does not match) or to EFAULT (a segfault has been caught while decompressing — it probably means expected_length was set way too low). Both cases suggest either wrongly computed length or data corruption.
The buf argument may be reused for multiple decompresses. However, the data will be overwritten by the next call.
Beware this function is not thread-safe and is not even reentrant (because of internal segfault handling).
Adler-32 checksum
This is here because it is commonly used to check data compressed by LiZaRd. However, it could also belong to hashing routines.
uint adler32_update(uint adler, const byte *ptr, uint len);
Update the Adler-32 checksum with more data. adler is the old value, byte points to len bytes of data to update with. Result is returned.
static inline uint adler32(const byte *buf, uint len);
Compute the Adler-32 checksum of a block of data.