Compress-LZF/LZF.pm

=head1 NAME

Compress::LZF - extremely light-weight Lempel-Ziv-Free compression

=head1 SYNOPSIS

   # import compress/decompress functions
   use Compress::LZF;
   # the same as above
   use Compress::LZF ':compress';

   $compressed = compress $uncompressed_data;
   $original_data = decompress $compressed;

   # import sfreeze, sfreeze_cref and sfreeze_c
   use Compress::LZF ':freeze';

   $serialized = sfreeze_c [4,5,6];
   $original_data = sthaw $serialized;

=head1 DESCRIPTION

LZF is an extremely fast (not that much slower than a pure memcpy)
compression algorithm. It is ideal for applications where you want to save
I<some> space but not at the cost of speed. It is ideal for repetitive
data as well. The module is self-contained and very small (no large
library to be pulled in). It is also free, so there should be no problems
incorporating this module into commercial programs.

I have no idea wether any patents in any countries apply to this
algorithm, but at the moment it is believed that it is free from any
patents.

=head1 FUNCTIONS

=over 4

=item $compressed = compress $uncompressed

=item $compressed = compress_best $uncompressed

Try to compress the given string as quickly and as much as possible. In
the worst case, the string can enlarge by 1 byte, but that should be the
absolute exception. You can expect a 45% compression ratio on large,
binary strings.

The C<compress_best> function uses a different algorithm that is slower
but usually achieves better compression.

=item $decompressed = decompress $compressed

Uncompress the string (compressed by C<compress>) and return the original
data. Decompression errors can result in either broken data (there is no
checksum kept) or a runtime error.

=item $serialized = sfreeze $value (simplified freeze)

=item $serialized = sfreeze_best $value

