forked from MichaelDipperstein/huffman
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathREADME
More file actions
157 lines (139 loc) · 6.65 KB
/
Copy pathREADME
File metadata and controls
157 lines (139 loc) · 6.65 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
DESCRIPTION
-----------
This archive contains a simple and readable ANSI C implementation of Huffman
coding and decoding. This implementation is not intended to be the best,
fastest, smallest, or any other performance related adjective.
More information on Huffman encoding may be found at:
https://michaeldipperstein.github.io/huffman.html
FILES
-----
canonical.c - Huffman encoding and decoding routines using canonical codes
COPYING - Rules for copying and distributing GPL software
COPYING.LESSER - Rules for copying and distributing LGPL software
huffman.c - Huffman encoding and decoding routines
huffman.h - Header file used by code calling library functions
huflocal.h - Header file with internal library definitions common to both
canonical and conventional techniques
huflocal.c - File with internal library functions common to both canonical
and conventional techniques
Makefile - makefile for this project (assumes gcc compiler and GNU make)
README - this file
sample.c - Demonstration of how to use Huffman library functions
optlist/ - Subtree containing optlist command line option parser library
bitfile/ - Subtree containing bitfile bitwise file library
bitarray/ - Subtree containing bitarray bitwise array library
BUILDING
--------
To build these files with GNU make and gcc, simply enter "make" from the
command line.
USAGE
-----
Usage: sample <options>
options:
-C : Encode/Decode using a canonical code.
-c : Encode input file to output file.
-d : Decode input file to output file.
-t : Generate code tree for input file to output file.
-i <filename> : Name of input file.
-o <filename> : Name of output file.
-h|? : Print out command line options.
-C Uses a canonical Huffman code (canonical.c).
-c Generates a Huffman tree for the specified input file (see -i) and
compresses a file using the tree to the specified output file (see -o).
-d Decompresses the specified input file (see -i) writing the results to
the specified output file (see -o). Only files compressed by this
program may be decompressed.
-t Generates a Huffman tree for the specified input file (see -i) and
writes the resulting code to the specified output file (see -o).
-i <filename> The name of the input file. There is no valid usage of this
program without a specified input file.
-o <filename> The name of the output file. If no file is specified, stdout
will be used. NOTE: Sending compressed output to stdout may
produce undesirable results.
LIBRARY API
-----------
Encoding Data (Traditional or Canonical codes):
int HuffmanEncodeFile(FILE *inFile, FILE *outFile);
int CanonicalEncodeFile(FILE *inFile, FILE *outFile);
inFile
The file stream to be encoded. It must be rewindable and opened.
NULL pointers will return an error.
outFile
The file stream receiving the encoded results. It must be opened. NULL
pointers will return an error.
Return Value
Zero for success, -1 for failure. Error type is contained in errno. Files
will remain open.
Decoding Data (Traditional or Canonical codes):
int HuffmanDecodeFile(FILE *inFile, FILE *outFile);
int CanonicalDecodeFile(FILE *inFile, FILE *outFile);
inFile
The file stream to be decoded. It must be opened. NULL pointers will
return an error.
outFile
The file stream receiving the decoded results. It must be opened. NULL
pointers will return an error.
Return Value
Zero for success, -1 for failure. Error type is contained in errno. Files
will remain open.
Displaying a Tree Generated by Algorithm (Traditional or Canonical codes):
int HuffmanShowTree(FILE *inFile, FILE *outFile);
int CanonicalShowTree(FILE *inFile, FILE *outFile);
inFile
The file stream that a tree will be generated for. It must be opened.
NULL pointers will return an error.
outFile
The file stream that the tree will be sent to. It must be opened. NULL
pointers will return an error. It is perfectly acceptable to use stdout.
Return Value
Zero for success, -1 for failure. Error type is contained in errno. Files
will remain open.
HISTORY
-------
10/23/03 - Corrected errors which occurred when encoding and decoding files
containing a single symbol.
- Modified canonical version to dynamically allocate the array used
to store the canonical list of codes.
- Use $(OS) environment variable to determine operating system in
Makefile.
11/20/03 - Correctly handle symbol codes that are over 16 bits long. These
changes can handle codes up to 255 bits long.
01/05/04 - Encode EOF along with other symbols
01/12/04 - Use bit stream file library
02/02/04 - Use bit array library
02/25/04 - Make huffman.c and chuffman.c more library like by removing main
and adding a header file with prototypes for encode/decode
functions.
- Add sample usage of functions.
06/14/04 - Use latest version of bitfile.c.
- Make routines local to huffman.c and chuffman.c static so that
they may be called from the same program.
- Include use of canonical and traditional Huffman codes in
sample program.
05/22/05 - Provides single declaration for items common canonical and
traditional encoding source
- Makefile builds libraries for easier LGPL compliance.
06/21/05 - Corrected BitFileGetBits/PutBits error that accessed an extra
byte when given an integral number of bytes.
08/29/07 - Explicitly licensed under LGPL version 3.
- Replaces getopt() with optlist library.
06/08/08 - Incorporates Emanuele Giaquinta's patch to eliminate redundant
check during the canonical decode process.
08/24/14 - Restructured code for cleaner Traditional/Canonical separation
11/18/14 - Changed the API so that encode and decode routines accept opened
file streams instead of file names.
- Changed return value to 0 for success and -1 for failure with
reason in errno.
- Upgraded to latest oplist and bitfile libraries.
- Tighter adherence to Michael Barr's "Top 10 Bug-Killing Coding
Standard Rules" (http://www.barrgroup.com/webinars/10rules).
07/16/17 - Changes for easier use with GitHub
TODO
----
- Provide a command line option to change symbol size.
- Implement bijective scheme for ending file on byte boundary without
counting the number of encoded symbols encoded (http://bijective.dogma.net/).
AUTHOR
------
Michael Dipperstein (mdipperstein@gmail.com)
https://michaeldipperstein.github.io