TypedArray

Exemple interactif

// Create a TypedArray with a size in bytes
const 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) dfinit un constructeur %TypedArray% qui est un [[Prototype]] de tous les constructeurs TypedArray. Ce constructeur n'est pas accessible directement. Il n'existe pas de %TypedArray% global ou de proprit TypedArray. Il est uniquement accessible via Object.getPrototypeOf(Int8Array.prototype) ou avec les mthodes semblables. L'ensemble des diffrents constructeurs TypedArrays hrite de proprits communes de la fonction %TypedArray%. De plus, tous les prototypes des tableaux typs (TypedArray.prototype) ont %TypedArray%.prototype pour [[Prototype]].

Lorsqu'on cre une instance de TypedArray (par exemple, une instance de Int8Array ou autre), un tampon de mmoire tableau est cr en interne par le moteur (si un objet ArrayBuffer est pass en argument, c'est celui-ci qui est utilis). C'est l'adresse de cette mmoire tampon qui est sauvegarde comme une proprit interne l'objet. Toutes les mthodes de %TypedArray%.prototype utiliseront ensuite cet espace pour les oprations.

Objets TypedArray

Constructeur

Cet objet ne peut pas tre instanci directement. On crera plutt une instance d'un tableau typ d'un type donn, tel que Int8Array ou BigInt64Array. Ces diffrents 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.

Paramtres

longueur

Lorsque le constructeur est appel avec un argument longueur, un tampon de mmoire interne sous forme de tableau est cr et dont la taille est longueur multiplie par BYTES_PER_ELEMENT octets. Chaque lment du tableau contient des zros.

tableauType

Lorsque le constructeur est appel avec un argument tableauType, tableauType est copi dans un nouveau tableau typ. Pour un tableay typ dont le type n'est pas BigInt64Array, le paramtre peut tre un objet de n'importe quel type de tableau typ en dehors de BigInt64Array (par exemple Int32Array). L'inverse est aussi valable, pour obtenir un tableau typ BigInt64Array, le paramtre devra ncessairement tre de type BigInt64Array. Chaque valeur contenue dans tableauType est convertie dans le type correspondant au constructeur avant d'tre copie dans le nouveau tableau. La longueur du nouveau tableau typ sera la mme que celle de l'argument tableauType.

objet

Lorsque le constructeur est appel avec un objet comme argument, un nouveau tableau typ est cr la faon de la mthode TypedArray.from().

buffer, decalageOctet, longueur

Lorsque le constructeur est appel avec un tampon de mmoire buffer, et ventuellement des arguments decalageOctet et longueur, une nouvelle vue sous la formule d'un tableau typ est cr sur l'objet ArrayBuffer port par le premier argument. Les paramtres decalageOctet et longueur indique l'intervalle de mmoire expose la vue du tableau typ. Si les deux paramtres sont absents, c'est tout le tampon qui est vu. Si seul le paramtre longueur est absent, c'est le reste du tampon qui est vu ( partir de decalageOctet).

Proprits statiques

TypedArray.BYTES_PER_ELEMENT

Renvoie un nombre indiquant la taille, exprime en octets, de chaque lment du tableau typ.

TypedArray.name

Renvoie la chane de caractres correspondant au nom du constructeur (par exemple, "Int8Array").

get TypedArray[@@species]

La fonction de construction utilise pour crer des objets drivs.

TypedArray

Le prototype pour les objes TypedArray.

Mthodes statiques

TypedArray.from()

Cre un nouveau tableau typ partir d'un objet itrable ou semblable un tableau. Voir aussi Array.from().

TypedArray.of()

Cre un nouveau tableau typ avec un nombre variable d'arguments. Voir aussi Array.of().

Proprits des instances

TypedArray.prototype.buffer

Renvoie l'objet ArrayBuffer rfrenc par le tableau typ. Il est dtermin au moment de la construction et est donc uniquement accessible en lecture seule.

TypedArray.prototype.byteLength

Renvoie la longueur, exprime en octets, du tableau typ. Elle est dtermine au moment de la construction et est donc uniquement accessible en lecture seule.

TypedArray.prototype.byteOffset

Renvoie le dcalage, exprim en octet, de la vue fournie par le tableau typ par rapport au dbut de l'objet ArrayBuffer correspondant. Il est dtermin au moment de la construction et est donc uniquement accessible en lecture seule.

TypedArray.prototype.length

Renvoie le nombre d'lments contenus dans le tableau typ. Il est dtermin au moment de la construction et est donc uniquement accessible en lecture seule.

Mthodes des instances

TypedArray.prototype.at()

Prend une valeur entire comme argument et renvoie l'lment situ cet indice. Il est possible d'utiliser des indices ngatifs, le tableau est alors parcouru depuis la fin.

TypedArray.prototype.copyWithin()

Copie une suite d'lments de tableau dans le tableau typ. Voir aussi Array.prototype.copyWithin().

TypedArray.prototype.entries()

Renvoie un nouvel objet itrateur de tableau qui contient les paires de cl/valeur pour chaque indice du tableau. Voir aussi Array.prototype.entries().

TypedArray.prototype.every()

Teste si l'ensemble des lments du tableau valident le test fourni par la fonction passe en argument. Voir aussi Array.prototype.every().

TypedArray.prototype.fill()

Remplit l'ensemble des lments du tableau situs entre un indice de dbut et un indice de fin avec une valeur statique. Voir aussi Array.prototype.fill().

TypedArray.prototype.filter()

Cre un nouveau tableau avec l'ensemble des lments du tableau pour lesquels la fonction passe en argument renvoi true. Voir aussi Array.prototype.filter().

TypedArray.prototype.find()

