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

FUNCTIONS
    $compressed = compress $uncompressed
    $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 "compress_best" function uses a different algorithm that is
        slower but usually achieves better compression.

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

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

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

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

    $serialized = sfreeze_cr $value (sfreeze and compress references)
    $serialized = sfreeze_cr_best $value
        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.

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

    $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.4
Committed:	Sun Aug 25 18:13:26 2013 UTC (10 years, 8 months ago) by root
Branch:	MAIN
CVS Tags:	rel-3_7
Changes since 1.3:	+67 -49 lines
Log Message:	3.7
#	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	root	1.3	problems incorporating this module into commercial programs.
26	root	1.1
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	root	1.4	$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	root	1.1
100			SEE ALSO
101			Other Compress::* modules, especially Compress::LZV1 (an older, less
102			speedy module that guarentees only 1 byte overhead worst case) and
103			Compress::Zlib.
104
105			http://liblzf.plan9.de/
106
107			AUTHOR
108			This perl extension and the underlying liblzf were written by Marc
109			Lehmann <schmorp@schmorp.de> (See also http://liblzf.plan9.de/).
110
111			BUGS