SAE32_2025/src/fr/iutfbleau/sae/util/ByteUtils.java

package fr.iutfbleau.sae.util;

/**
 * Classe utilitaire regroupant des opérations de conversion entre
 * entiers et octets.
 * <p>
 * Elle est utilisée pour encoder et décoder les champs binaires
 * du format PIF (largeur, hauteur, tailles, etc.).
 * </p>
 *
 * <p>
 * Cette classe :
 * <ul>
 *   <li>ne lit aucun fichier</li>
 *   <li>n'écrit aucun fichier</li>
 *   <li>ne manipule pas les bits individuellement</li>
 * </ul>
 * Elle fournit uniquement des conversions octets ↔ entiers.
 * </p>
 */
public final class ByteUtils {

    /**
     * Constructeur privé empêchant l'instanciation.
     * <p>
     * Cette classe est purement utilitaire et ne doit pas être instanciée.
     * </p>
     */
    private ByteUtils() {
        // j'empêche l'instanciation
    }

    /**
     * Convertit un entier non négatif en deux octets (ordre big-endian).
     * <p>
     * L'octet de poids fort est placé en première position,
     * suivi de l'octet de poids faible.
     * </p>
     *
     * @param value valeur entière à convertir (0 ≤ value ≤ 65535)
     * @return tableau de deux octets : [octetFort, octetFaible] M
     * @throws IllegalArgumentException si la valeur ne tient pas sur 2 octets
     */
    public static byte[] toBytes(int value) {
        if (value < 0 || value > 0xFFFF) {
            throw new IllegalArgumentException(
                "La valeur doit être comprise entre 0 et 65535"
            );
        }

        byte[] result = new byte[2];

        /*
         * Extraction de l'octet de poids fort :
         * - décalage de 8 bits vers la droite
         * - masquage pour ne conserver que les 8 bits utiles
         */
        result[0] = (byte) ((value >>> 8) & 0xFF);

        /*
         * Extraction de l'octet de poids faible :
         * - aucun décalage nécessaire
         * - masquage pour conserver les 8 bits de droite
         */
        result[1] = (byte) (value & 0xFF);

        return result;
    }

    /**
     * Reconstruit un entier à partir de deux octets (ordre big-endian).
     * <p>
     * L'octet de poids fort est replacé dans les bits 15 à 8,
     * puis combiné avec l'octet de poids faible.
     * </p>
     *
     * @param high octet de poids fort
     * @param low octet de poids faible
     * @return entier reconstruit à partir des deux octets
     */
    public static int toInt(byte high, byte low) {
        /*
         * - masquage pour supprimer le signe des octets Java
         * - décalage de l'octet fort vers la gauche
         * - combinaison des deux octets par un OU binaire
         */
        return ((high & 0xFF) << 8) | (low & 0xFF);
    }
}