ByteArray  - AS3

Nombre d’octets de données pouvant être lus à partir de la position actuelle dans le tableau d’octets et jusqu’à la fin de ce tableau.

Utilisez la propriété bytesAvailable conjointement avec les méthodes de lecture chaque fois que vous accédez à un objet ByteArray pour vous assurer que les données lues sont valides.

Indique l’encodage d’objet par défaut que doit utiliser la classe ByteArray pour une nouvelle occurrence de ByteArray. Lorsque vous créez une nouvelle occurrence de ByteArray, l’encodage correspondant débute par la valeur de defaultObjectEncoding. La propriété defaultObjectEncoding est initialisée à ObjectEncoding.AMF3.

Lorsqu’un objet est écrit ou lu dans des données binaires, la valeur objectEncoding permet de déterminer le format à utiliser : ActionScript 3.0, ActionScript 2.0 ou ActionScript 1.0. La valeur est une constante extraite de la classe ObjectEncoding.

Eléments de l’API associés

Modifie ou lit l’ordre des octets des données (Endian.BIG_ENDIAN ou Endian.LITTLE_ENDIAN). La valeur par défaut est BIG_ENDIAN.

Eléments de l’API associés

Longueur de l’objet ByteArray, en octets.

Si la longueur est définie sur une valeur supérieure à la longueur en cours, le côté droit du tableau d’octets est rempli de zéros.

Si la longueur est définie sur une valeur inférieure à la longueur en cours, le tableau d’octets est tronqué.

Permet de déterminer le format à utiliser (ActionScript 3.0, ActionScript 2.0 ou ActionScript 1.0) pour l’écriture ou la lecture d’une occurrence de ByteArray. La valeur est une constante extraite de la classe ObjectEncoding.

Eléments de l’API associés

Déplace le pointeur de fichier dans l’objet ByteArray ou en renvoie la position actuelle, en octets. Il s’agit de l’endroit où le prochain appel d’une méthode de lecture ou d’écriture démarre l’opération.

Indique si la mémoire sous-jacente du tableau d’octets est partageable (shareable). Pour un tableau d’octets partageable, toutes les occurrences de ByteArray dans tous les programmes de travail faisant référence au tableau d’octets utilisent la même mémoire système sous-jacente. La valeur par défaut est false, ce qui indique que la mémoire sous-jacente n’est pas partagée entre les programmes de travail.

Cette propriété a également une incidence sur ce que fait le moteur d’exécution avec le tableau d’octets si ce dernier est transmis à un programme de travail à l’aide de la méthode Worker.setSharedProperty() ou de la méthode MessageChannel.send() :

• Not shareable : si cette propriété est définie sur false, lorsque le tableau d’octets est transmis à un programme de travail, le moteur d’exécution crée une copie intégrale du tableau d’octets et alloue un nouveau segment de mémoire dans lequel stocker le contenu du tableau d’octets dupliqué
• Shareable : si cette propriété est définie sur true, lorsque le tableau d’octets est transmis à un programme de travail, le moteur d’exécution utilise la même mémoire sous-jacente que le tampon de stockage pour stocker le contenu de l’occurrence de l’objet ByteArray d’origine et celui de la nouvelle occurrence de l’objet ByteArray créée pour le deuxième programme de travail. Par défaut, les deux occurrences de l’objet ByteArray contiennent une référence au même tableau d’octets sous-jacent.

La possibilité d’accéder à un tableau d’octets partagé à partir de plusieurs programmes de travail simultanément peut entraîner une situation indésirable dans laquelle les deux programmes de travail manipulent en même temps la mémoire sous-jacente du tableau d’octets. Vous pouvez utiliser divers mécanismes pour contrôler l’accès à la mémoire partagée :

• les mécanismes de comparaison/remplacement fournis par les méthodes atomicCompareAndSwapIntAt() et atomicCompareAndSwapLength() de la classe ByteArray
• les mécanismes spécialisés fournis par les classes Mutex et Condition (dans le package flash.concurrent)

Définir cette propriété sur true affecte uniquement le code suivant qui transmet ce tableau d’octets à un programme de travail. Toute copie de ce tableau d’octets ayant déjà été transmise à un programme de travail continue d’exister en tant que copie indépendante.

