From: Alan Kennedy Date: Sun, 27 Jun 2004 21:39:00 +0000 (+0000) Subject: Documento Huffman para Doxy X-Git-Tag: svn_import~35 X-Git-Url: https://git.llucax.com/z.facultad/75.06/jacu.git/commitdiff_plain/5cb3396689e467ed4acaf0548668cb2924f0fd6f Documento Huffman para Doxy --- diff --git a/src/statichuff/statichuff.c b/src/statichuff/statichuff.c index 9168919..6b3b4d5 100644 --- a/src/statichuff/statichuff.c +++ b/src/statichuff/statichuff.c @@ -3,6 +3,7 @@ #include #include +/** Coloca un bit en un buffer statico */ 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; } +/** Realiza la copia de los datos de un nodo de huffman a otro */ 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; } +/** 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; @@ -50,6 +53,7 @@ int shuff_compnode(const void *node1, const void *node2) 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) { @@ -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; @@ -79,6 +84,7 @@ int shuff_rescalefreq(t_freq *freqtable) return totalfreq; } +/** Escanea las frecuencias de un chunk de datos */ 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; } +/** Escanea las frecuencias de un archivo y genera el modelo */ int shuff_scanfreq(char *inputfile, t_freq *freqtable) { /* Locals */ @@ -133,6 +140,7 @@ int shuff_scanfreq(char *inputfile, t_freq *freqtable) 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; @@ -156,6 +164,7 @@ SHUFFNODE *shuff_buildlist(t_freq *freqtable, int *nonzerofreqs) return inputlist; } +/** Genera el arbol de huffman en base a la tabla de frecuencias */ SHUFFNODE *shuff_buildtree(t_freq *ftable) { SHUFFNODE *lastsymbol; @@ -195,6 +204,7 @@ SHUFFNODE *shuff_buildtree(t_freq *ftable) return root; } +/** Imprime los codigos prefijos generados para los symbolos */ 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; @@ -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) { @@ -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; @@ -287,6 +300,7 @@ int shuff_encode_symbols(HUFF_STATE *shuff, SHUFFCODE *ctable) return 1; } +/** Prepara las estructuras de datos necesarias para una compresion */ int shuff_encode_file(HUFF_STATE *shuff) { /* Locals */ @@ -313,6 +327,7 @@ int shuff_encode_file(HUFF_STATE *shuff) 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) { @@ -330,6 +345,7 @@ SHUFFNODE *shuff_decode_symbols(SHUFFNODE *entrynode, unsigned long int buffer, 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; @@ -360,6 +376,7 @@ int shuff_decode_chunk(HUFF_STATE *shuff, char *chunk, int chunksize, int *decod else return 1; } +/** Realiza la descompresión de un archivo comprimido */ int shuff_decode_file(HUFF_STATE *shuff) { SHUFFNODE *currnode; @@ -396,6 +413,7 @@ int shuff_decode_file(HUFF_STATE *shuff) return 1; } +/** Inicializa un descompresor de huffman */ 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; } +/** Inicializa compresor de huffman por archivo */ 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; } +/** Inicializa compresor de huffman de a chunks */ 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; } +/** Carga un modelo estadistico para huffman */ int shuff_loadmodel(HUFF_STATE *shuff, char *modelfile) { FILE *fp; @@ -490,6 +511,7 @@ int shuff_loadmodel(HUFF_STATE *shuff, char *modelfile) { return 0; } +/** Graba un modelo estadístico de huffman */ int shuff_savemodel(HUFF_STATE *shuff) { FILE *fp; @@ -514,6 +536,7 @@ int shuff_savemodel(HUFF_STATE *shuff) { return 0; } +/** Desinicializa un compresor de huffman */ 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); } +/** Desinicializa un descompresor de huffman */ 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 97e8f4c..065b8c3 100644 --- a/src/statichuff/statichuff.h +++ b/src/statichuff/statichuff.h @@ -6,47 +6,139 @@ #include #include "../vfile/vfile.h" +/** \file + * Compresor Huffman Estático + * + * Interfaz del compresor Huffman Estático + * + * 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; +/** Estructura que representa un nodo de un árbol y/o inputlist de huffman */ 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; +/** Estructura que representa un código prefijo generado con el árbol de huffman */ 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; +/** Estructura que representa el estado del compresor Huffman Estático */ 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; - +/** Crea una estructura HUFF_STATE 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); + +/** Crea una estructura HUFF_STATE 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); + +/** Crea una estructura HUFF_STATE 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); + +/** 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); + +/** 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); + +/** 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); + +/** 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_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); + +/** 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); + +/** 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_ */