1 | =head1 NAME |
1 | =head1 NAME |
2 | |
2 | |
3 | Compress::LZF - extremely leight-weight Lev-Zimpel-Free compression |
3 | Compress::LZF - extremely light-weight Lempel-Ziv-Free compression |
4 | |
4 | |
5 | =head1 SYNOPSIS |
5 | =head1 SYNOPSIS |
6 | |
6 | |
7 | # import compress/decompress functions |
7 | # import compress/decompress functions |
8 | use Compress::LZF; |
8 | use Compress::LZF; |
… | |
… | |
23 | LZF is an extremely fast (not that much slower than a pure memcpy) |
23 | LZF is an extremely fast (not that much slower than a pure memcpy) |
24 | compression algorithm. It is ideal for applications where you want to save |
24 | compression algorithm. It is ideal for applications where you want to save |
25 | I<some> space but not at the cost of speed. It is ideal for repetitive |
25 | I<some> space but not at the cost of speed. It is ideal for repetitive |
26 | data as well. The module is self-contained and very small (no large |
26 | data as well. The module is self-contained and very small (no large |
27 | library to be pulled in). It is also free, so there should be no problems |
27 | library to be pulled in). It is also free, so there should be no problems |
28 | incoporating this module into commercial programs. |
28 | incorporating this module into commercial programs. |
29 | |
29 | |
30 | I have no idea wether any patents in any countries apply to this |
30 | I have no idea wether any patents in any countries apply to this |
31 | algorithm, but at the moment it is believed that it is free from any |
31 | algorithm, but at the moment it is believed that it is free from any |
32 | patents. |
32 | patents. |
33 | |
33 | |
34 | =head1 FUNCTIONS |
34 | =head1 FUNCTIONS |
35 | |
35 | |
|
|
36 | =over 4 |
|
|
37 | |
36 | =head2 $compressed = compress $uncompressed |
38 | =item $compressed = compress $uncompressed |
|
|
39 | |
|
|
40 | =item $compressed = compress_best $uncompressed |
37 | |
41 | |
38 | Try to compress the given string as quickly and as much as possible. In |
42 | Try to compress the given string as quickly and as much as possible. In |
39 | the worst case, the string can enlarge by 1 byte, but that should be the |
43 | the worst case, the string can enlarge by 1 byte, but that should be the |
40 | absolute exception. You can expect a 45% compression ratio on large, |
44 | absolute exception. You can expect a 45% compression ratio on large, |
41 | binary strings. |
45 | binary strings. |
42 | |
46 | |
|
|
47 | The C<compress_best> function uses a different algorithm that is slower |
|
|
48 | but usually achieves better compression. |
|
|
49 | |
43 | =head2 $decompressed = decompress $compressed |
50 | =item $decompressed = decompress $compressed |
44 | |
51 | |
45 | Uncompress the string (compressed by C<compress>) and return the original |
52 | Uncompress the string (compressed by C<compress>) and return the original |
46 | data. Decompression errors can result in either broken data (there is no |
53 | data. Decompression errors can result in either broken data (there is no |
47 | checksum kept) or a runtime error. |
54 | checksum kept) or a runtime error. |
48 | |
55 | |
49 | =head2 $serialized = sfreeze $value (simplified freeze) |
56 | =item $serialized = sfreeze $value (simplified freeze) |
|
|
57 | |
|
|
58 | =item $serialized = sfreeze_best $value |
50 | |
59 | |
51 | Often there is the need to serialize data into a string. This function does that, by using the Storable |
60 | Often there is the need to serialize data into a string. This function does that, by using the Storable |
52 | module. It does the following transforms: |
61 | module. It does the following transforms: |
53 | |
62 | |
54 | undef (the perl undefined value) |
63 | undef (the perl undefined value) |
… | |
… | |
65 | anyways, it tries to compress the string. |
74 | anyways, it tries to compress the string. |
66 | |
75 | |
67 | The C<sfreeze> functions will enlarge the original data one byte at most |
76 | The C<sfreeze> functions will enlarge the original data one byte at most |
68 | and will only load the Storable method when neccessary. |
77 | and will only load the Storable method when neccessary. |
69 | |
78 | |
|
|
79 | The C<sfreeze_best> function uses a different algorithm that is slower |
|
|
80 | but usually achieves better compression. |
|
|
81 | |
70 | =head2 $serialized = sfreeze_c $value (sfreeze and compress) |
82 | =item $serialized = sfreeze_c $value (sfreeze and compress) |
|
|
83 | |
|
|
84 | =item $serialized = sfreeze_c_best $value |
71 | |
85 | |
72 | Similar to C<sfreeze>, but always tries to C<c>ompress the resulting |
86 | Similar to C<sfreeze>, but always tries to C<c>ompress the resulting |
73 | string. This still leaves most small objects (most numbers) untouched. |
87 | string. This still leaves most small objects (most numbers) untouched. |
74 | |
88 | |
|
|
89 | The C<sfreeze_c> function uses a different algorithm that is slower |
|
|
90 | but usually achieves better compression. |
|
|
91 | |
75 | =head2 $serialized = sfreeze_cr $value (sfreeze and compress references) |
92 | =item $serialized = sfreeze_cr $value (sfreeze and compress references) |
|
|
93 | |
|
|
94 | =item $serialized = sfreeze_cr_best $value |
76 | |
95 | |
77 | Similar to C<sfreeze>, but tries to C<c>ompress the resulting string |
96 | Similar to C<sfreeze>, but tries to C<c>ompress the resulting string |
78 | unless it's a "simple" string. References for example are not "simple" and |
97 | unless it's a "simple" string. References for example are not "simple" and |
79 | as such are being compressed. |
98 | as such are being compressed. |
80 | |
99 | |
|
|
100 | The C<sfreeze_cr_best> function uses a different algorithm that is slower |
|
|
101 | but usually achieves better compression. |
|
|
102 | |
81 | =head2 $original_data = sthaw $serialized |
103 | =item $original_data = sthaw $serialized |
82 | |
104 | |
83 | Recreate the original object from it's serialized representation. This |
105 | Recreate the original object from it's serialized representation. This |
84 | function automatically detects all the different sfreeze formats. |
106 | function automatically detects all the different sfreeze formats. |
|
|
107 | |
|
|
108 | =item Compress::LZF::set_serializer $package, $freeze, $thaw |
|
|
109 | |
|
|
110 | Set the serialize module and functions to use. The default is "Storable", |
|
|
111 | "Storable::net_mstore" and "Storable::mretrieve", which should be fine for |
|
|
112 | most purposes. |
|
|
113 | |
|
|
114 | =back |
|
|
115 | |
|
|
116 | =head1 SUPPORT FOR THE PERL MULTICORE SPECIFICATION |
|
|
117 | |
|
|
118 | This module supports the perl multicore specification |
|
|
119 | (L<http://perlmulticore.schmorp.de/>) for all compression and |
|
|
120 | decompression functions. |
85 | |
121 | |
86 | =head1 SEE ALSO |
122 | =head1 SEE ALSO |
87 | |
123 | |
88 | Other Compress::* modules, especially Compress::LZV1 (an older, less |
124 | Other Compress::* modules, especially Compress::LZV1 (an older, less |
89 | speedy module that guarentees only 1 byte overhead worst case) and |
125 | speedy module that guarentees only 1 byte overhead worst case) and |
… | |
… | |
92 | http://liblzf.plan9.de/ |
128 | http://liblzf.plan9.de/ |
93 | |
129 | |
94 | =head1 AUTHOR |
130 | =head1 AUTHOR |
95 | |
131 | |
96 | This perl extension and the underlying liblzf were written by Marc Lehmann |
132 | This perl extension and the underlying liblzf were written by Marc Lehmann |
97 | <pcg@goof.com> (See also http://liblzf.plan9.de/). |
133 | <schmorp@schmorp.de> (See also http://liblzf.plan9.de/). |
98 | |
134 | |
99 | =head1 BUGS |
135 | =head1 BUGS |
100 | |
136 | |
101 | =cut |
137 | =cut |
102 | |
138 | |
103 | package Compress::LZF; |
139 | package Compress::LZF; |
104 | |
140 | |
105 | require Exporter; |
141 | require Exporter; |
106 | require DynaLoader; |
142 | require DynaLoader; |
107 | |
143 | |
108 | $VERSION = 0.1; |
144 | $VERSION = '3.7'; |
109 | @ISA = qw/Exporter DynaLoader/; |
145 | @ISA = qw/Exporter DynaLoader/; |
110 | %EXPORT_TAGS = ( |
146 | %EXPORT_TAGS = ( |
111 | freeze => [qw(sfreeze sfreeze_cr sfreeze_c sthaw)], |
147 | freeze => [qw(sfreeze sfreeze_best sfreeze_cr sfreeze_cr_best sfreeze_c sfreeze_c_best sthaw)], |
112 | compress => [qw(compress decompress)], |
148 | compress => [qw(compress compress_best decompress)], |
113 | ); |
149 | ); |
114 | |
150 | |
115 | Exporter::export_tags('compress'); |
151 | Exporter::export_tags('compress'); |
116 | Exporter::export_ok_tags('freeze'); |
152 | Exporter::export_ok_tags('freeze'); |
117 | |
153 | |