Un objetTypedArray décrit une vue organisée à la façon d'un tableau pour manipulerun tampon (buffer) de données binaires.TypedArray n'est pas une propriété globale, il n'existe pas non plus de constructeurTypedArray. En revanche, plusieurs propriétés globales existent et leurs valeurs permettent de construire des tableaux typés (typed arrays) avec différents types de données. Ceux-ci sont listés ci-après. Les pages suivantes permettent de décrire les propriétés et méthodes qui peuvent être utilisées sur les différents tableaux typés.

Exemple interactif

// Create a TypedArray with a size in bytesconst typedArray1 = new Int8Array(8);typedArray1[0] = 32;const typedArray2 = new Int8Array(typedArray1);typedArray2[1] = 42;console.log(typedArray1);// Expected output: Int8Array [32, 0, 0, 0, 0, 0, 0, 0]console.log(typedArray2);// Expected output: Int8Array [32, 42, 0, 0, 0, 0, 0, 0]

Description

ECMAScript 2015 (ES6) définit un constructeur%TypedArray% qui est un[[Prototype]] de tous les constructeursTypedArray. Ce constructeur n'est pas accessible directement. Il n'existe pas de%TypedArray% global ou de propriétéTypedArray. Il est uniquement accessible viaObject.getPrototypeOf(Int8Array.prototype) ou avec les méthodes semblables. L'ensemble des différents constructeursTypedArrays hérite de propriétés communes de la fonction%TypedArray%. De plus, tous les prototypes des tableaux typés (TypedArray.prototype) ont%TypedArray%.prototype pour[[Prototype]].

Lorsqu'on crée une instance deTypedArray (par exemple, une instance deInt8Array ou autre), un tampon de mémoire tableau est créé en interne par le moteur (si un objetArrayBuffer est passé en argument, c'est celui-ci qui est utilisé). C'est l'adresse de cette mémoire tampon qui est sauvegardée comme une propriété interne à l'objet. Toutes les méthodes de%TypedArray%.prototype utiliseront ensuite cet espace pour les opérations.

ObjetsTypedArray

Constructeur

Cet objet ne peut pas être instancié directement. On créera plutôt une instance d'un tableau typé d'un type donné, tel queInt8Array ouBigInt64Array. Ces différents types partagent une syntaxe commune pour leur constructeur :

new TypedArray();new TypedArray(longueur);new TypedArray(tableauType);new TypedArray(objet);new TypedArray(buffer);new TypedArray(buffer, decalageOctet);new TypedArray(buffer, decalageOctet, longueur);

OùTypedArray est un constructeur donné pour un type de tableau typé existant.

Paramètres

longueur

Lorsque le constructeur est appelé avec un argumentlongueur, un tampon de mémoire interne sous forme de tableau est créé et dont la taille estlongueur multipliée parBYTES_PER_ELEMENT octets. Chaque élément du tableau contient des zéros.

tableauType

Lorsque le constructeur est appelé avec un argumenttableauType,tableauType est copié dans un nouveau tableau typé. Pour un tableay typédont le type n'est pasBigInt64Array, le paramètre peut être un objet de n'importe quel type de tableau typé en dehors deBigInt64Array (par exempleInt32Array). L'inverse est aussi valable, pour obtenir un tableau typéBigInt64Array, le paramètre devra nécessairement être de typeBigInt64Array.Chaque valeur contenue danstableauType est convertie dans le type correspondant au constructeur avant d'être copiée dans le nouveau tableau. La longueur du nouveau tableau typé sera la même que celle de l'argumenttableauType.

objet

Lorsque le constructeur est appelé avec un objet comme argument, un nouveau tableau typé est créé à la façon de la méthodeTypedArray.from().

buffer,decalageOctet,longueur

Lorsque le constructeur est appelé avec un tampon de mémoirebuffer, et éventuellement des argumentsdecalageOctet etlongueur, une nouvelle vue sous la formule d'un tableau typé est créé sur l'objetArrayBuffer porté par le premier argument. Les paramètresdecalageOctet etlongueur indique l'intervalle de mémoire exposée à la vue du tableau typé. Si les deux paramètres sont absents, c'est tout le tampon qui est vu. Si seul le paramètrelongueur est absent, c'est le reste du tampon qui est vu (à partir dedecalageOctet).

Propriétés statiques

TypedArray.BYTES_PER_ELEMENT

Renvoie un nombre indiquant la taille, exprimée en octets, de chaque élément du tableau typé.

TypedArray.name

Renvoie la chaîne de caractères correspondant au nom du constructeur (par exemple,"Int8Array").

get TypedArray[@@species]

La fonction de construction utilisée pour créer des objets dérivés.

TypedArray

Le prototype pour les objesTypedArray.