Often there is the need to serialize data into a string. This function does that, by using the Storable
module. It does the following transforms:

  undef (the perl undefined value)
     => a special cookie (undef'ness is being preserved)
  IV, NV, PV (i.e. a _plain_ perl scalar):
     => stays as is when it contains normal text/numbers
     => gets serialized into a string
  RV, undef, other funny objects (magical ones for example):
     => data structure is freeze'd into a string.

That is, it tries to leave "normal", human-readable data untouched but
still serializes complex data structures into strings. The idea is to keep
readability as high as possible, and in cases readability can't be helped
anyways, it tries to compress the string.

The C<sfreeze> functions will enlarge the original data one byte at most
and will only load the Storable method when neccessary.

The C<sfreeze_best> function uses a different algorithm that is slower
but usually achieves better compression.

=item $serialized = sfreeze_c $value (sfreeze and compress)

=item $serialized = sfreeze_c_best $value

Similar to C<sfreeze>, but always tries to C<c>ompress the resulting
string. This still leaves most small objects (most numbers) untouched.

The C<sfreeze_c> function uses a different algorithm that is slower
but usually achieves better compression.

=item $serialized = sfreeze_cr $value (sfreeze and compress references)

=item $serialized = sfreeze_cr_best $value

Similar to C<sfreeze>, but tries to C<c>ompress the resulting string
unless it's a "simple" string. References for example are not "simple" and
as such are being compressed.

The C<sfreeze_cr_best> function uses a different algorithm that is slower
but usually achieves better compression.

=item $original_data = sthaw $serialized

Recreate the original object from it's serialized representation. This
function automatically detects all the different sfreeze formats.

=item Compress::LZF::set_serializer $package, $freeze, $thaw

Set the serialize module and functions to use. The default is "Storable",
"Storable::net_mstore" and "Storable::mretrieve", which should be fine for
most purposes.

=back

=head1 SUPPORT FOR THE PERL MULTICORE SPECIFICATION

This module supports the perl multicore specification
(L<http://perlmulticore.schmorp.de/>) for all compression (> 2000 octets) and
decompression (> 4000 octets) functions.

=head1 SEE ALSO

Other Compress::* modules, especially Compress::LZV1 (an older, less
speedy module that guarentees only 1 byte overhead worst case) and
Compress::Zlib.

http://liblzf.plan9.de/

=head1 AUTHOR

This perl extension and the underlying liblzf were written by Marc Lehmann
<schmorp@schmorp.de> (See also http://liblzf.plan9.de/).

=head1 BUGS

=cut

package Compress::LZF;

require Exporter;
require DynaLoader;

$VERSION = 3.8;
@ISA = qw/Exporter DynaLoader/;
%EXPORT_TAGS = (
      freeze   => [qw(sfreeze sfreeze_best sfreeze_cr sfreeze_cr_best sfreeze_c sfreeze_c_best sthaw)],
      compress => [qw(compress compress_best decompress)],
);

Exporter::export_tags('compress');
Exporter::export_ok_tags('freeze');

bootstrap Compress::LZF $VERSION;

1;


Revision:	1.35
Committed:	Mon Jun 29 23:51:28 2015 UTC (8 years, 10 months ago) by root
Branch:	MAIN
CVS Tags:	rel-3_8, HEAD
Changes since 1.34:	+3 -3 lines
Log Message:	3.8
#	Content
1	=head1 NAME
2
3	Compress::LZF - extremely light-weight Lempel-Ziv-Free compression
4
5	=head1 SYNOPSIS
6
7	# import compress/decompress functions
8	use Compress::LZF;
9	# the same as above
10	use Compress::LZF ':compress';
11
12	$compressed = compress $uncompressed_data;
13	$original_data = decompress $compressed;
14
15	# import sfreeze, sfreeze_cref and sfreeze_c
16	use Compress::LZF ':freeze';
17
18	$serialized = sfreeze_c [4,5,6];
19	$original_data = sthaw $serialized;
20
21	=head1 DESCRIPTION
22
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
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
27	library to be pulled in). It is also free, so there should be no problems
28	incorporating this module into commercial programs.
29
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
32	patents.
33
34	=head1 FUNCTIONS
35
36	=over 4
37
38	=item $compressed = compress $uncompressed
39
40	=item $compressed = compress_best $uncompressed
41
42	Try to compress the given string as quickly and as much as possible. In
43	the worst case, the string can enlarge by 1 byte, but that should be the
44	absolute exception. You can expect a 45% compression ratio on large,
45	binary strings.
46
47	The C<compress_best> function uses a different algorithm that is slower
48	but usually achieves better compression.
49
50	=item $decompressed = decompress $compressed
51
52	Uncompress the string (compressed by C<compress>) and return the original
53	data. Decompression errors can result in either broken data (there is no
54	checksum kept) or a runtime error.
55
56	=item $serialized = sfreeze $value (simplified freeze)
57
58	=item $serialized = sfreeze_best $value
59
60	Often there is the need to serialize data into a string. This function does that, by using the Storable
61	module. It does the following transforms:
62
63	undef (the perl undefined value)
64	=> a special cookie (undef'ness is being preserved)
65	IV, NV, PV (i.e. a _plain_ perl scalar):
66	=> stays as is when it contains normal text/numbers
67	=> gets serialized into a string
68	RV, undef, other funny objects (magical ones for example):
69	=> data structure is freeze'd into a string.
70
71	That is, it tries to leave "normal", human-readable data untouched but
72	still serializes complex data structures into strings. The idea is to keep
73	readability as high as possible, and in cases readability can't be helped
74	anyways, it tries to compress the string.
75
76	The C<sfreeze> functions will enlarge the original data one byte at most
77	and will only load the Storable method when neccessary.
78
79	The C<sfreeze_best> function uses a different algorithm that is slower
80	but usually achieves better compression.
81
82	=item $serialized = sfreeze_c $value (sfreeze and compress)
83
84	=item $serialized = sfreeze_c_best $value
85
86	Similar to C<sfreeze>, but always tries to C<c>ompress the resulting
87	string. This still leaves most small objects (most numbers) untouched.
88
89	The C<sfreeze_c> function uses a different algorithm that is slower
90	but usually achieves better compression.
91
92	=item $serialized = sfreeze_cr $value (sfreeze and compress references)
93
94	=item $serialized = sfreeze_cr_best $value
95
96	Similar to C<sfreeze>, but tries to C<c>ompress the resulting string
97	unless it's a "simple" string. References for example are not "simple" and
98	as such are being compressed.
99
100	The C<sfreeze_cr_best> function uses a different algorithm that is slower
101	but usually achieves better compression.
102
103	=item $original_data = sthaw $serialized
104
105	Recreate the original object from it's serialized representation. This
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 (> 2000 octets) and
120	decompression (> 4000 octets) functions.
121
122	=head1 SEE ALSO
123
124	Other Compress::* modules, especially Compress::LZV1 (an older, less
125	speedy module that guarentees only 1 byte overhead worst case) and
126	Compress::Zlib.
127
128	http://liblzf.plan9.de/
129
130	=head1 AUTHOR
131
132	This perl extension and the underlying liblzf were written by Marc Lehmann
133	<schmorp@schmorp.de> (See also http://liblzf.plan9.de/).
134
135	=head1 BUGS
136
137	=cut
138
139	package Compress::LZF;
140
141	require Exporter;
142	require DynaLoader;
143
144	$VERSION = 3.8;
145	@ISA = qw/Exporter DynaLoader/;
146	%EXPORT_TAGS = (
147	freeze => [qw(sfreeze sfreeze_best sfreeze_cr sfreeze_cr_best sfreeze_c sfreeze_c_best sthaw)],
148	compress => [qw(compress compress_best decompress)],
149	);
150
151	Exporter::export_tags('compress');
152	Exporter::export_ok_tags('freeze');
153
154	bootstrap Compress::LZF $VERSION;
155
156	1;
157
158
159
160
161