TypedArray

Un objet TypedArray décrit une vue organisée à la façon d'un tableau pour manipuler un tampon (buffer) de données binaires. TypedArray n'est pas une propriété globale, il n'existe pas non plus de constructeur TypedArray.  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.

Le code source de cet exemple interactif est disponible dans un dépôt GitHub. Si vous souhaitez contribuez à ces exemples, n'hésitez pas à cloner https://github.com/mdn/interactive-examples et à envoyer une pull request !

Syntaxe

new TypedArray(longueur);
new TypedArray(tableauTypé);
new TypedArray(objet);
new TypedArray(tampon [, décalageEnOctet [, longueur]]);

où TypedArray() est l'un de :

Int8Array();
Uint8Array();
Uint8ClampedArray();
Int16Array();
Uint16Array();
Int32Array();
Uint32Array();
Float32Array();
Float64Array();
BigInt64Array();
BigUint64Array();

Paramètres

longueur

Lorsque le constructeur est appelé avec un argument longueur, un tableau typé sera créé, contenant autant de zéros que longueur (par exemple avec une longueur de 3, on aura un tableau dont les trois éléments seront des zéros).

tableauTypé

Lorsque le constructeur est appelé avec un argument tableauTypé, qui peut être un tableau typé de n'importe quel type (par exemple Int32Array), le tableauTypé est copié dans un nouveau tableau typé. Chaque valeur du tableauTypé est convertie dans le type correspondant du nouveau tableau. Enfin, la longueur du tableau typé est fixée avec la longueur de tableauTypé.

objet

Lorsque le constructeur est invoqué avec un argument objet, un nouveau tableau typé est créé avec la méthode TypedArray.from().

tampon, décalageOctet, longueur

Lorsque le constructeur est appelé avec un tampon (buffer) ainsi qu'avec les paramètres optionnels décalageOctet et longueur, un nouveau tableau typé est créé comme une vue pour l'objet ArrayBuffer. Les paramètres décalageOctet et longueur permettent de définir l'intervalle de mémoire du buffer qui est présenté dans la vue qu'est le tableau typé. Si les deux derniers paramètres sont absents, l'ensemble du tampon sera considéré. Si longueur est absent, on considèrera l'ensemble de tampon à partir de l'octet décalageOctet.

Description

ECMAScript 2015 (ES6) définit 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 propriété TypedArray.  Il est uniquement accessible via Object.getPrototypeOf(Int8Array.prototype) ou avec les méthodes semblables. L'ensemble des différents constructeurs TypedArrays 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]].

Le constructeur %TypedArray% en tant que tel n'est pas très utile. Toute tentative d'appel ou d'utilisation avec une expression new renverra TypeError, sauf quand il est utilisé par le moteur JavaScript lors de la création de l'objet quand le moteur supporte les sous-classes. À l'heure actuelle, il n'existe pas de tels moteurs, pour cette raison %TypedArray% est uniquement utile dans les fonctions d'émulation (polyfill) our pour les propriétés des différents constructeurs TypedArray.

Lorsqu'on crée une instance de TypedArray (ex. une instance de Int8Array ou autre), un tampon de mémoire 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 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.

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 du ArrayBuffer 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 usuelle
var 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ées (Fx 25)
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 négatifs
Int8Array.prototype[-1] = "toto";
(new Int8Array(8))[-1]; // undefined

// Mais il est possible d'utiliser des propriétés nommées (Fx 30)
Int8Array.prototype.toto = "truc";
(new Int8Array(32)).toto; // "truc" 

Les objets TypedArray

Propriétés

TypedArray.BYTES_PER_ELEMENT

Cette propriété renvoie un nombre correspondant à la taille d'un élément du tableau selon le type de tableau utilisé.

TypedArray.length

La propriété de longueur, elle vaut 0.

TypedArray.name

Cette propriété 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.prototype

Le prototype des objets TypedArray.

Méthodes

TypedArray.from()

Cette méthohde permet de créer un nouveau tableau typé à partir d'un itérable ou d'un objet semblable à un tableau. Voir aussi Array.from().

TypedArray.of()

Cette méthode permet de créer un nouveau tableau typé à partir d'un nombre variable d'arguments. Voir aussi Array.of().

Prototype TypedArray

Toutes les instances de TypedArrays héritent de TypedArray.prototype.

Propriétés

TypedArray.prototype.constructor

Cette propriété renvoie la fonction qui a créé le prototype de l'instance. Elle correspondra à l'une des fonctions par défaut pour le type du tableau typé utilisé.

TypedArray.prototype.buffer Lecture seule

Cette propriété renvoie l'ArrayBuffer qui est référencé par le tableau typé. Cette propriété est définie lors de la construction et est donc accessible en lecture seule uniquement.

TypedArray.prototype.byteLength Lecture seule

Cette propriété renvoie la longueur (exprimée en octets) du tableau typé, à partir du début de l'ArrayBuffer. Cette propriété est définie lors de la construction et est donc accessible en lecture seule uniquement.

TypedArray.prototype.byteOffset Lecture seule

Cette propriété renvoie le décalage utilisé (exprimé en octets) entre le début du tableau typé et le début du ArrayBuffer. Cette propriété est définie lors de la construction et est donc accessible en lecture seule uniquement.

TypedArray.prototype.length Lecture seule

Cette propriété renvoie le nombre d'éléments contenus dans le tableau typé. Cette propriété est définie lors de la construction et est donc accessible en lecture seule uniquement.

