matteo/huffman
matteo
/
huffman
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Ajout de la documentation Doxygen

This commit is contained in:
Mattéo Delabre 2016-11-30 11:55:10 +01:00
parent a7c9148d5c
commit 67542a87c2
7 changed files with 267 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Doxyfile Normal file
View File

@ -0,0 +1,9 @@
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = Huffman
PROJECT_NUMBER = 0.1
PROJECT_BRIEF = "Compresseur Huffman en C, dans le cadre du projet HLIN303"
OUTPUT_DIRECTORY = "./out/doxygen"
RECURSIVE = YES
OUTPUT_LANGUAGE = French
OPTIMIZE_OUTPUT_FOR_C = YES

123
inc/buffer.h
View File

@ -1,5 +1,14 @@
#ifndef __IN303_BUFFER_H__ /**
#define __IN303_BUFFER_H__ * @file
* @brief Abstraction de l'écriture et la lecture d'un fichier bit à bit.
*
* Définir des structures et des fonctions de manipulation liées à
* un fichier et permettant d'accéder à son contenu ou de le modifier
* bit par bit au lieu d'octet par octet.
*/
#ifndef __HUFFMAN_BUFFER_H_INCLUDED__
#define __HUFFMAN_BUFFER_H_INCLUDED__
#include <stdio.h> #include <stdio.h>
#include <stdint.h> #include <stdint.h>
@ -7,78 +16,114 @@
#include "common.h" #include "common.h"
/** /**
* @brief Tampon d'écriture bit par bit.
*
* Tampon permettant d'abstraire l'écriture dans un fichier bit par * Tampon permettant d'abstraire l'écriture dans un fichier bit par
* bit au lieu d'octet par octet. Les bits sont vidés dans le fichier * bit au lieu d'octet par octet. Les bits sont vidés dans le fichier
* dès qu'un octet est complet * dès qu'un octet est complet, ou lorsque le vidage est forcé.
*/ */
typedef struct WriteBuffer WriteBuffer; typedef struct WriteBuffer {
struct WriteBuffer { /**
// Contient les données du tampon d'écriture, c'est-à-dire * Données du tampon d'écriture en attente de vidage.
// les données en attente de vidage dans le fichier */
int data; int data;
// Nombre de bits utilisés dans `data`. Si ce nombre vaut 8, /**
// le tampon d'écriture est plein * Nombre de bits utilisés dans WriteBuffer#data.
*/
size_t pending_bits; size_t pending_bits;
// Nombre d'octets écrits par le tampon d'écriture dans le /**
// fichier, correspondant au nombre de vidages du tampon * Nombre de vidages effectués par le tampon.
*/
bytecount flushed_count; bytecount flushed_count;
// Fichier dans lequel le tampon d'éciture est vidé à l'appel /**
// de `flushBuffer` ou au débordement * Fichier dans lequel le tampon est vidé.
*/
FILE* dest_file; FILE* dest_file;
}; } WriteBuffer;
/** /**
* Initialise un tampon d'écriture vide, avec le fichier donné comme * @brief Initialiser un tampon d'écriture.
* destination *
* Initialiser un tampon vide avec le fichier @p dest pour destination.
* @param dest Fichier de destination.
* @return Tampon créé.
*/ */
WriteBuffer createWriteBuffer(FILE*); WriteBuffer createWriteBuffer(FILE* dest);
/** /**
* Écrit le bit donné dans le tampon d'écriture * @brief Écrire un bit dans le tampon d'écriture.
*
* Ajouter le bit @p bit aux données du tampon @p buffer. Si le tampon est
* plein, vidage dans le fichier associé.
* @param bit Bit à ajouter au tampon (0 ou 1).
* @param buffer Tampon dans lequel ajouter le bit.
*/ */
void putBuffer(char bit, WriteBuffer*); void putBuffer(char bit, WriteBuffer* buffer);
/** /**
* Force le vidage du tampon dans son fichier et sa réinitialisation * @brief Forcer le vidage du tampon d'écriture.
* (les bits non-remplis seront remplacés par des 0) *
* Forcer le vidage du tampon dans son fichier et sa réinitialisation.
* Si le tampon est vide, pas de vidage (pas d'octet superflu écrit).
* Si le tampon n'est pas rempli, complétion à droite par des 0.
* @param buffer Tampon à vider.
*/ */
void flushBuffer(WriteBuffer*); void flushBuffer(WriteBuffer* buffer);
/** /**
* Récupère le nombre de vidages effectués sur le tampon d'écriture, * @brief Récupèrer le nombre de vidages effectués par ce tampon.
* correspondant au nombre d'octets écrits par le tampon dans le fichier *
* Permet de savoir combien d'octets ont été écrits dans le fichier
* par le tampon @p buffer.
* @param buffer Tampon à vérifier.
* @return Nombre de vidages effectués.
*/ */
bytecount getFlushedCount(WriteBuffer*); bytecount getFlushedCount(WriteBuffer* buffer);
/** /**
* Tampon permettant d'abstraire le lecture depuis un fichier bit par * @brief Tampon de lecture bit par bit.
*
* Tampon permettant d'abstraire la lecture d'un fichier bit par
* bit au lieu d'octet par octet. Un octet est lu depuis le fichier * bit au lieu d'octet par octet. Un octet est lu depuis le fichier
* dès que tous les bits du précédent ont été lus * seulement lorsque tous les bits du précédent octet ont été consommés.
*/ */
typedef struct ReadBuffer ReadBuffer; typedef struct ReadBuffer {
struct ReadBuffer { /**
// Contient les données du tampon de lecture, c'est-à-dire * Données du tampon de lecture en attente de lecture.
// le dernier octet lu depuis le fichier */
int data; int data;
// Numéro du prochain bit de `data` qui sera lu par `getBuffer` /**
* Numéro du prochain bit de ReadBuffer#data à lire.
*/
size_t next_bit; size_t next_bit;
// Fichier depuis lequel le tampon de lecture est rempli /**
* Fichier depuis lequel les données sont lues.
*/
FILE* source_file; FILE* source_file;
}; } ReadBuffer;
/** /**
* Initialise un tampon de lecture avec le fichier donné comme source * @brief Initialiser un tampon de lecture.
*
* Initialiser un tampon vide avec le fichier @p source comme source.
* @param source Fichier source.
* @return Tampon créé.
*/ */
ReadBuffer createReadBuffer(FILE*); ReadBuffer createReadBuffer(FILE* source);
/** /**
* Lit le prochain bit depuis le tampon de lecture * @brief Lire un bit depuis le tampon de lecture.
*
* Lire le prochain bit depuis le tampon de lecture, et lire un octet
* depuis la source si besoin est.
* @param buffer Tampon depuis lequel lire un bit.
* @return Valeur du bit qui est lu : 0 ou 1.
*/ */
char getBuffer(ReadBuffer*); char getBuffer(ReadBuffer* buffer);
#endif #endif // __HUFFMAN_BUFFER_H_INCLUDED__

