qccenthuffmantable.3

spiht for linux this is used to decod and encode vedio i wich all enjoy

.TH QCCENTHUFFMANTABLE 3 "QCCPACK" ""
.SH NAME
QccENTHuffmanTable \- 
data structure 
.B QccENTHuffmanTable
and corresponding
.B HUF
file format
for Huffman encoding and decoding
.SH SYNOPSIS
.B #include "libQccPack.h"
.sp
.BI "int QccENTHuffmanTableInitialize(QccENTHuffmanTable *" table );
.br
.BI "int QccENTHuffmanTableAlloc(QccENTHuffmanTable *" table );
.br
.BI "void QccENTHuffmanTableFree(QccENTHuffmanTable *" table );
.br
.BI "int QccENTHuffmanTablePrint(const QccENTHuffmanTable *" table );
.br
.BI "int QccENTHuffmanTableRead(QccENTHuffmanTable *" table );
.br
.BI "int QccENTHuffmanTableWrite(QccENTHuffmanTable *" table );
.SH DESCRIPTION
QccPack provides data structure
.B QccENTHuffmanTable
for representing the Huffman code table to use in Huffman encoding and
decoding.
.LP
The main component of a
.B QccENTHuffmanTable
is an array of
.B QccENTHuffmanTableEntry
entries (see below).  Each of these entries contain a source symbol
(an integer) and its correspoding Huffman codeword.
.SH "DATA STRUCTURE"
The
.B QccENTHuffmanTable
data structure is defined as:
.RS
.nf

typedef struct
{
  QccString filename;
  QccString magic_num;
  int major_version;
  int minor_version;
  int table_type;
  int table_length;
  QccENTHuffmanTableEntry *table;
  int *num_codewords_list;
  int num_codewords_list_length;
  int *symbol_list;
  int symbol_list_length;
  int codeword_max[QCCENTHUFFMAN_MAXCODEWORDLEN];
  int codeword_min[QCCENTHUFFMAN_MAXCODEWORDLEN];
  int codeword_ptr[QCCENTHUFFMAN_MAXCODEWORDLEN];
} QccENTHuffmanTable;
.fi
.RE
.LP
The fields of
.B QccENTHuffmanTable
are as follows:
.TP
.I filename
For tables associated with a file, this is the name of the file.
.TP
.IR magic_num ", " major_version ", " minor_version
For tables associated with a file, these are
the magic number and version of the file.
.TP
.I table_type
the type of the table, 
.B QCCENTHUFFMAN_DECODETABLE 
for a decoding table,
.B QCCENTHUFFMAN_ENCODETABLE
for an encoding table.
.TP
.I table_length
the number of entries in the table
.TP
.I table
the table of symbols and codewords
.TP
.IR num_codewords_list ", " num_codewords_list_length ,
.IR symbol_list ", " symbol_list_length
arrays and array lengths used for creating the Huffman table;
see
.BR QccENTHuffmanTableCreateDecodeTable (3)
.TP
.IR codeword_max ", " codeword_min ", " codeword_ptr
auxiliary arrays used for 
.B QCCENTHUFFMAN_DECODETABLE
type tables for the Huffman decoding process
(for internal QccPack use only)
.LP
The
.B QccENTHuffmanTableEntry
data structure, used to hold source symbols and their
corresponding codewords is defined as:
.RS
.nf

typedef struct
{
  int symbol;
  QccENTHuffmanCodeword codeword;
} QccENTHuffmanTableEntry;
.fi
.RE
.LP
The fields of
.B QccENTHuffmanTableEntry
are as follows:
.TP
.I symbol
the source symbol represented as an integer greater than or equal to 0
and less than or equal to
.B QCCENTHUFFMAN_MAXSYMBOL
.TP
.I codeword
the Huffman codeword
.LP
The
.B QccENTHuffmanCodeword
data structure, used to hold the Huffman codeword itself,
is defined as:
.RS
.nf

