Compress-LZF/LZF.pm

=head1 NAME

Compress::LZF - extremely leight-weight Lev-Zimpel-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
incoporating 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

=head2 $compressed = compress $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.

=head2 $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.

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

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:

  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 of all these C<sfreeze> functions 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.

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

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

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

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.

=head2 $original_data = sthaw $serialized

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

=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
<pcg@goof.com> (See also http://liblzf.plan9.de/).

=head1 BUGS

=cut

package Compress::LZF;

require Exporter;
require DynaLoader;

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

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

bootstrap Compress::LZF $VERSION;

1;


Revision:	1.2
Committed:	Thu Sep 27 19:51:24 2001 UTC (22 years, 7 months ago) by root
Branch:	MAIN
Changes since 1.1:	+39 -2 lines
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	Compress::LZF - extremely leight-weight Lev-Zimpel-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	incoporating 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	=head2 $compressed = compress $uncompressed
37
38	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
40	absolute exception. You can expect a 45% compression ratio on large,
41	binary strings.
42
43	=head2 $decompressed = decompress $compressed
44
45	Uncompress the string (compressed by C<compress>) and return the original
46	data. Decompression errors can result in either broken data (there is no
47	checksum kept) or a runtime error.
48
49	=head2 $serialized = sfreeze $value (simplified freeze)
50
51	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:
53
54	IV, NV, PV (i.e. a _plain_ perl scalar):
55	=> stays as is when it contains normal text/numbers
56	=> gets serialized into a string
57	RV, undef, other funny objects (magical ones for example):
58	=> data structure is freeze'd into a string.
59
60	That is, it tries to leave "normal", human-readable data untouched but
61	still serializes complex data structures into strings.
62
63	The idea of all these C<sfreeze> functions is to keep readability as high
64	as possible, and in cases readability can't be helped anyways, it tries to
65	compress the string.
66
67	The C<sfreeze> functions will enlarge the original data one byte at most
68	and will only load the Storable method when neccessary.
69
70	=head2 $serialized = sfreeze_c $value (sfreeze and compress)
71
72	Similar to C<sfreeze>, but always tries to C<c>ompress the resulting
73	string. This still leaves most small objects (most numbers) untouched.
74
75	=head2 $serialized = sfreeze_cr $value (sfreeze and compress references)
76
77	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
79	as such are being compressed.
80
81	=head2 $original_data = sthaw $serialized
82
83	Recreate the original object from it's serialized representation. This
84	function automatically detects all the different sfreeze formats.
85
86	=head1 SEE ALSO
87
88	Other Compress::* modules, especially Compress::LZV1 (an older, less
89	speedy module that guarentees only 1 byte overhead worst case) and
90	Compress::Zlib.
91
92	http://liblzf.plan9.de/
93
94	=head1 AUTHOR
95
96	This perl extension and the underlying liblzf were written by Marc Lehmann
97	<pcg@goof.com> (See also http://liblzf.plan9.de/).
98
99	=head1 BUGS
100
101	=cut
102
103	package Compress::LZF;
104
105	require Exporter;
106	require DynaLoader;
107
108	$VERSION = 0.1;
109	@ISA = qw/Exporter DynaLoader/;
110	%EXPORT_TAGS = (
111	freeze => [qw(sfreeze sfreeze_cr sfreeze_c sthaw)],
112	compress => [qw(compress decompress)],
113	);
114
115	Exporter::export_tags('compress');
116	Exporter::export_ok_tags('freeze');
117
118	bootstrap Compress::LZF $VERSION;
119
120	1;
121
122
123
124
125