26
inc/common.h
View File

@ -1,10 +1,30 @@
#ifndef __IN303_COMMON_H__ /**
#define __IN303_COMMON_H__ * @file
* @brief Définitions communes pour le reste du code.
*/
#ifndef __HUFFMAN_COMMON_H_INCLUDED__
#define __HUFFMAN_COMMON_H_INCLUDED__
/**
* @brief Macro correspondant à la valeur booléenne vraie (1).
*/
#define TRUE 1 #define TRUE 1
/**
* @brief Macro correspondant à la valeur booléenne fausse (0).
*/
#define FALSE 0 #define FALSE 0
/**
* @brief Macro correspondant au nombre de caractères possibles.
*/
#define NUM_CHARS 256 #define NUM_CHARS 256
/**
* @brief Alias du type d'entier non-signé 64 bits pour compter
* les longueurs de fichiers.
*/
typedef long long unsigned int bytecount; typedef long long unsigned int bytecount;
#endif #endif // __HUFFMAN_COMMON_H_INCLUDED__

20
inc/compress.h
View File

@ -1,8 +1,22 @@
#ifndef __IN303_COMPRESS_H__ /**
#define __IN303_COMPRESS_H__ * @file
* @brief Compression des fichiers.
*/
#ifndef __HUFFMAN_COMPRESS_H_INCLUDED__
#define __HUFFMAN_COMPRESS_H_INCLUDED__
#include <stdio.h> #include <stdio.h>
/**
* @brief Compresser le fichier @p source vers @p dest.
*
* Lit les caractères de @p source, applique l'algorithme de Huffman pour
* déterminer une représentation compacte et la stocke dans @p dest.
* @param source Fichier ouvert en lecture depuis lequel lire les données.
* @param dest Fichier ouvert en écriture dans lequel écrire les données
* compressées.
*/
void compress(FILE* source, FILE* dest); void compress(FILE* source, FILE* dest);
#endif #endif // __HUFFMAN_COMPRESS_H_INCLUDED__

20
inc/decompress.h
View File

