TypedArray - JavaScript

TypedArray
==========

***TypedArray*** オブジェクトは、背後にあるバイナリーデータバッファーの、配列風のビューを表します。 `TypedArray` という名称のグローバルプロパティがあるわけではなく、また直接 `TypedArray` コンストラクターが見えるわけではありません。代わりに、さまざまなグローバルプロパティがあり、それらの値は後述するように特定の要素の型における型付き配列のコンストラクターになります。下記のページで、それぞれの要素を持つ片引き配列で使用できる共通のプロパティやメソッドを確認できます。

試してみましょう
--------

解説
--

`TypedArray` コンストラクター（よく `%TypedArray%` と表記されます。JavaScript プログラムに公開されるグローバルに対応するものがあるわけではないため、「個別のもの」を表すためです）は、すべての `TypedArray` のサブクラスの共通のスーパークラスとして機能します。`%TypedArray%` はすべての型付き配列のサブクラスに対してユーティリティメソッドの共通インターフェイスを提供する「抽象クラス」であると考えてください。このコンストラクターは直接公開されていません。グローバルプロパティである `TypedArray` プロパティは存在しません。`オブジェクト.getPrototypeOf(Int8Array)` などを通してのみアクセスすることができます。

`TypedArray` のサブクラス（例えば `Int8Array`）のインスタンスを作成する際、配列バッファーがメモリーに内部作成されるか、コンストラクターの引数に `ArrayBuffer` オブジェクトが指定されると、代わりにその `ArrayBuffer` を使用します。バッファーアドレスはインスタンスの内部プロパティとして保存され、`%TypedArray%.prototype` のすべてのメソッドがその配列バッファーアドレスに基づいて値を設定したり取得したりします。

### TypedArray オブジェクト

| 型 | 値の範囲 | サイズ (バイト数) | Web IDL 型 |
| --- | --- | --- | --- |
| `Int8Array` | -128 から 127 | 1 | `byte` |
| `Uint8Array` | 0 から 255 | 1 | `octet` |
| `Uint8ClampedArray` | 0 から 255 | 1 | `octet` |
| `Int16Array` | -32768 から 32767 | 2 | `short` |
| `Uint16Array` | 0 から 65535 | 2 | `unsigned short` |
| `Int32Array` | -2147483648 から 2147483647 | 4 | `long` |
| `Uint32Array` | 0 から 4294967295 | 4 | `unsigned long` |
| `Float32Array` | `-3.4E38` から `3.4E38` および `1.2E-38` （最小の正の数） | 4 | `unrestricted float` |
| `Float64Array` | `-1.8E308` から `1.8E308` および `5E-324` （最小の正の数） | 8 | `unrestricted double` |
| `BigInt64Array` | -263 to 263 - 1 | 8 | `bigint` |
| `BigUint64Array` | 0 to 264 - 1 | 8 | `bigint` |

### 値のエンコード方式と正規化

すべての型付き配列は `ArrayBuffer` を操作して、各要素の正確なバイト表現を見ることができますので、数値がバイナリー形式でどのようにエンコードされているかが重要です。

* 符号なし整数の配列 (`Uint8Array`, `Uint16Array`, `Uint32Array`, `BigUint64Array`) は、数値を直接バイナリーで格納します。
* 符号付き整数の配列 (`Int8Array`, `Int16Array`, `Int32Array`, `BigInt64Array`) は、数値を 2 の補数を用いて格納します。
* 浮動小数点の配列 (`Float32Array`, `Float64Array`) は IEEE 754 浮動小数点形式を使用して数値を格納します。 `Number` のリファレンスには、正確な形式についての詳細情報があります。 JavaScript の数値は既定では倍精度浮動小数点数で、 `Float64Array` と同じ形式を使用します。 `Float32Array` で仮数に（52 ビットの代わりに）23 ビット、指数に（11 ビットの代わりに） 8 ビットを使用します。仕様では、すべての `NaN` 値が同じビットエンコーダ方式を使用することが要求されていますが、正確なビットパターンは実装に依存することに注意してください。
* `Uint8ClampedArray` は特殊なケースです。これは `Uint8Array` と同じようにバイナリーで格納されますが、範囲外の数値を格納した場合、最上位ビットを切り捨てるのではなく、数学的な値で 0 から 255 の範囲に数値を丸めます。

`Int8Array`、`Uint8Array`、`Uint8ClampedArray` を除くすべての型付き配列は、各要素を複数のバイトを使用して格納します。これらのバイトは、最上位から最下位（ビッグエンディアン）、または最下位から最上位（リトルエンディアン）の順に並べられます。詳しい説明はエンディアンを参照してください。型付き配列は常にプラットフォームネイティブのバイト順を使用します。バッファーから読み書きする際にエンディアンを指定したい場合は、代わりに `DataView` を使用してください。

これらの型付き配列に書き込む場合、表現可能な範囲外の値は正規化されます。

* すべての整数配列（`Uint8ClampedArray`を除く）は固定幅の数値変換を使用します。
* `Uint8ClampedArray` は、最初に数値を 0 から 255 の範囲に収めます（255 より大きい値は 255 になり、0 より小さい値は 0 になります）。そして、（切り捨てるのではなく）最も近い整数に丸めます。つまり、 2 つの整数のちょうど中間にある場合は、最も近い偶数の整数に丸めます。例えば、`0.5` は `0`、`1.5` は `2`、`2.5` は `2` となります。
* `Float32Array` では "round to even" を行い、 64 ビット浮動小数点数を 32 ビットに変換します。これは `Math.fround()` で指定されたアルゴリズムと同じです。
### サイズ変更可能なバッファー表示時の動作について

サイズ変更可能なバッファーのビューとして `TypedArray` を作成した場合、`TypedArray` が長さを追跡するよう構築されているかどうかにより、基盤のバッファーをサイズ変更した際に `TypedArray` のサイズに様々な影響を与えます。

3つ目の引数を除外したり、`undefined` を渡したりして、固有のサイズを持たない型付き配列を作成した場合、型付き配列は *長さ追跡* となり、後者のサイズが変更されると、基盤となる `buffer` に合わせて自動的にサイズ変更されます。

```js
const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2

buffer.resize(12);

console.log(float32.byteLength); // 12
console.log(float32.length); // 3
```

型付き配列を 3 つ目の `length` 引数で具体的なサイズを指定して作成した場合、後者が大きくなっても `buffer` を格納するためにサイズを変更することはありません。

```js
const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer, 0, 2);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2
console.log(float32[0]); // 0（初期値）

buffer.resize(12);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2
console.log(float32[0]); // 0（初期値）
```

`buffer` が縮小されるとき、見ている型付き配列が境界を越えることがあり、その場合、型付き配列の監視サイズは 0 に減少します。これは、長さ追跡を行わない型付き配列の長さが変化する唯一のケースです。

```js
const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer, 0, 2);

buffer.resize(7);

console.log(float32.byteLength); // 0
console.log(float32.length); // 0
console.log(float32[0]); // undefined
```

その後、 `buffer` を再び大きくして型付き配列を元に戻せば、型付き配列のサイズは元の値に戻ります。

```js
buffer.resize(8);

console.log(float32.byteLength); // 8
console.log(float32.length); // 2
console.log(float32[0]); // 0 - back in bounds again!
```

長さ追跡型の型付き配列でも、バッファーが `byteOffset` を超えて縮小された場合、同じことが起こり得る．

```js
const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
const float32 = new Float32Array(buffer, 4);
// float32 は長さを追跡しますが、4 バイト目からバッファー末尾までしか
// 拡張しないので、バッファーが 4 バイトより短くなるようにリサイズされる
// と、配列の型が範囲外になってしまいます。
buffer.resize(3);
console.log(float32.byteLength); // 0
```

コンストラクター
--------

このオブジェクトは直接インスタンス化できません。`new` で構築しようとすると `TypeError` が発生します。

```js
new (Object.getPrototypeOf(Int8Array))();
// TypeError: Abstract class TypedArray not directly constructable
```

その代わり、`Int8Array` や `BigInt64Array` のような特定の種類の型付き配列のインスタンスを作成してください。これらのオブジェクトは、すべてコンストラクターに共通の構文を持っています。

```js
new TypedArray()
new TypedArray(length)
new TypedArray(typedArray)
new TypedArray(object)

new TypedArray(buffer)
new TypedArray(buffer, byteOffset)
new TypedArray(buffer, byteOffset, length)
```

ここで *TypedArray* は特定の型のコンストラクターのうちの一つを表します。

**メモ:** すべての `TypedArray` サブクラスのコンストラクターは `new` を使ってのみ構築することができます。`new` なしで呼び出そうとすると `TypeError` が発生します。

### 引数

`typedArray`

`TypedArray` のサブクラスのインスタンスを指定して呼び出されると、`typedArray` が新しい型付き配列にコピーされます。長整数以外の `TypedArray` コンストラクターでは、`typedArray` 引数には長整数以外の型付き配列のうちのいずれか（`Int32Array` など）を指定します。同様に、長整数の `TypedArray` コンストラクター（`BigInt64Array` または `BigUint64Array`）では、`typedArray` 引数には長整数型のいずれかしか指定できません。`typedArray` の各値は、新しい配列にコピーされる前にコンストラクターの対応する型に変換される。新しい型付き配列の長さは `typedArray` の引数の長さと同じになります。

`object`

`TypedArray` インスタンスでないオブジェクトで呼び出された場合、`TypedArray.from()` メソッドと同じ方法で、新しい型付き配列を生成します。

`length` 省略可

オブジェクト以外で呼び出された場合、引数は型付き配列の長さを指定する数値として扱われます。内部配列バッファーがメモリー内に作成され、サイズは `length` に `BYTES_PER_ELEMENT` バイトを乗じたものとなり、0 で満たされます。すべての引数を除外すると、`0` を `length` として使用することと同じになります。

`buffer`, `byteOffset` 省略可, `length` 省略可

`ArrayBuffer` または `SharedArrayBuffer` インスタンスを指定し、さらに `byteOffset` および `length` 引数を付けて呼び出すと、指定したバッファーを参照する型付き配列ビューを新たに作成することができます。`byteOffset` （バイト単位）と `length` （要素数で、それぞれが `BYTES_PER_ELEMENT` バイトを占めます）の引数は、型付き配列ビューが参照するメモリー範囲を指定します。両方とも省略した場合、`buffer` の全体が参照されます。`length` のみが省略された場合、`buffer` の `byteOffset` 以降の部分が表示されます。`length` が省略された場合、型付き配列は長さ追跡となります。

### 例外

すべての `TypeArray` サブクラスのコンストラクターは、同じように操作します。すべてで以下のような例外を発生することがあります。

`TypeError`

以下のいずれかの場合に発生します。

* `typedArray` が渡されたが、現在のコンストラクターとは異なり長整数型のものであった場合、またはその逆。
* `typedArray` が渡されたが、そのバッファーが分離されていた場合、または分離された `buffer` が直接渡された場合。

`RangeError`

以下のいずれかの場合に発生します。

* 新しい型付き配列の長さが長すぎる。
* `buffer` （`length` 引数を指定しない場合）または `byteOffset` の長さが、新しい型付き配列の要素サイズの整数倍でない。
* `byteOffset` が有効な配列インデックス（0 から 253 - 1 の間の整数）でない。
* バッファーからビューを作成する場合、境界がバッファーの外側になる。言い換えれば、`byteOffset + length * TypedArray.BYTES_PER_ELEMENT > buffer.byteLength` となる。

静的プロパティ
-------

これらのプロパティは `TypedArray` コンストラクターオブジェクトで定義されており、したがってすべての `TypedArray` サブクラスのコンストラクターで共有されます。

`TypedArray[@@species]`

派生オブジェクトを作成するために使用されるコンストラクター関数です。

すべての `TypedArray` サブクラスには以下の静的プロパティもあります。

`TypedArray.BYTES_PER_ELEMENT`

さまざまな `TypedArray` インスタンスの要素のサイズを数値で返します。

静的メソッド
------

これらのメソッドは `TypedArray` コンストラクターオブジェクトに定義されているため、すべての `TypedArray` のサブクラスのコンストラクターに共有されます。

`TypedArray.from()`

配列風オブジェクトや反復可能オブジェクトから、新たな `TypedArray` を生成します。`Array.from()` もご覧ください。

`TypedArray.of()`

引数に与えた値をもとに、新たな `TypedArray` を生成します。`Array.of()` もご覧ください。

インスタンスプロパティ
-----------

これらのプロパティは `TypedArray.prototype` オブジェクトで定義されており、すべての `TypedArray` のサブクラスインスタンスで共有されています。

`TypedArray.prototype.buffer`

この型付き配列によって参照さている `ArrayBuffer` を返します。

`TypedArray.prototype.byteLength`

型付き配列の長さを (バイト単位で) 返します。

`TypedArray.prototype.byteOffset`

型付き配列の `ArrayBuffer` の先頭からのオフセットを (バイト単位で) 返します。

`TypedArray.prototype.constructor`

インスタンスオブジェクトを作成したコンストラクター関数です。`TypedArray.prototype.constructor` は隠された `TypedArray` のコンストラクター関数ですが、型付き配列のサブクラスはそれぞれ `constructor` プロパティを定義しています。

`TypedArray.prototype.length`

型付き配列内に保持された要素の数を返します。

`TypedArray.prototype[@@toStringTag]`

`TypedArray.prototype[@@toStringTag]` プロパティの初期値はゲッターで、型付き配列ののコンストラクター名と同じ文字列を返します。このプロパティは `this` の値が型付き配列のサブクラスのいずれでもない場合、 `undefined` を返します。このプロパティは `Object.prototype.toString()` で使用されます。ただし、`TypedArray` は独自の `toString()` メソッドを持っているので、このプロパティは`Object.prototype.toString.call()`を `thisArg` に型付き配列を設定して呼び出差ない限り、このプロパティの使用されません。

すべての `TypedArray` のサブクラスには、以下のインスタンスプロパティもあります。

`TypedArray.prototype.BYTES_PER_ELEMENT`

様々な `TypedArray` インスタンスの要素の大きさを数値で返します。

インスタンスメソッド
----------

これらのメソッドは `TypedArray` プロトタイプオブジェクトに定義されているため、すべての `TypedArray` サブクラスインスタンスで共有されます。

`TypedArray.prototype.at()`

整数値を受け取り、その位置にあるアイテムを返します。このメソッドでは負の整数を扱うことができ、最後の項目から逆向きに数えます。

`TypedArray.prototype.copyWithin()`

配列内で一連の配列要素をコピーします。 `Array.prototype.copyWithin()` も参照してください。

`TypedArray.prototype.entries()`

配列内のすべての位置に対するキー／値の組を含む、新しい配列イテレーターを返します。 `Array.prototype.entries()` も参照してください。

`TypedArray.prototype.every()`

配列内のすべての要素が関数によって提供されたテストに合格するかどうかテストを実行します。 `Array.prototype.every()` も参照してください。

`TypedArray.prototype.fill()`

開始位置から終了位置までのすべての要素に固定値を設定します。 `Array.prototype.fill()` も参照してください。

`TypedArray.prototype.filter()`

与えられたフィルタリング関数が `true` を返す配列のすべての要素をもつ新しい配列を生成します。 `Array.prototype.filter()` も参照してください。

`TypedArray.prototype.find()`

配列要素が与えられたテスト関数を満足したら、配列の値を返します。満足しなかった場合、 `undefined` を返します。 `Array.prototype.find()` も参照してください。

`TypedArray.prototype.findIndex()`

配列要素が与えられたテスト関数を満足したら、配列のインデックスを返します。満足しなかった場合は `-1` を返します。`Array.prototype.findIndex()` も参照してください。

`TypedArray.prototype.findLast()`

指定されたテスト関数を満たす配列の最後の要素の値を返し、適切な要素が得られなかった場合は `undefined` を返します。`Array.prototype.findLast()` も参照してください。

`TypedArray.prototype.findLastIndex()`

指定されたテスト関数を満たす配列の最後の要素のインデックスを返し、適切な要素が見つからなかった場合は `-1` を返します。`Array.prototype.findLastIndex()` も参照してください。

`TypedArray.prototype.forEach()`

配列内の各要素に対する関数を呼び出します。 `Array.prototype.forEach()` も参照してください。

`TypedArray.prototype.includes()`

型付き配列にある要素が含まれているかどうか判断し、それに応じて `true` または `false` を返します。 `Array.prototype.includes()` も参照してください。

`TypedArray.prototype.indexOf()`

指定された値に等しい配列内の要素の最初の位置を返します。見つからなかった場合は `-1` を返します。 `Array.prototype.indexOf()` も参照してください。

`TypedArray.prototype.join()`

すべての配列要素を 1 つの文字列に結合します。 `Array.prototype.join()` も参照してください。

`TypedArray.prototype.keys()`

配列内のそれぞれの位置に対するキーを含む新しい配列イテレーターを返します。 `Array.prototype.keys()` も参照してください。

`TypedArray.prototype.lastIndexOf()`

指定された値と等しい配列の要素の最後の位置を返します。見つからない場合は `-1` を返します。`Array.prototype.lastIndexOf()`を確かめて下さい。

`TypedArray.prototype.map()`

この配列のすべての要素で与えられた関数を呼び出した結果をもつ新しい配列を生成します。`Array.prototype.map()` も参照してください。

`TypedArray.prototype.reduce()`

アキュームレーターと配列のそれぞれの値（左から右へ）に対して関数を適用し、単一の値にまで縮小します。 `Array.prototype.reduce()` も参照してください。

`TypedArray.prototype.reduceRight()`

アキュームレーターと配列のそれぞれの値（右から左へ）に対して関数を適用し、単一の値にまで縮小します。 `Array.prototype.reduce()` も参照してください。

`TypedArray.prototype.reverse()`

配列要素の順番を反転させます。 — 最初の要素は最後になり、最後の要素は最初になります。 `Array.prototype.reverse()` も参照してください。

`TypedArray.prototype.set()`

入力値を指定した配列から読み込み、型付き配列内に複数の値を格納します。

`TypedArray.prototype.slice()`

配列の一部を取り出して新しい配列を返します。 `Array.prototype.slice()` も参照してください。

`TypedArray.prototype.some()`

ある配列の少なくとも 1 つの要素が与えられたテスト関数を満たした場合に `true` を返します。 `Array.prototype.some()` も参照してください。

`TypedArray.prototype.sort()`

配列の要素をソートし、その結果を返します。 `Array.prototype.sort()` も参照してください。

`TypedArray.prototype.subarray()`

与えられた開始位置と終了位置の要素インデックスから、新しい `TypedArray` を返します。

`TypedArray.prototype.toLocaleString()`

