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

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

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 <stdint.h>
@ -7,78 +16,114 @@
#include "common.h"
/**
* @brief Tampon d'écriture bit par bit.
*
* 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
* dès qu'un octet est complet
* dès qu'un octet est complet, ou lorsque le vidage est forcé.
*/
typedef struct WriteBuffer {
/**
* Données du tampon d'écriture en attente de vidage.
*/
typedef struct WriteBuffer WriteBuffer;
struct WriteBuffer {
// Contient les données du tampon d'écriture, c'est-à-dire
// les données en attente de vidage dans le fichier
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;
// 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;
// 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;
};
} WriteBuffer;
/**
* Initialise un tampon d'écriture vide, avec le fichier donné comme
* destination
* @brief Initialiser un tampon d'écriture.
*
* 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
* (les bits non-remplis seront remplacés par des 0)
* @brief Forcer le vidage du tampon d'écriture.
*
* 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,
* correspondant au nombre d'octets écrits par le tampon dans le fichier
* @brief Récupèrer le nombre de vidages effectués par ce tampon.
*
* Permet de savoir combien d'octets ont é é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
* dès que tous les bits du précédent ont é lus
* seulement lorsque tous les bits du précédent octet ont é consommés.
*/
typedef struct ReadBuffer {
/**
* Données du tampon de lecture en attente de lecture.
*/
typedef struct ReadBuffer ReadBuffer;
struct ReadBuffer {
// Contient les données du tampon de lecture, c'est-à-dire
// le dernier octet lu depuis le fichier
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;
// Fichier depuis lequel le tampon de lecture est rempli
/**
* Fichier depuis lequel les données sont lues.
*/
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__

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
/**
* @brief Macro correspondant à la valeur booléenne fausse (0).
*/
#define FALSE 0
/**
* @brief Macro correspondant au nombre de caractères possibles.
*/
#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;
#endif
#endif // __HUFFMAN_COMMON_H_INCLUDED__

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>
/**
* @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);
#endif
#endif // __HUFFMAN_COMPRESS_H_INCLUDED__

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>
/**
* @brief Décompresser le fichier @p source vers @p dest.
* Lit le fichier @p source ayant é 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);
#endif
#endif // __HUFFMAN_DECOMPRESS_H_INCLUDED__

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 "common.h"
//! \{
typedef struct HufVertex HufVertex;
typedef HufVertex* HufTree;
//! \}
/**
* Écrire des données de débogage sur la sortie d'erreurs standard
* (seulement si le mode verbeux est actif)
* @brief Écrire un message de débogage sur la sortie d'erreurs.
*
* 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, ...);
/**
* Active ou désactive l'affichage des messages de débogage (mode verbeux)
* sur la sortie d'erreurs standard
* @brief Activer ou désactiver l'affichage des messages de débogage.
*
* 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();
/**
* 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);
/**
* Afficher sur la sortie standard le tableau associant les caractères
* à leur effectif d'apparition passé en argument
* @brief Afficher sur la sortie d'erreurs le tableau associant les caractères
* à 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
* à leur étiquette passé en argument
* *@brief Afficher sur la sortie d'erreurs le tableau associant les caractères
* à 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__

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 <stdlib.h>
#include "common.h"
//! \{
typedef struct WriteBuffer WriteBuffer;
typedef struct ReadBuffer ReadBuffer;
//! \}
/**
* Représente un des sommets d'un arbre de Huffman (représente l'arbre
* en entier s'il s'agit de la racine)
* @brief Sommet d'un arbre binaire de Huffman.
*
* 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 {
/**
* Caractère associé au sommet, ou -1 si aucun caractère
* n'est associé (par exemple pour les sommets internes).
*/
typedef struct HufVertex HufVertex;
typedef HufVertex* HufTree;
struct HufVertex {
// Caractère associé à ce sommet ou -1 s'il n'y a aucun caractère
// associé (notamment s'il s'agit d'une branche)
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;
// Pointeurs vers les deux enfants de ce sommet. Ils valent tous
// deux NULL si le sommet est une feuille. À noter qu'un sommet
// a toujours 0 ou 2 enfants car un arbre de Huffman est binaire
HufVertex* child_l;
HufVertex* child_r;
};
/**
* Sommet enfant à gauche, ou NULL si ce sommet n'a pas d'enfant
* à gauche.
*/
struct HufVertex* child_l;
/**
* Construire un arbre de Huffman basé sur les effectifs
* de caractères passés dans `counts`
* Sommet enfant à droite, ou NULL si ce sommet n'a pas d'enfant
* à droite.
*/
struct HufVertex* child_r;
} HufVertex;
/**
* @brief Arbre binaire de Huffman (pointeur vers un @c HufVertex)
*/
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);
/**
* Écrit une représentation binaire de l'arbre dans le
* tampon passé en paramètre
* @brief Écrire un arbre dans le tampon d'écriture donné.
*
* É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é
* en paramètre
* @brief Lire un arbre depuis le tampon de lecture donné.
*
* 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
* généré par la fonction `createTree`
* @brief Libérer la mémoire occupée par un arbre.
* @param tree Arbre à libérer.
*/
void freeTree(HufTree tree);
/**
* 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
* @brief Créer la clé de codage à partir d'un arbre de Huffman.
*
* (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);
/**
* Libérer la mémoire occupée par un tableau d'étiquettes renvoyé
* par la fonction `labelTree`
* @brief Libérer la mémoire occupée par une clé de codage.
* @param labels Clé à libérer.
*/
void freeTreeLabels(char** labels);
#endif
#endif // __HUFFMAN_HUFTREE_H_INCLUDED__