Renvoie la valeur trouve dans le tableau si un lment du tableau satisfait au critre fourni par la fonction passe en argument, ou undefined s'il n'existe pas de tel lment. Voir aussi Array.prototype.find().

TypedArray.prototype.findIndex()

Renvoie l'indice d'un lment du tableau qui satisfait au critre fourni par la fonction passe en argument ou -1 s'il n'existe pas de tel lment. Voir aussi Array.prototype.findIndex().

TypedArray.prototype.forEach()

Appelle une fonction pour chaque lment du tableau. Voir aussi Array.prototype.forEach().

TypedArray.prototype.includes()

Dtermine si un tableau typ inclut un certain lment, renvoyant true ou false selon le cas de figure. Voir aussi Array.prototype.includes().

TypedArray.prototype.indexOf()

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

TypedArray.prototype.join()

Fusionne l'ensemble des lments du tableau en une chane de caractres. Voir aussi Array.prototype.join().

TypedArray.prototype.keys()

Renvoie un nouvel itrateur de tableau qui contient les cls pour chaque indice du tableau. Voir aussi Array.prototype.keys().

TypedArray.prototype.lastIndexOf()

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

TypedArray.prototype.map()

Cre un nouveau tableau dont les lments sont les rsultats de l'appel de la fonction passe en argument pour chaque lment du tableau original. Voir aussi Array.prototype.map().

TypedArray.prototype.reduce()

Applique une fonction avec un accumulateur pour chaque valeur du tableau (de gauche droite), afin de le rduire une seule valeur. Voir aussi Array.prototype.reduce().

TypedArray.prototype.reduceRight()

Applique une fonction avec un accumulateur pour chaque valeur du tableau (de droite gauche), afin de le rduire une seule valeur. Voir aussi Array.prototype.reduceRight().

TypedArray.prototype.reverse()

Inverse l'ordre des lments d'un tableau (le premier devenant le dernier, le dernier devenant le premier et ainsi de suite). Voir aussi Array.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 aussi Array.prototype.slice().

TypedArray.prototype.some()

Renvoie true si au moins un des lments du tableau satisfait au critre fourni par la fonction passe en argument. Voir aussi Array.prototype.some().

TypedArray.prototype.sort()

Trie les lments du tableau mme le tableau puis le renvoie. Voir aussi Array.prototype.sort().

TypedArray.prototype.subarray()

Renvoie un nouveau tableau typ avec les lments contenus entre un indice de dbut et un indice de fin.

TypedArray.prototype.values()

Renvoie un nouvel objet itrateur de tableau qui contient les valeurs pour chaque indice du tableau. Voir aussi Array.prototype.values().

TypedArray.prototype.toLocaleString()

Renvoie une chane de caractres localise qui reprsente le tableau et ses lments. Voir aussi Array.prototype.toLocaleString().

TypedArray.prototype.toString()

Renvoie une chane de caractres reprsentant le tableau et ses lments. Voir aussi Array.prototype.toString().

TypedArray.prototype[@@iterator]()

Renvoie un nouvel objet itrateur de tableau qui contient les valeurs pour chaque indice du tableau.

Exemples

Caractre obligatoire de new

partir d'ECMAScript 2015, les constructeurs TypedArray doivent tre appels avec l'oprateur new. Appeler un tel constructeur comme fonction, sans new, dclenchera une exception TypeError.

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

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

Accs aux proprits

Il est possible d'accder aux lments du tableau en utilisant la notation usuelle avec les crochets. Cependant, dfinir ou accder des proprits indexes ne se fera pas avec la chane de prototypes, mme si l'indice utilis est en dehors des limites du tableau. Les proprits indexes seront uniquement bases sur le contenu du ArrayBuffer et ne consulteront pas les proprits des objets. En revanche, il est toujours possible d'utiliser des proprits nommes, comme avec les autres objets.

// Dfinir et accder du contenu avec la syntaxe usuelle
let int16 = new Int16Array(2);
int16[0] = 42;
console.log(int16[0]); // 42

// Les proprits indexes sur les prototypes ne sont pas consultes
Int8Array.prototype[20] = "toto";
new Int8Array(32)[20]; // 0
// y compris en dehors des limites
Int8Array.prototype[20] = "toto";
new Int8Array(8)[20]; // undefined
// ou avec des index ngatifs
Int8Array.prototype[-1] = "toto";
new Int8Array(8)[-1]; // undefined

// Mais il est possible d'utiliser des proprits nommes
Int8Array.prototype.toto = "truc";
new Int8Array(32).toto; // "truc"

Impossibles geler

Les tableaux typs qui ne sont pas vides ne peuvent pas tre gels, car le tampon de mmoire ArrayBuffer sous-jacent pourrait tre modifi via une autre vue fournie par un autre tableau typ sur ce mme tampon. En pratique, cela voudrait dire que l'objet n'est pas rellement gel.

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

Alignement de decalageOctet

Lors de la construction d'un objet TypedArray comme une vue sur un tampon ArrayBuffer, l'argument decalageOctet doit tre align par rapport la taille des lments. Autrement dit, le dcalage fourni doit tre un multiple de BYTES_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 proprit byteLength

l'instar du paramtre decalageOctet, la proprit byteLength d'un objet ArrayBuffer pass au constructeur TypedArray doit tre un multiple de la valeur BYTES_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));

Spcifications

Compatibilit des navigateurs

Voir aussi

• Une prothse d'mulation pour les tableaux typs avec la bibliothque core-js
• Les tableaux typs en JavaScript
• ArrayBuffer
• DataView
• TextDecoder, une API utilitaire pour dcoder des chanes de caractres partir de donnes numriques