| 1 |
NAME |
| 2 |
Compress::LZF - extremely light-weight Lempel-Ziv-Free compression |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
# import compress/decompress functions |
| 6 |
use Compress::LZF; |
| 7 |
# the same as above |
| 8 |
use Compress::LZF ':compress'; |
| 9 |
|
| 10 |
$compressed = compress $uncompressed_data; |
| 11 |
$original_data = decompress $compressed; |
| 12 |
|
| 13 |
# import sfreeze, sfreeze_cref and sfreeze_c |
| 14 |
use Compress::LZF ':freeze'; |
| 15 |
|
| 16 |
$serialized = sfreeze_c [4,5,6]; |
| 17 |
$original_data = sthaw $serialized; |
| 18 |
|
| 19 |
DESCRIPTION |
| 20 |
LZF is an extremely fast (not that much slower than a pure memcpy) |
| 21 |
compression algorithm. It is ideal for applications where you want to |
| 22 |
save *some* space but not at the cost of speed. It is ideal for |
| 23 |
repetitive data as well. The module is self-contained and very small (no |
| 24 |
large library to be pulled in). It is also free, so there should be no |
| 25 |
problems incorporating this module into commercial programs. |
| 26 |
|
| 27 |
I have no idea wether any patents in any countries apply to this |
| 28 |
algorithm, but at the moment it is believed that it is free from any |
| 29 |
patents. |
| 30 |
|
| 31 |
FUNCTIONS |
| 32 |
$compressed = compress $uncompressed |
| 33 |
$compressed = compress_best $uncompressed |
| 34 |
Try to compress the given string as quickly and as much as possible. |
| 35 |
In the worst case, the string can enlarge by 1 byte, but that should |
| 36 |
be the absolute exception. You can expect a 45% compression ratio on |
| 37 |
large, binary strings. |
| 38 |
|
| 39 |
The "compress_best" function uses a different algorithm that is |
| 40 |
slower but usually achieves better compression. |
| 41 |
|
| 42 |
$decompressed = decompress $compressed |
| 43 |
Uncompress the string (compressed by "compress") and return the |
| 44 |
original data. Decompression errors can result in either broken data |
| 45 |
(there is no checksum kept) or a runtime error. |
| 46 |
|
| 47 |
$serialized = sfreeze $value (simplified freeze) |
| 48 |
$serialized = sfreeze_best $value |
| 49 |
Often there is the need to serialize data into a string. This |
| 50 |
function does that, by using the Storable module. It does the |
| 51 |
following transforms: |
| 52 |
|
| 53 |
undef (the perl undefined value) |
| 54 |
=> a special cookie (undef'ness is being preserved) |
| 55 |
IV, NV, PV (i.e. a _plain_ perl scalar): |
| 56 |
=> stays as is when it contains normal text/numbers |
| 57 |
=> gets serialized into a string |
| 58 |
RV, undef, other funny objects (magical ones for example): |
| 59 |
=> data structure is freeze'd into a string. |
| 60 |
|
| 61 |
That is, it tries to leave "normal", human-readable data untouched |
| 62 |
but still serializes complex data structures into strings. The idea |
| 63 |
is to keep readability as high as possible, and in cases readability |
| 64 |
can't be helped anyways, it tries to compress the string. |
| 65 |
|
| 66 |
The "sfreeze" functions will enlarge the original data one byte at |
| 67 |
most and will only load the Storable method when neccessary. |
| 68 |
|
| 69 |
The "sfreeze_best" function uses a different algorithm that is |
| 70 |
slower but usually achieves better compression. |
| 71 |
|
| 72 |
$serialized = sfreeze_c $value (sfreeze and compress) |
| 73 |
$serialized = sfreeze_c_best $value |
| 74 |
Similar to "sfreeze", but always tries to "c"ompress the resulting |
| 75 |
string. This still leaves most small objects (most numbers) |
| 76 |
untouched. |
| 77 |
|
| 78 |
The "sfreeze_c" function uses a different algorithm that is slower |
| 79 |
but usually achieves better compression. |
| 80 |
|
| 81 |
$serialized = sfreeze_cr $value (sfreeze and compress references) |
| 82 |
$serialized = sfreeze_cr_best $value |
| 83 |
Similar to "sfreeze", but tries to "c"ompress the resulting string |
| 84 |
unless it's a "simple" string. References for example are not |
| 85 |
"simple" and as such are being compressed. |
| 86 |
|
| 87 |
The "sfreeze_cr_best" function uses a different algorithm that is |
| 88 |
slower but usually achieves better compression. |
| 89 |
|
| 90 |
$original_data = sthaw $serialized |
| 91 |
Recreate the original object from it's serialized representation. |
| 92 |
This function automatically detects all the different sfreeze |
| 93 |
formats. |
| 94 |
|
| 95 |
Compress::LZF::set_serializer $package, $freeze, $thaw |
| 96 |
Set the serialize module and functions to use. The default is |
| 97 |
"Storable", "Storable::net_mstore" and "Storable::mretrieve", which |
| 98 |
should be fine for most purposes. |
| 99 |
|
| 100 |
SUPPORT FOR THE PERL MULTICORE SPECIFICATION |
| 101 |
This module supports the perl multicore specification |
| 102 |
(<http://perlmulticore.schmorp.de/>) for all compression (> 2000 octets) |
| 103 |
and decompression (> 4000 octets) functions. |
| 104 |
|
| 105 |
SEE ALSO |
| 106 |
Other Compress::* modules, especially Compress::LZV1 (an older, less |
| 107 |
speedy module that guarentees only 1 byte overhead worst case) and |
| 108 |
Compress::Zlib. |
| 109 |
|
| 110 |
http://liblzf.plan9.de/ |
| 111 |
|
| 112 |
AUTHOR |
| 113 |
This perl extension and the underlying liblzf were written by Marc |
| 114 |
Lehmann <schmorp@schmorp.de> (See also http://liblzf.plan9.de/). |
| 115 |
|
| 116 |
BUGS |