Si vous définissez cette propriété sur false alors qu’elle était définie sur true, la mémoire sous-jacente du tableau d’octets est immédiatement copiée dans un nouveau segment de mémoire système. Cette occurrence de ByteArray utilise désormais la nouvelle mémoire sous-jacente. Par conséquent, la mémoire sous-jacente de ce tableau d’octets n’est plus partagée avec d’autres programmes de travail, même si elle l’était auparavant. Si, par la suite, vous transmettez ce tableau d’octets à un programme de travail, sa mémoire sous-jacente est copiée comme avec les objets ByteArray dont la propriété shareable est définie sur false.

La valeur par défaut est false.

Eléments de l’API associés

Crée une occurrence de ByteArray qui représente un tableau d’octets contracté, afin de vous permettre d’utiliser les méthodes et propriétés de cette classe pour optimiser les flux et le stockage de vos données.

Dans une opération atomique unique, compare une valeur entière dans ce tableau d’octets à une autre valeur entière et, si elles correspondent, remplace ces octets par une autre valeur.

Cette méthode doit être utilisée avec un tableau d’octets dont la mémoire sous-jacente est partagée entre plusieurs programmes de travail (la propriété shareable de l’occurrence de ByteArray est définie sur true). Elle suit la procédure ci-dessous :

1. Lit une valeur entière depuis ce tableau d’octets en commençant à l’index (mesuré en octets) spécifié dans l’argument byteIndex
2. Compare la valeur actuelle de ce tableau d’octets à la valeur transmise dans l’argument expectedValue
3. Si les deux valeurs sont identiques, elle écrit la valeur de l’argument newValue dans le tableau d’octets à l’emplacement spécifié par le paramètre byteIndex et renvoie la valeur précédemment contenue dans ces octets (valeur lue à l’étape 1)
4. Dans le cas contraire, le contenu du tableau d’octets ne change pas et la méthode renvoie la valeur actuelle lue à partir du tableau d’octets

Toutes ces étapes sont exécutées dans une seule transaction matérielle atomique afin de garantir qu’aucune opération provenant d’autres programmes de travail ne modifie le contenu du tableau d’octets durant l’opération de comparaison/remplacement.

Paramètres

Eléments de l’API associés

Dans une opération atomique unique, compare la longueur de ce tableau d’octets à une valeur fournie et, si elles correspondent, modifie la longueur de ce tableau d’octets.

Cette méthode doit être utilisée avec un tableau d’octets dont la mémoire sous-jacente est partagée entre plusieurs programmes de travail (la propriété shareable de l’occurrence de ByteArray est définie sur true). Il effectue les opérations suivantes :

1. Lit la propriété length de l’entier de l’occurrence de ByteArray
2. Compare la longueur à la valeur transmise à l’argument expectedLength
3. Si les deux valeurs sont identiques, elle remplace la longueur du tableau d’octets par la valeur transmise en tant que paramètre newLength, ce qui augmente ou diminue la taille du tableau d’octets
4. Dans le cas contraire, le tableau d’octets n’est pas modifié

Toutes ces étapes sont exécutées dans une seule transaction matérielle atomique afin de garantir qu’aucune opération provenant d’autres programmes de travail ne modifie le contenu du tableau d’octets durant l’opération de comparaison/redimensionnement.

Paramètres

Eléments de l’API associés

Efface le contenu du tableau d’octets et réinitialise les propriétés length et position sur 0. L’appel à cette méthode libère explicitement la mémoire utilisée par l’occurrence de ByteArray.

Compresse le tableau d’octets. Tout le tableau d’octets est compressé. Après l’appel, la propriété length de l’objet ByteArray est définie sur la nouvelle longueur. La propriété position est définie à la fin du tableau d’octets.

Pour spécifier un algorithme de compression, vous devez transmettre une valeur (définie dans la classe CompressionAlgorithm) en tant que paramètre algorithm. Les algorithmes pris en charge sont les suivants :

Le format de données compressé zlib est décrit à l’adresse http://www.ietf.org/rfc/rfc1950.txt.

L’algorithme de compression deflate est décrit à l’adresse http://www.ietf.org/rfc/rfc1951.txt.

L’algorithme de compression lzma est décrit à la page suivante : http://www.7-zip.org/7z.html.