配列と要素を表すローカライズされた文字列を返します。 `Array.prototype.toLocaleString()` も参照してください。

`TypedArray.prototype.toReversed()`

元の配列を変更せずに、要素を逆順に並べた新しい配列を返します。

`TypedArray.prototype.toSorted()`

元の配列を変更せずに、要素を昇順に並べた新しい配列を返します。

`TypedArray.prototype.toString()`

配列と要素を表す文字列を返します。 `Array.prototype.toString()` も参照してください。

`TypedArray.prototype.values()`

配列内のそれぞれの位置に対する値を含む新しい配列イテレーターオブジェクトを返します。 `Array.prototype.values()` も参照してください。

`TypedArray.prototype.with()`

指定された位置の要素を指定された値で置き換えた新しい配列を、元の配列に変更を加えることなく返します。

`TypedArray.prototype[@@iterator]()`

配列内でそれぞれの位置に対する値を含む新しい配列イテレーターオブジェクトを返します。

例
-

### プロパティへのアクセス

配列内の要素は、標準の配列の添字構文 (すなわち、かぎ括弧を使用する表記) を使用して参照することができます。しかし、型付き配列でインデックス付きプロパティで取得または設定するときは、範囲外のインデックスでもプロパティのプロトタイプチェーンを探索しません。インデックス付きプロパティは `ArrayBuffer` を調べるのであり、オブジェクトのプロパティは探索しません。他のオブジェクト同様に、名前付きプロパティは使用できます。

```js
// 標準的な配列構文を使用して設定および取得
const int16 = new Int16Array(2);
int16[0] = 42;
console.log(int16[0]); // 42

// プロトタイプでインデックス付き配列を使用しても探索しない (Fx 25)
Int8Array.prototype[20] = "foo";
new Int8Array(32)[20]; // 0
// even when out of bound
Int8Array.prototype[20] = "foo";
new Int8Array(8)[20]; // undefined
// or with negative integers
Int8Array.prototype[-1] = "foo";
new Int8Array(8)[-1]; // undefined

// 名前付きプロパティも利用できる (Fx 30)
Int8Array.prototype.foo = "bar";
new Int8Array(32).foo; // "bar"
```

### 凍結できない

空でない `TypedArray` は凍結することができません。その基盤である `ArrayBuffer` はそのバッファーの別の `TypedArray` ビューを通して変更される可能性があるためです。これはオブジェクトが純粋に凍結されることがないことを意味しています。

```js
const i8 = Int8Array.of(1, 2, 3);
Object.freeze(i8);
// TypeError: Cannot freeze array buffer views with elements
```

### ByteOffset は正規化する必要がある

`ArrayBuffer` にビューとして `TypedArray` を構築した場合、`byteOffset` 引数は要素サイズの境界に配置する必要があります。言い換えれば、オフセットは `BYTES_PER_ELEMENT` の倍数でなければなりません。

```js
const i32 = new Int32Array(new ArrayBuffer(4), 1);
// RangeError: start offset of Int32Array should be a multiple of 4
```

```js
const i32 = new Int32Array(new ArrayBuffer(4), 0);
```

### ByteLength は正規化する必要がある

`byteOffset` 引数と同様に、`TypedArray` のコンストラクターに渡される `ArrayBuffer` の `byteLength` プロパティも、コンストラクターの `BYTES_PER_ELEMENT` の倍数にする必要があります。

```js
const i32 = new Int32Array(new ArrayBuffer(3));
// RangeError: byte length of Int32Array should be a multiple of 4
```

```js
const i32 = new Int32Array(new ArrayBuffer(4));
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-typedarray-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* 型付き配列のポリフィル (`core-js`)
* JavaScript の型付き配列ガイド
* `ArrayBuffer`
* `DataView`
* `TextDecoder`


Number - JavaScript

Number
======

**`Number`** （数値）の値は `37` や `-9.25` のような浮動小数点数を表します。

**`Number`** コンストラクターは、数値を扱うための定数とメソッドを含んでいます。他の型の値は `Number()` 関数を用いて数値に変換することができます。

解説
--

数値は、`255` や `3.14159` のようなリテラル形式で表現するのが最も一般的です。字句文法には、より詳しい参照があります。

```js
255; // 二百五十五
255.0; // 同じ数値
255 === 255.0; // true
255 === 0xff; // true （16 進記法）
255 === 0b11111111; // true （2 進記法）
255 === 0.255e3; // true （10 進指数記法）
```

JavaScript コードにおける `37` のような数値リテラルは浮動小数点値であり、整数ではありません。日常的に使用される独立した整数型はありません。（JavaScript は長整数 (`BigInt`) 型を持つようになりましたが、日常の利用で数値を置き換えるように設計されてはいません。 `37` は数値であり、長整数ではありません。）

関数として使用された場合、 `Number(value)` は文字列やその他の値を数値型に変換します。値が変換できない場合は、 `NaN` を返します。

```js
Number("123"); // 数値 123 を返す
Number("123") === 123; // true

Number("unicorn"); // NaN
Number(undefined); // NaN
```

### 数値のエンコーディング

JavaScript の数値 (`Number`) 型は IEEE 754 の倍精度 64ビットバイナリー形式であり、 Java や C# の `double` のようなものです。つまり、小数値を表しますが、格納される数値の大きさと精度には制限があります。とても簡単に説明すると、IEEE 754 の倍精度数は、3 つの部分を表すのに 64 ビットを使用します。

* 1 ビットの符号（*sign*, 正の数または負の数）
* 11 ビットの指数部（*exponent*, -1022 から 1023）
* 52 ビットの仮数部（*mantissa*, 0 と 1 の間の数値を表す）

仮数部（*significand* とも呼ばれる）は、実際の値を表す部分（有効数字）です。指数は、仮数を乗じるべき 2 のべき乗です。科学的記数法として考えると、次のようになります。

Number
=
(

−
1

)
sign

⋅
(
1
+
mantissa
)
⋅

2
exponent

\text{Number} = ({-1})^{\text{sign}} \cdot (1 + \text{mantissa}) \cdot 2^{\text{exponent}}

仮数部は 52 ビットで格納され、2 進数の小数でいうところの `1.…` 以降の桁と解釈されます。したがって，仮数部の精度は 2-52（`Number.EPSILON` で取得可能）、すなわち小数点以下 15 ～ 17 桁程度となります。演算は丸め誤差の影響を受けます。

数値が保持できる最大の値は 21024 - 1（底が 2 で指数が 1023、仮数が 0.1111...）であり、これは `Number.MAX_VALUE` で取得可能です。それ以上の値は、特殊な数値定数 `Infinity` で置き換えられます。

整数は、仮数が 53 ビット（先頭の 1 も含む）しか保持できないため、精度を落とさずに表せるのは -253 + 1 から 253 - 1 の範囲（`Number.MIN_SAFE_INTEGER` と `Number.MAX_SAFE_INTEGER` で取得できる）だけです。

これについては、ECMAScript 標準に記述されています。

### 数値への変換

数字を期待する多くの組み込み演算は、最初に引数を数字に変換します（`Number`オブジェクトが数字プリミティブと似たような動作をするのは、このためです）。この操作 は以下のように要約されます。

* 数値はそのまま返されます。
* `undefined` は `NaN` になります。
* `null` は `0` になります。
* `true` は `1` に、`false` は `0` になります。
* 文字列は、数値リテラルが入っているかのように解釈して変換されます。解釈に失敗した場合は `NaN` が返されます。実際の数値リテラルと比較すると、いくつかの異なる点があります。
    + 先頭および末尾のホワイトスペース/改行文字は無視されます。
    + 先頭が数字 `0` である場合、数値が 8 進数のリテラルとなる（または厳格モードで拒否される）ことはありません。
    + 文字列の始めには、符号を示すために `+` と `-` を置くことができます。（実際のコードでは、これらはリテラルの一部に「見える」のですが、実際には別個の単項演算子です。）ただし、符号は一度しか現れず、空白が続いてはいけません。
    + `Infinity` と `-Infinity` はリテラルとして認識されます。実際のコードでは、これらはグローバル変数です。
    + 空文字列またはホワイトスペースのみの文字列は `0` に変換されます。
    + 数値の区切り文字は許可されません。
* 長整数は、意図しない精度の低下を防ぐために `TypeError` 例外が発生します。
* シンボルは `TypeError` 例外が発生します。
* オブジェクトはまずプリミティブに変換されます（`[@@toPrimitive]()`を `"number"` のヒント付きで、`valueOf()`、`toString()` メソッドをこの順で呼び出すことで）。結果のプリミティブは数値へ変換されます。

JavaScript でほぼ同じ効果を得るには、2 つの方法があります。

* 単項プラス: `+x` は上で説明した数値変換の手順を、`x` を変換するためにそのまま実行します。
* `Number()` 関数: `Number(x)` は `x` を変換する同じアルゴリズムを使用します。ただし長整数は `TypeError` 例外を発生させず、精度が落ちる可能性があるものの、数値としての値を返します。

`Number.parseFloat()` および `Number.parseInt()` は `Number()` と似ていますが、文字列のみを若干異なる解釈ルールで変換します。例えば、`parseInt()` は小数点を解釈せず、 `parseFloat()` は `0x` の接頭辞を解釈しません。

#### 整数への変換

演算子の中には整数を期待するものがあり ます。特に、配列や文字列の添字、時刻の成分、数値の基数を扱う演算子はそうです。上記の数値強制の手順を実行した後、結果は切り捨てて（小数部分を捨てて）整数に変換します。数値が無限大 (±Infinity) の場合は、そのまま返します。数値が `NaN` または `-0` の場合、`0` を返します。したがって、結果は常に整数（`-0`ではない）か ±Infinity となります。

注目すべきは、整数に変換すると `undefined` も `null` も `0` になることです。これは `undefined` が `NaN` に変換され、これも `0` になるためです。

#### 固定長数値への変換

JavaScript には整数の 2 進数エンコーダーを処理する低レベルの関数がいくつかあり、特にビット演算子と `TypedArray` オブジェクトが有名です。ビット演算子は常にオペランドを 32 ビット整数に変換します。この場合、値を数値に変換した後、最初の切り捨てで小数部を取り除き、次に整数の 2 の補数で最低ビットを導いて、数値を指定の幅に正規化します。

```js
new Int32Array([1.1, 1.9, -1.1, -1.9]); // Int32Array(4) [ 1, 1, -1, -1 ]

new Int8Array([257, -257]); // Int8Array(2) [ 1, -1 ]
// 257 = 0001 0000 0001
// = 0000 0001 (mod 2^8)
// = 1
// -257 = 1110 1111 1111
// = 1111 1111 (mod 2^8)
// = -1 (as signed integer)

new Uint8Array([257, -257]); // Uint8Array(2) [ 1, 255 ]
// -257 = 1110 1111 1111
// = 1111 1111 (mod 2^8)
// = 255 (as unsigned integer)
```

コンストラクター
--------

`Number()`

新しい `Number` 値を生成します。

`Number` をコンストラクターとして（`new` を付けて）呼び出すと、`Number` オブジェクトを作成しますが、これはプリミティブでは**ありません**。例えば、`typeof new Number(42) === "object"` であり、`new Number(42) !== 42` となります（`new Number(42) == 42` ではあるが）。

**警告:** コンストラクターとして `Number` を使用することはほとんどないはずです。

静的プロパティ
-------

`Number.EPSILON`

数値として表される 2 個の数の最小の差です。

`Number.MAX_SAFE_INTEGER`

JavaScript における確実な整数の最大値 (253 - 1) です。

`Number.MAX_VALUE`

表現可能な正の数の最大値です。

`Number.MIN_SAFE_INTEGER`

JavaScript における確実な整数の最小値 (-(253 - 1)) です。

`Number.MIN_VALUE`

表現可能な正の数の最小値。0 に最も近い正の数です（0 ではありません）。

`Number.NaN`

特殊な "**N**ot **a** **N**umber" （数値ではない）の値です。

`Number.NEGATIVE_INFINITY`

負の無限大を表す特別な値です。オーバーフロー時に返されます。

`Number.POSITIVE_INFINITY`

無限大を表す特別な値です。オーバーフロー時に返されます。

静的メソッド
------

`Number.isFinite()`

渡された値が有限数であるかどうかを判断します。

`Number.isInteger()`

渡された値が整数であるかどうかを判断します。

`Number.isNaN()`

渡された値が `NaN` であるかどうかを判断します。

`Number.isSafeInteger()`

渡された値が確実な範囲の整数（-(253 - 1) から 253 - 1 の間）であるかどうかを判断します。

`Number.parseFloat()`

これはグローバルの `parseFloat()` 関数と同じです。

`Number.parseInt()`

これはグローバルの `parseInt()` 関数と同じです。

インスタンスプロパティ
-----------

これらのプロパティは `Number.prototype` に定義されており、すべての `Number` インスタンスで共有されます。

`Number.prototype.constructor`

インスタンスオブジェクトを作成したコンストラクター関数。`Number` インスタンスの場合、初期値は `Number` コンストラクターです。

インスタンスメソッド
----------

`Number.prototype.toExponential()`

指数表記で数値を表す文字列を返します。

`Number.prototype.toFixed()`

固定小数点表記で数値を表す文字列を返します。

`Number.prototype.toLocaleString()`

この値を言語依存の表現で表す文字列を返します。 `Object.prototype.toLocaleString()` メソッドを上書きします。

`Number.prototype.toPrecision()`

指定された精度で、固定小数点表記または指数表記で数値で表す文字列を返します。

`Number.prototype.toString()`

指定された基数を元に、指定されたオブジェクトを表す文字列を返します。 `Object.prototype.toString()` メソッドを上書きします。

`Number.prototype.valueOf()`

指定されたオブジェクトのプリミティブ値を返します。 `Object.prototype.valueOf()` メソッドを上書きします。

例
-

### Number オブジェクトを使用して変数に値を代入する

以下の例では、`Number` オブジェクトのプロパティを使用して、いくつかの数の変数に値を代入します。

```js
const biggestNum = Number.MAX\_VALUE;
const smallestNum = Number.MIN\_VALUE;
const infiniteNum = Number.POSITIVE\_INFINITY;
const negInfiniteNum = Number.NEGATIVE\_INFINITY;
const notANum = Number.NaN;
```

### Number の整数の範囲

次の例は、`Number` オブジェクトで表現可能な最小の整数値と最大の整数値です。

```js
const biggestInt = Number.MAX\_SAFE\_INTEGER; // (2\*\*53 - 1) => 9007199254740991
const smallestInt = Number.MIN\_SAFE\_INTEGER; // -(2\*\*53 - 1) => -9007199254740991
```

JSON にシリアライズされたデータを解析する場合、整数値がこの範囲を超えていると、 JSON パーサーがこの値を `Number` 型に変換したときに信頼できない値になります。

可能な回避策として、代わりに `String` を使用してください。

大きい数値は `BigInt` 型を用いて表すことができます。

### Number を使用して Date オブジェクトを変換する

以下の例は、 `Number` を関数として用いて、`Date` オブジェクトを数値に変換します。

```js
const d = new Date("December 17, 1995 03:24:00");
console.log(Number(d));
```

これは、コンソールに `819199440000` を出力します。

### 数字や null を数値に変換する

```js
Number("123"); // 123
Number("123") === 123; // true
Number("12.3"); // 12.3
Number("12.00"); // 12
Number("123e-1"); // 12.3
Number(""); // 0
Number(null); // 0
Number("0x11"); // 17
Number("0b11"); // 3
Number("0o11"); // 9
Number("foo"); // NaN
Number("100a"); // NaN
Number("-Infinity"); // -Infinity
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* 最新の `Number` の動作（2 進数と 8 進数のリテラルに対応）のポリフィル (`core-js`)
* `NaN`
* 算術演算子
* `Math` グローバルオブジェクト
* 任意の精度の整数型: `BigInt`


Int8Array - JavaScript

Int8Array
=========

**`Int8Array`** は型付き配列で、 2 の補数形式の 8 ビット符号付き整数値の配列を表します。中身は `0` で初期化されます。生成されると、配列内の要素はそのオブジェクトのメソッドを使用するか、配列の標準的な添字の構文 (すなわち、ブラケット記法) を使用するかして参照することができます。

コンストラクター
--------

`Int8Array()`

新しい `Int8Array` オブジェクトを生成します。

静的プロパティ
-------

`Int8Array.BYTES_PER_ELEMENT`

要素の大きさを数値で返します。`Int8Array` の場合は `1` です。

`Int8Array.name`

コンストラクター名を文字列値で返します。`Int8Array` の場合、 "Int8Array" です。

静的メソッド
------

`Int8Array.from()`

配列風オブジェクトまたは反復可能オブジェクトから新しい `Int8Array` オブジェクトを生成します。 `Array.from()` も参照してください。

`Int8Array.of()`

可変長引数で新しい `Int8Array` オブジェクトを生成します。`Array.of()` も参照してください。

インスタンスプロパティ
-----------

`Int8Array.prototype.buffer`

`Int8Array` オブジェクトによって参照される `ArrayBuffer` を返します。構築時に固定され、**読み取り専用**です。

`Int8Array.prototype.byteLength`

`ArrayBuffer` の先頭からの `Int8Array` の長さを (バイト単位で) 返します。構築時に固定され、**読み取り専用**です。

`Int8Array.prototype.byteOffset`

`ArrayBuffer` の先頭からの `Int8Array` のオフセットを (バイト単位で) 返します。構築時に固定され、**読み取り専用**です。

`Int8Array.prototype.length`

`Int8Array` オブジェクト内に保持されている要素の数を返します。構築時に固定され、**読み取り専用**です。

インスタンスメソッド
----------

`Int8Array.prototype.copyWithin()`

配列内で一連の配列要素をコピーします。`Array.prototype.copyWithin()` も参照してください。

`Int8Array.prototype.entries()`

配列内ですべての位置におけるキーと値の組を提供する新しい*配列イテレーター*を返します。`Array.prototype.entries()` も参照してください。

`Int8Array.prototype.every()`

配列内のすべての要素が関数によって提供されたテストに合格するかどうかテストを実行します。`Array.prototype.every()` も参照してください。

`Int8Array.prototype.fill()`

配列の先頭位置から末尾位置までのすべての要素を固定値に設定します。`Array.prototype.fill()` も参照してください。

`Int8Array.prototype.filter()`

この配列のすべての要素のうち、与えられたフィルタリング関数が `true` を返すものをもつ新しい配列を生成します。`Array.prototype.filter()` も参照してください。

`Int8Array.prototype.find()`

配列内の要素に与えられたテスト関数を満足するものがあったら、見つかった値を返します。見つからなければ `undefined` を返します。`Array.prototype.find()` も参照してください。

