SAE32_2025/src/fr/iutfbleau/sae/mhuffman/HuffmanNode.java

package fr.iutfbleau.sae.mhuffman;

/**
 * Représente un nœud de l'arbre de Huffman.
 * <p>
 * Un {@code HuffmanNode} peut être :
 * <ul>
 *   <li>une feuille, contenant une valeur (symbole) et une fréquence</li>
 *   <li>un nœud interne, contenant uniquement une fréquence et deux enfants</li>
 * </ul>
 * </p>
 *
 * <p>
 * Cette classe est une structure de données utilisée par {@code HuffmanTree}
 * pour construire l'arbre de Huffman.
 * </p>
 *
 * @author Algassimou Pellel Diallo
 * @version 1.1
 * @since 2025-12-17
 */
public class HuffmanNode {

    /** 
     * Valeur de la composante (symbole) représentée par ce nœud (uniquement pour les feuilles).
     * Représente la part de la composante (rouge, verte ou bleue) dans la couleur d'un pixel.
     * Pour les nœuds internes, cette valeur vaut -1.
     */
    private int value;

    /** Fréquence du symbole (somme des fréquences des enfants pour les nœuds internes). */
    private int frequence;

    /** Fils gauche du nœud (null si feuille). */
    private HuffmanNode left;

    /** Fils droit du nœud (null si feuille). */
    private HuffmanNode right;

    /**
     * Construit un nœud feuille de Huffman.
     * <p>
     * Ce constructeur est utilisé pour représenter une valeur
     * issue de la table de fréquences.
     * </p>
     *
     * @param value la valeur (symbole) représentée par ce nœud (entre 0 et 255)
     * @param frequence la fréquence d'apparition de la valeur
     * @throws IllegalArgumentException si la valeur n'est pas entre 0 et 255
     *         ou si la fréquence est négative
     */
    public HuffmanNode(int value, int frequence) {
        if (value < 0 || value > 255) {
            throw new IllegalArgumentException("La valeur doit être entre 0 et 255");
        }
        if (frequence < 0) {
            throw new IllegalArgumentException("La fréquence ne peut pas être négative");
        }
        this.value = value;
        this.frequence = frequence;
        this.left = null;
        this.right = null;
    }

    /**
     * Construit un nœud interne de Huffman.
     * <p>
     * Ce constructeur est utilisé lors de la fusion de deux nœuds
     * de plus faible fréquence lors de la construction de l'arbre.
     * </p>
     *
     * @param left le fils gauche
     * @param right le fils droit
     * @throws IllegalArgumentException si l'un des fils est null
     */
    public HuffmanNode(HuffmanNode left, HuffmanNode right) {
        if (left == null || right == null) {
            throw new IllegalArgumentException("Les fils ne peuvent pas être null");
        }
        this.value = -1; // Valeur sentinelle pour les nœuds internes
        this.left = left;
        this.right = right;
        this.frequence = left.frequence + right.frequence;
    }

    /**
     * Indique si ce nœud est une feuille.
     *
     * @return {@code true} si le nœud est une feuille, {@code false} sinon
     */
    public boolean isLeaf() {
        return this.left == null && this.right == null;
    }

    /**
     * Retourne la fréquence du nœud.
     *
     * @return la fréquence
     */
    public int getFrequence() {
        return this.frequence;
    }

    /**
     * Retourne le fils gauche du nœud.
     *
     * @return le fils gauche, ou null si le nœud est une feuille
     */
    public HuffmanNode getLeft() {
        return this.left;
    }

    /**
     * Retourne le fils droit du nœud.
     *
     * @return le fils droit, ou null si le nœud est une feuille
     */
    public HuffmanNode getRight() {
        return this.right;
    }

    /**
     * Retourne la valeur représentée par ce nœud.
     * <p>
     * Cette méthode n'a de sens que si le nœud est une feuille.
     * </p>
     *
     * @return la valeur du symbole (entre 0 et 255)
     * @throws IllegalStateException si le nœud n'est pas une feuille
     */
    public int getValue() {
        if (!this.isLeaf()) {
            throw new IllegalStateException("La valeur n'est définie que pour les feuilles.");
        }
        return this.value;
    }

    /**
     * Retourne une représentation textuelle du nœud.
     * <p>
     * Utile pour le débogage et l'affichage de l'arbre.
     * </p>
     *
     * @return une chaîne décrivant le nœud
     */
    @Override
    public String toString() {
        if (this.isLeaf()) {
            return "Feuille(valeur=" + this.value + ", freq=" + this.frequence + ")";
        }
        return "Noeud(freq=" + this.frequence + ")";
    }
}