L’algorithme de compression deflate est utilisé dans plusieurs formats de compression, notamment zlib, gzip, certaines implémentations zip, etc. Lorsque vous compressez les données avec l’un de ces formats de compression, les données compressées (par exemple, le fichier .zip) incluent non seulement la version compressée des données originales, mais également les informations de métadonnées. Exemples de types de métadonnées inclus dans divers formats de fichier : nom de fichier, date/heure de modification du fichier, taille du fichier original, commentaires, données du total de contrôle, etc.

Par exemple, lorsqu’un objet ByteArray est compressé à l’aide de l’algorithme zlib, l’objet ByteArray résultant est structuré dans un format spécifique. Certains octets contiennent des métadonnées sur les données compressées, alors que d’autres contiennent la version compressée actuelle des données originales de l’objet ByteArray. Comme l’indique la spécification du format de données compressées zlib, ces octets (c’est-à-dire la partie contenant la version compressée des données originales) sont compressées à l’aide de l’algorithme deflate. Par conséquent, ces octets sont identiques au résultat de l’appel de compress(air.CompressionAlgorithm.DEFLATE) sur le ByteArray original. Notez toutefois que l’appel de compress(air. CompressionAlgorithm.ZLIB) entraîne l’obtention de métadonnées supplémentaires, alors que l’appel de compress( CompressionAlgorithm.DEFLATE) comprend exclusivement la version compressée des données originales de l’objet ByteArray.

Si vous souhaitez utiliser le format deflate pour compresser les données d’une occurrence de ByteArray dans un format spécifique, tel que gzip ou zip, l’appel de la méthode compress(CompressionAlgorithm.DEFLATE) ne suffit pas. Vous devez créer un objet ByteArray structuré en tenant compte de la spécification du format de compression, et notamment des métadonnées appropriées, ainsi que des données compressées obtenues à l’aide du format deflate. De la même façon, pour décoder les données compressées dans un format tel que gzip ou zip, l’appel de la méthode uncompress(CompressionAlgorithm.DEFLATE) ne suffit pas. Vous devez tout d’abord séparer les métadonnées des données compressées, puis utiliser le format deflate pour décompresser les données compressées.

Paramètres

Eléments de l’API associés

Compresse le tableau d’octets à l’aide de l’algorithme de compression deflate. Tout le tableau d’octets est compressé.

Après l’appel, la propriété length de l’objet ByteArray est définie sur la nouvelle longueur. La propriété position est définie à la fin du tableau d’octets.

L’algorithme de compression deflate est décrit à l’adresse http://www.ietf.org/rfc/rfc1951.txt.

Si vous souhaitez utiliser le format deflate pour compresser les données d’une occurrence de ByteArray dans un format spécifique, tel que gzip ou zip, l’appel de la méthode deflate() ne suffit pas. Vous devez créer un objet ByteArray structuré en tenant compte de la spécification du format de compression, et notamment des métadonnées appropriées, ainsi que des données compressées obtenues à l’aide du format deflate. De la même façon, pour décoder les données compressées dans un format tel que gzip ou zip, l’appel de la méthode inflate() ne suffit pas. Vous devez tout d’abord séparer les métadonnées des données compressées, puis utiliser le format deflate pour décompresser les données compressées.

Eléments de l’API associés

Décompresse le tableau d’octets à l’aide de l’algorithme de compression deflate. Le tableau d’octets doit avoir été compressé à l’aide du même algorithme.

Après l’appel, la propriété length de l’objet ByteArray est définie sur la nouvelle longueur. La propriété position est définie sur 0.

L’algorithme de compression deflate est décrit à l’adresse http://www.ietf.org/rfc/rfc1951.txt.

Pour décoder les données compressées dans un format qui utilise l’algorithme de compression deflate (données au format gzip ou zip, par exemple), l’appel de la méthode inflate() pour un objet ByteArray contenant les données de format de compression ne suffit pas. Vous devez tout d’abord séparer les métadonnées faisant partie du format de données compressées des données compressées actuelles. Pour obtenir de plus amples informations, reportez-vous à description de la méthode compress().

Eléments de l’API associés

Lit une valeur booléenne dans le flux d’octets. Un seul octet est lu, et la valeur true est renvoyée s’il n’est pas nul, false dans le cas contraire.

Lit un octet signé dans le flux d’octets.

La valeur renvoyée est comprise entre -128 et 127.

Lit le nombre d’octets de données spécifié par le paramètre length dans le flux d’octets. Les octets sont lus dans l’objet ByteArray spécifié par le paramètre bytes et sont écrits dans l’objet ByteArray cible en commençant à la position spécifiée par offset.

