Uint8Array.prototype.setFromHex() — Methode · JavaScript-Referenz

Signatur

Uint8Array.prototype.setFromHex(string)

Beschreibung

setFromHex() liest einen hex-kodierten String (je zwei Zeichen 0-9, a-f oder A-F pro Byte) und schreibt die dekodierten Bytes ab Index 0 in das Uint8Array, auf dem die Methode aufgerufen wird. Anders als die statische Methode Uint8Array.fromHex() wird kein neues Array angelegt. Die Bytes landen in einem vorhandenen Puffer.

Das lohnt sich vor allem, wenn Sie Speicher wiederverwenden möchten, zum Beispiel in Schleifen, in Protokoll-Parsern oder beim Befüllen eines größeren ArrayBuffer an einer bestimmten Stelle. Dafür erzeugen Sie mit subarray() eine Ansicht ab dem gewünschten Offset und rufen setFromHex() auf dieser Ansicht auf.

Ist das Ziel-Array kleiner als die Menge der dekodierten Daten, hört die Methode auf, sobald das Array voll ist. Dabei gibt es keinen Fehler. Der Rückgabewert zeigt, wie weit dekodiert wurde: read ist die Anzahl der gelesenen Hex-Zeichen, written die Anzahl der geschriebenen Bytes. So können Sie Daten in Stücken verarbeiten.

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Hexadezimaler String mit gerader Länge. Groß- und Kleinschreibung sind erlaubt. Leerzeichen, Präfixe wie `0x` und Trennzeichen sind nicht erlaubt.

Rückgabewert

Typ

{ read: number, written: number }

Beschreibung

Ein Objekt mit read (Anzahl der gelesenen Hex-Zeichen, immer 2 × written) und written (Anzahl der ins Array geschriebenen Bytes).

Beispiele

Hex-String in einen vorhandenen Puffer dekodieren

const bytes = new Uint8Array(8);
const result = bytes.setFromHex("cafed00d");

console.log(result);
console.log(bytes);

{ read: 8, written: 4 } Uint8Array(8) [202, 254, 208, 13, 0, 0, 0, 0]

Ziel-Array zu klein – Dekodierung stoppt ohne Fehler

const small = new Uint8Array(2);
const { read, written } = small.setFromHex("cafed00d");

console.log(read, written);
console.log(small);
// Rest verarbeiten:
console.log("Noch offen:", "cafed00d".slice(read));

4 2 Uint8Array(2) [202, 254] Noch offen: d00d

An einer bestimmten Stelle schreiben (per subarray)

// Paket: 2 Byte Header + 4 Byte Nutzdaten
const packet = new Uint8Array(6);
packet[0] = 0x01; // Version
packet[1] = 0x04; // Länge

packet.subarray(2).setFromHex("DEADBEEF");
console.log(packet);

Uint8Array(6) [1, 4, 222, 173, 190, 239]

Fehlerbehandlung und Feature-Erkennung

const decodeInto = (target, hex) => {
  if (typeof Uint8Array.prototype.setFromHex !== "function") {
    throw new Error("setFromHex wird nicht unterstützt");
  }
  try {
    return target.setFromHex(hex);
  } catch (err) {
    console.error(`${err.name}: ungültiger Hex-String`);
    return null;
  }
};

const buf = new Uint8Array(4);
decodeInto(buf, "abz1"); // 'z' ist ungültig
console.log(buf); // Bytes vor dem Fehler wurden bereits geschrieben
decodeInto(buf, "abc"); // ungerade Länge

SyntaxError: ungültiger Hex-String Uint8Array(4) [171, 0, 0, 0] SyntaxError: ungültiger Hex-String

// Wichtig · Fallstricke

Fehler: Die Methode wirft einen SyntaxError, wenn der String Zeichen außerhalb des Hex-Alphabets enthält (auch Leerzeichen oder 0x) oder wenn seine Länge ungerade ist. Ist das Argument kein String, gibt es einen TypeError. Es findet keine automatische Umwandlung statt.
Teilweises Schreiben: Taucht ein ungültiges Zeichen mitten im String auf, stehen die Bytes davor bereits im Array. Das Array ist also nicht unverändert. Bei ungerader Länge wird dagegen nichts geschrieben, weil die Länge vorab geprüft wird.
Kein Überlauf-Fehler: Ein zu kleines Ziel-Array schneidet die Daten stillschweigend ab. Vergleichen Sie deshalb read mit string.length, wenn Sie Vollständigkeit brauchen.
Die Methode gibt es nur auf Uint8Array, nicht auf anderen TypedArrays. Die Bytes landen immer ab Index 0 des Arrays bzw. der Ansicht.
Kompatibilität: Die Methode ist recht neu (Proposal „ArrayBuffer base64“, ES2026). Ältere Umgebungen brauchen eine Feature-Erkennung oder ein Polyfill, z. B. core-js.

Siehe auch

Uint8Array.fromHex() Uint8Array.prototype.toHex() Uint8Array.prototype.setFromBase64() Uint8Array.fromBase64() TypedArray.prototype.subarray() Uint8Array