Méthodes

TypedArray.prototype.copyWithin()

Copie une suite d'éléments au sein du tableau typé. Voir aussi Array.prototype.copyWithin().

TypedArray.prototype.entries()

Renvoie un nouvel objet Array Iterator qui contient les clés/valeurs pour chaque indice du tableau. Voir aussi Array.prototype.entries().

TypedArray.prototype.every()

Teste si tous les éléments du tableau typé respectent une condition donnée sous la forme d'une fonction. Voir aussi Array.prototype.every().

TypedArray.prototype.fill()

Affecte une même valeur statique aux éléments du tableau typé entre un indice de début et un indice de fin. Voir aussi Array.prototype.fill().

TypedArray.prototype.filter()

Crée un nouveau tableau typé dont les éléments proviennent d'un tableau typé qu'on a filtré avec une fonction. Voir aussi Array.prototype.filter().

TypedArray.prototype.find()

Renvoie la valeur trouvée dans le tableau typé si un élément du tableau typé respecte une condition définie par une fonction. Si aucun élément n'est trouvé, undefined sera renvoyé. Voir aussi Array.prototype.find().

TypedArray.prototype.findIndex()

Renvoie l'indice de l'élément trouvé si un élément du tableau typé respecte une condition définie par une fonction. Si aucun élément n'est trouvé, -1 sera renvoyé. Voir aussi Array.prototype.findIndex().

TypedArray.prototype.forEach()

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

TypedArray.prototype.includes()

Détermine si un élément est contenu dans un tableau typé et renvoie true ou false selon le cas de figure. Voir aussi Array.prototype.includes().

TypedArray.prototype.indexOf()

Renvoie le premier indice (le plus petit) d'un élément du tableau typé qui a la valeur fournie en argument. Si aucun élément n'est trouvé, la valeur -1 sera renvoyée. Voir aussi Array.prototype.indexOf().

TypedArray.prototype.join()

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

TypedArray.prototype.keys()

Renvoie un nouvel objet Array Iterator qui contient les clés pour chaque élément du tableau. Voir aussi Array.prototype.keys().

TypedArray.prototype.lastIndexOf()

Renvoie le dernier indice (le plus grand) d'un élément du tableau typé qui a la valeur fournie en argument. Si aucun élément n'est trouvé, -1 sera renvoyé. Voir aussi Array.prototype.lastIndexOf().

TypedArray.prototype.map()

Crée un nouveau tableau typé dont les éléments sont les images des éléments du tableau typé courant par une fonction donnée. Voir aussi  Array.prototype.map().

TypedArray.prototype.move() Non implémenté

Ancienne version, non-standard, de TypedArray.prototype.copyWithin().

TypedArray.prototype.reduce()

Applique une fonction par rapport à un accumulateur pour chaque valeur du tableau (de gauche à droite) afin de réduire le tableau typé à une seule valeur. Voir aussi Array.prototype.reduce().

TypedArray.prototype.reduceRight()

Applique une fonction par rapport à un accumulateur pour chaque valeur du tableau (de droite à gauche) afin de réduire le tableau typé à une seule valeur. Voir aussi Array.prototype.reduceRight().

TypedArray.prototype.reverse()

Inverse l'ordre des éléments du tableau typé (le premier devient le dernier, le dernier devient le premier et ainsi de suite). Voir aussi Array.prototype.reverse().

TypedArray.prototype.set()

Cette méthode permet d'enregistrer plusieurs valeurs dans le tableau typé à partir d'un tableau donné.

TypedArray.prototype.slice()

Extrait un fragment du tableau typé et renvoie ce fragment sous forme d'un tableau typé. Voir aussi Array.prototype.slice().

TypedArray.prototype.some()

Renvoie true si au moins un élément du tableau typé respecte une condition définie par une fonction passée en argument. Voir aussi Array.prototype.some().

TypedArray.prototype.sort()

Trie les éléments du tableau typé sur place et renvoie le tableau typé. Voir aussi Array.prototype.sort().

TypedArray.prototype.subarray()

Cette méthode renvoie un nouvel objet TypedArray en fonction d'un indice de début et de fin.

TypedArray.prototype.values()

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

TypedArray.prototype.toLocaleString()

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

TypedArray.prototype.toString()

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

TypedArray.prototype[@@iterator]()

Renvoie un nouvel objet Array Iterator contenant les valeurs pour chaque indice du tableau typé.

Prothèse d'émulation (polyfill)

La plupart des méthodes des tableaux typés peuvent être en partie émulées grâce aux méthodes rattachées à Array :

var typedArrayTypes = [Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, ​​​Int32Array, Uint32Array, ​​​Float32Array, Float64Array];
for (var k in typedArrayTypes){
  for (var v in Array.prototype){
    if (Array.prototype.hasOwnProperty(v) &&
  ​​​​​         !typedArrayTypes[k].prototype.hasOwnProperty(v)){
      typedArrayTypes[k].prototype[v] = Array.prototype[v];
    }
  }
}

Spécifications

Compatibilité des navigateurs

Notes de compatibilité

À partir d'ECMAScript 2015 (ES6), les constructeurs TypedArray doivent être utilisés avec new. Appeler un constructeur TypedArray comme une fonction, sans new, provoquera une exception TypeError.

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

var dv = new Float64Array([1, 2, 3]);

Voir aussi

• Les tableaux typés en JavaScript
• ArrayBuffer
• DataView