Paramètres

Plus d’exemples

Lit un nombre à virgule flottante à deux décimales (64 bits), conforme à IEEE 754, dans le flux d’octets.

Lit un nombre à virgule flottante à une décimale (32 bits), conforme à IEEE 754, dans le flux d’octets.

Lit un entier de 32 bits signé dans le flux d’octets.

La valeur renvoyée est comprise entre -2147483648 et 2147483647.

Lit une chaîne à plusieurs octets de longueur spécifiée à partir du flux d’octets et à l’aide du jeu de caractères désigné.

Paramètres

Lit dans le flux d’octets un objet codé au format AMF (Action Message Format) sérialisé.

Eléments de l’API associés

Lit un entier de 16 bits signé dans le flux d’octets.

La valeur renvoyée est comprise entre -32768 et 32767.

Lit un octet non signé dans le flux d’octets.

La valeur renvoyée est comprise entre 0 et 255.

Lit un entier de 32 bits non signé dans le flux d’octets.

La valeur renvoyée est comprise entre 0 et 4294967295.

Lit un entier de 16 bits non signé dans le flux d’octets.

La valeur renvoyée est comprise entre 0 et 65535.

Lit une chaîne UTF-8 dans le flux d’octets. La chaîne doit être précédée d’un caractère non signé indiquant la longueur en octets.

Eléments de l’API associés

Lit une séquence d’octets UTF-8 spécifiée par le paramètre length dans le flux d’octets et renvoie une chaîne.

Paramètres

Fournit une méthode remplaçable pour personnaliser l’encodage JSON de valeurs dans un objet ByteArray.

La méthode JSON.stringify() recherche une méthode toJSON() sur chaque objet qu’elle traverse. Si la méthode toJSON() est trouvée, la méthode JSON.stringify() l’appelle automatiquement pour chaque valeur qu’elle rencontre, en transmettant la clé associée à la valeur.

ByteArray fournit une implémentation par défaut de toJSON() qui renvoie simplement le nom de la classe. Etant donné que le contenu de tout ByteArray nécessite une interprétation, les clients qui souhaitent exporter des objets ByteArray dans JSON doivent fournir leur propre implémentation. Pour ce faire, vous pouvez redéfinir la méthode toJSON() sur le prototype de classe.

La méthode toJSON() peut renvoyer une valeur de n’importe quel type. Si elle renvoie un objet, stringify() se répète dans cet objet. Si toJSON() renvoie une chaîne, stringify() ne se répète pas et poursuit sa traversée.

Paramètres

Informations complémentaires

Eléments de l’API associés

Convertit le tableau d’octets en chaîne. Si les données du tableau débutent par une marque d’ordre d’octet Unicode, l’application la respecte lors de la conversion en chaîne. Si System.useCodePage est défini sur true, l’application traite les données du tableau comme si elles figuraient dans l’actuelle page de codes système lors de la conversion.

Décompresse le tableau d’octets. Après l’appel, la propriété length de l’objet ByteArray est définie sur la nouvelle longueur. La propriété position est définie sur 0.

Le tableau d’octets doit avoir été compressé à l’aide du même algorithme que celui de décompression. Pour spécifier un algorithme de décompression, vous devez transmettre une valeur (définie dans la classe CompressionAlgorithm) en tant que paramètre algorithm. Les algorithmes pris en charge sont les suivants :

Le format de données compressé zlib est décrit à l’adresse http://www.ietf.org/rfc/rfc1950.txt.

L’algorithme de compression deflate est décrit à l’adresse http://www.ietf.org/rfc/rfc1951.txt.

L’algorithme de compression lzma est décrit à la page suivante : http://www.7-zip.org/7z.html.

Pour décoder les données compressées dans un format qui utilise l’algorithme de compression deflate (données au format gzip ou zip, par exemple), l’appel de la méthode uncompress(CompressionAlgorithm.DEFLATE) pour un objet ByteArray contenant les données de format de compression ne suffit pas. Vous devez tout d’abord séparer les métadonnées faisant partie du format de données compressées des données compressées actuelles. Pour obtenir de plus amples informations, reportez-vous à description de la méthode compress().

Paramètres

Eléments de l’API associés

