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 quelongueur
(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 exempleInt32Array
), letableauTypé
est copié dans un nouveau tableau typé. Chaque valeur dutableauTypé
est convertie dans le type correspondant du nouveau tableau. Enfin, la longueur du tableau typé est fixée avec la longueur detableauTypé
. objet
- Lorsque le constructeur est invoqué avec un argument
objet
, un nouveau tableau typé est créé avec la méthodeTypedArray.from()
. tampon
,décalageOctet
,longueur
- Lorsque le constructeur est appelé avec un
tampon
(buffer) ainsi qu'avec les paramètres optionnelsdécalageOctet
etlongueur
, un nouveau tableau typé est créé comme une vue pour l'objetArrayBuffer
. Les paramètresdécalageOctet
etlongueur
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 dutampon
sera considéré. Silongueur
est absent, on considèrera l'ensemble detampon
à 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
Type | Intervalle | Taille (exprimée en octets) | Description | Type Web IDL | Type équivalent en C |
Int8Array |
-128 à 127 | 1 | Entier signé en complément à deux sur 8 bits. | byte |
int8_t |
Uint8Array |
0 à 255 | 1 | Entier non signé sur 8 bits. | octet |
uint8_t |
Uint8ClampedArray |
0 à 255 | 1 | Entier non signé sur 8 bits (compris entre 0 et 255). | octet |
uint8_t |
Int16Array |
-32768 à 32767 | 2 | Entier signé en complément à deux sur 16 bits. | short |
int16_t |
Uint16Array |
0 à 65535 | 2 | Entier non signé sur 16 bits. | unsigned short |
uint16_t |
Int32Array |
-2147483648 à 2147483647 | 4 | Entier signé en complément à deux sur 32 bits. | long |
int32_t |
Uint32Array |
0 à 4294967295 | 4 | Entier non signé sur 32 bits. | unsigned long |
uint32_t |
Float32Array |
1.2x10-38 à 3.4x1038 | 4 | Nombre flottant sur 32 bits selon la représentation IEEE (7 chiffres significatifs). | unrestricted float |
float |
Float64Array |
5.0x10-324 à 1.8x10308 | 8 | Nombre flottant sur 64 bits selon la représentation IEEE (16 chiffres significatifs). | unrestricted double |
double |
BigInt64Array |
-263 à 263-1 | 8 | Nombre entier signé sur 64 bits en complément à deux. | bigint |
int64_t (signed long long) |
BigUint64Array |
0 à 264-1 | 8 | Nombre entier non signé sur 64 bits. | bigint |
uint64_t (unsigned long long) |
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 3.
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éthode 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 aussiArray.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 aussiArray.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
oufalse
selon le cas de figure. Voir aussiArray.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 aussiArray.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 aussiArray.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 aussiArray.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
Spécification | État | Commentaires |
---|---|---|
Typed Array Specification | Obsolete | Défini comme TypedArray et interface ArrayBufferView avec les différents types de vues des tableaux typés. Cette spécification a été englobée dans ECMAScript 2015. |
ECMAScript 2015 (6th Edition, ECMA-262) La définition de 'TypedArray Objects' dans cette spécification. |
Standard | Définition initiale au sein d'un standard ECMA. new est obligatoire. |
ECMAScript (ECMA-262) La définition de 'TypedArray Objects' dans cette spécification. |
Standard évolutif | ECMAScript 2017 a modifié les constructeurs TypedArray afin qu'ils utilisent l'opération ToIndex et puissent être utilisés sans argument. |
Compatibilité des navigateurs
BCD tables only load in the browser
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]);