TextEncoder.encodeInto() — Methode · JavaScript-Referenz

Signatur

TextEncoder.prototype.encodeInto(string, uint8Array)

Beschreibung

encodeInto() ist die speichersparende Variante von TextEncoder.prototype.encode(). Statt bei jedem Aufruf ein neues Uint8Array anzulegen, schreibt die Methode die UTF-8-Bytes in einen Puffer, den du selbst bereitstellst. Das ist besonders nützlich, wenn du viele Strings hintereinander kodierst, einen festen Puffer wiederverwenden willst oder direkt in den Speicher von WebAssembly (WebAssembly.Memory) bzw. in einen SharedArrayBuffer schreiben möchtest.

Der Rückgabewert ist ein Objekt mit zwei Eigenschaften: read gibt an, wie viele UTF-16-Codeeinheiten des Quell-Strings verarbeitet wurden, written gibt an, wie viele Bytes im Ziel geschrieben wurden. Ist der Zielpuffer zu klein, bricht die Kodierung vorher ab – aber nie mitten in einem Zeichen. Über read kannst du den Rest des Strings in einem weiteren Durchgang (etwa in einen neuen Puffer) kodieren.

Um sicherzugehen, dass der gesamte String passt, braucht der Puffer im schlimmsten Fall string.length * 3 Bytes, denn jede UTF-16-Codeeinheit ergibt höchstens drei UTF-8-Bytes (Surrogatpaare: 2 Codeeinheiten → 4 Bytes). Möchtest du an einer bestimmten Stelle im Puffer beginnen, übergibst du eine Teilansicht mit subarray().

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Der zu kodierende Text. Nicht-Strings werden zu einem String umgewandelt; einzelne (ungepaarte) Surrogate werden als U+FFFD (`EF BF BD`) kodiert.
$uint8Array Pflicht	Uint8Array		Zielpuffer, in den die UTF-8-Bytes ab Index 0 geschrieben werden. Für einen Versatz eine Ansicht mit `buffer.subarray(offset)` übergeben. Andere TypedArrays führen zu einem `TypeError`.

Rückgabewert

Typ

{ read: number, written: number }

Beschreibung

Objekt mit read (Anzahl verarbeiteter UTF-16-Codeeinheiten des Quell-Strings) und written (Anzahl geschriebener Bytes im Zielpuffer).

Beispiele

Grundlegende Nutzung mit ausreichend großem Puffer

const encoder = new TextEncoder();
const text = 'Grüße';
const buffer = new Uint8Array(text.length * 3);

const { read, written } = encoder.encodeInto(text, buffer);
console.log(read, written);
console.log(buffer.subarray(0, written));

5 7 Uint8Array(7) [71, 114, 195, 188, 195, 159, 101]

Zu kleiner Puffer – Abbruch an einer Zeichengrenze

const encoder = new TextEncoder();
const buffer = new Uint8Array(4);

// 'ä' braucht 2 Bytes, '😀' braucht 4 Bytes (2 Codeeinheiten)
const result = encoder.encodeInto('aä😀', buffer);
console.log(result);

// Rest des Strings ermitteln
console.log('Nicht kodiert:', 'aä😀'.slice(result.read));

{ read: 2, written: 3 } Nicht kodiert: 😀

Mehrere Strings hintereinander in einen Puffer schreiben

const encoder = new TextEncoder();
const buffer = new Uint8Array(64);
let offset = 0;

for (const word of ['Hallo', ' ', 'Welt', '!']) {
  const { written } = encoder.encodeInto(word, buffer.subarray(offset));
  offset += written;
}

const decoded = new TextDecoder().decode(buffer.subarray(0, offset));
console.log(offset, decoded);

11 Hallo Welt!

String in WebAssembly-Speicher schreiben

const memory = new WebAssembly.Memory({ initial: 1 }); // 64 KiB
const encoder = new TextEncoder();

const writeString = (str, ptr) => {
  const view = new Uint8Array(memory.buffer, ptr, str.length * 3);
  const { written } = encoder.encodeInto(str, view);
  return written; // Länge für die Wasm-Funktion
};

const len = writeString('Überweisung', 1024);
console.log(len);

12

// Wichtig · Fallstricke

Puffergröße: string.length reicht bei Nicht-ASCII-Zeichen nicht. Sicher ist string.length * 3. Prüfe nach dem Aufruf immer read === string.length, sonst wurde gekürzt – ohne Fehler oder Warnung.
Kein Nullterminator: Es wird kein abschließendes 0-Byte geschrieben. Bytes hinter written bleiben unverändert und können alte Daten enthalten. Nutze deshalb immer subarray(0, written).
read zählt UTF-16-Codeeinheiten, keine Unicode-Zeichen. Ein Emoji zählt als 2. Deshalb passt string.slice(read) genau.
Nur UTF-8: TextEncoder kann ausschließlich UTF-8 erzeugen; andere Kodierungen werden nicht unterstützt.
Wasm-Speicher: Wird WebAssembly.Memory vergrößert (grow()), werden vorhandene Ansichten ungültig (Länge 0). Lege die Uint8Array-Ansicht daher erst direkt vor dem Aufruf an.
Kompatibilität: Verfügbar in Chrome 74+, Firefox 66+, Safari 14.1+, Edge 79+ und Node.js 12.11+ (global); auch in Web Workern. In älteren Umgebungen auf encode() plus Uint8Array.prototype.set() ausweichen.

Siehe auch

Uint8Array TextEncoder.encode() TextDecoder.decode() AudioEncoder.encode() VideoEncoder.encode()