`Int8Array.prototype.findIndex()`

配列内の要素に与えられたテスト関数を満足するものがあったら、見つかった位置を返します。見つからなければ `-1` を返します。`Array.prototype.findIndex()` も参照してください。

`Int8Array.prototype.forEach()`

配列内のそれぞれの要素について関数を呼び出します。`Array.prototype.forEach()` も参照してください。

`Int8Array.prototype.includes()`

型付き配列に特定の要素があるかどうかを判断し、それに応じて `true` か `false`を返します。 `Array.prototype.includes()` も参照してください。

`Int8Array.prototype.indexOf()`

指定された値に等しい配列内の要素の最初の (最小の) 位置を返します。見つからなかった場合、 `-1` を返します。`Array.prototype.indexOf()` も参照してください。

`Int8Array.prototype.join()`

配列のすべての要素を 1 つの文字列に結合します。`Array.prototype.join()` も参照してください。

`Int8Array.prototype.keys()`

配列内ですべての位置におけるキーを提供する新しい*配列イテレーター*を返します。`Array.prototype.keys()` も参照してください。

`Int8Array.prototype.lastIndexOf()`

指定された値に等しい配列内の要素の最後の (最大の) 位置を返します。見つからなかった場合、 `-1` を返します。`Array.prototype.lastIndexOf()` も参照してください。

`Int8Array.prototype.map()`

この配列のすべての要素で与えられた関数を呼び出した結果をもつ新しい配列を生成します。`Array.prototype.map()` も参照してください。

`Int8Array.prototype.reduce()`

アキュムレーターとこの配列のそれぞれの値に対して (左から右へ) 関数を適用し、単一の値に還元します。`Array.prototype.reduce()` も参照してください。

`Int8Array.prototype.reduceRight()`

アキュムレーターとこの配列のそれぞれの値に対して (右から左へ) 関数を適用し、単一の値に還元します。`Array.prototype.reduceRight()` も参照してください。

`Int8Array.prototype.reverse()`

配列の要素の順番を反転させます。最初の要素は最後になり、最後の要素は最初になります。`Array.prototype.reverse()` も参照してください。

`Int8Array.prototype.set()`

入力値を指定した配列から読み込み、この型付き配列内に複数の値を格納します。

`Int8Array.prototype.slice()`

配列の一部を取り出して新しい配列を返します。`Array.prototype.slice()` も参照してください。

`Int8Array.prototype.some()`

この配列の 1 つ以上の要素が与えられたテスト関数を満たした場合に `true` を返します。`Array.prototype.some()` も参照してください。

`Int8Array.prototype.sort()`

配列の要素をその場で並べ替え、その配列を返します。`Array.prototype.sort()` も参照してください。

`Int8Array.prototype.subarray()`

指定された先頭と末尾の要素位置から新しい `Int8Array` を返します。

`Int8Array.prototype.values()`

配列内ですべての位置における値を提供する新しい*配列イテレーター*を返します。`Array.prototype.values()` も参照してください。

`Int8Array.prototype.toLocaleString()`

配列とその要素を表すローカライズされた文字列を返します。`Array.prototype.toLocaleString()` も参照してください。

`Int8Array.prototype.toString()`

配列とその要素を表す文字列を返します。`Array.prototype.toString()` も参照してください。

`Int8Array.prototype[@@iterator]()`

配列内ですべての位置における値を提供する新しい*配列イテレーター*を返します。

例
-

### 様々な方法で `Int8Array` を作成

```js
// 長さから
var int8 = new Int8Array(2);
int8[0] = 42;
console.log(int8[0]); // 42
console.log(int8.length); // 2
console.log(int8.BYTES\_PER\_ELEMENT); // 1

// 配列から
var arr = new Int8Array([21, 31]);
console.log(arr[1]); // 31

// From another TypedArray
var x = new Int8Array([21, 31]);
var y = new Int8Array(x);
console.log(y[0]); // 21

// ArrayBuffer から
var buffer = new ArrayBuffer(8);
var z = new Int8Array(buffer, 1, 4);

// 反復可能オブジェクトから
var iterable = (function\* () {
  yield\* [1, 2, 3];
})();
var int8 = new Int8Array(iterable);
// Int8Array[1, 2, 3]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # table-49 |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Int8Array` のポリフィルが `core-js` で利用できます
* JavaScript の型付き配列
* `ArrayBuffer`
* `DataView`


Infinity - JavaScript

Infinity
========

グローバルプロパティ **`Infinity`** は無限大を表す数値です。

| `Infinity` のプロパティ属性 |
| --- |
| 書込可能 | 不可 |
| 列挙可能 | 不可 |
| 設定可能 | 不可 |

試してみましょう
--------

解説
--

`Infinity` は*グローバルオブジェクト*のプロパティです。言い換えればグローバルスコープ内の変数です。

`Infinity` の初期値は `Number.POSITIVE_INFINITY` です。`Infinity` という値 (正の無限大) は他のあらゆる数より大きい数です。

この値は数学的に無限大のように振る舞います。詳しくは `Number.POSITIVE_INFINITY` を参照してください。

ECMAScript 5 の仕様では、`Infinity` は読み取り専用です (JavaScript 1.8.5 / Firefox 4 にて実装)。

例
-

### Infinity の使用

```js
console.log(Infinity); /\* Infinity \*/
console.log(Infinity + 1); /\* Infinity \*/
console.log(Math.pow(10, 1000)); /\* Infinity \*/
console.log(Math.log(0)); /\* -Infinity \*/
console.log(1 / Infinity); /\* 0 \*/
console.log(1 / 0); /\* Infinity \*/
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-value-properties-of-the-global-object-infinity |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Number.NEGATIVE_INFINITY`
* `Number.POSITIVE_INFINITY`
* `Number.isFinite`


parseInt() - JavaScript

parseInt()
==========

**`parseInt()`** 関数は、文字列の引数を解釈し、指定された基数 （数学的記数法の底）の整数値を返します。

試してみましょう
--------

構文
--

```js
parseInt(string)
parseInt(string, radix)
```

### 引数

`string`

整数で始まる文字列です。この引数では先頭のホワイトスペースは無視されます。

`radix` 省略可

`2` から `36` までの整数で、`string` の*基数*（数学的記数法の底）を表します。これは 32 ビット整数に変換されます。変換後にそれが 0 でなく、 [2, 36] の範囲外であった場合、この関数は常に `NaN` を返します。`0` または指定されなかった場合、基数は `string` の値に基づいて推測されます。既定で常に `10` になるわけではありません。下記の解説では、 `radix` が提供されなかった場合に何が起こるかをもっと詳細に説明しています。

### 返値

指定された `string` を解釈した整数値です。また、次の場合は `NaN` が返されます。

* `radix` が `2` よりも小さいか `36` よりも大きい、または
* ホワイトスペース以外の最初の文字が数値に変換できない。

**メモ:** JavaScript は言語レベルで「浮動小数点数」と「整数」の区別がありません。 `parseInt()` と `parseFloat()` は解釈の動作が異なるだけで、必ずしも返値が異なるわけではありません。例えば、 `parseInt("42")` と `parseFloat("42")` は同じ値である数値型の 42 を返します。

解説
--

`parseInt` 関数は第 1 引数を文字列に変換し、解釈したうえで、整数または `NaN` を返します。

`NaN` でない場合は、返値は第 1 引数を指定された `radix` で数値として解釈した整数値になります。(例えば、`radix` が `10` であれば 10 進数からの変換で、`8` であれば 8 進数からの変換で、`16` であれば 16 進数からの変換、などです。)

`radix` 引数は数値に変換されます。提供されなかった場合、または値が 0、`NaN`、`Infinity` のいずれかであった場合（`undefined` は `NaN` に強制されます）、 JavaScript は以下のように想定します。

1. 入力された `string` の先頭のホワイトスペースと、存在すれば `+`/`-` 符号が除去され、 `0x` または `0X` （ゼロ、従うこと以下で小文字または大文字の X）で始まっている場合、 `radix` は `16` とみなされ、文字列の残りの部分は 16 進数として解釈されます。
2. 入力された `string` が他の何らかの値で始まる場合、基数は `10` （10 進数）になります。

**メモ:** 他にも `0b` のような接頭辞は数値リテラルでは有効ですが、 `parseInt()` では通常の数字として扱われます。 `parseInt()` は `0` で始まる文字列を 8 進数の値として扱うことはありません。 `parseInt()` が認識できる接頭辞は、16 進数の値に対する `0x` または `0X` だけです。 `radix` がなければ、それ以外はすべて 10 進数として解釈されます。

基数が `16` の場合、 `parseInt()` では、オプションで符号文字 (`+`/`-`) の後に `0x` または `0X` を接頭辞として文字列を指定することができます。

（必要に応じて数値に変換された）基数の値が [2, 36] （両端を含む）の範囲になかった場合は、 `parseInt` は `NaN` を返します。

`10` 以上の基数については、`9` より大きい数字はアルファベットで示されます。たとえば、 16 進数（基数 `16`）では `A` から `F` が用いられます。文字の大文字小文字は区別しません。

`parseInt` は 2 つの符号を正確に理解します。`+` は正の符号で、`-` は負の符号です。これは解釈の最初の段階で、ホワイトスペースを除去した後に行われます。符号が見つからなかった場合は、アルゴリズムは次の段階に移行します。そうでなければ、符号を取り除いて残りの文字列の数値の解釈を実行します。

もし `parseInt` が `radix` で指定された基数に含まれる数字以外の文字に遭遇した場合、その文字とそれに続くすべての文字を無視し、この点まで解釈できた整数値を返します。例えば、 `1e3` は技術的には整数をエンコードしたものですが、（そして `parseFloat()` では正しく `1000` と解釈されますが）、 `parseInt("1e3", 10)` は `1` を返します。 `e` は基数 10 の有効な数字ではないからです。 `.` も数字ではないので、返値は常に整数になります。

 最初の文字が使用している基数で数字に変換できなかった場合は、 `parseInt` は `NaN` を返します。
 先頭のホワイトスペースは許容されます。

数値演算の目的では、`NaN` は基数がいくつであっても数値にはなりません。 `Number.isNaN` 関数を使うと、 `parseInt` の結果が `NaN` であるかどうか確かめられます。数値演算で `NaN` が与えられると、演算結果も `NaN` になります。

巨大な数値では `e` の文字を文字列表現の中で使用しますので（例えば **`6.022E23`** は 6.022 × 10^23 を表します）、`parseInt` を使用して数値を切り捨てると、とても大きな数字やとても小さな数字を使用する際に予期しない結果を生み出すことがあります。 `parseInt` を `Math.trunc()` の代用として使うべきではありません。

To convert a number to its string literal in a particular radix, use `thatNumber.toString(radix)`.

`parseInt()` は数値を返すので、文字列が表す整数が安全な範囲の外の場合、精度が落ちる可能性があります。 `BigInt()` 関数は `BigInt` を返すことで、任意の長さの整数を正確に解釈することに対応しています。

例
-

### parseInt() の使用

以下の例はいずれも `15` を返します。

```js
parseInt("0xF", 16);
parseInt("F", 16);
parseInt("17", 8);
parseInt("015", 10); // ただし `parseInt('015', 8)` は 13 を返す
parseInt("15,123", 10);
parseInt("FXX123", 16);
parseInt("1111", 2);
parseInt("15 \* 3", 10);
parseInt("15e2", 10);
parseInt("15px", 10);
parseInt("12", 13);
```

以下の例はいずれも `NaN` を返します。

```js
parseInt("Hello", 8); // まったく数字ではない
parseInt("546", 2); // 2 進数では 0 または 1 以外の数字は無効
```

以下の例はいずれも `-15` を返します。

```js
parseInt("-F", 16);
parseInt("-0F", 16);
parseInt("-0XF", 16);
parseInt("-17", 8);
parseInt("-15", 10);
parseInt("-1111", 2);
parseInt("-15e1", 10);
parseInt("-12", 13);
```

以下の例は `224` を返します。

```js
parseInt("0e0", 16);
```

`parseInt()` は `BigInt` の値を扱いません。 `n` の文字で解釈を停止し、それまでの文字列を通常の整数として扱うため、精度が落ちる可能性があります。

```js
parseInt("900719925474099267n");
// 900719925474099300
```

代わりに、文字列を末尾の `n` なしで `BigInt()` 関数に渡してください。

```js
BigInt("900719925474099267");
// 900719925474099267n
```

`parseInt` は数値の区切り文字を扱うことができません。

```js
parseInt("123\_456"); // 123
```

### 文字列でないものに対する parseInt() を使用

`parseInt()` は、文字列でないものを大きな基数で扱う場合に興味深い結果をもたらすことがあります。例えば、 `36` の場合です（これはすべての英数字を有効な数字にします）。

```js
parseInt(null, 36); // 1112745: "null" の文字列は 36 進数で 1112745
parseInt(undefined, 36); // 86464843759093: "undefined" の文字列は 36 進数で 86464843759093
```

一般に、 `Math.trunc()` の代用として使用するのは良くない考えです。小さな数では使えるかもしれません。

```js
parseInt(15.99, 10); // 15
parseInt(-15.1, 10); // -15
```

しかし、これはたまたま、この数値の文字列表現が基本的な小数表記 (`"15.99"`, `"-15.1"`) を使用しており、 `parseInt()` が小数点で止まっているためにうまく動作しているだけです。 1e+21 以上または 1e-7 以下の数値は、文字列表現に指数表記 (`"1.5e+22"`, `"1.51e-8"`) を使用するため、 `parseInt()` は常に最初の桁の後に来る `e` の文字または小数点で停止します。つまり、大きな数でも小さな数でも、 `parseInt()` は 1 桁の整数を返すということです。