@ -1,8 +1,22 @@
#ifndef __IN303_DECOMPRESS_H__ /**
#define __IN303_DECOMPRESS_H__ * @file
* @brief Décompression des fichiers.
*/
#ifndef __HUFFMAN_DECOMPRESS_H_INCLUDED__
#define __HUFFMAN_DECOMPRESS_H_INCLUDED__
#include <stdio.h> #include <stdio.h>
/**
* @brief Décompresser le fichier @p source vers @p dest.
* Lit le fichier @p source ayant été compressé avec l'algorithme de Huffman
* et écrit les données décompressées dans @p dest.
* @param source Fichier ouvert en lecture depuis lequel lire les données.
* @param dest Fichier ouvert en écriture dans lequel écrire les données
* décompressées.
*/
void decompress(FILE* source, FILE* dest); void decompress(FILE* source, FILE* dest);
#endif #endif // __HUFFMAN_DECOMPRESS_H_INCLUDED__

56
inc/display.h
View File

@ -1,45 +1,69 @@
#ifndef __IN303_DISPLAY_H__ /**
#define __IN303_DISPLAY_H__ * @file
* @brief Gestion de l'affichage.
*/
#ifndef __HUFFMAN_DISPLAY_H_INCLUDED__
#define __HUFFMAN_DISPLAY_H_INCLUDED__
#include <stdlib.h> #include <stdlib.h>
#include "common.h" #include "common.h"
//! \{
typedef struct HufVertex HufVertex; typedef struct HufVertex HufVertex;
typedef HufVertex* HufTree; typedef HufVertex* HufTree;
//! \}
/** /**
* Écrire des données de débogage sur la sortie d'erreurs standard * @brief Écrire un message de débogage sur la sortie d'erreurs.
* (seulement si le mode verbeux est actif) *
* Cette fonction n'a aucun effet si l'affichage des messages de débogage
* ne sont pas activés, sinon le message est affiché dans @c stderr.
* @param format Format d'affichage à la printf.
* @param ... Variables pour l'affichage.
*/ */
void printVerbose(const char* format, ...); void printVerbose(const char* format, ...);
/** /**
* Active ou désactive l'affichage des messages de débogage (mode verbeux) * @brief Activer ou désactiver l'affichage des messages de débogage.
* sur la sortie d'erreurs standard *
* Si le paramètre est vrai, les appels suivants à @c printVerbose seront
* affichés sur la sortie d'erreurs. Sinon, ils n'auront aucun effet.
* @param enable Activer ou désactiver l'affichage.
*/ */
void setVerbose(int); void setVerbose(int enable);
/** /**
* Renvoie l'état du mode verbeux * @brief Vérifie si les messages de débogage sont activés ou non.
*/ */
int isVerbose(); int isVerbose();
/** /**
* Afficher sur la sortie standard l'arbre passé en paramètre * @brief Afficher sur la sortie d'erreurs une représentation de l'arbre
* passé en paramètre.
*
* @param tree L'arbre à afficher.
*/ */
void printTree(HufTree tree); void printTree(HufTree tree);
/** /**
* Afficher sur la sortie standard le tableau associant les caractères * @brief Afficher sur la sortie d'erreurs le tableau associant les caractères
* à leur effectif d'apparition passé en argument * à leur effectif d'apparition passé en argument.
*
* @param counts Tableau d'association des effectifs.
* @param total Nombre total de caractères.
* @param size Taille du tableau @p counts.
*/ */
void printCountsTable(bytecount*, bytecount total, size_t); void printCountsTable(bytecount* counts, bytecount total, size_t size);
/** /**
* Afficher sur la sortie standard le tableau associant les caractères * *@brief Afficher sur la sortie d'erreurs le tableau associant les caractères
* à leur étiquette passé en argument * à leur étiquette passé en argument.
*
* @param labels Tableau d'association des étiquettes.
* @param size Taille du tableau @p labels.
*/ */
void printLabelsTable(char**, size_t); void printLabelsTable(char** labels, size_t size);
#endif #endif // __HUFFMAN_DISPLAY_H_INCLUDED__

113
inc/huftree.h
View File

