String.prototype.charCodeAt() — Methode · JavaScript-Referenz

Signatur

String.prototype.charCodeAt(index)

Beschreibung

charCodeAt() liest die UTF-16-Code-Einheit an einer bestimmten Stelle eines Strings und gibt sie als Zahl zurück. JavaScript-Strings bestehen intern aus einer Folge von 16-Bit-Code-Einheiten. Für alle Zeichen der Basic Multilingual Plane (BMP, also U+0000 bis U+FFFF) entspricht der Wert direkt dem Unicode-Codepunkt. Dazu gehören lateinische Buchstaben, Umlaute und die meisten Schriftzeichen.

Typische Einsatzfälle sind einfache Hash-Funktionen, Prüfsummen, Zeichenklassen-Prüfungen ohne reguläre Ausdrücke (etwa „ist das eine Ziffer?“), Verschiebe-Chiffren wie ROT13 und das Umwandeln von Strings in Byte-Folgen. Weil kein Codepunkt zusammengesetzt werden muss, ist die Methode sehr schnell.

Wichtig: Zeichen außerhalb der BMP, zum Beispiel viele Emojis, werden in UTF-16 als Surrogatpaar aus zwei Code-Einheiten gespeichert. charCodeAt() liefert dann nur eine Hälfte dieses Paares (0xD800–0xDBFF oder 0xDC00–0xDFFF). Den vollständigen Codepunkt bekommt man mit codePointAt().

Ist der Index negativ oder größer oder gleich length, gibt die Methode NaN zurück und wirft keinen Fehler. Der Index wird vorher in eine Ganzzahl umgewandelt: Nachkommastellen werden abgeschnitten, und aus undefined oder NaN wird 0.

Parameter

Name	Typ	Default	Beschreibung
$index	number	0	Nullbasierte Position der gewünschten Code-Einheit. Der Wert wird in eine Ganzzahl umgewandelt (Nachkommastellen werden abgeschnitten, `NaN`/`undefined` wird zu `0`). Negative Werte werden nicht vom Ende aus gezählt.

Rückgabewert

Typ

number

Beschreibung

Ganzzahl zwischen 0 und 65535 für die UTF-16-Code-Einheit am Index, oder NaN, wenn der Index außerhalb von 0 bis length - 1 liegt.

Beispiele

Grundlegende Nutzung und Index außerhalb des Bereichs

const wort = 'Äpfel';

console.log(wort.charCodeAt(0));   // 'Ä'
console.log(wort.charCodeAt(1));   // 'p'
console.log(wort.charCodeAt());    // ohne Index → 0
console.log(wort.charCodeAt(1.9)); // wird zu 1 abgeschnitten
console.log(wort.charCodeAt(10));  // außerhalb
console.log(wort.charCodeAt(-1));  // negativ → kein Zählen vom Ende

196 112 196 112 NaN NaN

Einfacher String-Hash (djb2) für Cache-Schlüssel

const djb2 = (str) => {
  let hash = 5381;
  for (let i = 0; i < str.length; i++) {
    // hash * 33 + Code-Einheit, auf 32 Bit begrenzt
    hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
  }
  return hash >>> 0; // als vorzeichenlose Zahl
};

console.log(djb2('programmierung.net'));
console.log(djb2('hallo') === djb2('hallo'));

(eine feste 32-Bit-Zahl) true

ROT13-Verschlüsselung über Zeichencodes

const rot13 = (text) =>
  text.replace(/[a-z]/gi, (ch) => {
    const basis = ch <= 'Z' ? 65 : 97; // 'A' bzw. 'a'
    return String.fromCharCode(((ch.charCodeAt(0) - basis + 13) % 26) + basis);
  });

console.log(rot13('Hallo Welt'));
console.log(rot13(rot13('Hallo Welt')));

Unyyb Jryg Hallo Welt

Fallstrick: Emojis und Surrogatpaare

const emoji = '😀';

console.log(emoji.length);                     // zwei Code-Einheiten
console.log(emoji.charCodeAt(0).toString(16)); // High Surrogate
console.log(emoji.charCodeAt(1).toString(16)); // Low Surrogate
console.log(emoji.codePointAt(0).toString(16)); // echter Codepunkt

2 d83d de00 1f600

// Wichtig · Fallstricke

Surrogatpaare: Bei Zeichen außerhalb der BMP (Emojis, seltene CJK-Zeichen, mathematische Symbole) gibt charCodeAt() nur eine Hälfte des Paares zurück. Für echte Unicode-Codepunkte codePointAt() verwenden. Wenn man über den String iterieren will, statt über die Indizes zu zählen, for...of oder [...str] nutzen.
Kein negativer Index: Anders als bei at() zählt charCodeAt(-1) nicht vom Ende, sondern liefert NaN. Für das letzte Zeichen str.charCodeAt(str.length - 1) schreiben.
Stille Fehler: Ein ungültiger Index wirft keine Ausnahme, sondern gibt NaN zurück. In Rechnungen wie bei Hash-Funktionen breitet sich dieses NaN unbemerkt weiter aus. Die Schleifengrenze sollte daher immer i < str.length sein.
Kein Byte-Wert: Das Ergebnis ist eine UTF-16-Einheit und kein UTF-8-Byte. Für echte Bytes ist new TextEncoder().encode(str) das richtige Werkzeug.
Kompatibilität: Die Methode gehört seit ECMAScript 1 zum Standard und wird von allen Browsern und von Node.js unterstützt.

Siehe auch

String.prototype.codePointAt() String.fromCharCode() String.fromCodePoint() String.prototype.charAt() String.prototype.at() TextEncoder