typedef struct
{
  int length;
  int codeword;
} QccENTHuffmanCodeword;
.RE
.LP
The fields of
.B QccENTHuffmanCodeword
are as follows:
.TP
.I length
the length, in bits, of the codeword
.TP
.I codeword
the actual Huffman codeword, stored in the least-significant
.I length
bits of the
.I codeword
integer; the most-significant bit of the Huffman codeword (i.e.,
at the "root" of the Huffman tree and the first bit to be output
during the encoding of the corresponding symbol) is stored in the
left-most position
.SH "FILE FORMAT"
For reading and writing structures
of type
.BR QccENTHuffmanTable ,
QccPack provides the
.B HUF
file format.
This file format starts with an ASCII header followed by
ASCII data.
The ASCII header consists of magic-number/revision
information
followed by any amount of white space
(space, `\\t' (tab), `\\n' (newline), `\\r' (return)) and/or
comments lines (lines starting with `#').  Following this white space,
additional ASCII
header information is given, separated by blanks and newlines.
ASCII data follows this ASCII header information.
.LP
The
.B HUF
file format consists of the following information:
.RS
.sp
.BI HUF X.X
.br
.I "<white space>"
.br
.I num_codewords_list_length
.br
.I symbol_list_length
.br
.I num_codewords_list
.br
\|.
.br
\|.
.br
\|.
.br
.I symbol_list
.br
\|.
.br
\|.
.br
\|.
.br
.sp
.RE
where
.B HUF
is the magic number,
.I X.X
is the version number,
.I "<white space>"
is white space and/or 
comment lines, 
.I num_codewords_list_length
is the length of the 
.I num_codewords_list
to appear later in the file,
and
.I symbol_list_length
is the length of the
.I symbol_list
to appear later in the file.
.I num_codewords_list
is the list of the number of codewords, starting with length 1.
.I symbol_list
is the list of symbols (in decimal integers) corresponding to the codewords.
.LP
For example, if the Huffman table has the following symbols and
codewords,
.RS
.nf

  Symbol     Codeword Length      Codeword
-------------------------------------------
   'a'              2                00
   'b'              2                01
   'c'              3                100
   'd'              4                1010
   'e'              4                1011

.fi
.RE
the corresponding
.BR HUF -format
file would be:
.RS
.nf

HUFX.X
# Optional comment(s) here
4
5
0               <----- Start with length = 1
2
1
2
97              <----- Decimal integer representation of symbols
98
99
100
101

.fi
.RE
Note: the stuff starting with the "<----" arrows is merely 
an annotation and is not actually a legal part of the file.
.SH "ROUTINES"
.B QccENTHuffmanTableInitialize()
should be called before any use of a
.B QccENTHuffmanTable
structure.
.B QccENTHuffmanTableInitialize()
initializes the fields of
.I table
to the following values:
.RS

.IR table_type :
.B QCCENTHUFFMAN_DECODETABLE
.br
.IR table :
.B NULL
.br
.IR table_length :
0
.RE
.LP
.B QccENTHuffmanTableAlloc()
allocates the Huffman table. 
.I table_length
must be set before calling
.BR QccENTHuffmanTableAlloc() .
.LP
.B QccENTHuffmanTableFree()
frees the 
.I table
array.
.LP
.B QccENTHuffmanTablePrint()
prints the contents of
.I table
to stdout.
.LP
.BR QccENTHuffmanTableRead()
reads a Huffman table from a 
.BR HUF -format
file.
.I table
is returned as either a decoding or encoding table; set
.IR table -> table_type
to either
.B QCCENTHUFFMAN_ENCODETABLE
or
.BR QCCENTHUFFMAN_DECODETABLE ,
respectively,
before calling
.BR QccENTHuffmanTableRead() .
.BR QccENTHuffmanTableRead()
reads the list of numbers of codewords and the list of symbols from
the file whose name is given by
.IR table -> filename
(must be set before calling
.BR QccENTHuffmanTableRead() )
and then calls either
.BR QccENTHuffmanTableCreateEncodeTable (3)
or
.BR QccENTHuffmanTableCreateDecodeTable (3),
as appropriate,
to generate the actual table,
.IR table -> table ,
of Huffman codewords.
.LP
.BR QccENTHuffmanTableWrite()
writes the Huffman table,
.IR table ,
to the 
.BR HUF -format
file whose name is given in
.IR table -> filename .
Usually, 
.I table
will be either an encoding table
.RI ( table -> table_type
=
.BR QCCENTHUFFMAN_ENCODETABLE )
or a decoding table
.RI ( table -> table_type
=
.BR QCCENTHUFFMAN_DECODETABLE )
that was created by a call to
.BR QccENTHuffmanDesign (3).
.SH "RETURN VALUE"
These routines return 0 on success, and 1 on failure.
.SH "SEE ALSO"
.BR QccENTHuffmanTableCreateDecodeTable (3),
.BR QccENTHuffmanTableCreateEncodeTable (3),
.BR QccENTHuffmanDecode (3),
.BR QccENTHuffmanEncode (3),
.BR QccENTHuffmanDesign (3),
.BR QccPackENT (3),
.BR QccPack (3)
.LP
D. A. Huffman, "A Method for the Construction of Minimum-Redundancy Codes,"
.IR "Proceedings of the IRE" ,
vol. 40, pp. 1098-1101, September 1952.
.SH AUTHOR
Copyright (C) 1997-2009  James E. Fowler
.\"  The programs herein are free software; you can redistribute them an.or
.\"  modify them under the terms of the GNU General Public License
.\"  as published by the Free Software Foundation; either version 2
.\"  of the License, or (at your option) any later version.
.\"  
.\"  These programs are distributed in the hope that they will be useful,
.\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"  GNU General Public License for more details.
.\"  
.\"  You should have received a copy of the GNU General Public License
.\"  along with these programs; if not, write to the Free Software
.\"  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.