fastlzlib.txt

Fastlzlib readme file

What the library does
---------------------

Fastlzlib is a zlib-like library created by Exalead SA., using fast block
compression, such as LZ4 or fastLZ.

The API is nearly identical to the zlib one, and uses the same types and
error codes. The file "fastlzlib-zlib.h" can even be used for testing purpose,
to provide zlib compatible support to programs using it, without the need
of modifying the code.

Stream description
------------------

Streams are made of contiguous compressed blocks, terminated by an empty
compressed block (which is an EOF marker).

Each compressed block has an header at the begining, little endian, 

#define BLOCK_TYPE_RAW         0x1
#define BLOCK_TYPE_COMPRESSED  0xc

struct fastlzlib_header {
  Bytef magic[7];          /* "FastLZ\0" (7 bytes) */
  Bytef packed_type;       /* type + block size power offset (8-bit) */
  uInt compressed_size;    /* compressed size (32-bit) */
  uInt uncompressed_size;  /* uncompressed size (32-bit) */
} fastlzlib_header;

The packed_type member is a 8-bit value, the left four bits is the block type
(see BLOCK_TYPE* values), and the right four bits is the block size power
offset, that is, ( log2(block_size) - 10 )

The EOF marker is identified by compressed_size == 0 and uncompressed_size == 0.
The block_size member is constant for a given stream, and is only informational.

Immediately following the header, lies the compressed raw stream block.

struct fastlzlib_stream {
  fastlzlib_header header;
  Bytef compressed_data[]; /* 'compressed_size' bytes */
} fastlzlib_stream;

The complete block size is sizeof(fastlzlib_header) + compressed_size, and
sizeof(fastlzlib_header) == 16.

The header can be used to seek efficiently to a given uncompressed stream
position, by reading headers and skipping compressed data without reading it
until the desired block is reached.

Note: the uncompressed size is 32-bit, but MUST be lower than the block size
in use for the stream. A stream larger than the block size will be splitted
in several blocks. There is no limit on the number of blocks a stream can
embed.

RAW compressed stream description
---------------------------------

type == BLOCK_TYPE_RAW
The raw stream is uncompressed ; this type is used for blocks too small to be
compressed (64 bytes or less)

type == BLOCK_TYPE_COMPRESSED
The raw stream is compressed using a block compression method. See LZ4/FastLZ
reference for more information on the respective algorithm used.

License
-------

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Copyright
---------

library code is copyright (C) 2010-2013 Exalead SA. (http://www.exalead.com/)
LZ4 code is copyright (C) 2012 Yann Collet (yann.collet.73@gmail.com)
fastLZ code is copyright (C) 2007 Ariya Hidayat (ariya@kde.org)