Documento Huffman para Doxy

diff --git a/src/statichuff/statichuff.c b/src/statichuff/statichuff.c
index 916891966611f46a32409f3b11e88df24d0cf3e6..6b3b4d526a5defb62c25d13583993ba811a3934c 100644 (file)
--- a/src/statichuff/statichuff.c
+++ b/src/statichuff/statichuff.c
@@ -3,6 +3,7 @@
 #include <stdlib.h>
 #include <string.h>
 
 #include <stdlib.h>
 #include <string.h>
 

+/** Coloca un bit en un buffer statico */

 void putbit(char bit, char restart, char flush, VFILE *fp)
 {
        static unsigned long int bits_buffer = 0;
 void putbit(char bit, char restart, char flush, VFILE *fp)
 {
        static unsigned long int bits_buffer = 0;


@@ -35,6 +36,7 @@ void putbit(char bit, char restart, char flush, VFILE *fp)
        return;
 }
 
        return;
 }
 

+/** Realiza la copia de los datos de un nodo de huffman a otro */

 void shuff_cpynode(SHUFFNODE *node1, SHUFFNODE *node2)
 {
        node1->symbol = node2->symbol;
 void shuff_cpynode(SHUFFNODE *node1, SHUFFNODE *node2)
 {
        node1->symbol = node2->symbol;


@@ -43,6 +45,7 @@ void shuff_cpynode(SHUFFNODE *node1, SHUFFNODE *node2)
        node1->rchild = node2->rchild;  
 }
 
        node1->rchild = node2->rchild;  
 }
 

+/** Realiza una comparacion de dos nodos de huffman */

 int shuff_compnode(const void *node1, const void *node2)
 {      
        if (((SHUFFNODE*)node1)->freq < ((SHUFFNODE*)node2)->freq) return 1;
 int shuff_compnode(const void *node1, const void *node2)
 {      
        if (((SHUFFNODE*)node1)->freq < ((SHUFFNODE*)node2)->freq) return 1;


@@ -50,6 +53,7 @@ int shuff_compnode(const void *node1, const void *node2)
        return 0;
 }
 
        return 0;
 }
 

+/** Destruye un arbol de huffman recursivamente */

 void shuff_destroy_tree(SHUFFNODE *node) {
        /* Si llegue a una hoja, destruyo y vuelvo */
        if (node->symbol < 256) {
 void shuff_destroy_tree(SHUFFNODE *node) {
        /* Si llegue a una hoja, destruyo y vuelvo */
        if (node->symbol < 256) {


@@ -65,6 +69,7 @@ void shuff_destroy_tree(SHUFFNODE *node) {
        }
 }
 
        }
 }
 

+/** Reescala las frecuencias de huffman a la mitad */

 int shuff_rescalefreq(t_freq *freqtable)
 { 
        int i;
 int shuff_rescalefreq(t_freq *freqtable)
 { 
        int i;


@@ -79,6 +84,7 @@ int shuff_rescalefreq(t_freq *freqtable)
        return totalfreq;
 }
 
        return totalfreq;
 }
 

+/** Escanea las frecuencias de un chunk de datos */

 int shuff_scanfreq_chunk(HUFF_STATE *chunkshuff, char* chunk, int chunksize)
 {      
        /* Locals */                    
 int shuff_scanfreq_chunk(HUFF_STATE *chunkshuff, char* chunk, int chunksize)
 {      
        /* Locals */                    


@@ -104,6 +110,7 @@ int shuff_scanfreq_chunk(HUFF_STATE *chunkshuff, char* chunk, int chunksize)
        return 1;
 }
 
        return 1;
 }
 

+/** Escanea las frecuencias de un archivo y genera el modelo */

 int shuff_scanfreq(char *inputfile, t_freq *freqtable)
 {
        /* Locals */    
 int shuff_scanfreq(char *inputfile, t_freq *freqtable)
 {
        /* Locals */    


@@ -133,6 +140,7 @@ int shuff_scanfreq(char *inputfile, t_freq *freqtable)
        return 1;
 }
 
        return 1;
 }
 

+/** Genera un input list que sera utilizada para generar el arbol */

 SHUFFNODE *shuff_buildlist(t_freq *freqtable, int *nonzerofreqs)
 {
        int i,j = 0,nonzero = 0;        
 SHUFFNODE *shuff_buildlist(t_freq *freqtable, int *nonzerofreqs)
 {
        int i,j = 0,nonzero = 0;        


@@ -156,6 +164,7 @@ SHUFFNODE *shuff_buildlist(t_freq *freqtable, int *nonzerofreqs)
        return inputlist;
 }
 
        return inputlist;
 }
 

+/** Genera el arbol de huffman en base a la tabla de frecuencias */

 SHUFFNODE *shuff_buildtree(t_freq *ftable)
 {
        SHUFFNODE *lastsymbol;
 SHUFFNODE *shuff_buildtree(t_freq *ftable)
 {
        SHUFFNODE *lastsymbol;


@@ -195,6 +204,7 @@ SHUFFNODE *shuff_buildtree(t_freq *ftable)
        return root;
 }
 
        return root;
 }
 

+/** Imprime los codigos prefijos generados para los symbolos */

 void shuff_printcodes(SHUFFCODE *codetable,t_freq *freqtable)
 {
        int i,j;
 void shuff_printcodes(SHUFFCODE *codetable,t_freq *freqtable)
 {
        int i,j;


@@ -216,6 +226,7 @@ void shuff_printcodes(SHUFFCODE *codetable,t_freq *freqtable)
        }
 }
 
        }
 }
 

