[ViewVC] Annotation of: cvs/Compress-LZF/README

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

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;

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 *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.

FUNCTIONS
  $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.

  $decompressed = decompress $compressed
    Uncompress the string (compressed by "compress") and return the original
    data. Decompression errors can result in either broken data (there is no
    checksum kept) or a runtime error.

  $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:

      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 "sfreeze" functions will enlarge the original data one byte at most
    and will only load the Storable method when neccessary.

  $serialized = sfreeze_c $value (sfreeze and compress)
    Similar to "sfreeze", but always tries to "c"ompress the resulting
    string. This still leaves most small objects (most numbers) untouched.

  $serialized = sfreeze_cr $value (sfreeze and compress references)
    Similar to "sfreeze", but tries to "c"ompress the resulting string
    unless it's a "simple" string. References for example are not "simple"
    and as such are being compressed.

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

  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.

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/

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

BUGS
Revision:	1.2
Committed:	Fri Jul 7 15:47:10 2006 UTC (17 years, 10 months ago) by root
Branch:	MAIN
CVS Tags:	rel-1_71, rel-1_8, rel-1_7
Changes since 1.1:	+3 -3 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	NAME
2	root	1.2	Compress::LZF - extremely light-weight Lempel-Ziv-Free compression
3	root	1.1
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 incoporating 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			Try to compress the given string as quickly and as much as possible. In
34			the worst case, the string can enlarge by 1 byte, but that should be the
35			absolute exception. You can expect a 45% compression ratio on large,
36			binary strings.
37
38			$decompressed = decompress $compressed
39			Uncompress the string (compressed by "compress") and return the original
40			data. Decompression errors can result in either broken data (there is no
41			checksum kept) or a runtime error.
42
43			$serialized = sfreeze $value (simplified freeze)
44			Often there is the need to serialize data into a string. This function
45			does that, by using the Storable module. It does the following
46			transforms:
47
48			undef (the perl undefined value)
49			=> a special cookie (undef'ness is being preserved)
50			IV, NV, PV (i.e. a _plain_ perl scalar):
51			=> stays as is when it contains normal text/numbers
52			=> gets serialized into a string
53			RV, undef, other funny objects (magical ones for example):
54			=> data structure is freeze'd into a string.
55
56			That is, it tries to leave "normal", human-readable data untouched but
57			still serializes complex data structures into strings. The idea is to
58			keep readability as high as possible, and in cases readability can't be
59			helped anyways, it tries to compress the string.
60
61			The "sfreeze" functions will enlarge the original data one byte at most
62			and will only load the Storable method when neccessary.
63
64			$serialized = sfreeze_c $value (sfreeze and compress)
65			Similar to "sfreeze", but always tries to "c"ompress the resulting
66			string. This still leaves most small objects (most numbers) untouched.
67
68			$serialized = sfreeze_cr $value (sfreeze and compress references)
69			Similar to "sfreeze", but tries to "c"ompress the resulting string
70			unless it's a "simple" string. References for example are not "simple"
71			and as such are being compressed.
72
73			$original_data = sthaw $serialized
74			Recreate the original object from it's serialized representation. This
75			function automatically detects all the different sfreeze formats.
76
77			Compress::LZF::set_serializer $package, $freeze, $thaw
78			Set the serialize module and functions to use. The default is
79	root	1.2	"Storable", "Storable::net_mstore" and "Storable::mretrieve", which
80			should be fine for most purposes.
81	root	1.1
82			SEE ALSO
83			Other Compress::* modules, especially Compress::LZV1 (an older, less
84			speedy module that guarentees only 1 byte overhead worst case) and
85			Compress::Zlib.
86
87			http://liblzf.plan9.de/
88
89			AUTHOR
90			This perl extension and the underlying liblzf were written by Marc
91			Lehmann <schmorp@schmorp.de> (See also http://liblzf.plan9.de/).
92
93			BUGS