String.prototype.codePointAt()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2015年9月.

codePointAt() は String 値のメソッドで、指定されたインデックスから始まる文字の Unicode コードポイント値である非負の整数を返します。インデックスは Unicode コードポイントではなく、UTF-16 コード単位に基づくことに注意してください。

試してみましょう

const icons = "☃★♲";

console.log(icons.codePointAt(1));
// 予想される結果: "9733"

構文

codePointAt(index)

引数

index

返す文字の 0 基点のインデックスです。整数に変換され、undefined は 0 に変換されます。

返値

指定された位置 index にある文字のコードポイント値を表す非負の整数値です。

index が 0 – str.length - 1 の範囲外であれば、codePointAt() は undefined を返します。
index の位置の要素が UTF-16 上位サロゲートであった場合、そのコードポイントのサロゲートペアを返します。
index の位置の要素が UTF-16 下位サロゲートであった場合、下位サロゲートコード単位のみを返します。

解説

文字列の中の文字は、左から右に向けてインデックス付けされています。最初の文字の添字は 0 であり、最後の文字の添字は str という名前の文字列であれば str.length - 1 です。

Unicode のコードポイントは 0 から 1114111 (0x10FFFF) までの範囲です。UTF-16 では、それぞれの文字列のインデックスは 0 ～ 65536 のコード単位です。上位のコードポイントは 16 ビットのサロゲート擬似文字のペアによって表されます。したがって、codePointAt() は文字列の 2 つのインデックスにまたがるコードポイントを返す可能性があります。Unicode に関する情報はUTF-16 文字、Unicode コードポイント、書記素クラスターを参照してください。

例

codePointAt() の使用

js
"ABC".codePointAt(0); // 65
"ABC".codePointAt(0).toString(16); // 41

"😍".codePointAt(0); // 128525
"\ud83d\ude0d".codePointAt(0); // 128525
"\ud83d\ude0d".codePointAt(0).toString(16); // 1f60d

"😍".codePointAt(1); // 56845
"\ud83d\ude0d".codePointAt(1); // 56845
"\ud83d\ude0d".codePointAt(1).toString(16); // de0d

"ABC".codePointAt(42); // undefined

codePointAt() の繰り返し

文字列インデックスを使用してループ処理を行うと、同じコードポイントが 2 回参照されることになります（1 回目は上位サロゲート、2 回目は下位サロゲート）。また、2 回目に codePointAt() が返すのは下位サロゲートのみです。そのため、インデックスによるループ処理は避けた方が良いでしょう。

js
const str = "\ud83d\udc0e\ud83d\udc71\u2764";

for (let i = 0; i < str.length; i++) {
  console.log(str.codePointAt(i).toString(16));
}
// '1f40e', 'dc0e', '1f471', 'dc71', '2764'

代わりに、for...of 文やスプレッド構文を使用してください。どちらも文字列の [Symbol.iterator]() を呼び出し、コードポイント単位で反復処理をします。それから、codePointAt(0) でそれぞれの要素のコードポイントを取得してください。

js
for (const codePoint of str) {
  console.log(codePoint.codePointAt(0).toString(16));
}
// '1f40e', '1f471', '2764'

[...str].map((cp) => cp.codePointAt(0).toString(16));
// ['1f40e', '1f471', '2764']