+/** Inicializa la tabla de codigos prefijos */

 void shuff_zerocodes(SHUFFCODE *table)
 {
        int i;
 void shuff_zerocodes(SHUFFCODE *table)
 {
        int i;


@@ -227,6 +238,7 @@ void shuff_zerocodes(SHUFFCODE *table)
        }
 }
 
        }
 }
 

+/** Genera la tabla de codigos prefijos en base al árbol de huffman */

 void shuff_buildcodes(SHUFFCODE *table, SHUFFNODE *node, int level, int code)
 {
        if (node->symbol < 256) {
 void shuff_buildcodes(SHUFFCODE *table, SHUFFNODE *node, int level, int code)
 {
        if (node->symbol < 256) {


@@ -242,6 +254,7 @@ void shuff_buildcodes(SHUFFCODE *table, SHUFFNODE *node, int level, int code)
        }
 }
 
        }
 }
 

+/** Realiza la compresion / encoding efectivo de un archivo */

 int shuff_encode_symbols(HUFF_STATE *shuff, SHUFFCODE *ctable)
 {
        FILE *fpsource;
 int shuff_encode_symbols(HUFF_STATE *shuff, SHUFFCODE *ctable)
 {
        FILE *fpsource;


@@ -287,6 +300,7 @@ int shuff_encode_symbols(HUFF_STATE *shuff, SHUFFCODE *ctable)
        return 1;       
 }
 
        return 1;       
 }
 

+/** Prepara las estructuras de datos necesarias para una compresion */

 int shuff_encode_file(HUFF_STATE *shuff)
 {
        /* Locals */            
 int shuff_encode_file(HUFF_STATE *shuff)
 {
        /* Locals */            


@@ -313,6 +327,7 @@ int shuff_encode_file(HUFF_STATE *shuff)
        return 1;
 }
 
        return 1;
 }
 