```js
parseInt(4.7 \* 1e22, 10); // 巨大な数値が 4 になる
parseInt(0.00000000000434, 10); // 御苦笑の数値が 4 になる

parseInt(0.0000001, 10); // 1
parseInt(0.000000123, 10); // 1
parseInt(1e-7, 10); // 1
parseInt(1000000000000000000000, 10); // 1
parseInt(123000000000000000000000, 10); // 1
parseInt(1e21, 10); // 1
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-parseint-string-radix |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `parseFloat()`
* `Number()`
* `Number.parseFloat()`
* `Number.parseInt()`
* `isNaN()`
* `Number.prototype.toString()`
* `Object.prototype.valueOf()`
* `BigInt()`


AsyncFunction - JavaScript

AsyncFunction
=============

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2017.

* Learn more
* See full compatibility
* Report feedback
**`AsyncFunction`** オブジェクトは、非同期関数のメソッドを提供します。JavaScript では、すべての非同期関数が実際に `AsyncFunction` オブジェクトです。

`AsyncFunction` はグローバルオブジェクトでは*ない*ことに注意してください。これは以下のようなコードで取得することができます。

```js
const AsyncFunction = async function () {}.constructor;
```

`AsyncFunction` は `Function` のサブクラスです。

コンストラクター
--------

`AsyncFunction()`

新しい `AsyncFunction` オブジェクトを生成します。

インスタンスプロパティ
-----------

*インスタンスプロパティを親である `Function` から継承しています*。

これらのプロパティは `AsyncFunction.prototype` で定義されており、すべての `AsyncFunction` のインスタンスで共有されます。

`AsyncFunction.prototype.constructor`

インスタンスオブジェクトを作成したコンストラクター関数。`AsyncFunction` インスタンスの場合、初期値は `AsyncFunction` コンストラクターです。

`AsyncFunction.prototype[@@toStringTag]`

`@@toStringTag` プロパティの初期値は、文字列 `"AsyncFunction"` です。このプロパティは `Object.prototype.toString()` で使用されます。

**メモ:** `AsyncFunction` のインスタンスには `prototype` プロパティがありません。

インスタンスメソッド
----------

*インスタンスメソッドを親である `Function` から継承しています*。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-async-function-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `async function` 宣言
* `async function` 式
* `Function`
* `AsyncGeneratorFunction`
* `GeneratorFunction`
* 関数


URIError - JavaScript

URIError
========

**`URIError`** オブジェクトは、グローバル URI 処理関数が間違った方法で使用された場合のエラーを表します。

コンストラクター
--------

`URIError()`

新しい `URIError` オブジェクトを生成します。

インスタンスプロパティ
-----------

`URIError.prototype.message`

エラーメッセージです。 ECMA-262 において `URIError` は自身の `message` プロパティを提供するべきとされていますが、 SpiderMonkey では `Error.prototype.message` を継承しています。

`URIError.prototype.name`

エラー名です。 `Error` から継承しています。

`URIError.prototype.fileName`

このエラーが発生したファイルのパスです。 `Error` から継承しています。

`URIError.prototype.lineNumber`

このエラーが発生したファイル内の行番号です。 `Error` から継承しています。

`URIError.prototype.columnNumber`

このエラーが発生した行内の桁番号です。 `Error` から継承しています。

`URIError.prototype.stack`

スタックトレースです。 `Error` から継承しています。

例
-

### URIError のキャッチ

```js
try {
  decodeURIComponent("%");
} catch (e) {
  console.log(e instanceof URIError); // true
  console.log(e.message); // "malformed URI sequence"
  console.log(e.name); // "URIError"
  console.log(e.fileName); // "Scratchpad/1"
  console.log(e.lineNumber); // 2
  console.log(e.columnNumber); // 2
  console.log(e.stack); // "@Scratchpad/2:2:3\n"
}
```

### URIError の生成

```js
try {
  throw new URIError("Hello", "someFile.js", 10);
} catch (e) {
  console.log(e instanceof URIError); // true
  console.log(e.message); // "Hello"
  console.log(e.name); // "URIError"
  console.log(e.fileName); // "someFile.js"
  console.log(e.lineNumber); // 10
  console.log(e.columnNumber); // 0
  console.log(e.stack); // "@Scratchpad/2:2:9\n"
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-native-error-types-used-in-this-standard-urierror |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Error`
* `decodeURI()`
* `decodeURIComponent()`
* `encodeURI()`
* `encodeURIComponent()`


Uint8Array - JavaScript

Uint8Array
==========

**`Uint8Array`** は型付き配列で、 8 ビット符号なし整数値の配列を表します。中身は `0` で初期化されます。生成されると、配列内の要素はそのオブジェクトのメソッドを使用するか、配列の標準的な添字の構文 (すなわち、ブラケット記法) を使用するかして参照することができます。

コンストラクター
--------

`Uint8Array()`

新しい `Uint8Array` オブジェクトを生成します。

静的プロパティ
-------

`Uint8Array.BYTES_PER_ELEMENT`

要素の大きさを数値で返します。`Uint8Array` の場合は `1` です。

`Uint8Array.name`

コンストラクター名を文字列値で返します。`Uint8Array` の場合、 "`Uint8Array`" です。

静的メソッド
------

`Uint8Array.from()`

配列風オブジェクトまたは反復可能オブジェクトから新しい `Uint8Array` オブジェクトを生成します。 `Array.from()` も参照してください。

`Uint8Array.of()`

可変長引数で新しい `Uint8Array` オブジェクトを生成します。`Array.of()` も参照してください。

インスタンスプロパティ
-----------

`Uint8Array.prototype.buffer`

`Uint8Array` オブジェクトによって参照される `ArrayBuffer` を返します。構築時に固定され、**読み取り専用**です。

`Uint8Array.prototype.byteLength`

`Uint8Array` の長さを (バイト単位で) 返します。構築時に固定され、**読み取り専用**です。

`Uint8Array.prototype.byteOffset`

`ArrayBuffer` の先頭からの `Uint8Array` のオフセットを (バイト単位で) 返します。構築時に固定され、**読み取り専用**です。

`Uint8Array.prototype.length`

`Uint8Array` オブジェクト内に保持されている要素の数を返します。構築時に固定され、**読み取り専用**です。

インスタンスメソッド
----------

`Uint8Array.prototype.copyWithin()`

配列内で一連の配列要素をコピーします。`Array.prototype.copyWithin()` も参照してください。

`Uint8Array.prototype.entries()`

配列内ですべての位置におけるキーと値の組を提供する新しい*配列イテレーター*を返します。`Array.prototype.entries()` も参照してください。

`Uint8Array.prototype.every()`

配列内のすべての要素が関数によって提供されたテストに合格するかどうかテストを実行します。`Array.prototype.every()` も参照してください。

`Uint8Array.prototype.fill()`

配列の先頭位置から末尾位置までのすべての要素を固定値に設定します。`Array.prototype.fill()` も参照してください。

`Uint8Array.prototype.filter()`

この配列のすべての要素のうち、与えられたフィルタリング関数が `true` を返すものをもつ新しい配列を生成します。`Array.prototype.filter()` も参照してください。

`Uint8Array.prototype.find()`

配列内の要素に与えられたテスト関数を満足するものがあったら、見つかった値を返します。見つからなければ `undefined` を返します。`Array.prototype.find()` も参照してください。

`Uint8Array.prototype.findIndex()`

配列内の要素に与えられたテスト関数を満足するものがあったら、見つかった位置を返します。見つからなければ `-1` を返します。`Array.prototype.findIndex()` も参照してください。

`Uint8Array.prototype.forEach()`

配列内のそれぞれの要素について関数を呼び出します。`Array.prototype.forEach()` も参照してください。

`Uint8Array.prototype.includes()`

型付き配列に特定の要素があるかどうかを判断し、それに応じて `true` か `false`を返します。 `Array.prototype.includes()` も参照してください。

`Uint8Array.prototype.indexOf()`

指定された値に等しい配列内の要素の最初の (最小の) 位置を返します。見つからなかった場合、 `-1` を返します。`Array.prototype.indexOf()` も参照してください。

`Uint8Array.prototype.join()`

配列のすべての要素を 1 つの文字列に結合します。`Array.prototype.join()` も参照してください。

`Uint8Array.prototype.keys()`

配列内ですべての位置におけるキーを提供する新しい*配列イテレーター*を返します。`Array.prototype.keys()` も参照してください。

`Uint8Array.prototype.lastIndexOf()`

指定された値に等しい配列内の要素の最後の (最大の) 位置を返します。見つからなかった場合、 `-1` を返します。`Array.prototype.lastIndexOf()` も参照してください。

`Uint8Array.prototype.map()`

この配列のすべての要素で与えられた関数を呼び出した結果をもつ新しい配列を生成します。`Array.prototype.map()` も参照してください。

`Uint8Array.prototype.reduce()`

アキュムレーターとこの配列のそれぞれの値に対して (左から右へ) 関数を適用し、単一の値に還元します。`Array.prototype.reduce()` も参照してください。

`Uint8Array.prototype.reduceRight()`

アキュムレーターとこの配列のそれぞれの値に対して (右から左へ) 関数を適用し、単一の値に還元します。`Array.prototype.reduceRight()` も参照してください。

`Uint8Array.prototype.reverse()`

配列の要素の順番を反転させます。最初の要素は最後になり、最後の要素は最初になります。`Array.prototype.reverse()` も参照してください。

`Uint8Array.prototype.set()`

入力値を指定した配列から読み込み、この型付き配列内に複数の値を格納します。

`Uint8Array.prototype.slice()`

配列の一部を取り出して新しい配列を返します。`Array.prototype.slice()` も参照してください。

`Uint8Array.prototype.some()`

この配列の 1 つ以上の要素が与えられたテスト関数を満たした場合に `true` を返します。`Array.prototype.some()` も参照してください。

`Uint8Array.prototype.sort()`

配列の要素をその場で並べ替え、その配列を返します。`Array.prototype.sort()` も参照してください。

`Uint8Array.prototype.subarray()`

指定された先頭と末尾の要素位置から新しい `Uint8Array` を返します。

`Uint8Array.prototype.values()`

配列内ですべての位置における値を提供する新しい*配列イテレーター*を返します。`Array.prototype.values()` も参照してください。

`Uint8Array.prototype.toLocaleString()`

配列とその要素を表すローカライズされた文字列を返します。`Array.prototype.toLocaleString()` も参照してください。

`Uint8Array.prototype.toString()`

配列とその要素を表す文字列を返します。`Array.prototype.toString()` も参照してください。

`Uint8Array.prototype[@@iterator]()`

配列内ですべての位置における値を提供する新しい*配列イテレーター*を返します。

例
-

### 様々な方法で `Uint8Array` を作成

```js
// 長さから
var uint8 = new Uint8Array(2);
uint8[0] = 42;
console.log(uint8[0]); // 42
console.log(uint8.length); // 2
console.log(uint8.BYTES\_PER\_ELEMENT); // 1

// 配列から
var arr = new Uint8Array([21, 31]);
console.log(arr[1]); // 31

// From another TypedArray
var x = new Uint8Array([21, 31]);
var y = new Uint8Array(x);
console.log(y[0]); // 21

// ArrayBuffer から
var buffer = new ArrayBuffer(8);
var z = new Uint8Array(buffer, 1, 4);

// 反復可能オブジェクトから
var iterable = (function\* () {
  yield\* [1, 2, 3];
})();
var uint8 = new Uint8Array(iterable);
// Uint8Array[1, 2, 3]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # table-49 |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Uint8Array` のポリフィルが `core-js` で利用できます
* JavaScript の型付き配列
* `ArrayBuffer`
* `DataView`


Map - JavaScript

Map
===

**`Map`** オブジェクトはキーと値のペアを保持し、キーが最初に挿入された順序を覚えています。キーや値には任意の値（オブジェクトとプリミティブ値）を使用することができます。

試してみましょう
--------

解説
--

`Map` オブジェクトは、キーと値のペアのコレクションです。`Map` のキーは**一度しか出現しません**。`Map` の集合の中で一意です。`Map` オブジェクトはキーと値のペアで反復処理されます。`for...of` ループは、各反復処理に対して `[キー, 値]` という 2 つのメンバーからなる配列を返します。反復処理は *挿入順* で行われます。これは、それぞれのキーと値のペアが `set()` メソッドによって最初にマップに挿入された順番に対応します（つまり、 `set()` が呼ばれたときには、すでに同じ値を持つキーがマップになかったということです）。

仕様書では、「平均して、集合の要素数に対してサブリニアなアクセス時刻を提供する」マップを実装することを要求しています。したがって、複雑度が O(N) よりも高い場合、内部的にはハッシュ表（O(1) ルックアップ）、探索木（O(log(N)) ルックアップ）、あるいは他のデータ構造として表すことが可能です。

### キーの等価性

キー値の等価性は SameValueZero アルゴリズムに基づいて評価されます。（以前は SameValue が使われており、 `0` と `-0` が異なるものとして扱われていました。ブラウザーの互換性をチェックしてください）。これは `NaN` を `NaN` と等価と見なすもので（`NaN !== NaN` ですが）、他の値はすべて `===` 演算子の意味に従って等価性が考慮されます。

### Object と Map の比較

`Object` と `Map` は似ています。どちらもキーを値に設定したり、それらの値を受け取ったり、キーを削除したり、キーに何かが格納されているかどうかを判定したりすることができます。この意味で（そして他の組み込みオブジェクトがなかったため）、従来 `Object` は `Map` として使われてきました。

しかし、いくつかの場面で `Map` の方が勝るような重要な違いがあります。

|  | Map | Object |
| --- | --- | --- |
| 偶発的なキー | `Map` は既定では何もキーを持っていません。明示的に設定したものだけを含みます。 | `Object` にはプロトタイプがあります。よって既定のキーを含んでいるので、注意しないと自分のキーと衝突する可能性があります。

**メモ:** ES5 では、
 `Object.create(null)`
 を使用すると回避できますが、これはめったに行われていません。

 |
| セキュリティ | `Map` はユーザーが提供したキーと値を使用しても安全です。 |
 ユーザーが提供したキーと値のペアを `Object` に設定すると、攻撃者がオブジェクトのプロトタイプを上書きできる可能性があり、
 オブジェクトインジェクション攻撃につながる可能性があります。偶発的なキーの問題と同様に、これも`null`-prototypeオブジェクトを使用することによって軽減することができます。
  |
| キーの型 | `Map` のキーはあらゆる値がなることができます
 （関数、オブジェクト、あらゆるプリミティブなど）。
  | `Object` のキーは文字列またはシンボルでなければなりません。 |
| キーの順序 | `Map` のキーは、単純で直感的な方法で順序付けられます。すなわち、反復処理を行うと、 `Map` オブジェクトは挿入順でキーを返します。 | 通常の `Object` のキーは現在では順序付けされていますが、以前はそうではなかったので、順序は複雑です。結果として、プロパティの順序に頼らない方が良いでしょう。

 この順序は ECMAScript 2015 で初めて自身のプロパティに対してのみ定義されましたが、 ECMAScript 2020 では継承されたプロパティに対しても同様に順序が定義されています。
 OrdinaryOwnPropertyKeys
 と
 EnumerateObjectProperties
 の抽象指定操作を参照してください。しかし、オブジェクトのプロパティが**すべて**反復処理される単一の単一のメカニズムはないことに注意してください。
 （`for-in` は列挙可能な文字列キーのプロパティのみを含む、 `Object.keys` は自分自身の列挙可能な文字列キーのプロパティのみを含む、 `Object.getOwnPropertyNames` は列挙不可能な場合でも自分自身の文字列キーのプロパティを含む、 `Object.getOwnPropertySymbols` は、
 `Symbol` キーを持つプロパティに対しても同じことを行う、など。）
  |
| 大きさ | `Map` の中のアイテム数は、 `size` プロパティで簡単に得ることができます。 | `Object` 内のアイテムの数を決定することは、より回りくどく、効率的ではありません。一般的な方法は、 `Object.keys()` から返される配列の `length` を通じて行う方法です。 |
| 反復処理 | `Map` は 反復可能 ですので、直接反復処理を行うことができます。 | `Object`
 では反復処理を行うのに、いくつかの形でキーの一覧を取得して、そのうえで反復処理を行う必要があります。
 `Object` は 反復処理プロトコルを実装していないので、オブジェクトを JavaScript の for...of 文を使用して直接反復処理を行うことは（既定では）できません。

**メモ:**
* オブジェクトに反復処理プロトコルを実装したり、 `Object.keys` または `Object.entries` を使用して反復処理を行うことはできます。
* for...in 文により、オブジェクトの*列挙可能な*プロパティを反復処理することができます。

 |
| 性能 | キーと値のペアを頻繁に追加したり削除したりすることが求められる場面では、性能がより良くなります。 | キーと値のペアを頻繁に追加したり削除したりすることに最適化されていません。 |
| シリアライズと解釈 | シリアライズや解釈のためのネイティブな対応はありません。
（ただし、 *replacer* 引数で `JSON.stringify()` を使用し、 *reviver* 引数で `JSON.parse()` を使用することで、 `Map` のために、独自のシリアライズと解釈の対応を作成することができます。 Stack Overflow の質問 How do you JSON.stringify an ES6 Map? を参照してください。） | `Object` から JSON へのシリアライズには、 `JSON.stringify()` を使用してネイティブに対応しています。
JSON から `Object` への解釈には、 `JSON.parse()` を使用してネイティブに対応しています。 |

### オブジェクトプロパティの設定

Map オブジェクトに対してオブジェクトプロパティを設定すると正しく動作しますが、混乱を催すことが考えられます。

たとえば、次の例は一応動作するように見えます。

```js
const wrongMap = new Map();
wrongMap["bla"] = "blaa";
wrongMap["bla2"] = "blaaa2";

console.log(wrongMap); // Map { bla: 'blaa', bla2: 'blaaa2' }
```

しかし、このようにプロパティを設定すると、 Map データ構造を使用しません。一般的なオブジェクトの機能を使用します。 'bla' の値はクエリーを行うための Map に格納されません。データにその他の操作を行うと失敗します。

```js
wrongMap.has("bla"); // false
wrongMap.delete("bla"); // false
console.log(wrongMap); // Map { bla: 'blaa', bla2: 'blaaa2' }
```

Map にデータを格納する正しい方法は、 `set(key, value)` メソッドを使用する方法です。

```js
const contacts = new Map();
contacts.set("Jessie", { phone: "213-555-1234", address: "123 N 1st Ave" });
contacts.has("Jessie"); // true
contacts.get("Hilary"); // undefined
contacts.set("Hilary", { phone: "617-555-4321", address: "321 S 2nd St" });
contacts.get("Jessie"); // {phone: "213-555-1234", address: "123 N 1st Ave"}
contacts.delete("Raymond"); // false
contacts.delete("Jessie"); // true
console.log(contacts.size); // 1
```

Map 風のブラウザー API
---------------

**ブラウザーの `Map` 風オブジェクト** (または「Map 風オブジェクト」) は、多くの点で `Map` のようにふるまう Web API のインターフェイスです。

`Map` と同様に、エントリーはオブジェクトに追加されたのと同じ順番で走査できます。
 また、`Map` 風オブジェクトと `Map` は同じ名前で同じ挙動のプロパティおよびメソッドを持ちます。
 しかし、`Map` と違い、各エントリーのキーと値には事前に定義された特定の型しか使用できません。

 使用可能な型は、仕様書の IDL 定義で設定されています。
 たとえば、`RTCStatsReport` (en-US) はキーには文字列を、値にはオブジェクトを用いなければならない `Map` 風オブジェクトです。
 これは、仕様書の IDL で以下のように定義されています。

```webidl
interface RTCStatsReport {
  readonly maplike<DOMString, object>;
};
```

`Map` 風オブジェクトは読み取り専用のことも、読み書き可能なこともあります。(上の IDL の `readonly` キーワードに注目してください)

* 読み取り専用の `Map` 風オブジェクトは、プロパティ `size` と、メソッド `entries()`、`forEach()`、`get()`、`has()`、`keys()`、`values()`、`@@iterator` を持ちます。
* 書き込み可能な `Map` 風オブジェクトは、これに加えてメソッド `clear()`、`delete()`、`set()` を持ちます。

これらのメソッドとプロパティは、キーと値の型の制約を除いて、`Map` の対応するエンティティと同様にふるまいます。

以下は、読み取り専用の `Map` 風ブラウザーオブジェクトの例です。

* `AudioParamMap`
* `RTCStatsReport` (en-US)
* `EventCounts` (en-US)
* `KeyboardLayoutMap`
* `MIDIInputMap`
* `MIDIOutputMap`
コンストラクター
--------

`Map()`

新しい `Map` オブジェクトを生成します。

静的プロパティ
-------

`get Map[@@species]`

派生クラスを生成するためのコンストラクター関数です。

インスタンスプロパティ
-----------

`Map.prototype[@@toStringTag]`

`@@toStringTag` プロパティの初期値は文字列 `"Map"` です。このプロパティは `Object.prototype.toString()` で使用されます。

`Map.prototype.size`

`Map` オブジェクトの中のキーと値のペアの数を返します。

インスタンスメソッド
----------

`Map.prototype.clear()`

`Map` オブジェクトからすべてのキーと値のペアを削除します。

`Map.prototype.delete()`

`Map` オブジェクトに要素が存在し、削除された場合は `true` を返します。要素が存在しなければ `false` を返します。その後では `Map.prototype.has(key)` が `false` を返すようになります。

`Map.prototype.get()`

`key` で指定されたキーに結び付けられた値を返します。存在しない場合は `undefined` を返します。

`Map.prototype.has()`

論理値で、渡されたキーに結び付けられた要素が `Map` オブジェクト内に存在するかどうかを返します。

`Map.prototype.set()`

`Map` オブジェクト内の `key` で指定されたキーの値を `value` に設定します。その `Map` オブジェクトを返します。

`Map.prototype[@@iterator]()`

`Map` オブジェクト内の各要素の `[key, value] の配列` が挿入順で含む、新しいイテレーターオブジェクトを返します。

`Map.prototype.keys()`

`Map` オブジェクト内の各要素のキーが挿入順で含む、新しいイテレーターオブジェクトを返します。

`Map.prototype.values()`

`Map` オブジェクト内の各要素の値が挿入順で含む、新しいイテレーターオブジェクトを返します。

`Map.prototype.entries()`

`Map` オブジェクト内の要素に対して挿入順にすべての要素の `[key, value]` の配列を含む、新しいイテレーターオブジェクトを返します。

`Map.prototype.forEach()`

`callbackFn` を、 `Map` オブジェクトに存在するそれぞれのキーと値のペアに対して 1 回ずつ、挿入順に呼び出します。 `thisArg` 引数が `forEach` に与えられた場合は、それぞれのコールバックでこれを `this` の値として使用します。

例
-

### Map オブジェクトの使用

```js
const myMap = new Map();

const keyString = '文字列'
const keyObj = {};
const keyFunc  function() {};

// 値を設定する
myMap.set(keyString, "'文字列' と結び付けられた値");
myMap.set(keyObj, 'keyObj と結び付けられた値');
myMap.set(keyFunc, 'keyFunc と結び付けられた値');

console.log(myMap.size); // 3

// 値を取得する
console.log(myMap.get(keyString)); // "'文字列' と結び付けられた値"
console.log(myMap.get(keyObj)); // "keyObj と結び付けられた値"
console.log(myMap.get(keyFunc)); // "keyFunc と結び付けられた値"

console.log(myMap.get('文字列')); // "'文字列' と結び付けられた値"。 keyString === '文字列' であるため
console.log(myMap.get({})); // undefined, keyObj !== {} であるため
console.log(myMap.get(function() {})); // undefined, keyFunc !== function () {} であるため
```

### NaN を Map のキーとして使用

`NaN` もまたキーとして使うことができます。すべての `NaN` は自身と等しくない（`NaN !== NaN` は真）にもかかわらず、以下の例は動作します。これは `NaN` が互いに区別できないためです。

```js
const myMap = new Map();
myMap.set(NaN, "not a number");

myMap.get(NaN);
// "not a number"

const otherNaN = Number("foo");
myMap.get(otherNaN);
// "not a number"
```

### for..of を使用した Map の反復処理

マップは `for..of` ループを使用して反復処理を行うことができます。

```js
const myMap = new Map();
myMap.set(0, "zero");
myMap.set(1, "one");

for (const [key, value] of myMap) {
  console.log(`${key} = ${value}`);
}
// 0 = zero
// 1 = one

for (const key of myMap.keys()) {
  console.log(key);
}
// 0
// 1

for (const value of myMap.values()) {
  console.log(value);
}
// zero
// one

for (const [key, value] of myMap.entries()) {
  console.log(`${key} = ${value}`);
}
// 0 = zero
// 1 = one
```

### forEach() で Map を反復処理

マップは `forEach()` メソッドを使用して反復できます。

```js
myMap.forEach((value, key) => {
  console.log(`${key} = ${value}`);
});
// 0 = zero
// 1 = one
```

### Array オブジェクトとの関係

```js
const kvArray = [
  ["キー1", "値1"],
  ["キー2", "値2"],
];

// 通常の Map コンストラクターを使って、キーと値の 2 次元配列をマップに変換する
const myMap = new Map(kvArray);

console.log(myMap.get("キー1")); // "値1" を返す

// 展開演算子を使って、マップをキー・値の 2 次元配列に変換する
console.log(Array.from(myMap)); // kvArray とまったく同じ Array を表示する

// あるいは展開演算子をキーまたは値のイテレーターに使って、キーまたは値のみの配列を得る
console.log([...myMap]);

// または keys() や values() のイテレーターを使用して配列に変換する
console.log(Array.from(myMap.keys())); // ["key1", "key2"] が出力される
```

### Map の複製と混合

`Array` と同様に、 `Map` は複製することができます。

```js
const original = new Map([[1, "one"]]);

const clone = new Map(original);

console.log(clone.get(1)); // one
console.log(original === clone); // false (useful for shallow comparison)
```

**メモ:** *データ自身*は複製されないことに注意しておいてください。

マップはキーの固有性を保持しながら混合可能です。

```js
const first = new Map([
  [1, "one"],
  [2, "two"],
  [3, "three"],
]);

const second = new Map([
  [1, "uno"],
  [2, "dos"],
]);

// 2 つのマップを混合します。重複するキーは後勝ちになります。
// スプレッド演算子は基本的に Map を Array に変換します。
const merged = new Map([...first, ...second]);

console.log(merged.get(1)); // uno
console.log(merged.get(2)); // dos
console.log(merged.get(3)); // three
```

Map は Array と混合することもできます。

```js
const first = new Map([
  [1, "one"],
  [2, "two"],
  [3, "three"],
]);

const second = new Map([
  [1, "uno"],
  [2, "dos"],
]);

// マップと配列を混合します。重複するキーは後勝ちになります。
const merged = new Map([...first, ...second, [1, "eins"]]);

console.log(merged.get(1)); // eins
console.log(merged.get(2)); // dos
console.log(merged.get(3)); // three
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Map` のポリフィルは `core-js` で利用できます
* `Set`
* `WeakMap`
* `WeakSet`


eval() - JavaScript

eval()
======

**警告:** 文字列から JavaScript を実行することは、非常に大きなセキュリティリスクを伴います。`eval()` を使用すると、悪意のある者が任意のコードを実行することがあまりにも簡単になります。下記の eval() を使わないでください!を参照してください。

**`eval()`** 関数は、文字列として表現された JavaScript コードを評価します。ソースはスクリプトとして解釈されます。

試してみましょう
--------

構文
--

```js
eval(script)
```

### 引数

`script`

JavaScript の式、文、または一連の文を表す文字列です。式には、既存オブジェクトの変数およびプロパティを含められます。これはスクリプトとして解釈されますので、 `import` 宣言（モジュールの中に存在しうる）は許可されていません。

### 返値

与えられたコードの評価結果の値を返します。評価結果が空の場合は、`undefined` を返します。もし `script` が文字列プリミティブでなければ、 `eval()` は引数を変更せずに返します。

### 例外

コードを評価している間に発生するあらゆる例外が発生します。もし `script` がスクリプトとして解釈できなかった場合は `SyntaxError` になります。

解説
--

`eval()` はグローバルオブジェクトの関数プロパティです。

`eval()` 関数の引数は文字列です。
 ソース文字列をスクリプト本体として評価します。つまり、文と式の両方が使用可能です。コードの完了値を返します。式の場合は、式が評価された値です。多くの文や宣言も同様に完了値を持ちますが、その結果は意外なものになることがあります（例えば、代入の完了値は代入された値ですが、 `let` の完了値は undefined です）。そのため、文の完了値には頼らないことをお勧めします。

厳格モードでは、 `eval` という名前の変数を宣言したり、 `eval` に代入したりすることは `SyntaxError` になります。

```js
"use strict";

const eval = 1; // SyntaxError: Unexpected eval or arguments in strict mode
```

`eval()` の引数が文字列でない場合、`eval()` は引数を変更せずに返します。次の例では、プリミティブの代わりに `String` オブジェクトを渡すと、 `eval()` は文字列を評価するのではなく、 `String` オブジェクトを返します。

```js
eval(new String("2 + 2")); // "2 + 2" を含む String オブジェクトを返す
eval("2 + 2"); // 4 を返す
```

一般的な方法でこの課題をうまく回避するには、`eval()` に渡す前に、自分で引数を文字列に変換することができます。

```js
const expression = new String("2 + 2");
eval(String(expression)); // 4 を返します
```

### 直接的または間接的な eval

`eval()` の呼び出しには、直接的な eval と間接的な eval の 2 つのモードがあります。直接的な eval は `eval( )` が唯一の形です（呼び出す関数の名前は `eval` で、その値はグローバルな `eval` 関数です）。それ以外のすべて は、エイリアス変数経由、メンバーアクセスやその他の式経由、またはオプショナルチェーン `?.` 演算子を使用して呼び出すことも含めて、間接的なものです。

```js
// eval を返すためにカンマ演算子を使用する間接的呼び出し
(0, eval)("x + y");

// オプショナルチェーンによる間接的呼び出し
eval?.("x + y");

// eval を格納し返すために変数を使用する間接的呼び出し
const geval = eval;
geval("x + y");

// メンバーアクセスによる間接的呼び出し
const obj = { eval };
obj.eval("x + y");
```

間接的な eval は、コードが別個の `<script>` タグの中で評価されるように見ることができます。これはつまり次のような意味です。

* 間接的な eval はローカルスコープではなくグローバルスコープで動作し、評価されるコードは呼び出されるスコープ内のローカル変数にアクセスすることはありません。

```js
function test() {
  const x = 2;
  const y = 4;
  // 直接呼び出し、ローカルスコープを使用
  console.log(eval("x + y")); // 結果は 6
  // eval を返すカンマ演算子を使用した間接呼び出し
  console.log(eval?.("x + y")); // グローバルスコープを使用、x は未定義のため例外が発生
}
```

* 間接的な `eval` は周囲のコンテキストの厳格さを継承せず、ソース文字列自体に `"use strict"` ディレクティブがある場合にのみ 厳格モード になります。

```js
function strictContext() {
  "use strict";
  eval?.(`with (Math) console.log(PI);`);
}
function strictContextStrictEval() {
  "use strict";
  eval?.(`"use strict"; with (Math) console.log(PI);`);
}
strictContext(); // Logs 3.141592653589793
strictContextStrictEval(); // 文字列が厳格モードであるため SyntaxError を発生します。
```

一方、直接的な eval は、呼び出すコンテキストの厳格さを継承します。

```js
function nonStrictContext() {
  eval(`with (Math) console.log(PI);`);
}
function strictContext() {
  "use strict";
  eval(`with (Math) console.log(PI);`);
}
nonStrictContext(); // Logs 3.141592653589793
strictContext(); // 厳格モードなので SyntaxError が発生します。
```

* もしソース文字列が厳格モードで解釈されていない場合、 `var` で宣言された変数と 関数宣言 は周囲のスコープに入ってしまいます。厳格モードのコンテキストでの直接的な eval であった場合、または `eval` のソース文字列自体が厳格モードであった場合、 `var` と関数宣言は周囲のスコープに「漏れる」ことはありません。

```js
// コンテキストもソース文字列も厳格モードではないため、 var は周囲のスコープで変数を作成します。
eval("var a = 1;");
console.log(a); // 1
// コンテキストは厳格ではありませんが、 eval のソースは厳格なので、 b は評価されたスクリプトにスコープされます。
eval("'use strict'; var b = 1;");
console.log(b); // ReferenceError: b is not defined

function strictContext() {
  "use strict";
  // コンテキストは厳格ですが、これは間接的なもので、文字列は厳格ではありません。
  eval?.("var c = 1;");
  // 厳密なコンテキストでのディレクティブ eval なので、 d はスコープされます。
  eval("var d = 1;");
}
strictContext();
console.log(c); // 1
console.log(d); // ReferenceError: d is not defined
```

評価される文字列内の `let` および `const` 宣言は、常にそのスクリプトにスコープされます。
* ディレクティブ eval は追加のコンテキスト式にアクセスすることができます。例えば、関数の本体で `new.target` を使用することができます。

```js
function Ctor() {
  eval("console.log(new.target)");
}
new Ctor(); // [Function: Ctor]
```

eval() を使わないでください!
------------------

直接的な `eval()` はいくつもの問題を引き起こします。

* `eval()` は呼び出し元の権限で渡されたコードを実行します。悪意のある第三者に影響を受ける可能性のある文字列で `eval()` を実行すると、そのウェブページや拡張機能の権限において、ユーザーのマシン上で悪意のあるコードを実行してしまう可能性があります。さらに重要なことに、サードパーティのコードが `eval()` が（直接的な eval であれば）呼び出されたスコープを見ることができるため、攻撃者がローカル変数を読み取ったり変更したりすることができてしまいます。
* 現代の JavaScript では多くの構造が JS エンジンによって最適化されているため、`eval()` は他の方法よりも低速です。
* 現代の JavaScript インタープリターは JavaScript を機械語に変換します。これは、変数の名前の概念がすべて消滅することを意味します。したがって、`eval()` を使用すると、ブラウザーは長い高価な変数名検索を実行して、変数が機械語のどこに存在しているかを把握し、その値を設定します。さらに、`eval()` が変数の型の変更など、その変数に新しい変数をもたらす可能性もあり、生成されたすべての機械語を再評価して補正させられる可能性があります。
* スコープが `eval()` によって推移的に依存されている場合、ミニファイヤーはミニ化をあきらめます。そうしないと `eval()` は実行時に正しい変数を読み込むことができないからです。

`eval()` や関連のメソッドを使用することで、最適化したり、完全に避けることができる用途はたくさんあります。

#### 間接的 eval() の使用

このコードを考えてみてください。

```js
function looseJsonParse(obj) {
  return eval(`(${obj})`);
}
console.log(looseJsonParse("{ a: 4 - 1, b: function () {}, c: new Date() }"));
```

間接的 eval を使用して厳格モードを強制するだけで、コードはずっと良くなります。

```js
function looseJsonParse(obj) {
  return eval?.(`"use strict";(${obj})`);
}
console.log(looseJsonParse("{ a: 4 - 1, b: function () {}, c: new Date() }"));
```

上記の 2 つのコードスニペットは同じように動作するように見えるかもしれませんが、そうではありません。前者は直接的 eval を使用しているので、複数の問題が発生します。

* より多くの範囲を検査するため、非常に時間がかかります。評価される文字列中の `c: new Date()` に注目してください。間接的 eval のバージョンでは、オブジェクトはグローバルスコープで評価されるので、インタープリターは `Date` が `Date` という名前のローカル変数ではなく、グローバルな `Date()` コンストラクターを参照しているとみなされます。しかし、直接的 eval を使用するコードでは、インタープリターはこれを想定することができません。例えば、次の例では、評価された文字列の `Date` は `window.Date()` を参照しません。

```js
function looseJsonParse(obj) {
  function Date() {}
  return eval(`(${obj})`);
}
console.log(looseJsonParse(`{ a: 4 - 1, b: function () {}, c: new Date() }`));
```

したがって、この `eval()` バージョンでは、ブラウザーは高価なルックアップ呼び出しを行い、`Date()` というローカル変数があるかどうかを確認します。
* 厳格モードを使用していない場合、 `eval()` ソース内の `var` 宣言は周囲のスコープの変数になります。これは、文字列が外部入力から取得された場合、特に同じ名前の既存の変数がある場合に、デバッグしにくい課題につながります。
* 直接的 eval は、周囲のスコープのバインディングを読み込んだり、変更したりすることができます。
* 直接的 `eval` を使用する場合、特に eval ソースが厳格モードであることを証明できない場合、 `eval()` ソースはその周囲のスコープ内の任意の変数名に依存することができるため、エンジン（およびビルドツール）はインライン化に関連するすべての最適化を無効にしなければなりません。

しかし、間接的な `eval()` を使用すると、評価されたソースが読み込む既存のグローバル変数以外の追加のバインディングを渡すことができません。評価されるソースがアクセスすべき追加の変数を指定する必要がある場合は、コンストラクター `Function()` を使用することを検討してください。

#### Function() コンストラクターの使用

`Function()` コンストラクターは、上記の間接的 eval の例ととてもよく似ています。グローバルスコープで渡された JavaScript ソースを、ローカルバインディングを読み込んだり変更したりすることなく評価するので、エンジンは直接 `eval()` を実行するよりも多くの最適化を実行することができます。

`eval()` と `Function()`の異なる点は、`Function()`に渡された文字列はスクリプトとしてではなく、関数本体として解釈できるということです。例えば、関数本体の最上位では `return` 文を使用することができますが、スクリプトの中では使用できません。

`Function()` コンストラクターは、変数を引数として渡して eval ソース内でローカルバインディングを作成したい場合に有益です。

```js
function Date(n) {
  return [
    "Monday",
    "Tuesday",
    "Wednesday",
    "Thursday",
    "Friday",
    "Saturday",
    "Sunday",
  ][n % 7 || 0];
}
function runCodeWithDateFunction(obj) {
  return Function("Date", `"use strict";return (${obj});`)(Date);
}
console.log(runCodeWithDateFunction("Date(5)")); // Saturday
```

`eval()` と `Function()` はどちらも暗黙的に任意のコードを評価するので、厳格な CSP 設定では禁止されています。また、一般的な用途では `eval()` や `Function()` に代わる、より安全な（そして、より高速な）方法が他にもあります。

#### ブラケットアクセサーの使用

プロパティ名からプロパティ自体への変換を行うために `eval()` を使用しないでください。アクセスされるオブジェクトのプロパティがコードが実行されるまでわからない場合の例を考えてみましょう。これは `eval()` で行うことができます。

```js
const obj = { a: 20, b: 30 };
const propName = getPropName(); // returns "a" or "b"

const result = eval(`obj.${propName}`);
```

ただし、ここで `eval()` は必要ありません。実際、この使い方はお勧めできません。なぜなら `propName` が有効な識別子でないと構文エラーになるからです。さらに、 `getPropName` が制御する関数でない場合、任意のコードを実行してしまう可能性があります。代わりにプロパティアクセサーを使用したほうが、より速くて安全です。

```js
const obj = { a: 20, b: 30 };
const propName = getPropName(); // "a" または "b" が返される
const result = obj[propName]; // obj[ "a" ] は obj.a と同じ
```

このメソッドを使用して子孫プロパティにアクセスすることもできます。`eval()` を使うと以下のようになります。

```js
const obj = { a: { b: { c: 0 } } };
const propPath = getPropPath(); // "a.b.c" などを返す

const result = eval(`obj.${propPath}`); // 0
```

ここで `eval()` を回避するには、プロパティのパスを分割し、様々なプロパティをループすることで行うことができます。

```js
function getDescendantProp(obj, desc) {
  const arr = desc.split(".");
  while (arr.length) {
    obj = obj[arr.shift()];
  }
  return obj;
}

const obj = { a: { b: { c: 0 } } };
const propPath = getPropPath(); // "a.b.c" などを返す
const result = getDescendantProp(obj, propPath);
```

プロパティの設定も同様に行うことができます。

```js
function setDescendantProp(obj, desc, value) {
  const arr = desc.split(".");
  while (arr.length > 1) {
    obj = obj[arr.shift()];
  }
  return (obj[arr[0]] = value);
}

const obj = { a: { b: { c: 0 } } };
const propPath = getPropPath(); // "a.b.c" などを返す
const result = setDescendantProp(obj, propPath, 1); // obj.a.b.c は 1 になる
```

しかし、制約のない入力でブラケットアクセッサを使用することも安全ではありません。オブジェクトインジェクション攻撃を許す可能性もあります。

#### コールバックの使用

JavaScript 第一級関数を備えており、関数を他の API の引数としたり、変数やオブジェクトのプロパティに保存したりすることができます。多くの DOM API はこれを考慮して作られているので、次のように書くことができます（また、書くべきです）。

```js
// setTimeout(" ... ", 1000) を使う代わりに
setTimeout(() => {
  // …
}, 1000);

// elt.setAttribute("onclick", "…") を使う代わりに
elt.addEventListener("click", () => {
  // …
});
```

文字列を連結せずにパラメーター化した関数を作成する方法としては、クロージャを使う方法も便利です。

### JSON の使用

`eval()` の呼び出しに使おうとしている文字列がコードではなくデータ（例えば `"[1, 2, 3]"` で配列を表す）を含むものであれば、JSON に切り替えることを検討してください。これは JavaScript のサブセットを使用することで、文字列でデータを表現することができます。

JSON の構文は JavaScript の構文に比べて制限があり、多くの有効な JavaScript リテラルが JSON としては解釈されないことに注意してください。例えば、最後にカンマを付けることは JSON では許されておらず、オブジェクトリテラル内のプロパティ名（キー）は引用符で囲む必要があります。後で JSON として解析される文字列を生成するには、JSON シリアライザーを使うようにしてください。

任意のコードではなく、注意深く制約されたデータを渡すことは、一般的によい考えです。例えば、ウェブページの内容を取得できるよう設計された拡張であれば、JavaScript コードの代わりに XPath を使って取得ルールを定義できます。

例
-

### eval() の使用

次のコードでは、`eval` を含むどちらの文も 42 を返します。最初のコードは文字列 "`x + y + 1`" を評価します。2 番目のコードは文字列 "`42`" を評価します。

```js
const x = 2;
const y = 39;
const z = "42";
eval("x + y + 1"); // 42 が返される
eval(z); // 42 が返される
```

### 評価される最後の式について

`eval()` は最後に評価された式の値を返します。 `if` については、評価された最後の式または文になります。

```js
const str = "if (a) { 1 + 1 } else { 1 + 2 }";
let a = true;
let b = eval(str); // 2 が返される

console.log(`b is: ${b}`); // b is: 2

a = false;
b = eval(str); // 3 が返される

console.log(`b is: ${b}`); // b is: 3
```

次の例では `eval()` を使用して文字列 `str` を評価しています。この文字列は、`x` が 5 であれば `z` に 42 という値を割り当てる、そうでなければ `z` に 0 を代入するという JavaScript の文で構成されています。 2 つ目の文が実行されると、 `eval()` はこれらの文を発生させ、文の集合も評価して `z` に代入された値を返します。

```js
const x = 5;
const str = `if (x === 5) {
 console.log("z is 42");
 z = 42;
} else {
 z = 0;
}`;

console.log("z is ", eval(str)); // z is 42 z is 42
```

複数の値を割り当てる場合は、最後の値を返します。

```js
let x = 5;
const str = `if (x === 5) {
 console.log("z is 42");
 z = 42;
 x = 420;
} else {
 z = 0;
}`;

console.log("x is", eval(str)); // z is 42 x is 420
```

### 関数定義の文字列の `eval` には先頭と末尾に "(" と ")" が必要

```js
// 関数宣言
const fctStr1 = "function a() {}";
// 関数宣言
const fctStr2 = "(function b() {})";
const fct1 = eval(fctStr1); // undefined を返しますが、グローバル関数として `a` が使えるようになる
const fct2 = eval(fctStr2); // 関数 `b` を返す
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-eval-x |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* プロパティアクセサー
* WebExtensions: コンテンツスクリプトでの eval() の使用


WeakRef - JavaScript

WeakRef
=======

**`WeakRef`** オブジェクトは、ガベージコレクションを受けることを妨げない他のオブジェクトへの弱い参照を保持します。

解説
--

`WeakRef` オブジェクトはオブジェクトへの弱い参照を持ち、これは*ターゲット*または*リファレント*と呼ばれます。オブジェクトへの弱い参照は、ガベージコレクターによるオブジェクトの回収を妨げない参照です。対照的に、通常の（または*強い*）参照はオブジェクトをメモリーに保持します。オブジェクトが強い参照を持たなくなった場合、 JavaScript エンジンのガベージコレクターは、オブジェクトを破棄してメモリーを再取得することがあります。そうなると、弱い参照からオブジェクトを取得することはできなくなります。

未登録のシンボルもガベージコレクション可能であるため、`WeakRef` オブジェクトの対象として使用することもできます。ただし、使用する用途は限られます。

### 可能な限り避ける

`WeakRef` の正しい使用には慎重な検討が必要であり、可能であれば避けた方が良いでしょう。また、仕様で保証されていない特定の動作に依存しないことも重要です。ガベージコレクションがいつ、どのように、そしてどのように発生するかは、使用している JavaScript エンジンの実装に依存します。あるエンジンで観察した動作が、別のエンジン、同じエンジンの別のバージョン、あるいは同じエンジンの同じバージョンでも少し違う状況では異なる可能性があります。ガベージコレクションは、 JavaScript エンジンの実装者が常に解決策を改良している難しい問題です。

ここでは、 `WeakRef` 導入の提案の著者が盛り込んだ具体的なポイントをいくつか紹介します。

>
> ガベージコレクションは複雑です。アプリケーションもしくはライブラリーが WeakRef のガベージコレクションの解放処理か、即時にファイナライザー（解放処理のコールバック）の呼び出し処理に依存している場合は、予想した動作とは異なる動作を行うかもしれません。解放処理は予想よりもかなり後に行われるか、もしくは行われないからです。以下に挙げた様々な原因が考えられます。
>
>
> * あるオブジェクトは、別のオブジェクトよりずっと早くガベージコレクションされるかもしれません。たとえ、世代集合などによって同じ時点で到達できなくなったとしてもです。
> * ガベージコレクションの作業は、インクリメンタル技術やコンカレント技術を使用して、時間をかけて分割させることがあります。
> * メモリー使用量やレスポンスのバランスをとるために、さまざまなランタイムヒューリスティックを使用する可能性があります。
> * JavaScript エンジンは、到達できないように見えること（例えば、クロージャやインラインキャッシュなど）への参照を保持することがあります。
> * JavaScript エンジンが異なれば、これらのことは異なる形で行われるかもしれませんし、同じエンジンでもバージョンによってアルゴリズムが変わるかもしれません。
> * 複雑な要因によって、特定の API を使用している場合など、オブジェクトが予期せぬ時点まで保持されることがあります。
>
>
>

WeakRef における注意
--------------

* コードがターゲットオブジェクトの `WeakRef` を作成した直後、または `WeakRef` の `deref` メソッドからターゲットオブジェクトを取得した場合、そのターゲットオブジェクトは現在の JavaScript のジョブ（スクリプトジョブの終わりに実行するプロミスリアクションジョブを含む）が終わるまで取り戻されません。すなわち、イベントループのターンの間だけ、オブジェクトが再取得されるのを「見る」ことができます。これは主に、指定された JavaScript エンジンのガベージコレクタの挙動をコードで明らかにすることを避けるためです。（ガベージコレクションは難しい問題です。JavaScriptエンジンの実装者は常に、これはうまくいく方法を洗練し、改善しています。）
* 複数の `WeakRef` が同じターゲットを持つ場合、互いに一致します。そのうちの一つで `deref` を呼び出した結果は、そのうちのもう一つで `deref` を呼び出した結果と一致します（同じジョブで）。
* もし `WeakRef` の対象が `FinalizationRegistry` にもある場合、 `WeakRef` の対象はレジストリーに関連するクリーンアップコールバックが呼び出される前に、同時にクリアされます。
* `WeakRef` の対象を変更することはできず、常に元の対象オブジェクトか、その対象が再取得されたときに `undefined` になるだけです。
* `WeakRef` は `deref` から `undefined` を返さないかもしれません。たとえ、対象とするオブジェクトが何も強く保持されていなくても、ガベージコレクターがそのオブジェクトを取り戻すことを決定しないかもしれないからです。
コンストラクター
--------

`WeakRef()`

新しい `WeakRef` オブジェクトを生成します。

インスタンスプロパティ
-----------

これらのプロパティは `WeakRef.prototype` で定義されており、すべての `WeakRef` インスタンスで共有されます。

`WeakRef.prototype.constructor` 省略可

インスタンスオブジェクトを作成したコンストラクター関数です。 `WeakRef` インスタンスの場合、初期値は `WeakRef` コンストラクターです。

**メモ:** このプロパティは仕様上 "normative optional" とされており、適合性のある実装では `constructor` プロパティを公開しないことを意味しています。これにより、任意のコードが `WeakRef` コンストラクターを取得し、ガベージコレクションを監視することができなくなります。しかし、主要なエンジンはすべて既定では公開しています。

`WeakRef.prototype[@@toStringTag]`

`@@toStringTag` プロパティの初期値は文字列 `"WeakRef"` です。このプロパティは `Object.prototype.toString()` で使用されます。

インスタンスメソッド
----------

`WeakRef.prototype.deref()`

`WeakRef` オブジェクトの対象オブジェクトを返すか、対象オブジェクトが既に回収されている場合は `undefined` を返します。

例
-

### WeakRef オブジェクトの使用

この例では、 DOM 要素に表示させるカウンターを開始させ、その要素が存在しなくなったときに停止させます。

```js
class Counter {
  constructor(element) {
    // Remember a weak reference to the DOM element
    this.ref = new WeakRef(element);
    this.start();
  }

  start() {
    if (this.timer) {
      return;
    }

    this.count = 0;

    const tick = () => {
      // Get the element from the weak reference, if it still exists
      const element = this.ref.deref();
      if (element) {
        element.textContent = ++this.count;
      } else {
        // The element doesn't exist anymore
        console.log("The element is gone.");
        this.stop();
        this.ref = null;
      }
    };

    tick();
    this.timer = setInterval(tick, 1000);
  }

  stop() {
    if (this.timer) {
      clearInterval(this.timer);
      this.timer = 0;
    }
  }
}

const counter = new Counter(document.getElementById("counter"));
setTimeout(() => {
  document.getElementById("counter").remove();
}, 5000);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-weak-ref-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `FinalizationRegistry`
* `WeakSet`
* `WeakMap`


GeneratorFunction - JavaScript

GeneratorFunction
=================

**`GeneratorFunction` コンストラクター**は、新しいジェネレーター関数オブジェクトを生成します。 JavaScript では、すべてのジェネレーター関数が実際に `GeneratorFunction` オブジェクトです。

`GeneratorFunction` はグローバルオブジェクトではないことに注意してください。次のコードを評価することによって得られます。

```js
Object.getPrototypeOf(function\* () {}).constructor;
```

試してみましょう
--------

構文
--
```

new GeneratorFunction ([arg1[, arg2[, ...argN]],] functionBody)
```

### 引数

`arg1, arg2, ... argN`

形式的な引数名として関数に使用される名前です。それぞれが有効な JavaScript の識別子であるか、カンマで区切った文字列のリストで、例えば "`x`", "`theValue`", "`a,b`" などです。

`functionBody`

関数定義を構成する JavaScript 文を含む文字列。

解説
--

`GeneratorFunction` コンストラクターで生成されたジェネレーター関数オブジェクトは、関数が生成されたときにパースされます。これは、ジェネレーター関数を `function* 式`で定義してからコード内で呼び出す方法ほど効率的ではありません。というのも、そのような関数はコードの残りの部分と共にパースされるからです。

関数に渡されたすべての引数は、渡された順に、作成される関数内の引数の識別子の名前として扱われます。

**メモ:** `ジェネレーター関数`が `GeneratorFunction` コンストラクターによって生成された場合、生成コンテキストのクロージャは作成されません。常にグローバルスコープに生成されます。

実行すると、ローカル変数とグローバルグローバル変数にのみアクセスでき、 `GeneratorFunction` コンストラクターが呼び出されたスコープの変数にはアクセスできません。

これは、ジェネレーター関数式のコードで `eval` を使用した場合とは異なります。

`GeneratorFunction` コンストラクターを (`new` 演算子を使用せずに) 関数として呼び出した場合、コンストラクターとして呼び出したときと同じ効果があります。

例
-

### GeneratorFunction() コンストラクターからジェネレーター関数を生成する

```js
var GeneratorFunction = Object.getPrototypeOf(function\* () {}).constructor;
var g = new GeneratorFunction("a", "yield a \* 2");
var iterator = g(10);
console.log(iterator.next().value); // 20
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-generatorfunction-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* function\* 関数
* function\* 式
* `Function`
* 関数文
* 関数式
* 関数と関数スコープ


encodeURIComponent() - JavaScript

encodeURIComponent()
====================

**`encodeURIComponent()`** 関数は、 URI (Uniform Resource Identifier) 構成要素を特定の文字を UTF-8 文字エンコーディングで表された 1 個から 4 個のエスケープシーケンスに置き換えることでエンコードします (サロゲートペアで構成される文字のみ 4 個のエスケープシーケンスになります)。

試してみましょう
--------

構文
--
```

encodeURIComponent(str);
```

### 引数

`str`

URI の構成要素となる文字列です。

### 返値

与えられた文字列を表す URI 構成要素としてエンコードされた新しい文字列です。

返値
--

`encodeURIComponent` は**下記を除く**すべての文字をエスケープします。
```

エスケープされないもの:

    A-Z a-z 0-9 - _ . ! ~ * ' ( )
```

`encodeURIComponent()` と **`encodeURI`** の違いは以下の通りです。

```js
var set1 = ";,/?:@&=+$"; // Reserved Characters
var set2 = "-\_.!~\*'()"; // Unescaped Characters
var set3 = "#"; // Number Sign
var set4 = "ABC abc 123"; // Alphanumeric Characters + Space

console.log(encodeURI(set1)); // ;,/?:@&=+$
console.log(encodeURI(set2)); // -\_.!~\*'()
console.log(encodeURI(set3)); // #
console.log(encodeURI(set4)); // ABC%20abc%20123 (the space gets encoded as %20)

console.log(encodeURIComponent(set1)); // %3B%2C%2F%3F%3A%40%26%3D%2B%24
console.log(encodeURIComponent(set2)); // -\_.!~\*'()
console.log(encodeURIComponent(set3)); // %23
console.log(encodeURIComponent(set4)); // ABC%20abc%20123 (the space gets encoded as %20)
```

上位・下位のペアでないサロゲート文字をエンコードしようとした場合 `URIError` が発生します。

```js
// 上位・下位の正しいペア
console.log(encodeURIComponent("\uD800\uDFFF"));

// 上位のみであり "URIError: malformed URI sequence" が発生
console.log(encodeURIComponent("\uD800"));

// 下位のみであり "URIError: malformed URI sequence" が発生
console.log(encodeURIComponent("\uDFFF"));
```

フォームからサーバーに `POST` されるユーザー入力値には `encodeURIComponent` を使用してください。これは、特殊な HTML エンティティやエンコード/デコードを必要とする他の文字のデータ入力中に誤って生成される可能性がある `&` 記号をエンコードします。

例えば、ユーザーが `Jack & Jill` と入力した場合、テキストは `Jack & Jill` とエンコードされる可能性があります。`encodeURIComponent()` を使用しない場合は "&" が新しいフィールドの始まりとしてサーバー上で解釈され、データの完全性が損なわれる可能性があります。

`application/x-www-form-urlencoded` では、スペースは `+` に置換されます。そのため、`encodeURIComponent()` による置換に加えて `%20` を `+` に置き換えることが望まれるかもしれません。

( ! ' ( ) \* が予約語になっている) RFC 3986 仕様を忠実に順守するには、これらの URI 区切り文字としての役目が失われてしまうものの、以下の例が問題なく使用できます。

```js
function fixedEncodeURIComponent(str) {
  return encodeURIComponent(str).replace(/[!'()\*]/g, function (c) {
    return "%" + c.charCodeAt(0).toString(16);
  });
}
```

例
-

### Content-Disposition とリンクヘッダーのエンコーディング

次の例は、サーバーレスポンスヘッダー引数の `Content-Disposition` や `Link` で (UTF-8 からなるファイル名などに) 必要となる特別な UTF-8 エンコーディングを提供します。

```js
var fileName = "my file(2).txt";
var header =
  "Content-Disposition: attachment; filename\*=UTF-8''" +
  encodeRFC5987ValueChars(fileName);

console.log(header);
// logs "Content-Disposition: attachment; filename\*=UTF-8''my%20file%282%29.txt"

function encodeRFC5987ValueChars(str) {
  return (
    encodeURIComponent(str)
      // Note that although RFC3986 reserves "!", RFC5987 does not,
      // so we do not need to escape it
      .replace(/['()]/g, escape) // i.e., %27 %28 %29
      .replace(/\\*/g, "%2A")
      // The following are not required for percent-encoding per RFC5987,
      // so we can allow for a little better readability over the wire: |`^
      .replace(/%(?:7C|60|5E)/g, unescape)
  );
}

// here is an alternative to the above function
function encodeRFC5987ValueChars2(str) {
  return (
    encodeURIComponent(str)
      // Note that although RFC3986 reserves "!", RFC5987 does not,
      // so we do not need to escape it
      .replace(/['()\*]/g, (c) => "%" + c.charCodeAt(0).toString(16)) // i.e., %27 %28 %29 %2a (Note that valid encoding of "\*" is %2A
      // which necessitates calling toUpperCase() to properly encode)
      // The following are not required for percent-encoding per RFC5987,
      // so we can allow for a little better readability over the wire: |`^
      .replace(/%(7C|60|5E)/g, (str, hex) =>
        String.fromCharCode(parseInt(hex, 16)),
      )
  );
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-encodeuricomponent-uricomponent |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `decodeURI`
* `encodeURI`
* `decodeURIComponent`


Uint8ClampedArray - JavaScript

Uint8ClampedArray
=================

**`Uint8ClampedArray`** は型付き配列で、 0-255 に制約される 8 ビット符号なし整数値の配列を表します。指定された値が [0,255] の範囲を超えた場合、 0 または 255 が代わりに設定されます。整数以外を指定しようとすると、最も近い整数が設定されます。中身は `0` で初期化されます。生成されると、配列内の要素はそのオブジェクトのメソッドを使用するか、配列の標準的な添字の構文 (すなわち、ブラケット記法) を使用するかして参照することができます。

コンストラクター
--------

`Uint8ClampedArray()`

新しい `Uint8ClampedArray` オブジェクトを生成します。

静的プロパティ
-------

`Uint8ClampedArray.BYTES_PER_ELEMENT`

要素の大きさを数値で返します。`Uint8ClampedArray` の場合は `1` です。

`Uint8ClampedArray.name`

コンストラクター名を文字列値で返します。`Uint8ClampedArray` の場合、 "`Uint8ClampedArray`" です。

静的メソッド
------

`Uint8ClampedArray.from()`

配列風オブジェクトまたは反復可能オブジェクトから新しい `Uint8ClampedArray` オブジェクトを生成します。 `Array.from()` も参照してください。

`Uint8ClampedArray.of()`

可変長引数で新しい `Uint8ClampedArray` オブジェクトを生成します。`Array.of()` も参照してください。

インスタンスプロパティ
-----------

`Uint8ClampedArray.prototype.buffer`

`Uint8ClampedArray` オブジェクトによって参照される `ArrayBuffer` を返します。構築時に固定され、**読み取り専用**です。

`Uint8ClampedArray.prototype.byteLength`

`Uint8ClampedArray` の `ArrayBuffer` の先頭からの長さを (バイト単位で) 返します。構築時に固定され、**読み取り専用**です。

`Uint8ClampedArray.prototype.byteOffset`

`ArrayBuffer` の先頭からの `Uint8ClampedArray` のオフセットを (バイト単位で) 返します。構築時に固定され、**読み取り専用**です。

`Uint8ClampedArray.prototype.length`

`Uint8ClampedArray` オブジェクト内に保持されている要素の数を返します。構築時に固定され、**読み取り専用**です。

インスタンスメソッド
----------

`Uint8ClampedArray.prototype.copyWithin()`

配列内で一連の配列要素をコピーします。`Array.prototype.copyWithin()` も参照してください。

`Uint8ClampedArray.prototype.entries()`

配列内ですべての位置におけるキーと値の組を提供する新しい*配列イテレーター*を返します。`Array.prototype.entries()` も参照してください。

`Uint8ClampedArray.prototype.every()`

配列内のすべての要素が関数によって提供されたテストに合格するかどうかテストを実行します。`Array.prototype.every()` も参照してください。

`Uint8ClampedArray.prototype.fill()`

配列の先頭位置から末尾位置までのすべての要素を固定値に設定します。`Array.prototype.fill()` も参照してください。

`Uint8ClampedArray.prototype.filter()`

この配列のすべての要素のうち、与えられたフィルタリング関数が `true` を返すものをもつ新しい配列を生成します。`Array.prototype.filter()` も参照してください。

`Uint8ClampedArray.prototype.find()`

配列内の要素に与えられたテスト関数を満足するものがあったら、見つかった値を返します。見つからなければ `undefined` を返します。`Array.prototype.find()` も参照してください。

`Uint8ClampedArray.prototype.findIndex()`

配列内の要素に与えられたテスト関数を満足するものがあったら、見つかった位置を返します。見つからなければ `-1` を返します。`Array.prototype.findIndex()` も参照してください。

`Uint8ClampedArray.prototype.forEach()`

配列内のそれぞれの要素について関数を呼び出します。`Array.prototype.forEach()` も参照してください。

`Uint8ClampedArray.prototype.includes()`

型付き配列に特定の要素があるかどうかを判断し、それに応じて `true` か `false`を返します。 `Array.prototype.includes()` も参照してください。

`Uint8ClampedArray.prototype.indexOf()`

指定された値に等しい配列内の要素の最初の (最小の) 位置を返します。見つからなかった場合、 `-1` を返します。`Array.prototype.indexOf()` も参照してください。

`Uint8ClampedArray.prototype.join()`

配列のすべての要素を 1 つの文字列に結合します。`Array.prototype.join()` も参照してください。

`Uint8ClampedArray.prototype.keys()`

配列内ですべての位置におけるキーを提供する新しい*配列イテレーター*を返します。`Array.prototype.keys()` も参照してください。

`Uint8ClampedArray.prototype.lastIndexOf()`

指定された値に等しい配列内の要素の最後の (最大の) 位置を返します。見つからなかった場合、 `-1` を返します。`Array.prototype.lastIndexOf()` も参照してください。

`Uint8ClampedArray.prototype.map()`

この配列のすべての要素で与えられた関数を呼び出した結果をもつ新しい配列を生成します。`Array.prototype.map()` も参照してください。

`Uint8ClampedArray.prototype.reduce()`

アキュムレーターとこの配列のそれぞれの値に対して (左から右へ) 関数を適用し、単一の値に還元します。`Array.prototype.reduce()` も参照してください。

`Uint8ClampedArray.prototype.reduceRight()`

アキュムレーターとこの配列のそれぞれの値に対して (右から左へ) 関数を適用し、単一の値に還元します。`Array.prototype.reduceRight()` も参照してください。

`Uint8ClampedArray.prototype.reverse()`

配列の要素の順番を反転させます。最初の要素は最後になり、最後の要素は最初になります。`Array.prototype.reverse()` も参照してください。

`Uint8ClampedArray.prototype.set()`

入力値を指定した配列から読み込み、この型付き配列内に複数の値を格納します。

`Uint8ClampedArray.prototype.slice()`

配列の一部を取り出して新しい配列を返します。`Array.prototype.slice()` も参照してください。

`Uint8ClampedArray.prototype.some()`

この配列の 1 つ以上の要素が与えられたテスト関数を満たした場合に `true` を返します。`Array.prototype.some()` も参照してください。

`Uint8ClampedArray.prototype.sort()`

配列の要素をその場で並べ替え、その配列を返します。`Array.prototype.sort()` も参照してください。

`Uint8ClampedArray.prototype.subarray()`

指定された先頭と末尾の要素位置から新しい `Uint8ClampedArray` を返します。

`Uint8ClampedArray.prototype.values()`

配列内ですべての位置における値を提供する新しい*配列イテレーター*を返します。`Array.prototype.values()` も参照してください。

`Uint8ClampedArray.prototype.toLocaleString()`

配列とその要素を表すローカライズされた文字列を返します。`Array.prototype.toLocaleString()` も参照してください。

`Uint8ClampedArray.prototype.toString()`

配列とその要素を表す文字列を返します。`Array.prototype.toString()` も参照してください。

`Uint8ClampedArray.prototype[@@iterator]()`

配列内ですべての位置における値を提供する新しい*配列イテレーター*を返します。

例
-

### 様々な方法で `Uint8ClampedArray` を作成

```js
// 長さから
var uintc8 = new Uint8ClampedArray(2);
uintc8[0] = 42;
uintc8[1] = 1337;
console.log(uintc8[0]); // 42
console.log(uintc8[1]); // 255 (制約を受けた)
console.log(uintc8.length); // 2
console.log(uintc8.BYTES\_PER\_ELEMENT); // 1

// 配列から
var arr = new Uint8ClampedArray([21, 31]);
console.log(arr[1]); // 31

// From another TypedArray
var x = new Uint8ClampedArray([21, 31]);
var y = new Uint8ClampedArray(x);
console.log(y[0]); // 21

// ArrayBuffer から
var buffer = new ArrayBuffer(8);
var z = new Uint8ClampedArray(buffer, 1, 4);

// 反復可能オブジェクトから
var iterable = (function\* () {
  yield\* [1, 2, 3];
})();
var uintc8 = new Uint8ClampedArray(iterable);
// Uint8ClampedArray[1, 2, 3]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # table-49 |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Uint8ClampedArray` のポリフィルが `core-js` で利用できます
* JavaScript の型付き配列
* `ArrayBuffer`
* `DataView`


Intl - JavaScript

Intl
====

**`Intl`** オブジェクトは、 ECMAScript の国際化 API の名前空間で、言語に依存した文字列の比較、数値の書式化と、日付の書式化を提供します。 **`Intl`** オブジェクトは、いくつかのコンストラクターに加え、国際化コンストラクターや他の言語に関する関数に共通する機能へのアクセスを提供します。

コンストラクタープロパティ
-------------

`Intl.Collator()`

言語に依存した文字列の比較を可能にするオブジェクトである collator のためのコンストラクターです。

`Intl.DateTimeFormat()`

言語に依存した日時の書式化を可能にするオブジェクトのためのコンストラクターです。

`Intl.DisplayNames()`

言語、地域、文字体系の表示名の一貫した翻訳を可能にするオブジェクトのコンストラクターです。

`Intl.ListFormat()`

言語に依存したリストの書式化を可能にするオブジェクトのためのコンストラクターです。

`Intl.Locale()`

Unicode ロケール識別子を表すオブジェクトのためのコンストラクターです。

`Intl.NumberFormat()`

言語に依存した数値フォーマットを可能にするオブジェクトのためのコンストラクターです。

`Intl.PluralRules()`

複数形を意識した書式化や複数形の言語規則を可能にするオブジェクトのためのコンストラクターです。

`Intl.RelativeTimeFormat()`

言語を意識した相対時刻の書式化を可能にするオブジェクトのためのコンストラクターです。

`Intl.Segmenter()`

ロケールを意識したテキスト区切りを可能にするオブジェクトのためのコンストラクターです。

メソッド
----

`Intl.getCanonicalLocales()`

正規のロケール名を返すメソッド。

`Intl.supportedValuesOf()` (en-US)

この実装が対応している一意のカレンダー、照合順序、通貨、計数法、単位値を含む、ソートされた配列を返します。

ロケールの識別とネゴシエーション
----------------

国際化コンストラクターや他のコンストラクターの言語を意識したメソッド (関連情報に記載) は、ロケールを識別して実際に使用するものを決定するために共通のパターンを使用しています。これらはすべて、 `locales` と `options` の引数を受け取り、 `options.localeMatcher` プロパティで指定したアルゴリズムを使用して 要求されたロケールと対応しているロケールとのネゴシエーションを行います。

### locales 引数

`locales` 引数は、指定された操作に使用するロケールを特定するために使用されます。 JavaScript の実装では `locales` を調べて、表現された指定を満たすものに最も近い、理解可能なロケールを計算します。 `locales` は次のものを取ることができます。

* `undefined` (または省略): その実装の既定のロケールが使用されます。
* ロケール: ロケール識別子またはロケール識別子を持つ `Intl.Locale` オブジェクトです。
* ロケールのリスト: 何らかの他の値で、オブジェクトに変換され、ロケールの配列として扱われます。

後 2 者では、実際に使用されるロケールは、ロケールネゴシエーションによって決定された、最も良く対応しているロケールになります。

ロケール識別子は以下のものから成る文字列です。

1. 言語サブタグ
2. (任意で) 文字体系サブタグ
3. (任意で) 地域 (または国) サブタグ
4. (任意で) 1 つ以上の変化形サブタグ (すべて固有でなければならない)
5. (任意で) 1 つ以上の BCP 47 拡張シーケンス
6. (任意で) 私的に使用する拡張シーケンス

...存在するサブタグやシーケンスはすべて、ハイフンで区切ります。ロケール識別子は大文字小文字の区別のない ASCII です。しかし、文字体系サブタグではタイトルケース (最初の文字が大文字で、以降の文字は小文字) を、地域サブタグは大文字、それ以外はすべて小文字を使う習慣があります。

* "`hi`": ヒンディー語 (主たる言語)
* "`de-AT`": オーストリア (地域) で使用されているドイツ語 (言語)
* "`zh-Hans-CN`": 中国 (地域) で使用されている簡体字 (文字体系) で書かれている中国語 (言語)。
* "`en-emodeng`": 英語 (言語) の "Early modern English" 方言 (変化形)

言語、文字体系、地域 (国を含む)、 (稀に使用される) 変化形を識別するサブタグは、 IANA 言語サブタグレジストリーに登録されています。このレジストリーは長期にわたって定期的に更新されており、実装は常に最新であるとは限らないため、サブタグが広く対応されていることを頼りすぎないようにしてください。

BCP 47 拡張シーケンスは、単一の数字または文字 (`"x"` 以外) と、ハイフンで区切られた 1 つ以上の 2 から 8 文字の文字または数字によるサブタグで構成されています。それぞれの数字または文字に対して 1 つのシーケンスのみが許可されていますので、 "`de-a-foo-a-foo`" は無効です。 BCP 47 拡張サブタグは Unicode CLDR Project で定義されています。現在は 2 つの拡張機能の意味のみが定義されています。

* `"u"` (Unicode) 拡張は `Intl.Collator`, `Intl.NumberFormat`, `Intl.DateTimeFormat` の各オブジェクトにおいて、ロケール固有の動作のカスタマイズを要求するために使用することができます。
    + "`de-DE-u-co-phonebk`": ドイツ語のソート順の電話帳変化形を使用します。このソート順では、ウムラウト付きの母音を、 ä → ae, ö → oe, ü → ue のように、ウムラウトの付かない母音二文字に展開したものと見なした順で並べ替えします。
    + "`th-TH-u-nu-thai`": 数値書式で、タイの数字 (๐, ๑, ๒, ๓, ๔, ๕, ๖, ๗, ๘, ๙) を使用します。
    + "`ja-JP-u-ca-japanese`": 日時書式で和暦を使用します。すなわち、 2013 年は平成 25 年として表現されます。
    + "`en-GB-u-ca-islamic`": イギリス英語でイスラム暦 (Hijri) を使用します。グレゴリオ暦で2017年10月14日は、 Hijri 暦で 24 Muharram, 1439 です。
* `"t"` (transformed) 拡張は、他のロケールから翻訳されたテキストなど、変換されたコンテンツを示します。現在のところ、 `Intl` の機能で `"t"` 拡張を考慮するものはありません。しかし、この拡張はネストされたロケールを含むことがあります。たとえば、 "`de-t-en`" には英語のロケール識別子が含まれています。入れ子のロケールが存在する場合、それは有効なロケール識別子でなければなりません。例えば、 "`en-emodeng-emodeng`" は (`emodeng` の変化形サブタグが重複しているため) 無効なので、"`de-t-en-emodeng-emodeng`"も無効です。

最後に、"x "という文字を使った私的使用の拡張シーケンスがあり、その後にハイフンで区切られた 1 ～ 8 文字または数字のサブタグが 1 つ以上続きます。これにより、アプリケーションが独自に使用する情報をエンコードすることができますが、すべての `Intl` の操作では無視されます。

### ロケールネゴシエーション

`locales` 引数は、すべての Unicode 拡張を除去した後、アプリケーションからの優先順位付き要求として解釈されます。ランタイムは、利用可能なロケールと比較し、利用可能なロケールのうち最適なものを選びます。マッチングアルゴリズムは二種類あります。 "`lookup`" マッチャーは、BCP 47 で指定された Lookup アルゴリズムに従います。 "`best fit`" マッチャーでは、ランタイムが少なくとも、あるいは場合によっては、 Lookup アルゴリズムの結果よりもリクエストに適合したロケールを提供します。アプリケーションが `locales` 引数を提供しなかった場合や、リクエストに一致するロケールをランタイムが持っていなかった場合は、ランタイムの既定のロケールが使用されます。マッチャーは、 `options` 引数のプロパティを使って選択することができます (下記参照)。

ネゴシエーションにより選択された言語タグが Unicode 拡張の部分文字列を持っているとき、その拡張はここで、構築されたオブジェクトや関数の振る舞いをカスタマイズするために使われます。それぞれのコンストラクターや関数は、 Unicode 拡張用のキーのごく一部分のみ対応しており、また、対応する値は、多くの場合言語タグに依存します。例えば、 "`co`" キー (コレクション)は、 `Intl.Collator` だけが対応しており、そのキーに対する "`phonebk`" の値はドイツ語だけが対応しています。

### options 引数

`options` 引数は、コンストラクターや関数ごとに異なるプロパティをもつオブジェクトである必要があります。 `options` 引数が与えられなかった場合、または、未定義の場合、すべてのプロパティに対して既定値が使用されます。

言語を意識するすべてのコンストラクターや関数が対応しているプロパティが一つあります。 `localeMatcher` プロパティで、この値は "`lookup`" または "`best fit`" の文字列である必要があり、上記のロケールマッチングアルゴリズムのうちから一つを選択します。

例
-

### 日付と数値の書式化

`Intl` を使用して、特定の言語や地域で一般的な形で日付や数値を書式化することができます。

```js
const count = 26254.39;
const date = new Date("2012-05-24");

function log(locale) {
  console.log(
    `${new Intl.DateTimeFormat(locale).format(date)} ${new Intl.NumberFormat(
 locale,
 ).format(count)}`,
  );
}

log("en-US");
// 期待される出力: 5/24/2012 26,254.39

log("de-DE");
// 期待される出力: 24.5.2012 26.254,39
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # intl-object |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* 導入: The ECMAScript Internationalization API
* コンストラクター
    + `Intl.Collator()`
    + `Intl.DateTimeFormat()`
    + `Intl.ListFormat()`
    + `Intl.NumberFormat()`
    + `Intl.PluralRules()`
    + `Intl.RelativeTimeFormat()`
    + `Intl.Locale()`
    + `Intl.Segmenter()`
* メソッド
    + `String.prototype.localeCompare()`
    + `Number.prototype.toLocaleString()`
    + `Date.prototype.toLocaleString()`
    + `Date.prototype.toLocaleDateString()`
    + `Date.prototype.toLocaleTimeString()`


Date - JavaScript

Date
====

JavaScript の **`Date`** オブジェクトは、単一の瞬間の時刻をプラットフォームに依存しない形式で表します。 `Date` オブジェクトは協定世界時 (UTC) の 1970 年 1 月 1 日からの経過ミリ秒数を表す `Number` の値を含んでいます。

**メモ:** TC39 は Temporal という、新しい日付/時刻の API を開発しています。これについて詳しくは Igalia のブログを参照してください。まだ正式利用の準備はできていません。

解説
--

### ECMAScript 元期 とタイムスタンプ

JavaScript の日時は基本的に、 ECMAScript 元期 、すなわち協定世界時 (UTC) の 1970 年 1 月 1 日深夜 0 時（UNIX 元期と同等）からの経過ミリ秒数で示されます。

**メモ:** Date オブジェクトの中心となる時間値は UTC ですが、日付と時刻、またはその一部を取得する基本的なメソッドは、すべて地方時（ホストシステムなど）のタイムゾーンとオフセットで動作することを覚えておくことが重要です。

`Date` の最大値は、確実な整数の最大値 (`Number.MAX_SAFE_INTEGER`、9,007,199,254,740,991) と同じ値ではないことに注意が必要です。代わりに ECMA-262 では、 UTC の 1970 年 1 月 1 日から前後 ±100,000,000 (1 億) 日（つまり、紀元前 271821 年 4 月 20 日 - 紀元 275760 年 9 月 13 日）を標準の `Date` オブジェクトで表すことができると定義しています。

### 日時形式とタイムゾーンの変換

様々な形式で日時を取得したり、タイムゾーンの変換を行ったりすることができる方法はたくさんあります。特に便利なのは、世界時標準 (World Time Standard) で定義されている世界標準時である協定世界時 (UTC) で日付と時刻を出力する関数です。（この時間は歴史的に*グリニッジ標準時*として知られており、 UTC はイギリスのロンドンとその近くのグリニッジを含む子午線に沿って位置しています。）ユーザーの端末は現地時間を提供します。

地方時の日付と時刻の個々の部分を読み書きするメソッド（`getDay()` や `setHours()` など）に加えて、 UTC を使用して日付と時刻を読み書きする同等のメソッド（`getUTCDay()` や `setUTCHours()` など）もあります。

コンストラクター
--------

`Date()`

関数として呼び出された場合、現在の日付と時刻の文字列表現を返します。すべての引数は無視されます。この結果は `new Date().toString()` を実行するのと同じです。

`new Date()`

コンストラクターとして呼び出された場合、新しい `Date` オブジェクトを返します。

静的メソッド
------

`Date.now()`

現在の時刻に対応する数値、すなわち UTC の 1970 年 1 月 1 日 00:00:00 から経過したミリ秒数を表す数値を返します。うるう秒は無視します。

`Date.parse()`

日付を表す文字列を解釈して、地方時で 1970 年 1 月 1 日 00:00:00 から経過したミリ秒数を表す数値を返します。うるう秒は無視します。

**メモ:** ブラウザーごとに動作が異なり一貫性がないため、 `Date.parse` で文字列を解釈しないことを強く推奨します。

`Date.UTC()`

最も長い形式のコンストラクターと同じ引数（すなわち 2 〜 7）を受け取り、 1970 年 1 月 1 日 00:00:00 （UTC）から経過したミリ秒数を返します。うるう秒は無視します。

インスタンスメソッド
----------

`Date.prototype.getDate()`

地方時に基づき、指定された日時の「日」 (`1`–`31`) を返します。

`Date.prototype.getDay()`

地方時に基づき、指定された日時の「曜日」 (`0`–`6`) を返します。

`Date.prototype.getFullYear()`

地方時に基づき、指定された日時の「年」 (4 桁の年であれば 4 桁) を返します。

`Date.prototype.getHours()`

地方時に基づき、指定された日時の「時」 (`0`–`23`) を返します。

`Date.prototype.getMilliseconds()`

地方時に基づき、指定された日時の「ミリ秒」 (`0`–`999`) を返します。

`Date.prototype.getMinutes()`

地方時に基づき、指定された日時の「分」 (`0`–`59`) を返します。

`Date.prototype.getMonth()`

地方時に基づき、指定された日時の「月」 (`0`–`11`) を返します。

`Date.prototype.getSeconds()`

地方時に基づき、指定された日時の「秒」 (`0`–`59`) を返します。

`Date.prototype.getTime()`

指定された日時を協定世界時 (UTC) の 1970 年 1 月 1 日 00:00:00 からの経過ミリ秒単位の数値で返します。 (それ以前の時刻では負の数を返します。)

`Date.prototype.getTimezoneOffset()`

現地の時間帯のオフセットを分で返します。

`Date.prototype.getUTCDate()`

協定世界時に基づき、指定された日時の「日」 (`1`–`31`) を返します。

`Date.prototype.getUTCDay()`

協定世界時に基づき、指定された日時の「曜日」 (`0`–`6`) を返します。

`Date.prototype.getUTCFullYear()`

協定世界時に基づき、指定された日時の「年」 (4 桁の年であれば 4 桁) を返します。

`Date.prototype.getUTCHours()`

協定世界時に基づき、指定された日時の「時」 (`0`–`23`) を返します。

`Date.prototype.getUTCMilliseconds()`

協定世界時に基づき、指定された日時の「ミリ秒」 (`0`–`999`) を返します。

`Date.prototype.getUTCMinutes()`

協定世界時に基づき、指定された日時の「分」 (`0`–`59`) を返します。

`Date.prototype.getUTCMonth()`

協定世界時に基づき、指定された日時の「月」 (`0`–`11`) を返します。

`Date.prototype.getUTCSeconds()`

協定世界時に基づき、指定された日時の「秒」 (`0`–`59`) を返します。

`Date.prototype.getYear()`
非推奨

地方時に基づき、指定された日時の「年」 (ふつうは 2–3 桁) を返します。代わりに `getFullYear()` を使用してください。

`Date.prototype.setDate()`

地方時に基づき、指定された日時の「日」を設定します。

`Date.prototype.setFullYear()`

地方時に基づき、指定された日時の「年」を完全な形 (例えば、 4 桁の年であれば 4 桁) で設定します。

`Date.prototype.setHours()`

地方時に基づき、指定された日時の「時」を設定します。

`Date.prototype.setMilliseconds()`

地方時に基づき、指定された日時の「ミリ秒」を設定します。

`Date.prototype.setMinutes()`

地方時に基づき、指定された日時の「分」を設定します。

`Date.prototype.setMonth()`

地方時に基づき、指定された日時の「月」を設定します。

`Date.prototype.setSeconds()`

地方時に基づき、指定された日時の「秒」を設定します。

`Date.prototype.setTime()`

`Date` オブジェクトを協定世界時(UTC) の 1970 年 1 月 1 日 00:00:00 からのミリ秒単位の数で表された時刻に設定します。

`Date.prototype.setUTCDate()`

協定世界時に基づき、指定された日時の「日」を設定します。

`Date.prototype.setUTCFullYear()`

協定世界時に基づき、指定された日時の「年」を完全な形で設定します。

`Date.prototype.setUTCHours()`

協定世界時に基づき、指定された日時の「時」を設定します。

`Date.prototype.setUTCMilliseconds()`

協定世界時に基づき、指定された日時の「ミリ秒」を設定します。

`Date.prototype.setUTCMinutes()`

協定世界時に基づき、指定された日時の「分」を設定します。

`Date.prototype.setUTCMonth()`

協定世界時に基づき、指定された日時の「月」を設定します。

`Date.prototype.setUTCSeconds()`

協定世界時に基づき、指定された日時の「秒」を設定します。

`Date.prototype.setYear()`
非推奨

協定地方時に基づき、指定された日時の「年」 (ふつうは 2–3 桁) を設定します。代わりに `setFullYear()` を使用してください。

`Date.prototype.toDateString()`

`Date` の「日付」部を、 'Thu Apr 12 2018' のように人間が読みやすい形式の文字列にして返します。

`Date.prototype.toISOString()`

日付を ISO 8601 Extended Format に準じた文字列に変換します。

`Date.prototype.toJSON()`

`toISOString()` を使用して `Date` を表す文字列を返します。`JSON.stringify()` の代わりに使用してください。

`Date.prototype.toGMTString()`
非推奨

GMT (UTC) タイムゾーンを基準にした `Date` を表す文字列を返します。代わりに `toUTCString()` を使用してください。

`Date.prototype.toLocaleDateString()`

この日時の日付部分を、システム設定に基づいて地域性を考慮した表現による文字列にして返します。

`Date.prototype.toLocaleString()`

日付を地域の日付書式に従った文字列に変換して返します。`Object.prototype.toLocaleString()` メソッドを上書きします。

`Date.prototype.toLocaleTimeString()`

この日時の時刻部分を、システム設定に基づいて地域性を考慮した表現による文字列にして返します。

`Date.prototype.toString()`

指定された `Date` オブジェクトを表す文字列を返します。 `Object.prototype.toString()` メソッドを上書きします。

`Date.prototype.toTimeString()`

`Date` の「時刻」部を人間が読みやすい形式の文字列にして返します。

`Date.prototype.toUTCString()`

日時を UTC タイムゾーンを使用する文字列に変換します。

`Date.prototype.valueOf()`

`Date` オブジェクトのプリミティブ値を返します。`Object.prototype.valueOf()` メソッドを上書きします。

例
-

### Date オブジェクトを生成するいくつかの方法

以下の例で、 JavaScript の日時を生成するいくつかの方法を示します。

**メモ:** `Date` コンストラクター（および `Date.parse` と同等）で日付文字列を解釈する際には、常に入力が ISO 8601 形式 (`YYYY-MM-DDTHH:mm:ss.sssZ`) であることを確認してください。他の形式で解釈した場合には、その挙動は実装によって定義されていて、すべてのブラウザーで動くとは限りません。多数の異なる形式に対応するためには、ライブラリーが役に立ちます。

```js
const today = new Date();
const birthday = new Date("December 17, 1995 03:24:00"); // 避けてください。すべてのランタイムで動作するとは限りません。
const birthday2 = new Date("1995-12-17T03:24:00"); // これは ISO8601 互換であり、動作が信頼できます
const birthday3 = new Date(1995, 11, 17); // 月は 0 起点です
const birthday4 = new Date(1995, 11, 17, 3, 24, 0);
const birthday5 = new Date(628021800000); // 元期からのタイムスタンプ
```

### toString メソッドの返値の形式

```js
const date = new Date("2020-05-12T23:50:21.817Z");
date.toString(); // Tue May 12 2020 18:50:21 GMT-0500 (Central Daylight Time)
date.toDateString(); // Tue May 12 2020
date.toTimeString(); // 18:50:21 GMT-0500 (Central Daylight Time)
date.toISOString(); // 2020-05-12T23:50:21.817Z
date.toUTCString(); // Tue, 12 May 2020 23:50:21 GMT
date.toGMTString(); // Tue, 12 May 2020 23:50:21 GMT
date.toJSON(); // 2020-05-12T23:50:21.817Z
date.toLocaleString(); // 5/12/2020, 6:50:21 PM
date.toLocaleDateString(); // 5/12/2020
date.toLocaleTimeString(); // 6:50:21 PM
```

### 年月日や時刻の取得

```js
const date = new Date();
const [month, day, year] = [
  date.getMonth(),
  date.getDate(),
  date.getFullYear(),
];
const [hour, minutes, seconds] = [
  date.getHours(),
  date.getMinutes(),
  date.getSeconds(),
];
```

### 2 桁の年の補完

`new Date()` は 2 桁の年の値に対して、古くで望ましくない一貫性のない挙動を示します。具体的には、 `new Date()` の呼び出しに 2 桁の年の値が与えられた場合、その年の値はリテラルの年として扱われず、そのまま使用され、代わりに相対的なオフセットとして解釈されます。ある場合には 1900 年からのオフセットとなりますが、またある場合には 2000 年からのオフセットになります。

```js
let date = new Date(98, 1); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date = new Date(22, 1); // Wed Feb 01 1922 00:00:00 GMT+0000 (GMT)
date = new Date("2/1/22"); // Tue Feb 01 2022 00:00:00 GMT+0000 (GMT)

// 古い方法。常に 2 桁の年の値を 1900 からの相対値として解釈する
date.setYear(98);
date.toString(); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date.setYear(22);
date.toString(); // Wed Feb 01 1922 00:00:00 GMT+0000 (GMT)
```

西暦 0 年から 99 年までの間の年を生成および取得するには、`setFullYear()` メソッドと `getFullYear()` メソッドを使用してください。

```js
// 推奨されるメソッドです。どんな値でも相対オフセットではなく、そのまま
// 年として解釈します。
date.setFullYear(98);
date.getFullYear(); // 98 (not 1998)
date.setFullYear(22);
date.getFullYear(); // 22 (not 1922, not 2022)
```

### 経過時間の計算

以下の例で、2 つの JavaScript の日付の間で経過した時間を計る方法を示します。

日 (夏時間の切り替えによる)、月、年の長さが異なるため、経過時間を時、分、秒以上の単位で表現するには、いくつかの問題に対処する必要がありますので、事前によく調べて使用してください。

```js
// Date オブジェクトを使用
const start = Date.now();

// 時間を計りたいイベントをここに置く
doSomethingForALongTime();
const end = Date.now();
const elapsed = end - start; // ミリ秒単位の経過時間
```

```js
// 組み込みメソッドを使用
const start = new Date();

// 時間を計りたいイベントをここに置く
doSomethingForALongTime();
const end = new Date();
const elapsed = end.getTime() - start.getTime(); // ミリ秒単位の経過時間
```

```js
// 関数をテストして返値を取得する
function printElapsedTime(testFn) {
  const startTime = Date.now();
  const result = testFn();
  const endTime = Date.now();

  console.log(`Elapsed time: ${String(endTime - startTime)} milliseconds`);
  return result;
}

const yourFunctionReturn = printElapsedTime(yourFunction);
```

**メモ:** Web Performance API の高精度時刻機能に対応しているブラウザーでは、 `Performance.now()` で、 `Date.now()` よりも高信頼かつ高精度な経過時間の測定が可能です。

### ECMAScript 元期からの経過秒数を取得する

```js
const seconds = Math.floor(Date.now() / 1000);
```

この場合、整数だけを返すことが重要です（単純な除算ではできません）。また、実際に経過した秒数を返すことも重要です（ですから、上の例では `Math.round()` ではなく `Math.floor()` を使っています）。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date()` コンストラクター


Generator - JavaScript

Generator
=========

**`Generator`** オブジェクトはジェネレーター関数によって返され、反復可能プロトコルとイテレータープロトコルの両方に準拠しています。

試してみましょう
--------

コンストラクター
--------

このオブジェクトを直接インスタンス化することはできません。代わりに、ジェネレーター関数から `Generator` のインスタンスを返すことができます。
```

function* generator() {
  yield 1;
  yield 2;
  yield 3;
}

const gen = generator(); // "Generator { }"
```

インスタンスメソッド
----------

`Generator.prototype.next()`

`yield` 式で得られた値を返します。

`Generator.prototype.return()`

与えられた値を返し、ジェネレーターを終了します。

`Generator.prototype.throw()`

ジェネレーターにエラーを投げます。（そのジェネレーターの中からキャッチされない限り、ジェネレーターも終了します）

例
-

### 無限イテレーター

```js
function\* infinite() {
  let index = 0;

  while (true) {
    yield index++;
  }
}

const generator = infinite(); // "Generator { }"

console.log(generator.next().value); // 0
console.log(generator.next().value); // 1
console.log(generator.next().value); // 2
// ...
```

仕様
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-generator-objects |

ブラウザー実装状況
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `function*`
* `function*` 式
* `GeneratorFunction`
* 反復処理プロトコル (en-US)


JSON - JavaScript

JSON
====

**`JSON`** オブジェクトは、 JavaScript Object
Notation (JSON) を解釈するメソッドや、値を JSON に変換するメソッドを持ちます。これは呼び出しや構築をすることができず、また 2 つのメソッドプロパティを除いて、これ自身に興味深い機能性はありません。

解説
--

### JavaScript と JSON の違い

JSON は、オブジェクト、配列、数値、文字列、論理値、そして `null` をシリアライズする構文です。これは JavaScript の構文に基づいていますが、区別されるものです。JavaScript ならば JSON であるというわけでは*ありません*。

**オブジェクトと配列**

プロパティ名は二重引用符で括った文字列にしなければなりません。末尾のカンマを置いてはいけません。

**数値**

先頭にゼロを置くことは禁止されています。また、小数点は 1 桁以上の数字の後ろに置かなければなりません。 `NaN` と `Infinity` には対応していません。

**あらゆる JSON のテキストは有効な JavaScript の式です...**

...ただし、proposal to make all JSON text valid ECMA-262 を実装した JavaScript エンジンのみでの話です。この提案を実装していないエンジンでは、 U+2028 LINE SEPARATOR と U+2029 PARAGRAPH SEPARATOR は JSON の文字列リテラルとプロパティのキーでは許されますが、これらの機能を JavaScript 文字列リテラルの中で使用すると `SyntaxError` になります。

`JSON.parse()` が文字列を JSON として解釈し、`eval` が文字列を JavaScript として実行するこの例を考えてみてください。

```js
let code = '"\u2028\u2029"';
JSON.parse(code); // どのエンジンでも "\u2028\u2029" と評価される
eval(code); // 古いエンジンでは SyntaxError が発生する
```

他の違いとしては、二重引用符で囲まれた文字列のみを許可していることや、 `undefined` やコメントの規定がないことなどが挙げられます。 JSON に基づいたより人間に優しい設定フォーマットを使いたい場合、 Babel コンパイラーによって使われる JSON5 と、より一般的に使われる YAML があります。

### JSON の完全な構文

有効な JSON の構文は、ABNF で表現された以下の文法で公式に定義されています。これは IETF の JSON 標準 (RFC) からコピーしたものです。
```

JSON-text = object / array
begin-array     = ws %x5B ws  ; [ left square bracket
begin-object    = ws %x7B ws  ; { left curly bracket
end-array       = ws %x5D ws  ; ] right square bracket
end-object      = ws %x7D ws  ; } right curly bracket
name-separator  = ws %x3A ws  ; : colon
value-separator = ws %x2C ws  ; , comma
ws = *(
     %x20 /              ; Space
     %x09 /              ; Horizontal tab
     %x0A /              ; Line feed or New line
     %x0D                ; Carriage return
     )
value = false / null / true / object / array / number / string
false = %x66.61.6c.73.65   ; false
null  = %x6e.75.6c.6c      ; null
true  = %x74.72.75.65      ; true
object = begin-object [ member *( value-separator member ) ]
         end-object
member = string name-separator value
array = begin-array [ value *( value-separator value ) ] end-array
number = [ minus ] int [ frac ] [ exp ]
decimal-point = %x2E       ; .
digit1-9 = %x31-39         ; 1-9
e = %x65 / %x45            ; e E
exp = e [ minus / plus ] 1*DIGIT
frac = decimal-point 1*DIGIT
int = zero / ( digit1-9 *DIGIT )
minus = %x2D               ; -
plus = %x2B                ; +
zero = %x30                ; 0
string = quotation-mark *char quotation-mark
char = unescaped /
    escape (
        %x22 /          ; "    quotation mark  U+0022
        %x5C /          ; \    reverse solidus U+005C
        %x2F /          ; /    solidus         U+002F
        %x62 /          ; b    backspace       U+0008
        %x66 /          ; f    form feed       U+000C
        %x6E /          ; n    line feed       U+000A
        %x72 /          ; r    carriage return U+000D
        %x74 /          ; t    tab             U+0009
        %x75 4HEXDIG )  ; uXXXX                U+XXXX
escape = %x5C              ; \
quotation-mark = %x22      ; "
unescaped = %x20-21 / %x23-5B / %x5D-10FFFF

HEXDIG = DIGIT / %x41-46 / %x61-66   ; 0-9, A-F, or a-f
       ; HEXDIG equivalent to HEXDIG rule in [RFC5234]
DIGIT = %x30-39            ; 0-9
      ; DIGIT equivalent to DIGIT rule in [RFC5234]
```

重要でないホワイトスペースは、基本的に任意の場所に置くことができますが、 `JSONNumber` (数値に空白を含んではいけません) や `JSONString` (対応する文字であると解釈されるか、エラーが発生します) の内部を除きます。ホワイトスペースとして有効な文字はタブ文字 (U+0009)、キャリッジリターン (U+000D)、ラインフィード (U+000A)、空白 (U+0020) のみです。

静的メソッド
------

`JSON.parse(text[, reviver])`

文字列 `text` を JSON として解析し、オプションで生成された値とそのプロパティを変換し、値を返します。 JavaScript と JSON の違いに関連するものを含め、 JSON の構文に違反すると `SyntaxError` が発生します。`reviver` オプションは、`replacer` が他のデータ型の代用として使用したものを解釈することができます。

`JSON.stringify(value[, replacer[, space]])`

指定した値に対応する JSON 文字列を返します。オプションで、特定のプロパティのみを含むか、ユーザー定義の方法でプロパティ値を置き換えることもできます。既定では、すべての `undefined` のインスタンスは `null` に置き換えられ、その他の対応していないネイティブデータ型は打ち切られます。 `replacer` オプションでは、他の動作を指定することができます。

例
-

### JSON の例

```json
{
  "browsers": {
    "firefox": {
      "name": "Firefox",
      "pref\_url": "about:config",
      "releases": {
        "1": {
          "release\_date": "2004-11-09",
          "status": "retired",
          "engine": "Gecko",
          "engine\_version": "1.7"
        }
      }
    }
  }
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-json-object |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.toJSON()`
* JSON Diff checker
* JSON Beautifier/editor
* JSON Parser
* JSON Validator