Signatur
Beschreibung
Uint32Array ist ein typisiertes Array (TypedArray), das 32-Bit-Ganzzahlen ohne Vorzeichen im Wertebereich von 0 bis 4 294 967 295 speichert. Jedes Element belegt genau 4 Bytes im zugrunde liegenden ArrayBuffer. Die Byte-Reihenfolge richtet sich nach der Plattform (in der Praxis fast immer Little-Endian auf x86/x64-Systemen).
Uint32Array eignet sich besonders für performanzkritische Binärdatenverarbeitung, z. B. beim Lesen von Datei-Headern, Netzwerk-Protokollen, WebGL-Puffern, kryptografischen Algorithmen oder Audio-/Grafikverarbeitung. Da der Speicher zusammenhängend und typsicher ist, kann die JavaScript-Engine ihn deutlich effizienter verwalten als ein gewöhnliches Array.
Wie alle TypedArrays unterstützt Uint32Array die bekannten Array-Methoden (map, filter, forEach, reduce, slice, set, subarray usw.) sowie den Index-basierten Zugriff über []. Schreibt man einen Wert außerhalb des darstellbaren Bereichs, wird dieser modulo 2³² gespeichert (stille Kürzung).
Ein Uint32Array kann aus einer Längenangabe, einem anderen TypedArray, einem normalen Array, einem iterierbaren Objekt oder einem bestehenden ArrayBuffer (mit optionalem Byte-Offset und Element-Anzahl) erstellt werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $length | number | Anzahl der Elemente (nicht Bytes). Der interne ArrayBuffer wird mit length × 4 Bytes angelegt, alle Werte mit 0 initialisiert. |
|
| $typedArray | TypedArray | Ein bestehendes TypedArray, dessen Werte in Uint32Array konvertiert und kopiert werden. |
|
| $object | Array|Iterable | Ein array-ähnliches oder iterierbares Objekt; jedes Element wird in eine vorzeichenlose 32-Bit-Ganzzahl umgewandelt. | |
| $buffer | ArrayBuffer|SharedArrayBuffer | Ein bestehender Puffer, auf den das TypedArray als View zugreift. Kein Kopiervorgang — Änderungen wirken sich direkt auf den Puffer aus. | |
| $byteOffset | number | 0 | Byte-Offset innerhalb des buffer, ab dem das View beginnt. Muss ein Vielfaches von 4 sein. |
| $length | number | Anzahl der Elemente im View, wenn ein buffer übergeben wird. Lässt man den Wert weg, erstreckt sich das View bis zum Ende des Puffers. |
Rückgabewert
Uint32Array, die auf einem internen oder übergebenen ArrayBuffer liegt.Beispiele
Einfaches Erstellen und Zugreifen
// Uint32Array mit 4 Elementen anlegen
const arr = new Uint32Array([10, 200, 3000, 4000000000]);
console.log(arr[0]); // 10
console.log(arr[3]); // 4000000000
console.log(arr.byteLength); // 16 (4 Elemente × 4 Bytes)
// Wertebereich-Kürzung (modulo 2^32)
const overflow = new Uint32Array(1);
overflow[0] = 4294967297; // 2^32 + 1
console.log(overflow[0]); // 1Gemeinsamer ArrayBuffer mit DataView
// Binär-Header lesen: Magic-Bytes + Versionsnummer + Payload-Länge
const buffer = new ArrayBuffer(12);
const view = new DataView(buffer);
// Header befüllen (Little-Endian)
view.setUint32(0, 0xDEADBEEF, true); // Magic
view.setUint32(4, 2, true); // Version
view.setUint32(8, 1024, true); // Payload-Länge
// Mit Uint32Array auslesen (plattform-nativ, hier Little-Endian)
const header = new Uint32Array(buffer);
console.log(header[0].toString(16)); // deadbeef
console.log(header[1]); // 2
console.log(header[2]); // 1024Typische Array-Methoden auf Uint32Array
const pixels = new Uint32Array([0xFF0000FF, 0x00FF00FF, 0x0000FFFF]);
// Jeden Wert transformieren
const shifted = pixels.map(p => (p >>> 8)); // Alpha-Kanal entfernen
console.log(shifted[0].toString(16)); // ff0000
// Summierung aller Werte
const sum = pixels.reduce((acc, val) => acc + val, 0);
console.log(sum);
// Teilbereich ohne Kopie
const sub = pixels.subarray(1, 3);
console.log(sub.length); // 2// Wichtig · Fallstricke
Byte-Reihenfolge: Uint32Array verwendet die native Byte-Reihenfolge der Plattform. Für plattformunabhängige Binär-Serialisierung (z. B. Netzwerk-Protokolle) sollte stattdessen DataView mit expliziter Endianness verwendet werden (getUint32/setUint32 mit dem littleEndian-Flag).
Stille Kürzung: Werte außerhalb von [0, 4 294 967 295] werden ohne Fehler per Modulo-Arithmetik gespeichert. Negative Zahlen werden ebenfalls still in vorzeichenlose Werte umgewandelt (z. B. −1 → 4 294 967 295).
Kein Kopieren bei Buffer-Übergabe: Wird ein ArrayBuffer direkt übergeben, zeigt das Uint32Array als View auf denselben Speicher. Mehrere Views auf denselben Buffer können sich gegenseitig überschreiben — dies ist gewollt, aber eine häufige Fehlerquelle.
SharedArrayBuffer: In Kombination mit SharedArrayBuffer und Atomics kann Uint32Array für Thread-sichere Inter-Worker-Kommunikation eingesetzt werden. Hier gelten besondere Sicherheitsanforderungen (COOP/COEP-Header).