Méthodes statiques

TypedArray.from()

Crée un nouveau tableau typé à partir d'un objet itérable ou semblable à un tableau. Voir aussiArray.from().

TypedArray.of()

Crée un nouveau tableau typé avec un nombre variable d'arguments. Voir aussiArray.of().

Propriétés des instances

TypedArray.prototype.buffer

Renvoie l'objetArrayBuffer référencé par le tableau typé. Il est déterminé au moment de la construction et est donc uniquement accessibleen lecture seule.

TypedArray.prototype.byteLength

Renvoie la longueur, exprimée en octets, du tableau typé. Elle est déterminée au moment de la construction et est donc uniquement accessibleen lecture seule.

TypedArray.prototype.byteOffset

Renvoie le décalage, exprimé en octet, de la vue fournie par le tableau typé par rapport au début de l'objetArrayBuffer correspondant. Il est déterminé au moment de la construction et est donc uniquement accessibleen lecture seule.

TypedArray.prototype.length

Renvoie le nombre d'éléments contenus dans le tableau typé. Il est déterminé au moment de la construction et est donc uniquement accessibleen lecture seule.

Méthodes des instances

TypedArray.prototype.at()

Prend une valeur entière comme argument et renvoie l'élément situé à cet indice. Il est possible d'utiliser des indices négatifs, le tableau est alors parcouru depuis la fin.

TypedArray.prototype.copyWithin()

Copie une suite d'éléments de tableau dans le tableau typé. Voir aussiArray.prototype.copyWithin().

TypedArray.prototype.entries()

Renvoie un nouvel objet itérateur de tableau qui contient les paires de clé/valeur pour chaque indice du tableau. Voir aussiArray.prototype.entries().

TypedArray.prototype.every()

Teste si l'ensemble des éléments du tableau valident le test fourni par la fonction passée en argument. Voir aussiArray.prototype.every().

TypedArray.prototype.fill()

Remplit l'ensemble des éléments du tableau situés entre un indice de début et un indice de fin avec une valeur statique. Voir aussiArray.prototype.fill().

TypedArray.prototype.filter()

Crée un nouveau tableau avec l'ensemble des éléments du tableau pour lesquels la fonction passée en argument renvoitrue. Voir aussiArray.prototype.filter().

TypedArray.prototype.find()

Renvoie la valeur trouvée dans le tableau si un élément du tableau satisfait au critère fourni par la fonction passée en argument, ouundefined s'il n'existe pas de tel élément. Voir aussiArray.prototype.find().

TypedArray.prototype.findIndex()

Renvoie l'indice d'un élément du tableau qui satisfait au critère fourni par la fonction passée en argument ou-1 s'il n'existe pas de tel élément. Voir aussiArray.prototype.findIndex().

TypedArray.prototype.forEach()

Appelle une fonction pour chaque élément du tableau. Voir aussiArray.prototype.forEach().

TypedArray.prototype.includes()

Détermine si un tableau typé inclut un certain élément, renvoyanttrue oufalse selon le cas de figure. Voir aussiArray.prototype.includes().

TypedArray.prototype.indexOf()

Renvoie le plus petit indice d'un élément du tableau qui est égal à la valeur fournie en argument, ou-1 si aucun élément n'est trouvé. Voir aussiArray.prototype.indexOf().

TypedArray.prototype.join()

Fusionne l'ensemble des éléments du tableau en une chaîne de caractères. Voir aussiArray.prototype.join().

TypedArray.prototype.keys()

Renvoie un nouvel itérateur de tableau qui contient les clés pour chaque indice du tableau. Voir aussiArray.prototype.keys().

TypedArray.prototype.lastIndexOf()

Renvoie le plus grand indice d'un élément du tableau qui est égal à la valeur fournie, ou-1 s'il n'y a pas de tel élément. Voir aussiArray.prototype.lastIndexOf().

TypedArray.prototype.map()

Crée un nouveau tableau dont les éléments sont les résultats de l'appel de la fonction passée en argument pour chaque élément du tableau original. Voir aussiArray.prototype.map().

TypedArray.prototype.reduce()

Applique une fonction avec un accumulateur pour chaque valeur du tableau (de gauche à droite), afin de le réduire à une seule valeur. Voir aussiArray.prototype.reduce().

TypedArray.prototype.reduceRight()

Applique une fonction avec un accumulateur pour chaque valeur du tableau (de droite à gauche), afin de le réduire à une seule valeur. Voir aussiArray.prototype.reduceRight().

TypedArray.prototype.reverse()

Inverse l'ordre des éléments d'un tableau (le premier devenant le dernier, le dernier devenant le premier et ainsi de suite). Voir aussiArray.prototype.reverse().