Ecrit une valeur booléenne. Un seul octet est écrit, conformément au paramètre value, soit 1 si true ou 0 si false.

Paramètres

Ecrit un octet dans le flux d’octets.

Les 8 bits inférieurs du paramètre sont utilisés. Les 24 bits supérieurs ne sont pas pris en compte.

Paramètres

Ecrit une séquence d’octets length extraits du tableau d’octets bytes, des octets offset de début (index de base zéro) dans le flux d’octets.

Si le paramètre length est omis, la longueur par défaut, 0, est utilisée. La méthode écrit tout le contenu de la mémoire tampon à partir de offset. Si le paramètre offset est également omis, toute la mémoire tampon est écrite.

Si les paramètres offset et length sont hors limites, ils sont réglés sur le début et la fin du tableau (bytes).

Paramètres

Plus d’exemples

Ecrit un nombre à virgule flottante à deux décimales (64 bits), conforme à IEEE 754, dans le flux d’octets.

Paramètres

Ecrit un nombre à virgule flottante à une décimale (32 bits) et conforme à IEEE 754 dans le flux d’octets.

Paramètres

Ecrit un entier de 32 bits signé dans le flux d’octets.

Paramètres

Ecrit une chaîne à plusieurs octets dans le flux d’octets en utilisant le jeu de caractères spécifié.

Paramètres

Ecrit un objet dans le tableau d’octets au format AMF sérialisé.

Paramètres

Eléments de l’API associés

Ecrit un entier de 16 bits dans le flux d’octets. Les 16 bits inférieurs du paramètre sont utilisés. Les 16 bits supérieurs ne sont pas pris en compte.

Paramètres

Ecrit un entier de 32 bits non signé dans le flux d’octets.

Paramètres

Ecrit une chaîne UTF-8 dans le flux d’octets. La longueur de la chaîne UTF-8 exprimée en octets est d’abord écrite sous forme d’entier de 16 bits, suivi des octets représentant les caractères de la chaîne.

Paramètres

Ecrit une chaîne UTF-8 dans le flux d’octets. Comme writeUTF(), mais la méthode writeUTFBytes() n’insère pas dans la chaîne un préfixe correspondant à un mot de 16 bits.

Paramètres

1. Déclarez une nouvelle occurrence de l’objet byteArr.
2. Ecrivez la valeur équivalente en octets de la valeur booléenne false, puis vérifiez la longueur et relisez-la.
3. Ecrivez la valeur à virgule flottante à double décimale de la valeur mathématique de pi.
4. Relisez chacun des neuf octets écrits dans le tableau d’octets.

Remarque : lorsque la méthode trace() est appelée sur un octet, elle imprime l’équivalent décimal des octets stockés dans le tableau d’octets.

Vous remarquerez qu’un segment de code est ajouté à la fin pour vérifier les erreurs de fin de fichier et s’assurer que la lecture du flux d’octets ne dépasse pas la fin.

package {
    import flash.display.Sprite;
    import flash.utils.ByteArray;
    import flash.errors.EOFError;

    public class ByteArrayExample extends Sprite {        
        public function ByteArrayExample() {
            var byteArr:ByteArray = new ByteArray();

            byteArr.writeBoolean(false);
            trace(byteArr.length);            // 1
            trace(byteArr[0]);            // 0

            byteArr.writeDouble(Math.PI);
            trace(byteArr.length);            // 9
            trace(byteArr[0]);            // 0
            trace(byteArr[1]);            // 64
            trace(byteArr[2]);            // 9
            trace(byteArr[3]);            // 33
            trace(byteArr[4]);            // 251
            trace(byteArr[5]);            // 84
            trace(byteArr[6]);            // 68
            trace(byteArr[7]);            // 45
            trace(byteArr[8]);            // 24
            
            byteArr.position = 0;

            try {
                trace(byteArr.readBoolean() == false); // true
            } 
            catch(e:EOFError) {
                trace(e);           // EOFError: Error #2030: End of file was encountered.
            }
            
            try {
                trace(byteArr.readDouble());        // 3.141592653589793
            }
            catch(e:EOFError) {
                trace(e);           // EOFError: Error #2030: End of file was encountered.
            }
            
            try {
                trace(byteArr.readDouble());
            } 
            catch(e:EOFError) {
                trace(e);            // EOFError: Error #2030: End of file was encountered.
            }
        }
    }
}