@ -1,76 +1,117 @@
#ifndef __IN303_HUFTREE_H__ /**
#define __IN303_HUFTREE_H__ * @file
* @brief Représentation mémoire des arbres binaires de Huffman.
*
* Définir une structure permettant de représenter en mémoire les
* arbres binaires de Huffman et des fonctions permettant de manipuler
* ces arbres.
*/
#ifndef __HUFFMAN_HUFTREE_H_INCLUDED__
#define __HUFFMAN_HUFTREE_H_INCLUDED__
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
#include "common.h" #include "common.h"
//! \{
typedef struct WriteBuffer WriteBuffer; typedef struct WriteBuffer WriteBuffer;
typedef struct ReadBuffer ReadBuffer; typedef struct ReadBuffer ReadBuffer;
//! \}
/** /**
* Représente un des sommets d'un arbre de Huffman (représente l'arbre * @brief Sommet d'un arbre binaire de Huffman.
* en entier s'il s'agit de la racine) *
* Sommet possédant éventuellement une valeur (caractère associé),
* un effectif d'apparition (nombre d'occurences du caractère dans la source)
* et un sommet enfant à gauche et/ou à droite.
*/ */
typedef struct HufVertex HufVertex; typedef struct HufVertex {
typedef HufVertex* HufTree; /**
struct HufVertex { * Caractère associé au sommet, ou -1 si aucun caractère
// Caractère associé à ce sommet ou -1 s'il n'y a aucun caractère * n'est associé (par exemple pour les sommets internes).
// associé (notamment s'il s'agit d'une branche) */
unsigned int value; unsigned int value;
// Indique l'effectif du caractère associée à ce sommet /**
// dans le fichier source, ou -1 s'il n'y a aucun caractère associé * Effectif du caractère associé au sommet, ou -1 si aucun
* caractère n'est associé.
*/
bytecount count; bytecount count;
// Pointeurs vers les deux enfants de ce sommet. Ils valent tous /**
// deux NULL si le sommet est une feuille. À noter qu'un sommet * Sommet enfant à gauche, ou NULL si ce sommet n'a pas d'enfant
// a toujours 0 ou 2 enfants car un arbre de Huffman est binaire * à gauche.
HufVertex* child_l; */
HufVertex* child_r; struct HufVertex* child_l;
};
/**
* Sommet enfant à droite, ou NULL si ce sommet n'a pas d'enfant
* à droite.
*/
struct HufVertex* child_r;
} HufVertex;
/** /**
* Construire un arbre de Huffman basé sur les effectifs * @brief Arbre binaire de Huffman (pointeur vers un @c HufVertex)
* de caractères passés dans `counts` */
typedef HufVertex* HufTree;
/**
* @brief Construire un arbre de Huffman.
* *
* (résultat à libérer avec `freeTree`) * Lire les effectifs de caractères dans @p counts et en déduire
* un arbre binaire de Huffman. Le résultat doit être libéré avec
* la fonction @c freeTree.
* @param counts Comptes des caractères.
* @return Arbre construit.
*/ */
HufTree createTree(bytecount* counts); HufTree createTree(bytecount* counts);
/** /**
* Écrit une représentation binaire de l'arbre dans le * @brief Écrire un arbre dans le tampon d'écriture donné.
* tampon passé en paramètre *
* Écrire une représentation binaire de l'arbre @p tree
* dans le tampon @p buffer.
* @param tree Arbre à représenter.
* @param buffer Tampon cible.
*/ */
void writeTree(HufTree, WriteBuffer*); void writeTree(HufTree tree, WriteBuffer* buffer);
/** /**
* Reconstruit un arbre de Huffman à partir du fichier passé * @brief Lire un arbre depuis le tampon de lecture donné.
* en paramètre *
* Reconstruire un arbre de Huffman à partir du tampon de lecture
* @p buffer. Le résultat doit être libéré avec la fonction @c freeTree.
* @return L'arbre reconstruit.
*/ */
HufTree readTree(ReadBuffer*); HufTree readTree(ReadBuffer* buffer);
/** /**
* Libérer la mémoire occupée par un arbre de Huffman * @brief Libérer la mémoire occupée par un arbre.
* généré par la fonction `createTree` * @param tree Arbre à libérer.
*/ */
void freeTree(HufTree tree); void freeTree(HufTree tree);
/** /**
* Associer à chaque feuille de l'arbre une étiquette unique basée * @brief Créer la clé de codage à partir d'un arbre de Huffman.
* sur sa position dans l'arbre. Aucune étiquette n'est ainsi préfixe
* d'une autre. Le tableau renvoyé associe chaque caractère ASCII
* à son préfixe, ou à NULL s'il n'est pas présent dans l'arbre
* *
* (résultat à libérer avec `freeTreeLabels`) * Associer à chaque feuille de l'arbre une étiquette unique basée sur
* sa position dans l'arbre. Aucune étiquette n'est ainsi préfixe d'une
* autre. Le tableau renvoyé associe chaque caractère ASCII à son préfixe
* ou à NULL s'il n'est pas présent dans l'arbre. Le résultat doit être
* libéré avec @c freeTreeLabels.
*
* @param tree Arbre source de la clé de codage.
* @return Clé générée.
*/ */
char** createTreeLabels(HufTree tree); char** createTreeLabels(HufTree tree);
/** /**
* Libérer la mémoire occupée par un tableau d'étiquettes renvoyé * @brief Libérer la mémoire occupée par une clé de codage.
* par la fonction `labelTree` * @param labels Clé à libérer.
*/ */
void freeTreeLabels(char** labels); void freeTreeLabels(char** labels);
#endif #endif // __HUFFMAN_HUFTREE_H_INCLUDED__