TypedArray.prototype.set()

Enregistre plusieurs valeurs dans le tableau typé à partir d'un tableau de valeurs donné.

TypedArray.prototype.slice()

Extrait une section d'un tableau et renvoie un nouveau tableau. Voir aussiArray.prototype.slice().

TypedArray.prototype.some()

Renvoietrue si au moins un des éléments du tableau satisfait au critère fourni par la fonction passée en argument. Voir aussiArray.prototype.some().

TypedArray.prototype.sort()

Trie les éléments du tableau à même le tableau puis le renvoie. Voir aussiArray.prototype.sort().

TypedArray.prototype.subarray()

Renvoie un nouveau tableau typé avec les éléments contenus entre un indice de début et un indice de fin.

TypedArray.prototype.values()

Renvoie un nouvel objetitérateur de tableau qui contient les valeurs pour chaque indice du tableau. Voir aussiArray.prototype.values().

TypedArray.prototype.toLocaleString()

Renvoie une chaîne de caractères localisée qui représente le tableau et ses éléments. Voir aussiArray.prototype.toLocaleString().

TypedArray.prototype.toString()

Renvoie une chaîne de caractères représentant le tableau et ses éléments. Voir aussiArray.prototype.toString().

TypedArray.prototype[@@iterator]()

Renvoie un nouvel objetitérateur de tableau qui contient les valeurs pour chaque indice du tableau.

Exemples

Caractère obligatoire denew

À partir d'ECMAScript 2015, les constructeursTypedArray doivent être appelés avec l'opérateurnew. Appeler un tel constructeur comme fonction, sansnew, déclenchera une exceptionTypeError.

let dv = Int8Array([1, 2, 3]);// TypeError: calling a builtin Int8Array constructor// without new is forbidden

let dv = new Int8Array([1, 2, 3]);

Accès aux propriétés

Il est possible d'accéder aux éléments du tableau en utilisant la notation usuelle avec les crochets. Cependant, définir ou accéder à des propriétés indexées ne se fera pas avec la chaîne de prototypes, même si l'indice utilisé est en dehors des limites du tableau. Les propriétés indexées seront uniquement basées sur le contenu duArrayBuffer et ne consulteront pas les propriétés des objets. En revanche, il est toujours possible d'utiliser des propriétés nommées, comme avec les autres objets.

// Définir et accéder du contenu avec la syntaxe usuellelet int16 = new Int16Array(2);int16[0] = 42;console.log(int16[0]); // 42// Les propriétés indexées sur les prototypes ne sont pas consultéesInt8Array.prototype[20] = "toto";new Int8Array(32)[20]; // 0// y compris en dehors des limitesInt8Array.prototype[20] = "toto";new Int8Array(8)[20]; // undefined// ou avec des index négatifsInt8Array.prototype[-1] = "toto";new Int8Array(8)[-1]; // undefined// Mais il est possible d'utiliser des propriétés nomméesInt8Array.prototype.toto = "truc";new Int8Array(32).toto; // "truc"

Impossibles à geler

Les tableaux typés qui ne sont pas vides ne peuvent pas être gelés, car le tampon de mémoireArrayBuffer sous-jacent pourrait être modifié via une autre vue fournie par un autre tableau typé sur ce même tampon. En pratique, cela voudrait dire que l'objet n'est pas réellement gelé.

const i8 = Int8Array.of(1, 2, 3);Object.freeze(i8);// TypeError: Cannot freeze array buffer views with elements

Alignement dedecalageOctet

Lors de la construction d'un objetTypedArray comme une vue sur un tamponArrayBuffer, l'argumentdecalageOctet doit être aligné par rapport à la taille des éléments. Autrement dit, le décalage fourni doit être un multiple deBYTES_PER_ELEMENT.

const i32 = new Int32Array(new ArrayBuffer(4), 1);// RangeError: start offset of Int32Array should be a multiple of 4

const i32 = new Int32Array(new ArrayBuffer(4), 0);

Alignement de la propriétébyteLength

À l'instar du paramètredecalageOctet, la propriétébyteLength d'un objetArrayBuffer passé au constructeurTypedArray doit être un multiple de la valeurBYTES_PER_ELEMENT correspondant au type du constructeur.

const i32 = new Int32Array(new ArrayBuffer(3));// RangeError: byte length of Int32Array should be a multiple of 4

const i32 = new Int32Array(new ArrayBuffer(4));

Spécifications

Compatibilité des navigateurs

Voir aussi

• Une prothèse d'émulation pour les tableaux typés avec la bibliothèquecore-js
• Les tableaux typés en JavaScript
• ArrayBuffer
• DataView
• TextDecoder, une API utilitaire pour décoder des chaînes de caractères à partir de données numériques