+/** Decodifica una serie de bits en un symbolo y lo devuelve */

 SHUFFNODE *shuff_decode_symbols(SHUFFNODE *entrynode, unsigned long int buffer, 
                                                         int *bitsleft, unsigned short int *symbol)
 {
 SHUFFNODE *shuff_decode_symbols(SHUFFNODE *entrynode, unsigned long int buffer, 
                                                         int *bitsleft, unsigned short int *symbol)
 {


@@ -330,6 +345,7 @@ SHUFFNODE *shuff_decode_symbols(SHUFFNODE *entrynode, unsigned long int buffer,
        else return shuff_decode_symbols(entrynode->rchild,buffer,bitsleft,symbol);
 }
 
        else return shuff_decode_symbols(entrynode->rchild,buffer,bitsleft,symbol);
 }
 

+/** Decodifica chunksize symbolos y los devuelve en un chunk de datos */

 int shuff_decode_chunk(HUFF_STATE *shuff, char *chunk, int chunksize, int *decodedbytes)
 {
        SHUFFNODE *currnode = shuff->codetree;  
 int shuff_decode_chunk(HUFF_STATE *shuff, char *chunk, int chunksize, int *decodedbytes)
 {
        SHUFFNODE *currnode = shuff->codetree;  


@@ -360,6 +376,7 @@ int shuff_decode_chunk(HUFF_STATE *shuff, char *chunk, int chunksize, int *decod
        else return 1;
 }
 
        else return 1;
 }
 

+/** Realiza la descompresión de un archivo comprimido */

 int shuff_decode_file(HUFF_STATE *shuff)
 {      
        SHUFFNODE *currnode;    
 int shuff_decode_file(HUFF_STATE *shuff)
 {      
        SHUFFNODE *currnode;    


@@ -396,6 +413,7 @@ int shuff_decode_file(HUFF_STATE *shuff)
        return 1;
 }
 
        return 1;
 }
 

+/** Inicializa un descompresor de huffman */

 HUFF_STATE *shuff_init_decoder(char *inputfile, char *outputfile)
 {
        /* Locals */
 HUFF_STATE *shuff_init_decoder(char *inputfile, char *outputfile)
 {
        /* Locals */


@@ -424,6 +442,7 @@ HUFF_STATE *shuff_init_decoder(char *inputfile, char *outputfile)
        return shuff;
 }
 
        return shuff;
 }
 

+/** Inicializa compresor de huffman por archivo */

 HUFF_STATE *shuff_init_encoder_byfile(char *inputfile, char *outputfile, long volsize)
 {
        /* Locals */
 HUFF_STATE *shuff_init_encoder_byfile(char *inputfile, char *outputfile, long volsize)
 {
        /* Locals */


@@ -448,6 +467,7 @@ HUFF_STATE *shuff_init_encoder_byfile(char *inputfile, char *outputfile, long vo
        return fshuff;
 }
 
        return fshuff;
 }
 

+/** Inicializa compresor de huffman de a chunks */

 HUFF_STATE *shuff_init_encoder_bychunk(char *outputfile, long volsize)
 {
        /* Locals */
 HUFF_STATE *shuff_init_encoder_bychunk(char *outputfile, long volsize)
 {
        /* Locals */


@@ -475,6 +495,7 @@ HUFF_STATE *shuff_init_encoder_bychunk(char *outputfile, long volsize)
        return cshuff;
 }
 
        return cshuff;
 }
 

+/** Carga un modelo estadistico para huffman */

 int shuff_loadmodel(HUFF_STATE *shuff, char *modelfile) {
 
        FILE *fp;
 int shuff_loadmodel(HUFF_STATE *shuff, char *modelfile) {
 
        FILE *fp;


@@ -490,6 +511,7 @@ int shuff_loadmodel(HUFF_STATE *shuff, char *modelfile) {
        return 0;       
 }
 
        return 0;       
 }
 

+/** Graba un modelo estadístico de huffman */

 int shuff_savemodel(HUFF_STATE *shuff) {
 
        FILE *fp;
 int shuff_savemodel(HUFF_STATE *shuff) {
 
        FILE *fp;


@@ -514,6 +536,7 @@ int shuff_savemodel(HUFF_STATE *shuff) {
        return 0;
 }
 
        return 0;
 }
 

+/** Desinicializa un compresor de huffman */

 void shuff_deinit_encoder(HUFF_STATE *shuff)
 {
        /* Libero mallocs y cierro archivos */
 void shuff_deinit_encoder(HUFF_STATE *shuff)
 {
        /* Libero mallocs y cierro archivos */


@@ -527,6 +550,7 @@ void shuff_deinit_encoder(HUFF_STATE *shuff)
        if (shuff->codetree) shuff_destroy_tree(shuff->codetree);
 }
 
        if (shuff->codetree) shuff_destroy_tree(shuff->codetree);
 }
 

+/** Desinicializa un descompresor de huffman */

 void shuff_deinit_decoder(HUFF_STATE *shuff)
 {
        /* Libero mallocs y cierro archivos */  
 void shuff_deinit_decoder(HUFF_STATE *shuff)
 {
        /* Libero mallocs y cierro archivos */  

diff --git a/src/statichuff/statichuff.h b/src/statichuff/statichuff.h
index 97e8f4cc2026c2488397066201c6649c66993ed5..065b8c39b6bd06ce3e63bce6256842ca2498e669 100644 (file)
--- a/src/statichuff/statichuff.h
+++ b/src/statichuff/statichuff.h
@@ -6,47 +6,139 @@
 #include <unistd.h>
 #include "../vfile/vfile.h"
 
 #include <unistd.h>
 #include "../vfile/vfile.h"
 

+/** \file
+ * Compresor Huffman Estático
+ *
+ * <b>Interfaz del compresor Huffman Estático</b>
+ *
+ * El siguiente compresor permite la compresión/descompresión estadística de un
+ * archivo o bien chunks de datos. Posee tambien como feature opcional, el grabado 
+ * y carga de un modelo estadístico (Tabla de Frecuencias), conocido como Huffman Canonico.
+ *
+ */
+
+/** Tipo que representa una frecuencia de un símbolo */

 typedef unsigned long int t_freq;
 
 typedef unsigned long int t_freq;
 

+/** Estructura que representa un nodo de un árbol y/o inputlist de huffman */

 typedef struct t_freqnode {
 typedef struct t_freqnode {

-       unsigned short int symbol;
-       t_freq freq;
-       struct t_freqnode *lchild;
-       struct t_freqnode *rchild;
+       unsigned short int symbol; /**< Símbolo que representa el nodo */
+       t_freq freq; /**< Frecuencia del nodo */
+       struct t_freqnode *lchild; /**< Hijo izquierdo del nodo */
+       struct t_freqnode *rchild; /**< Hijo derecho del nodo */

 } SHUFFNODE;
 
 } SHUFFNODE;
 

+/** Estructura que representa un código prefijo generado con el árbol de huffman */

 typedef struct t_code {
 typedef struct t_code {

-       unsigned long int code;
-       unsigned char codelength;
+       unsigned long int code; /**< Codigo prefijo de algún símbolo */
+       unsigned char codelength; /**< Longitud en bits del código prefijo */

 } SHUFFCODE;
 
 } SHUFFCODE;
 

+/** Estructura que representa el estado del compresor Huffman Estático */

 typedef struct t_huff {
 typedef struct t_huff {

-       FILE *coderfp; /* fpointer usado en el coder de bychunk para el temp */
-       VFILE *decoderfp; /* fpointer al archivo a descomrimir */
-       char *sourcefile; /* Nombre del archivo a comprimir */
-       char *targetfile; /* Nombre del archivo comprimido */
-       long volsize; /* Tamanio de volumen para multivol */
-       char bychunk; /* 0 works byfile, 1 works bychunk */
-       char canonic; /* 1 Huffman Canonico con preloaded freqtable */
-       t_freq *freqtable; /* Tabla de frecuencias */
-       t_freq sumfreq; /* Frecuencia total acumulada */
-       SHUFFNODE *codetree; /* Puntero al arbol de codigos prefijos */         
-       unsigned long int bytesleft; /* Cuanto falta descomprimir en un bychunk */      
-       unsigned long int codebuffer; /* Buffer de descompresion para bychunk */
-       int bitsleft; /* Posicion en el buffer de descompresion para bychunk */
+       FILE *coderfp; /**< FPointer usado en el coder de bychunk para el temp */
+       VFILE *decoderfp; /**< FPointer al archivo a descomrimir */
+       char *sourcefile; /**< Nombre del archivo a comprimir o a descomprimir */
+       char *targetfile; /**< Nombre del archivo comprimido o descomprimido */
+       long volsize; /**< Tamanio de volumen para multivol */
+       char bychunk; /**< 0 works byfile, 1 works bychunk */
+       char canonic; /**< 1 Huffman Canonico con preloaded freqtable */
+       t_freq *freqtable; /**< Tabla de frecuencias */
+       t_freq sumfreq; /**< Frecuencia total acumulada */
+       SHUFFNODE *codetree; /**< Puntero al arbol de codigos prefijos */               
+       unsigned long int bytesleft; /**< Cuanto falta descomprimir en un bychunk */    
+       unsigned long int codebuffer; /**< Buffer de descompresion para bychunk */
+       int bitsleft; /**< Posicion en el buffer de descompresion para bychunk */

 } HUFF_STATE;
 
 } HUFF_STATE;
 

-
+/** Crea una estructura <em>HUFF_STATE<em> y la inicializa para utilizarla
+ * para comprimir archivos.
+ *
+ * \param inputfile Archivo a comprimir.
+ * \param outputfile Archivo destino de la compresión.
+ * \param volsize Size del volumen en caso de compresión multivolumen.
+ * \return \b HUFF_STATE* Puntero a estructura creada e inicializada.
+ */

 HUFF_STATE *shuff_init_encoder_byfile(char *inputfile, char *outputfile, long volsize);
 HUFF_STATE *shuff_init_encoder_byfile(char *inputfile, char *outputfile, long volsize);

+
+/** Crea una estructura <em>HUFF_STATE<em> y la inicializa para utilizarla
+ * para comprimir una secuencia de chunks de datos.
+ *
+ * \param outputfile Archivo destino de la compresión.
+ * \param volsize Size del volumen en caso de compresión multivolumen.
+ * \return \b HUFF_STATE* Puntero a estructura creada e inicializada.
+ */

 HUFF_STATE *shuff_init_encoder_bychunk(char *outputfile, long volsize);
 HUFF_STATE *shuff_init_encoder_bychunk(char *outputfile, long volsize);

+
+/** Crea una estructura <em>HUFF_STATE<em> y la inicializa para utilizarla
+ * en la descompresión de un archivo.
+ *
+ * \param inputfile Archivo a descomprimir.
+ * \param outputfile Archivo destino de la descompresión.
+ * \return \b HUFF_STATE* Puntero a estructura creada e inicializada.
+ */

 HUFF_STATE *shuff_init_decoder(char *inputfile, char *outputfile);
 HUFF_STATE *shuff_init_decoder(char *inputfile, char *outputfile);

+
+/** Desinicializa el compresor Huffman, cerrando files y liberando memoria.
+ *
+ * \param shuff Puntero a la estructura usada para el estado del compresor.
+ */

 void shuff_deinit_encoder(HUFF_STATE *shuff);
 void shuff_deinit_encoder(HUFF_STATE *shuff);

+
+/** Desinicializa el compresor Huffman, cerrando files y liberando memoria.
+ *
+ * \param shuff Puntero a la estructura usada para el estado del compresor.
+ */

 void shuff_deinit_decoder(HUFF_STATE *shuff);
 void shuff_deinit_decoder(HUFF_STATE *shuff);

+
+/** Ejecuta la compresión de un archivo previamente indicado a través de
+ * las rutinas de inicializacion de Huffman.
+ *
+ * \param shuff Puntero a la estructura usada para el estado del compresor.
+ * \return \b int Indica éxito de la operacion. (1 Exito, 0 Error)
+ */

 int shuff_encode_file(HUFF_STATE *shuff);
 int shuff_encode_file(HUFF_STATE *shuff);

+
+/** Ejecuta la descompresión de un archivo previamente indicado a través de
+ * las rutinas de inicializacion de Huffman.
+ *
+ * \param shuff Puntero a la estructura usada para el estado del compresor.
+ * \return \b int Indica éxito de la operacion. (1 Exito, 0 Error)
+ */

 int shuff_decode_file(HUFF_STATE *shuff);
 int shuff_decode_file(HUFF_STATE *shuff);

-int shuff_scanfreq_chunk(HUFF_STATE *chunkshuff, char* chunk, int chunksize);
+
+/** Recibe un chunk de datos y analiza la frecuencia de sus caracteres
+ * actualizando el modelo de frecuencias en consecuencia.
+ *
+ * \param chunkshuff Puntero a la estructura usada para el estado del compresor.
+ * \param chunk Puntero al chunk de datos.
+ * \param chunksize Size del chunk de datos.
+ * \return \b int Indica éxito de la operacion. (1 Exito, 0 Error)
+ */
+int shuff_scanfreq_chunk(HUFF_STATE *shuff, char* chunk, int chunksize);
+
+/** Descomprime un chunk de datos cuyo size es especificado en la rutina.
+ *
+ * \param shuff Puntero a la estructura usada para el estado del compresor.
+ * \param chunk Puntero al buffer donde se decodificara el chunk.
+ * \param chunksize Size del buffer o chunk que se quiere obtener.
+ * \return \b int Indica si hay mas datos a descomprimir o no (1 hay, 0 no hay)
+ */

 int shuff_decode_chunk(HUFF_STATE *shuff, char *chunk, int chunksize, int *decodedbytes);
 int shuff_decode_chunk(HUFF_STATE *shuff, char *chunk, int chunksize, int *decodedbytes);

+
+/** Graba el modelo de un archivo que se ha comprimido. (Tabla de Freq)
+ *
+ * \param shuff Puntero a la estructura usada para el estado del compresor. 
+ * \return \b int Indica éxito de la operación. (1 Exito, 0 Error);
+ */

 int shuff_savemodel(HUFF_STATE *shuff);
 int shuff_savemodel(HUFF_STATE *shuff);

+
+/** Carga un modelo de huffman (Tabla de Freq) para ser usando en Huff Canonico
+ *
+ * \param shuff Puntero a la estructura usada para el estado del compresor. 
+ * \param modelfile Nombre del archivo que posee el modelo a cargar.
+ * \return \b int Indica éxito de la operación. (1 Exito, 0 Error);
+ */

 int shuff_loadmodel(HUFF_STATE *shuff, char *modelfile);
 
 #endif /* _STATICHUFF_H_ */
 int shuff_loadmodel(HUFF_STATE *shuff, char *modelfile);
 
 #endif /* _STATICHUFF_H_ */