Binaries

```
public interface Binaries
```
Cette bibliothèque fournit une outil à outils permettant de créer et d'effectuer les opérations courantes sur des configurations binaires. Une configuration binaire est définie par son format (le nombre de bits) et son contenu. Le format est déterminé de la façon suivante:
- à la création, il est juste suffisant pour contenir la valeur initiale (newBinary( String). Il est toutefois possible de préciser ce format de manière explicite (newBinary( String, int)).
- pour les opérations bit à bit (#and(extensions.Binary, extensions.Binary), #or(extensions.Binary, extensions.Binary)), #or(extensions.Binary, extensions.Binary), #xor(extensions.Binary, extensions.Binary), #not(extensions.Binary)), c'est le format du plus grand opérande qui est adopté.
- pour les opérations de décalage (#lsl(extensions.Binary, int) , #lsr(extensions.Binary, int) , #asr(extensions.Binary, int) ), le format de l'opérande est conservé.
- pour les opérations arithmétiques (#add(extensions.Binary, extensions.Binary) ), le format est allongé de 1 bit (ce qui permet de stocker la valeur d'une retenue éventuelle.
Le format ne peut dépasser 32 bits. Une opération qui devrait impliquer un dépassement de cette limite provoquera une erreur et l'arrêt du programme.

Syntaxe de la chaîne d'initialisation.
La chaîne d'initialisation utilisée dans plusieurs fonctions (newBinary( String), newBinary( String, int), readBinary() et readBinary(int)) est la suivante:
- Si la chaîne commence par "0x" ou "0X": La fin de la chaîne est interprétée comme une chaîne hexadécimale. Elle ne devrait donc comporter que des chiffres décimaux ou des lettres A à F ou a à f.
- Si la chaîne commence par "0b" ou "0B": La fin de la chaîne est interprétée comme une chaîne binaire. Elle ne devrait donc comporter que des chiffres binaires 0 ou 1.
- Dans tous les autres cas: La fin de la chaîne est interprétée comme une chaîne décimale. Elle ne devrait donc comporter que des chiffres décimaux 0 à 9.
Si cette n'est pas respectée, les fonctions ci-dessus provoqueront une erreur.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Binary`	`add(Binary b1, Binary b2)` Réalise l'addition binaire de deux opérandes.
`Binary`	`and(Binary b1, Binary b2)` Calcule et retourne la configuration binaire résultante de l'opération ET bit à bit entre les deux opérandes.
`Binary`	`asr(Binary b1, int decalage)` Calcule et retourne la configuration binaire résultante du décalage arithmétique à droite de l'opérande `b1` de `decalage` positions.
`Binary`	`dropCarry(Binary b)` Permet d'extraire la partie fixe (hors retenue) du résultat d'une addition.
`Binary`	`getCarry(Binary b)` Permet d'isoler la retenue provoque par une addition.
`Binary`	`lsl(Binary b1, int decalage)` Calcule et retourne la configuration binaire résultante du décalage logique à gauche de l'opérande `b1` de `decalage` positions.
`Binary`	`lsr(Binary b1, int decalage)` Calcule et retourne la configuration binaire résultante du décalage logique à droite de l'opérande `b1` de `decalage` positions.
`Binary`	`newBinary(long valeur)` Crée une configuration binaire initialisée par la valeur du paramètre.
`Binary`	`newBinary(long valeur, int format)` Crée une configuration binaire de format fixé et initialisée par la valeur du paramètre.
`Binary`	`newBinary( String valeur)` Crée une configuration binaire, décimale ou hexadécimale, initialisée.
`Binary`	`newBinary( String valeur, int format)` Crée une configuration binaire, décimale ou hexadécimale de format fixé et initialisée.
`Binary`	`not(Binary b1)` Calcule et retourne la configuration binaire résultante de l'opération NON bit à bit entre les deux opérandes.
`Binary`	`or(Binary b1, Binary b2)` Calcule et retourne la configuration binaire résultante de l'opération ET bit à bit entre les deux opérandes.
`void`	`println(Binary b)` Affiche la valeur d'une configuration binaire.
`Binary`	`readBinary()` Demande la saisie d'une ligne à l'utilisateur et interprète cette saisie pour initialiser la configuration binaire créée.
`Binary`	`readBinary(int format)` Demande la saisie d'une ligne à l'utilisateur et interprète cette saisie pour initialiser la configuration binaire créée, de format fixe.
`Binary`	`xor(Binary b1, Binary b2)` Calcule et retourne la configuration binaire résultante de l'opération OU (inclusif) bit à bit entre les deux opérandes.

- Method Detail
  - newBinary
```
Binary newBinary(long valeur)
```
    Crée une configuration binaire initialisée par la valeur du paramètre. Le paramètre peut être spécifié en décimal ou en hexadécimal. (pour la notation binaire, voir newBinary( String). La configuration est juste assez large pour coder la valeur entière. Les valeurs négatives sont admises et utilisent le codage en complément à 2.
    Exemples:
    Binary b = newBinary(15) ; créera un quarté (4 bits) de valeur "1111" (notation décimale).
    Binary b = newBinary(-128) ; créera un paquet de 8 bits de valeur "1000000" (notation décimale signée).
    Binary b = newBinary(0x4F) ; créera un paquet de 7 bits de valeur "1001111" (notation hexadécimale).
    
    Parameters:
    
    valeur - La valeur initiale de la configuration.
    
    Returns:
    
    La configuration binaire créée.
  - newBinary
```
Binary newBinary(long valeur,
                 int format)
```
    Crée une configuration binaire de format fixé et initialisée par la valeur du paramètre. Les valeurs négatives sont admises et utilisent le codage en complément à 2. La taille de la configuration est précisée par la valeur du second paramètre. Si cette taille est nulle ou si elle n'est pas suffisante, une erreur se produit.
    
    Parameters:
    
    valeur - La valeur initiale de la configuration.
    
    Returns:
    
    La configuration binaire créée.
  - newBinary
```
Binary newBinary( String valeur)
```
    Crée une configuration binaire, décimale ou hexadécimale, initialisée. La chaîne d'initialisation doit être composée de chiffres binaires. Pour une notation décimale ou en hexadécimale, voir newBinary(long). Si la chaîne contient autre chose que des 0 et des 1, une erreur se produit. La format produit est déterminé par la longueur de la chaîne.
    Exemples:
    Binary b = newBinary("0b00000000") ; créera un octet (8 bits) de valeur nulle (soit 00000000b).
    Binary b = newBinary("255") ; créera un octet (8 bits) de valeur 11111111).
    Binary b = newBinary("0x10") ; créera un quintet (5 bits) de valeur 10000b).
    
    Parameters:
    
    valeur - La valeur initiale de la configuration.
    
    Returns:
    
    La configuration binaire créée.
  - newBinary
```
Binary newBinary( String valeur,
                 int format)
```
    Crée une configuration binaire, décimale ou hexadécimale de format fixé et initialisée. La chaîne d'initialisation doit être d'au maximum format bits. Une chaîne plus courte que le format demandé sera cadrée à droite (poids faibles) et complétée par des 0. Une chaîne plus longue engendrera une erreur.
    Exemples:
    Binary b = newBinary("0b11", 8) ; créera un octet (8 bits) de valeur 11 (soit 00000001b).
    Binary b = newBinary("0x11", 4) ; provoquera une erreur.
    
    Parameters:
    
    valeur - La valeur initiale de la configuration.
    
    format - La taille voulue pour la configuration produite.
    
    Returns:
    
    La configuration binaire créée.
  - readBinary
```
Binary readBinary()
```
    Demande la saisie d'une ligne à l'utilisateur et interprète cette saisie pour initialiser la configuration binaire créée. La syntaxe de la saisie est la même que pour la fonction newBinary( String)
    
    Returns:
    
    La configuration binaire calculée.
  - readBinary
```
Binary readBinary(int format)
```
    Demande la saisie d'une ligne à l'utilisateur et interprète cette saisie pour initialiser la configuration binaire créée, de format fixe. La syntaxe de la saisie est la même que pour la fonction newBinary( String). Si le format n'est pas suffisant pour héberger la valeur fournie, une erreur est générée.
    
    Parameters:
    
    format - La taille voulue pour la configuration produite.
    
    Returns:
    
    La configuration binaire calculée.
  - println
```
void println(Binary b)
```
    Affiche la valeur d'une configuration binaire. Les formes binaires est hexadécimales sont affichées.
    
    Parameters:
    
    b -
  - and
```
Binary and(Binary b1,
           Binary b2)
```
    Calcule et retourne la configuration binaire résultante de l'opération ET bit à bit entre les deux opérandes. Le format du résultat est le plus grand des formats des entrées (la plus petite entrée étant cadrée à droite et complétée par des 0).
    Exemple: and(newBinaire("0011"), newBinaire("0101")) donne "0001"
    
    Parameters:
    
    b1 - Le premier opérande.
    
    b2 - Le second opérande.
    
    Returns:
    
    La configuration binaire calculée.
  - or
```
Binary or(Binary b1,
          Binary b2)
```
    Calcule et retourne la configuration binaire résultante de l'opération ET bit à bit entre les deux opérandes. Le format du résultat est le plus grand des formats des entrées (la plus petite entrée étant cadrée à droite et complétée par des 0).
    Exemple: or(newBinaire("0011"), newBinaire("0101")) donne "0111"
    
    Parameters:
    
    b1 - Le premier opérande.
    
    b2 - Le second opérande.
    
    Returns:
    
    La configuration binaire calculée.
  - xor
```
Binary xor(Binary b1,
           Binary b2)
```
    Calcule et retourne la configuration binaire résultante de l'opération OU (inclusif) bit à bit entre les deux opérandes. Le format du résultat est le plus grand des formats des entrées (la plus petite entrée étant cadrée à droite et complétée par des 0).
    Exemple: xor(newBinaire("0011"), newBinaire("0101")) donne "0110"
    
    Parameters:
    
    b1 - Le premier opérande.
    
    b2 - Le second opérande.
    
    Returns:
    
    La configuration binaire calculée.
  - not
```
Binary not(Binary b1)
```
    Calcule et retourne la configuration binaire résultante de l'opération NON bit à bit entre les deux opérandes. Le format du résultat est celui de l'entrée.
    Exemple: not(newBinaire("0101")) donne "1010"
    
    Parameters:
    
    b1 - L'opérande.
    
    Returns:
    
    La configuration binaire calculée.
  - asr
```
Binary asr(Binary b1,
           int decalage)
```
    Calcule et retourne la configuration binaire résultante du décalage arithmétique à droite de l'opérande b1 de decalage positions. Les bits situé à droite sont perdus. Le format de l'opérande est conservé.
    Note: Le décalage arithmétique recopie et laisse inchangé le bit de signe (bit de poids fort). Exemple: asr(newBinaire("10110001"), 3) donne "11110110" Exemple: asr(newBinaire("00110001"), 3) donne "00000110"
    
    Parameters:
    
    b1 - L'opérande.
    
    decalage - Le nombre de positions décalées (0 = aucun changement).
    
    Returns:
    
    La configuration binaire calculée.
  - lsl
```
Binary lsl(Binary b1,
           int decalage)
```
    Calcule et retourne la configuration binaire résultante du décalage logique à gauche de l'opérande b1 de decalage positions. Les bits situé à gauche sont perdus. Le format de l'opérande est conservé.
    Exemple: lsl(newBinaire("10110001"), 2) donne "11000100"
    
    Parameters:
    
    b1 - L'opérande.
    
    decalage - Le nombre de positions décalées (0 = aucun changement).
    
    Returns:
    
    La configuration binaire calculée.
  - lsr
```
Binary lsr(Binary b1,
           int decalage)
```
    Calcule et retourne la configuration binaire résultante du décalage logique à droite de l'opérande b1 de decalage positions. Les bits situé à droites sont perdus. Le format de l'opérande est conservé.
    Note: Le décalage logique recopie le bit de signe (bit de poids fort) mais le met à 0. Exemple: lsr(newBinaire("10110001"), 3) donne "00010110" Exemple: lsr(newBinaire("00110001"), 3) donne "00000110"
    
    Parameters:
    
    b1 - L'opérande.
    
    decalage - Le nombre de positions décalées (0 = aucun changement).
    
    Returns:
    
    La configuration binaire calculée.
  - add
```
Binary add(Binary b1,
           Binary b2)
```
    Réalise l'addition binaire de deux opérandes. Le format du résultat est le plus grand des formats des entrées plus 1 (pour la retenue). (la plus petite entrée étant cadrée à droite et complétée par des 0). Les fonctions Binaries#getCarry(extensions.Binary) et Binaries#dropCarry(extensions.Binary) peuvent ensuite être exploitées pour isoler la retenue ou forcer un calcul sur un nombre fixe de bits.
    Exemple:
```
 // Calcul et décomposition des résultats d'une addition binaire.
 Binary b1 = newBinaire("0b1101") ;
 Binary b2 = newBinaire("0b0101") ;
 Binary resultat = add(b1, b2) ; // Calcule  10010 sur (4 + 1) bits.
 Binary carry = getCarry(resultat) ; // carry = 1
 Binary fixe = dropCarry(resultat) ; // fixe = 0b0010 (sur 4 bits) 
```
    Parameters:
    
    b1 - La première opérande.
    
    b2 - La seconde opérande.
    
    Returns:
    
    le binaire correspondant à l'addition binaire de b1 et b2.
  - getCarry
```
Binary getCarry(Binary b)
```
    Permet d'isoler la retenue provoque par une addition.
    
    Parameters:
    
    b - Le résultat de l'addition.
    
    Returns:
    
    La retenue (sur 1 bit : 0 ou 1)
  - dropCarry
```
Binary dropCarry(Binary b)
```
    Permet d'extraire la partie fixe (hors retenue) du résultat d'une addition.
    
    Parameters:
    
    b - Le résultat de l'addition.
    
    Returns:
    
    Le résultat amputé de la retenue.

Interface Binaries

Syntaxe de la chaîne d'initialisation.

Method Summary

Method Detail

newBinary

newBinary

newBinary

newBinary

readBinary

readBinary

println

and

or

xor

not

asr

lsl

lsr

add

getCarry

dropCarry