1NAME
2    Compress::LZF - extremely light-weight Lempel-Ziv-Free compression
3
4SYNOPSIS
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
19DESCRIPTION
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
31FUNCTIONS
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
100SUPPORT 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
105SEE 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
112AUTHOR
113    This perl extension and the underlying liblzf were written by Marc
114    Lehmann <schmorp@schmorp.de> (See also http://liblzf.plan9.de/).
115
116BUGS
117