Atomics.compareExchange() - JavaScript

Atomics.compareExchange()
=========================

静的な **`Atomics.compareExchange()`** メソッドは、指定された値を配列内の指定した位置に格納し、その値を返します。これは、その位置での古い値が、期待された値と同じであったかどうかを返すものです。これは不可分操作で、変更された値が書き戻されるまで、他の書き込みが行われないことが保証されます。

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

構文
--

```js
Atomics.compareExchange(typedArray, index, expectedValue, replacementValue);
```

### 引数

`typedArray`

共有整数の型付き配列です。 `Int8Array`, `Uint8Array`, `Int16Array`, `Uint16Array`, `Int32Array`, `Uint32Array` の何れかです。

`index`

`typedArray` で `value` と交換する位置です。

`expectedValue`

等価性をチェックする値です。

`replacementValue`

交換する数値です。

### 返値

指定された位置 (`typedArray[index]`) にあった古い値です。

### 例外

* `typedArray` が許可された整数型の何れでもない場合、`TypeError` が発生します。
* `index` が `typedArray` の範囲を超えている場合、 `RangeError` が発生します。
例
-

### compareExchange() の使用

```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 7;

Atomics.compareExchange(ta, 0, 7, 12); // returns 7, the old value
Atomics.load(ta, 0); // 12
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.compareexchange |

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

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

関連情報
----

* `Atomics`
* `Atomics.exchange()`


Atomics.store() - JavaScript

Atomics.store()
===============

静的な **`Atomics.store()`** メソッドは、指定された値を配列内の指定した位置に格納し、その値を返します。

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

構文
--

```js
Atomics.store(typedArray, index, value);
```

### 引数

`typedArray`

整数の型付き配列です。 `Int8Array`, `Uint8Array`, `Int16Array`, `Uint16Array`, `Int32Array`, `Uint32Array` の何れかです。

`index`

`typedArray` で `value` を格納する位置です。

`value`

格納する値です。

### 返値

格納された値です。

### 例外

* `typedArray` が許可された整数型の何れでもない場合、`TypeError` が発生します。
* `index` が `typedArray` の範囲を超えている場合、 `RangeError` が発生します。
例
-

### store() の使用

```js
var sab = new SharedArrayBuffer(1024);
var ta = new Uint8Array(sab);

Atomics.store(ta, 0, 12); // 12
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.store |

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

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

関連情報
----

* `Atomics`
* `Atomics.load()`


Atomics.xor() - JavaScript

Atomics.xor()
=============

**`Atomics.xor()`** は静的メソッドで、配列内の指定した位置にある指定された値とのビット単位の XOR を計算し、その位置にあった古い値を返します。これは不可分操作であり、変更された値が書き戻されるまで他の書き込みが行われないことが保証されます。

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

構文
--

```js
Atomics.xor(typedArray, index, value);
```

### 引数

`typedArray`

整数の型付き配列です。 `Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array`、`BigUint64Array` のいずれかです。

`index`

`typedArray` の中でビット単位の XOR を計算する位置です。

`value`

ビット単位の XOR を計算する値です。

### 返値

指定された位置にあった古い値 (`typedArray[index]`) です。

### 例外

* `TypeError`: `typedArray` が許可されている整数の型ではなかった場合に発生します。
* `RangeError`: `index` が `typedArray` の範囲を超えていた場合に発生します。
解説
--

 ビット単位の XOR 演算は、 `a` と `b` が異なる場合に 1 になります。
 XOR 演算の真理値表は次の通りです。

| `a` | `b` | `a ^ b` |
| --- | --- | --- |
| 0 | 0 | 0 |
| 0 | 1 | 1 |
| 1 | 0 | 1 |
| 1 | 1 | 0 |

例えば、ビット単位の XOR では `5 ^ 1` の結果が `0100`、すなわち 10 進数で 4 になります。
```

5  0101
1  0001
   ----
4  0100
```

例
-

### xor の使用

```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 5;

Atomics.xor(ta, 0, 1); // 古い値である 5 を返す
Atomics.load(ta, 0); // 4
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.xor |

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

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

関連情報
----

* `Atomics`
* `Atomics.and()`
* `Atomics.or()`


Atomics.isLockFree() - JavaScript

Atomics.isLockFree()
====================

 静的な
 **`Atomics.isLockFree()`**
 メソッドは、 `Atomics` のメソッドが、要素のバイト数が指定された大きさである型付き配列に適用された場合、ロックまたは不可分のハードウェア操作を使用するかどうかを見極めるために使用されます。指定された大きさが整数型の TypedArray 型の BYTES\_PER\_ELEMENT プロパティのいずれでもない場合は、 `false` を返します。

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

構文
--

```js
Atomics.isLockFree(size);
```

### 引数

`size`

チェックするバイト単位の大きさです。

### 返値

`true` または `false` で、操作がロック不要であるかどうかを示します。

例
-

### isLockFree の使用

```js
Atomics.isLockFree(1); // true
Atomics.isLockFree(2); // true
Atomics.isLockFree(3); // false
Atomics.isLockFree(4); // true
Atomics.isLockFree(5); // false
Atomics.isLockFree(6); // false
Atomics.isLockFree(7); // false
Atomics.isLockFree(8); // true
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.islockfree |

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

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

関連情報
----

* `Atomics`


Atomics.wait() - JavaScript

Atomics.wait()
==============

**`Atomics.wait()`** は静的なメソッドで、 `Int32Array` 中の指定された位置に指定された値が保存されているかどうかを検証し、検証できるまでスリープ、もしくはタイムアウトします。返値は "`ok`", "`not-equal`", "`timed-out`" のいずれかです。

**メモ:** この操作は共有された `Int32Array` に対してのみ可能で、またメインスレッドでは実行できません。

構文
--

```js
Atomics.wait(typedArray, index, value);
Atomics.wait(typedArray, index, value, timeout);
```

### 引数

`typedArray`

共有された `Int32Array`。

`index`

待つ対象となる `typedArray` の中の位置。

`value`

期待される値。

`timeout` 省略可

ミリ秒で表した待ち時間。時間が指定されなかった場合は `Infinity`。

### 返値

文字列で、 "ok", "not-equal", or "timed-out" のいずれか。

### 例外

* typedArray が許可された整数型の何れでもない場合、`TypeError` が発生します。
* index が typedArray の範囲を超えている場合、 `RangeError` が発生します。
例
-

### wait() の使用

次のような共有された `Int32Array` があったとします。

```js
const sab = new SharedArrayBuffer(1024);
const int32 = new Int32Array(sab);
```

読み手のスレッドはスリープし、 0 番目の値が 0 であることを期待して待ちます。これが成立している間、処理は進みません。しかし、書き手のスレッドが新しい値を格納した場合、書き手のスレッドによって通知され、新しい値 (123) が返ります。

```js
Atomics.wait(int32, 0, 0);
console.log(int32[0]); // 123
```

書き手のスレッドは新しい値を格納し、待っているスレッドに書き込みが完了したことを知らせます。

```js
console.log(int32[0]); // 0;
Atomics.store(int32, 0, 123);
Atomics.notify(int32, 0, 1);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.wait |

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

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

関連情報
----

* `Atomics`
* `Atomics.notify()`


Atomics.sub() - JavaScript

Atomics.sub()
=============

静的な **`Atomics.sub()`** メソッドは、配列内の指定した位置の値から減算して、その場所にあった古い値を返します。この不可分操作は、修正された値が書き戻されるまで、ほかの書き込みが発生しないことを保証します。

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

構文
--

```js
Atomics.sub(typedArray, index, value);
```

### 引数

`typedArray`

整数の型付き配列です。 `Int8Array`, `Uint8Array`, `Int16Array`, `Uint16Array`, `Int32Array`, `Uint32Array`, `BigInt64Array`, `BigUint64Array` のいずれかです。

`index`

`typedArray` で `value` を減算する位置です。

`value`

減算する数値です。

### 返値

指定された位置 (`typedArray[index]`) にあった古い値です。

### 例外

* typedArray が許可された整数型の何れでもない場合、`TypeError` が発生します。
* index が typedArray の範囲を超えている場合、 `RangeError` が発生します。
例
-

### sub の使用

```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 48;

Atomics.sub(ta, 0, 12); // 古い値である 48 を返す
Atomics.load(ta, 0); // 36
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.sub |

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

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

関連情報
----

* `Atomics`
* `Atomics.add()`


Atomics.and() - JavaScript

Atomics.and()
=============

静的な **`Atomics.and()`** メソッドは、配列内の指定した位置の値に指定した値でビット単位の AND を計算し、その位置の古い値を返します。これは不可分操作で、修正された値が書き戻されるまで、他の書き込みが起こらないことを保証します。

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

構文
--

```js
Atomics.and(typedArray, index, value);
```

### 引数

`typedArray`

共有整数の型付き配列です。 `Int8Array`, `Uint8Array`, `Int16Array`, `Uint16Array`, `Int32Array`, `Uint32Array` の何れかです。

`index`

`typedArray` でビット単位の AND を計算する位置です。

`value`

ビット単位の AND を取る数値です。

### 返値

指定された位置 (`typedArray[index]`) にあった古い値です。

### 例外

* `typedArray` が許可された整数型の何れでもない場合、`TypeError` が発生します。
* `index` が `typedArray` の範囲を超えている場合、 `RangeError` が発生します。
解説
--

ビット単位の AND 操作は、 `a` と `b` の両方が 1 であった場合のみ 1 を生成します。 AND 操作の真理値表を示します。

| `a` | `b` | `a & b` |
| --- | --- | --- |
| 0 | 0 | 0 |
| 0 | 1 | 0 |
| 1 | 0 | 0 |
| 1 | 1 | 1 |

例えば、ビット単位の AND を `5 & 1` で行うと、結果は `0001` すなわち 10 進数で 1 となります。
```

5  0101
1  0001
   ----
1  0001
```

例
-

### and() の使用

```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 5;

Atomics.and(ta, 0, 1); // 古い値である 5 を返す
Atomics.load(ta, 0); // 1
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.and |

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

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

関連情報
----

* `Atomics`
* `Atomics.or()`
* `Atomics.xor()`


Atomics.add() - JavaScript

Atomics.add()
=============

静的な **`Atomics.add()`** メソッドは、配列内の指定した位置の値に加算して、その位置の古い値を返します。これは不可分操作で、修正された値が書き戻されるまで、他の書き込みが起こらないことを保証します。

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

構文
--

```js
Atomics.add(typedArray, index, value);
```

### 引数

`typedArray`

共有整数の型付き配列です。 `Int8Array`, `Uint8Array`, `Int16Array`, `Uint16Array`, `Int32Array`, `Uint32Array` の何れかです。

`index`

`typedArray` で `value` を加算する位置です。

`value`

加算する数値です。

### 返値

指定された位置 (`typedArray[index]`) にあった古い値です。

### 例外

* `typedArray` が許可された整数型の何れでもない場合、`TypeError` が発生します。
* `index` が `typedArray` の範囲を超えている場合、 `RangeError` が発生します。
例
-

### add() の使用

```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);

Atomics.add(ta, 0, 12); // 古い値である 0 を返す。
Atomics.load(ta, 0); // 12
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.add |

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

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

関連情報
----

* `Atomics`
* `Atomics.sub()`


Atomics.or() - JavaScript

Atomics.or()
============

静的な **`Atomics.or()`** メソッドは、配列内の指定した位置の値に指定した値でビット単位の OR を計算し、その位置にあった古い値を返します。これは不可分操作で、修正された値が書き戻されるまで、他の書き込みが起こらないことを保証します。

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

構文
--

```js
Atomics.or(typedArray, index, value);
```

### 引数

`typedArray`

整数の型付き配列です。 `Int8Array`, `Uint8Array`, `Int16Array`, `Uint16Array`, `Int32Array`, `Uint32Array`, `BigInt64Array`, `BigUint64Array` の何れかです。

`index`

`typedArray` でビット単位の OR を計算する位置です。

`value`

ビット単位の OR を取る数値です。

### 返値

指定された位置 (`typedArray[index]`) にあった古い値です。

### 例外

* `typedArray` が許可された整数型の何れでもない場合、`TypeError` が発生します。
* `index` が `typedArray` の範囲を超えている場合、 `RangeError` が発生します。
解説
--

ビット単位の OR 操作は、 a と b のどちらかが 1 であった場合に 1 を生成します。 OR 操作の真理値表を示します。

| `a` | `b` | `a | b` |
| --- | --- | --- |
| 0 | 0 | 0 |
| 0 | 1 | 1 |
| 1 | 0 | 1 |
| 1 | 1 | 1 |

例えば、ビット単位の OR を 5 | 1 で行うと、結果は 0101 すなわち 10 進数で 5 となります。
```

5  0101
1  0001
   ----
5  0101
```

例
-

### or の使用

```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 2;

Atomics.or(ta, 0, 1); // returns 2, the old value
Atomics.load(ta, 0); // 3
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.or |

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

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

関連情報
----

* `Atomics`
* `Atomics.and()`
* `Atomics.xor()`


Atomics.notify() - JavaScript

Atomics.notify()
================

静的メソッドである **`Atomics.notify()`** は、待ち行列で休眠状態にあるエージェントに通知します。

**メモ:** この操作は共有された `Int32Array` に対してのみ動作します。
 共有されていない `ArrayBuffer` オブジェクトでは `0` を返します。

構文
--

```js
Atomics.notify(typedArray, index, count);
```

### 引数

`typedArray`

共有された `Int32Array`。

`index`

起動する対象となる `typedArray` 中の位置。

`count` 省略可

通知する休眠状態のエージェントの数。既定値は `+Infinity` です。

### 返値

* 起動したエージェントの数を返します。
* 共有されていない `ArrayBuffer` オブジェクトが使用された場合は、 `0`
 を返します。
### 例外

* `typedArray` が許可された整数型の何れでもない場合、`TypeError` が発生します。
* `index` が `typedArray` の範囲を超えている場合、 `RangeError` が発生します。
例
-

### `notify` の使用

共有された `Int32Array` を用意します。

```js
const sab = new SharedArrayBuffer(1024);
const int32 = new Int32Array(sab);
```

読み手のスレッドは、0 番目の値が 0 であることを期待して休眠状態になります。それが満たされている間は処理が進みません。しかし、書き手のスレッドが新しい値を格納した場合、読み手のスレッドは書き手のスレッドによって起動され、新しい値 (123) を取得します。

```js
Atomics.wait(int32, 0, 0);
console.log(int32[0]); // 123
```

書き手のスレッドは新しい値を格納し、待機中のスレッドに通知を行います。

```js
console.log(int32[0]); // 0;
Atomics.store(int32, 0, 123);
Atomics.notify(int32, 0, 1);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.notify |

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

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

関連情報
----

* `Atomics`
* `Atomics.wait()`


Atomics.load() - JavaScript

Atomics.load()
==============

静的な **`Atomics.load()`** メソッドは、配列内の指定された位置の値を返します。

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

構文
--

```js
Atomics.load(typedArray, index);
```

### 引数

`typedArray`

整数の型付き配列です。 `Int8Array`, `Uint8Array`, `Int16Array`, `Uint16Array`, `Int32Array`, `Uint32Array` の何れかです。

`index`

`typedArray` の中で値を読み込む位置。

### 返値

指定された位置 (`typedArray[index]`) にある値です。

### 例外

* `typedArray` が許可された整数型の何れでもない場合、`TypeError` が発生します。
* `index` が `typedArray` の範囲を超えている場合、 `RangeError` が発生します。
例
-

### `load` の使用

```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);

Atomics.add(ta, 0, 12);
Atomics.load(ta, 0); // 12
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.load |

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

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

関連情報
----

* `Atomics`
* `Atomics.store()`


WeakRef() コンストラクター - JavaScript

WeakRef() コンストラクター
==================

**`WeakRef()`** コンストラクターは、 `WeakRef` オブジェクトを生成します。

構文
--

```js
new WeakRef(target)
```

**メモ:** `WeakRef()` は `new` との組み合わせでのみ構築されます。 `new` 無しで呼び出そうとすると `TypeError` が発生します。

### 引数

`target`

WeakRef の参照先となるターゲット値（リファレントとも呼ばれます）。オブジェクトまたは未登録のシンボルでなければなりません。

### 返値

指定されたターゲット地を参照する `WeakRef` オブジェクトです。

### 例外

`TypeError`

`target` がオブジェクトまたは未登録のシンボルではない場合に発生します。

例
-

### 新しい WeakRef オブジェクトの生成

完全な例は中心となる `WeakRef` ページを参照してください。

```js
class Counter {
  constructor(element) {
    // DOM 要素への弱い参照を覚える
    this.ref = new WeakRef(element);
    this.start();
  }
}
```

仕様書
---

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

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

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

関連情報
----

* `WeakRef`


WeakRef.prototype.deref() - JavaScript

WeakRef.prototype.deref()
=========================

`deref` メソッドは `WeakRef` インスタンスのターゲットオブジェクトを返します。そのオブジェクトが既にガベージコレクションされている場合は `undefined` を返します。

構文
--

```js
deref()
```

### 引数

なし。

### 返値

WeakRef の参照先となるターゲット値で、オブジェクトまたは未登録のシンボルでなければなりません。そのオブジェクトが既にガベージコレクションされている場合は `undefined` です。

解説
--

重要な注意事項については `WeakRef` ページの WeakRef の注意事項の節を参照してください。

例
-

### deref の使用

完全な例については `WeakRef` ページ内の例の節を参照してください。

```js
const tick = () => {
  // 弱参照から要素を取得する (まだ存在していれば)
  const element = this.ref.deref();
  if (element) {
    element.textContent = ++this.count;
  } else {
    // 要素が既に存在しない場合
    console.log("この要素は消滅しました");
    this.stop();
    this.ref = null;
  }
};
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-weak-ref.prototype.deref |

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

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

関連情報
----

* `WeakRef`


Number.parseInt() - JavaScript

Number.parseInt()
=================

**`Number.parseInt()`** は静的メソッドで、文字列の引数を解釈し、指定された基数の整数値を返します。

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

構文
--

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

### 引数

`string`

解釈する値で、文字列に変換されます。先頭のホワイトスペースは無視されます。

`radix` 省略可

`2` から `36` までの整数で、 `string` の*基数*（数学的記数法の底）を表します。

`radix` が未定義または `0` であった場合、通常は `10` と見なされますが、数値が `0x` または `0X` のコードの組み合わせであった場合は `16` と見なされます。

### 返値

指定された `string` を解析した整数値です。

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

例
-

### Number.parseInt と parseInt

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

```js
Number.parseInt === parseInt; // true
```

この目的は、グローバル値のモジュール化のためです。詳細や例は `parseInt()` を参照してください。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.parseint |

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

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

関連情報
----

* `Number.parseInt` のポリフィル (`core-js`)
* 所属先の `Number` オブジェクト
* グローバルメソッドの `parseInt()`


Number.POSITIVE_INFINITY - JavaScript

Number.POSITIVE\_INFINITY
=========================

**`Number.POSITIVE_INFINITY`** プロパティは正の無限大を表す値です。

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

値
-

グローバルの `Infinity` プロパティとの値と同じです。

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

解説
--

`Number.POSITIVE_INFINITY` の値は、数学的な無限大とは少々異なった振る舞いをします。

* `POSITIVE_INFINITY` も含む任意の正の値と、 `POSITIVE_INFINITY` の積は `POSITIVE_INFINITY` になります。
* `NEGATIVE_INFINITY` も含む任意の負の値と、 `POSITIVE_INFINITY` の積は `NEGATIVE_INFINITY` になります。
* 任意の正の数を `POSITIVE_INFINITY` で割った商は、正のゼロになります（IEEE 754 で定義されているとおり）。
* 任意の負の数を `POSITIVE_INFINITY` で割った商は、負のゼロになります（IEEE 754 で定義されているとおり）。
* 零 と `POSITIVE_INFINITY` の積は `NaN` になります。
* `NaN` と `POSITIVE_INFINITY` の積は `NaN` になります。
* `POSITIVE_INFINITY` を `NEGATIVE_INFINITY` 以外の任意の負の値で割った商は `NEGATIVE_INFINITY` になります。
* `POSITIVE_INFINITY` を `POSITIVE_INFINITY` 以外の任意の正の値で割った商は `POSITIVE_INFINITY` になります。
* `POSITIVE_INFINITY` を `NEGATIVE_INFINITY` と `POSITIVE_INFINITY` のどちらかで割った商は `NaN` になります。
* `Number.POSITIVE_INFINITY > x` は任意の数 *x* が `POSITIVE_INFINITY` でない場合に true になります。

成功した場合に有限数を返す関数がエラーである状態を示すために、`Number.POSITIVE_INFINITY` プロパティを使いたいかもしれません。しかし、そのような場合は `NaN` の方がより適しているでしょう。

`POSITIVE_INFINITY` は `Number` の静的プロパティですので、数値のプロパティとしてではなく、常に `Number.POSITIVE_INFINITY` として使用してください。

例
-

### POSITIVE\_INFINITY の使用

以下の例では、変数 `bigNumber` に最大値よりも大きな値が代入されています。`if` 文が実行されるとき、`bigNumber` は `Infinity` の値を持つので、処理が継続する前に `bigNumber` により扱いやすい値がセットされます。

```js
let bigNumber = Number.MAX\_VALUE \* 2;

if (bigNumber === Number.POSITIVE\_INFINITY) {
  bigNumber = returnFinite();
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.positive\_infinity |

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

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

関連情報
----

* `Number.NEGATIVE_INFINITY`
* `Number.isFinite()`
* `Infinity`
* `isFinite()`


Number() コンストラクター - JavaScript

Number() コンストラクター
=================

**`Number()`** コンストラクターは、 `Number` オブジェクトを生成します。関数として呼び出された場合は、数値型のプリミティブ値を返します。

構文
--

```js
new Number(value)
Number(value)
```

**メモ:** `Number()` は `new` を付けてもつけなくても呼び出せますが、効果は異なります。返値を参照してください。

### 引数

`value`

作成するオブジェクトの数値です。

### 返値

`Number` がコンストラクターとして（`new` 付きで）呼び出された場合は、`Number` オブジェクトを作成します。これはプリミティブでは**ありません**。

`Number` が関数として呼び出された場合、引数を数値プリミティブに変換します。長整数 (BigInt) は数値へ変換されます。値が変換できない場合は、`NaN` を返します。

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

例
-

### Number オブジェクトの生成

```js
const a = new Number("123"); // a === 123 は false
const b = Number("123"); // b === 123 は true
a instanceof Number; // は true
b instanceof Number; // は false
typeof a; // "object"
typeof b; // "number"
```

### Number() を使用して長整数を数値へ変換

`Number()` は、とても明示的なので、例外を発生させずに長整数 (BigInt) を数値に変換することができる唯一のケースです。

```js
+1n; // TypeError: Cannot convert a BigInt value to a number
0 + 1n; // TypeError: Cannot mix BigInt and other types, use explicit conversions
```

```js
Number(1n); // 1
```

なお、長整数が安全に表現するのに長すぎる場合、精度が下がることがあります。

```js
BigInt(Number(2n \*\* 54n + 1n)) === 2n \*\* 54n + 1n; // false
```

仕様書
---

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

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

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

関連情報
----

* 現在の `Number` の動作（2 進数と 8 進数のリテラルの対応あり）のポリフィル (`core-js`)
* `NaN`
* `Math` グローバルオブジェクト
* 可変精度の整数: `BigInt`


Number.MAX_SAFE_INTEGER - JavaScript

Number.MAX\_SAFE\_INTEGER
=========================

**`Number.MAX_SAFE_INTEGER`** 定数は、JavaScript における安全な整数の最大値 (253 – 1) を表します。

もっと大きな整数には、 `BigInt` を使用することを検討してください。

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

値
-

`9007199254740991` （9,007,199,254,740,991、または ~9 千兆）。

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

解説
--

倍精度浮動小数点型数値は仮数部を表わすのに 52 ビットしかないため、安全に表現できる整数は -(253 – 1) と 253 – 1 との間です。この文脈で示している「安全」とは、整数を正確に表現し、正しく比較する能力を指します。たとえば、 `Number.MAX_SAFE_INTEGER + 1 === Number.MAX_SAFE_INTEGER + 2` は、数学的には不正確ですが true と評価されます。詳細については `Number.isSafeInteger()` を見てください。

`MAX_SAFE_INTEGER` は `Number` の静的なプロパティなので、数値のプロパティとしてではなく、常に `Number.MAX_SAFE_INTEGER` として使うようにしてください。

例
-

### MAX\_SAFE\_INTEGER の返値

```js
Number.MAX\_SAFE\_INTEGER; // 9007199254740991
```

### MAX\_SAFE\_INTEGER と EPSILON の関係

`Number.EPSILON` は 2-52 であり、 `MAX_SAFE_INTEGER` は 253 - 1 です。どちらも仮数部の幅である 53 ビット（最上位ビットは常に 1）から来ています。これらを乗算すると、2 にとても近い（しかし等しくはない）値が得られます。

```js
Number.MAX\_SAFE\_INTEGER \* Number.EPSILON; // 1.9999999999999998
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.max\_safe\_integer |

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

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

関連情報
----

* `Number.MAX_SAFE_INTEGER` のポリフィル (`core-js`)
* `Number.MIN_SAFE_INTEGER`
* `Number.isSafeInteger()`
* `BigInt`


Number.MIN_VALUE - JavaScript

Number.MIN\_VALUE
=================

**`Number.MIN_VALUE`** 静的データプロパティは、 JavaScript において表すことが可能な最小の正の数値を表します。

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

値
-

2-1074、または `5E-324` です。

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

解説
--

`Number.MIN_VALUE` プロパティは、浮動小数点の精度で表すことができる最小の正の数です（最も小さな負の数ではありません）。言い換えれば、最も 0 に近い数です。ECMAScript の仕様書では、実装が対応する必要のある精度を定義していません。代わりに仕様書では、「その実装で実際に表すことができる、 0 ではない最も小さな正の数でなければならない」とあります。これは、小さな IEEE-754 浮動小数点数では非正規化されるためですが、実装するためにこの表現に対応する必要はなく、その場合は `Number.MIN_VALUE` が大きくなる可能性があります。

実際、V8（Chrome、Edge、Node.js で使用）、SpiderMonkey（Firefox で使用）、JavaScriptCore（Safari で使用）などの主なエンジンにおける正確な値は、 2-1074 または `5E-324` です。

`MIN_VALUE` は `Number` の静的プロパティですので、数値のプロパティとしてではなく、常に `Number.MIN_VALUE` として使用してください。

例
-

### MIN\_VALUE の使用

以下のコードは、2 つの数値を割り算しています。その結果が `MIN_VALUE` より大きいか等しい場合は、`func1` 関数が呼び出されます。それ以外の場合は、`func2` 関数が呼び出されます。

```js
if (num1 / num2 >= Number.MIN\_VALUE) {
  func1();
} else {
  func2();
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.min\_value |

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

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

関連情報
----

* `Number.MAX_VALUE`


Number.prototype.valueOf() - JavaScript

Number.prototype.valueOf()
==========================

**`valueOf()`** メソッドは `Number` オブジェクトがラップしているプリミティブ値を返します。

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

構文
--

```js
valueOf()
```

### 返値

指定した `Number` オブジェクトのプリミティブ値を表した数値です。

解説
--

このメソッドは、通常は JavaScript によって内部的に呼び出されるものであり、ウェブのコード中で明示的に呼び出されることはありません。

例
-

### valueOf の使用

```js
const numObj = new Number(10);
console.log(typeof numObj); // object

const num = numObj.valueOf();
console.log(num); // 10
console.log(typeof num); // number
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.valueof |

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

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

関連情報
----

* `Object.prototype.valueOf()`


Number.prototype.toString() - JavaScript

Number.prototype.toString()
===========================

**`toString()`** メソッドは、指定された数値を表現する文字列を返します。

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

構文
--

```js
toString()
toString(radix)
```

### 引数

`radix` 省略可

数値を表現するために使われる基数を指定する、 `2` から `36` までの整数です。既定値は 10 です。

### 返値

指定された数値を表現する文字列です。

例外
--

`RangeError`

`toString()` は、与えられた `radix` が `2` 未満、または `36` を超える場合、`RangeError` が発生します。

解説
--

`Number` オブジェクトは `Object` の `toString()` メソッドを上書きします。つまり、 `Object.prototype.toString()` を継承していません。`Number` の値では、`toString` メソッドは指定された基数でオブジェクトを表した文字列を返します。

10 より大きい基数では、 9 より大きい数をアルファベットの文字で示します。例えば、16 進表記（基数 16）では、`a` から `f` までが使われます。

`numObj` が負の場合、符号は保存されます。これは基数が 2 の場合も同様です。返される文字列は、`-` 記号で始まる数値の正の 2 進数表現であり、数値の 2 の補数では**ありません**。

`0` と `-0` はどちらも文字列表現が `"0"` となります。`Infinity` は `"Infinity"` を返し、 `NaN` は `"NaN"` を返します。

数値が整数でない場合、小数点 `.` を用いて小数点以下の位置を区切ります。科学的記数法は、基数が10で、数の大きさ（符号は無視）が 1021 以上、10-6 以下の場合に使用します。この場合、返す文字列は常に指数の符号を明示的に指定します。

```js
console.log((10 \*\* 21.5).toString()); // "3.1622776601683794e+21"
console.log((10 \*\* 21.5).toString(8)); // "526665530627250154000000"
```

この `toString()` メソッドは、`this` 値が数値プリミティブまたは `Number` ラッパーオブジェクトである必要があります。他の `this` 値に対しては、数値に変換しようとせずに `TypeError` を発生させます。

`Number` には `[@@toPrimitive]()` メソッドがないので、 `Number` *オブジェクト* がテンプレートリテラル などのように文字列を期待するコンテキストで用いられるとき、 JavaScript は `toString()` メソッドを自動的に呼び出します。しかし、数値プリミティブは `toString()` メソッドを参照して [coerced to strings] (/ja/docs/Web/JavaScript/Reference/Global\_Objects/String#string\_coercion) するのではなく、初期の `toString()` 実装と同じアルゴリズムを使用して直接変換される。

```js
Number.prototype.toString = () => "Overridden";
console.log(`${1}`); // "1"
console.log(`${new Number(1)}`); // "Overridden"
```

例
-

### toString の使用

```js
const count = 10;
console.log(count.toString()); // "10"

console.log((17).toString()); // "17"
console.log((17.2).toString()); // "17.2"

const x = 6;
console.log(x.toString(2)); // "110"
console.log((254).toString(16)); // "fe"
console.log((-10).toString(2)); // "-1010"
console.log((-0xff).toString(2)); // "-11111111"
```

### 数値文字列の基数変換

10 進数でない基数の数値を表す文字列がある場合、`parseInt()` と `toString()` を使用して別の基数に変換することが可能です。

```js
const hex = "CAFEBABE";
const bin = parseInt(hex, 16).toString(2); // "11001010111111101011101010111110"
```

精度の低下に注意してください。元となる数値文字列が大きすぎる（例えば `Number.MAX_SAFE_INTEGER` より大きい）場合、代わりに `BigInt` を使用してください。ただし、`BigInt` コンストラクタは、数値リテラルを表す文字列（`0b`, `0o`, `0x` から始まる文字列）にしか対応していません。元の基数が 2 進数、8 進数、10 進数、16 進数のいずれでもない場合は、基数変換を手で書くか、ライブラリーを使用する必要があるかもしれません。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.tostring |

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

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

関連情報
----

* `Number.prototype.toFixed()`
* `Number.prototype.toExponential()`
* `Number.prototype.toPrecision()`


Number.prototype.toFixed() - JavaScript

Number.prototype.toFixed()
==========================

**`toFixed()`** メソッドは、数を固定小数点表記を用いて整形します。

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

構文
--

```js
toFixed()
toFixed(digits)
```

### 引数

`digits` 省略可

小数点の後に現れる桁の数です。これは `0` 以上 `100` 以下の値です。この引数が省略されると、`0` として扱われます。

### 返値

与えられた数値を固定小数点表記を用いて表した文字列です。

例外
--

`RangeError`

`digits` が `0` 以上 `100` 以下ではない場合に発生します。

`TypeError`

このメソッドが `Number` ではないオブジェクト上で実行された場合に発生します。

解説
--

`toFixed()` メソッドは `numObj` の文字列表記を、指数表記を使用せず、小数点以下を正確に `digits` 桁として返します。必要に応じて数値は丸められ、小数部は指定された長さになるよう必要に応じて 0 で埋められます。

`numObj` の絶対値が `1e+21` 以上の場合は、このメソッドは単純に `Number.prototype.toString()` を呼び出し、指数表記での文字列を返します。`toFixed()` は `numObj` の値が有限数でない場合、`"Infinity"`、`"NaN"`、`"-Infinity"` の何れかを返します。

`toFixed()` の出力は、一部の値では `toString()` よりも正確かもしれませんが、これは `toString()` が隣の数値と区別できる程度の有効数字しか出力しないためです。例えば、次のようになります。

```js
(1000000000000000128).toString(); // '1000000000000000100'
(1000000000000000128).toFixed(0); // '1000000000000000128'
```

しかし、高すぎる `digits` の精度を選ぶと、10 進数の小数を浮動小数点で正確に表せないため、予期せぬ結果を返すことがあります。例えば次のようになります。

```js
(0.3).toFixed(50); // '0.29999999999999998889776975374843459576368331909180'
```

例
-

### toFixed() の使用

```js
const numObj = 12345.6789;

numObj.toFixed(); // '12346'。四捨五入され小数部がなくなる
numObj.toFixed(1); // '12345.7' を返す。切り上げ
numObj.toFixed(6); // '12345.678900'を返す。0 を追加
(1.23e20).toFixed(2); // '123000000000000000000.00'
(1.23e-10).toFixed(2); // '0.00'
(2.34).toFixed(1); // '2.3'
(2.35).toFixed(1); // '2.4'。切り上げ
(2.55).toFixed(1); // '2.5'
// 浮動小数点数で正確に表せず、最も近い浮動小数点数の
// 方が低いため、切り捨てられる。
(2.449999999999999999).toFixed(1); // '2.5'
// 2.45 との差が NUMBER.EPSILON 未満なので、切り上げ
// このリテラルは、実際には 2.45 と同じ数値をエンコードしている

(6.02 \* 10 \*\* 23).toFixed(50); // 6.019999999999999e+23; 巨大な数値は指数表記を使用
```

### toFixed() を負の数に使用

メンバーアクセスは単項マイナスよりも優先順位が高いので、文字列を取得するためには。負の数の式全体をグループ化する必要があります。

```js
-2.34.toFixed(1); // -2.3, a number
(-2.34).toFixed(1); // '-2.3'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.tofixed |

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

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

関連情報
----

* `Number.prototype.toExponential()`
* `Number.prototype.toPrecision()`
* `Number.prototype.toString()`
* `Number.EPSILON`


Number.prototype.toExponential() - JavaScript

Number.prototype.toExponential()
================================

**`toExponential()`** メソッドは `Number` オブジェクトを指数表記で表した文字列を返します。

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

構文
--

```js
toExponential()
toExponential(fractionDigits)
```

### 引数

`fractionDigits` 省略可

任意です。小数点の後の桁数を指定する整数です。既定値はその数を表すのに必要な数の桁です。

### 返値

`Number` オブジェクトを、指数表記 (小数点前は 1 桁、小数点の後は `fractionDigits` によって指定された桁で切り捨て) で表した文字列です。

### 例外

`RangeError`

`fractionDigits` が `1` 以上 `100` 以下ではない場合に発生します。

`TypeError`

このメソッドが `Number` ではないオブジェクトに対して呼び出された場合に発生します。

解説
--

`fractionDigits` 引数が省略された場合、小数点の後の桁数は、その値を特定するのに必要な桁数になります。

`toExponential` メソッドを 1 つの数値リテラル、または、指数も小数点もない数値リテラルに対して使用する場合、ドットが小数点として解釈されることを防ぐために、メソッド呼び出しに先立つドットの前に空白を置いてください。

引数 `fractionDigits` で指定された桁よりも多くの桁を持っている数の場合、その数は、`fractionDigits` の桁で表すことができる最も近い数で表されます。`toFixed()` メソッドの説明における概数表現の説明を参照してください。それは、`toExponential` メソッドにも適用されます。

例
-

### toExponential の使用

```js
const numObj = 77.1234;

console.log(numObj.toExponential()); // 7.71234e+1 と表示
console.log(numObj.toExponential(4)); // 7.7123e+1 と表示
console.log(numObj.toExponential(2)); // 7.71e+1 と表示
console.log((77.1234).toExponential()); // 7.71234e+1 と表示
console.log((77).toExponential()); // 7.7e+1 と表示
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.toexponential |

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

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

関連情報
----

* 多くのバグ修正を含んだ `Number.prototype.toExponential` のポリフィル が `core-js` で利用できます
* `Number.prototype.toFixed()`
* `Number.prototype.toPrecision()`
* `Number.prototype.toString()`


Number.NEGATIVE_INFINITY - JavaScript

Number.NEGATIVE\_INFINITY
=========================

**`Number.NEGATIVE_INFINITY`** プロパティは負の無限大を表す値です。

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

値
-

グローバルの `Infinity` プロパティの負の値と同じです。

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

解説
--

`Number.NEGATIVE_INFINITY` の値は、数学的な無限大とは少々異なった振る舞いをします。

* `POSITIVE_INFINITY` も含む任意の正の値と、 `NEGATIVE_INFINITY` の積は `NEGATIVE_INFINITY` になります。
* `NEGATIVE_INFINITY` も含む任意の負の値と、 `NEGATIVE_INFINITY` の積は `POSITIVE_INFINITY` になります。
* 任意の正の数を `NEGATIVE_INFINITY` で割った商は、負のゼロになります（IEEE 754 で定義されているとおり）。
* 任意の負の数を `NEGATIVE_INFINITY` で割った商は、正のゼロになります（IEEE 754 で定義されているとおり）。
* 零 と `NEGATIVE_INFINITY` の積は `NaN` になります。
* NaN と `NEGATIVE_INFINITY` の積は `NaN` になります。
* `NEGATIVE_INFINITY` を `NEGATIVE_INFINITY` 以外の任意の負の値で割った商は `POSITIVE_INFINITY` になります。
* `NEGATIVE_INFINITY` を `POSITIVE_INFINITY` 以外の任意の正の値で割った商は `NEGATIVE_INFINITY` になります。
* `NEGATIVE_INFINITY` を `NEGATIVE_INFINITY` または `POSITIVE_INFINITY` のいずれかで割った商は `NaN` になります。
* `x > Number.NEGATIVE_INFINITY` は *x* の値が `NEGATIVE_INFINITY` ではない場合に true になります。

成功した場合に有限数を返す関数がエラーである状態を示すために、`Number.NEGATIVE_INFINITY` プロパティを使いたいかもしれません。しかし、そのような場合は `NaN` の方がより適しているでしょう。

`NEGATIVE_INFINITY` は `Number` の静的プロパティですので、数値のプロパティとしてではなく、常に `Number.NEGATIVE_INFINITY` として使用してください。

例
-

### NEGATIVE\_INFINITY の使用

以下の例では、変数 `smallNumber` に最小値よりも小さな値が代入されています。`if` ステートメントが実行されたとき、`smallNumber` は `-Infinity` の値を持つので、処理が継続する前に `smallNumber` により扱いやすい値がセットされます。

```js
let smallNumber = -Number.MAX\_VALUE \* 2;

if (smallNumber === Number.NEGATIVE\_INFINITY) {
  smallNumber = returnFinite();
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.negative\_infinity |

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

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

関連情報
----

* `Number.POSITIVE_INFINITY`
* `Number.isFinite()`
* `Infinity`
* `isFinite()`


Number.MAX_VALUE - JavaScript

Number.MAX\_VALUE
=================

**`Number.MAX_VALUE`** 静的データプロパティは、 JavaScript において表すことが可能な最大の数値を表します。

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

値
-

21024 - 1、またはおよそ `1.7976931348623157E+308` です。

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

解説
--

`MAX_VALUE` よりも大きな数値は `Infinity` で表され、正確な値が失われます。

`MAX_VALUE` は `Number` の静的プロパティですので、 数値のプロパティとしてではなく、常に `Number.MAX_VALUE` として使用してください。

例
-

### MAX\_VALUE の使用

以下のコードは、2 つの数値を掛け算しています。その結果が `MAX_VALUE` より小さいか等しい場合は、`func1` 関数が呼び出されます。それ以外の場合は、`func2` 関数が呼び出されます。

```js
if (num1 \* num2 <= Number.MAX\_VALUE) {
  func1();
} else {
  func2();
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.max\_value |

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

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

関連情報
----

* `Number.MIN_VALUE`
* 所属先の `Number` オブジェクト


Number.prototype.toLocaleString() - JavaScript

Number.prototype.toLocaleString()
=================================

**`toLocaleString()`** メソッドは、この数値を表す言語依存の文字列を返します。 `Intl.NumberFormat` API に対応している実装においては、このメソッドは単に `Intl.NumberFormat` を呼び出します。

数多くの数値を書式化する場合は、 `Intl.NumberFormat` オブジェクトを作成して `format()` メソッドで提供される機能を使用してください。

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

構文
--

```js
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
```

### 引数

`locales` および `options` 引数で機能の動作をカスタマイズすることができ、アプリケーションが書式化の習慣を用いる言語を指定することができます。

`Intl.NumberFormat` API に対応している実装では、これらの引数は正確に `Intl.NumberFormat()` コンストラクターの引数に対応します。`Intl.NumberFormat` に対応していない実装では、引数を無視するように求められ、使用するロケールと返す文字列の形式を完全に実装に依存するようになります。

`locales` 省略可

BCP 47 言語タグを持つ文字列、またはそのような文字列の配列。`Intl.NumberFormat()` コンストラクターの `locales` 引数に対応します。

`Intl.NumberFormat` の対応がない実装では、この引数は無視され、普通はホストのロケールが使用されます。

`options` 省略可

出力する書式を調整するオブジェクトです。`Intl.NumberFormat()` コンストラクターの `options` 引数に対応します。

`Intl.NumberFormat` の対応がない実装では、この引数は無視されます。

引数と使い方について詳しくは、`Intl.NumberFormat()`
コンストラクターを参照してください。

### 返値

指定された数値の言語依存の表現による文字列です。

`Intl.NumberFormat` のある実装では、これは `new Intl.NumberFormat(locales, options).format(number)` と等価です。

例
-

### toLocaleString() の使用

ロケールを指定しない基本的な使用です。既定のロケールと既定のオプションの整形された文字列が返されます。

```js
const number = 3500;

console.log(number.toLocaleString()); // アメリカ英語のロケールでは "3,500" を表示
```

### locales および options 引数に対応しているかどうかを調べる

`locales` および `options` 引数は、すべての実装で対応していない可能性があります。国際化 API の対応はオプションであり、システムによっては必要なデータを持っていないこともあるためです。国際化対応のない実装の場合、`toLocaleString()` は常にシステムのロケールを使用しますが、これは望むものとは異なるかもしれません。なぜなら、 `locales` および `options` 引数に対応している実装は、 `Intl` API に対応している必要があるからです。後者の存在を調べて対応することができます：

```js
function toLocaleStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.NumberFormat === "function"
  );
}
```

### locales の使用

この例ではローカライズされた数値変換のバリエーションのいくつかを示します。アプリケーションのユーザーインターフェイスで使われる言語の形式を得るために、`locales` 引数を用いている言語（そしておそらくいくつかの代替言語）を明示することを確かめてください。

```js
const number = 123456.789;

// ドイツ語では小数点にカンマを用い、千の桁区切りにピリオドを用いる
console.log(number.toLocaleString("de-DE"));
// → 123.456,789

// 多くのアラビア語圏の国のアラビア語では、東アラビア数字を用いる
console.log(number.toLocaleString("ar-EG"));
// → ١٢٣٤٥٦٫٧٨٩

// インド語では thousands/lakh/crore の区切りを用いる
console.log(number.toLocaleString("en-IN"));
// → 1,23,456.789

// nu 拡張キーでは、漢数字などの計数法をリクエストする
console.log(number.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// → 一二三,四五六.七八九

// バリ語など対応していない可能性のある言語をリクエストする場合は、
// 予備の言語 (この場合はインドネシア語) を含める
console.log(number.toLocaleString(["ban", "id"]));
// → 123.456,789
```

### options の使用

`toLocaleString` によって得られる結果は `options` 引数を使用してカスタマイズできます。

```js
const number = 123456.789;

// 通貨形式をリクエスト
console.log(
  number.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// → 123.456,79 €

// 日本円には副単位がない
console.log(
  number.toLocaleString("ja-JP", { style: "currency", currency: "JPY" }),
);
// → ￥123,457

// 有効桁数を 3 桁に制限
console.log(number.toLocaleString("en-IN", { maximumSignificantDigits: 3 }));
// → 1,23,000

// 数値の書式化にホストの既定の言語とオプションを使用する
const num = 30000.65;
console.log(
  num.toLocaleString(undefined, {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  }),
);
// → "30,000.65"（既定の言語が英語の場合）
// → "30.000,65"（既定の言語がドイツ語の場合）
// → "30 000,65"（既定の言語がフランス語の場合）
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.tolocalestring |
| ECMAScript Internationalization API Specification # sup-number.prototype.tolocalestring |

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

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

関連情報
----

* `Number.prototype.toString()`


Number.isSafeInteger() - JavaScript

Number.isSafeInteger()
======================

**`Number.isSafeInteger()`** は静的メソッドで、指定された値が*安全な整数*であるかどうかを判定します。

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

構文
--

```js
Number.isSafeInteger(testValue)
```

### 引数

`testValue`

安全な整数かどうかをテストする値です。

### 返値

論理値で、与えられた数値が安全な整数である数値であれば `true` を返します。そうでなければ `false` です。

解説
--

安全な整数とは、 -(253 - 1) から 253 - 1 までのすべての整数であり、両端を含みます (±9,007,199,254,740,991)。安全な整数は次のようなものです。

* 正確に IEEE-754 倍精度数として表現することができる
* その IEEE-754 表現は、他の整数を IEEE-754 の表現に適合するように、丸めた結果にはならない

例えば、253 - 1 は安全な整数です。正確に表現することができ、他の整数は、どの IEEE-754 丸めモードの下で丸めたものにもなっていません。対照的に、253 は安全な整数では*ありません*。これは IEEE-754 で正確に表現できますが、整数値 253 + 1 は直接 IEEE-754 では表現できず、四捨五入や切り捨ての丸めによって 253 になるからです。

完全な精度で ~9 千兆より大きい値や小さい値を扱うには、任意精度演算ライブラリーを使用する必要があります。数値の浮動小数点表現の詳細については、 What Every Programmer Needs to Know about Floating Point Arithmetic を参照してください。s

巨大な整数値については、 `BigInt` 型を使用することを検討してください。

例
-

### isSafeInteger() の使用

```js
Number.isSafeInteger(3); // true
Number.isSafeInteger(2 \*\* 53); // false
Number.isSafeInteger(2 \*\* 53 - 1); // true
Number.isSafeInteger(NaN); // false
Number.isSafeInteger(Infinity); // false
Number.isSafeInteger("3"); // false
Number.isSafeInteger(3.1); // false
Number.isSafeInteger(3.0); // true
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.issafeinteger |

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

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

関連情報
----

* `Number.isSafeInteger` のポリフィル (`core-js`)
* 所属先の `Number` オブジェクト
* `Number.MIN_SAFE_INTEGER`
* `Number.MAX_SAFE_INTEGER`
* `BigInt`


Number.MIN_SAFE_INTEGER - JavaScript

Number.MIN\_SAFE\_INTEGER
=========================

**`Number.MIN_SAFE_INTEGER`** 静的データプロパティは、JavaScript における安全な整数の最小値 (-(253 - 1)) を表します。

これよりも小さな整数値を表す場合は、 `BigInt` を使用することを検討してください。

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

値
-

`-9007199254740991`（-9,007,199,254,740,991、またはおよそ -9 千兆）です。

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

解説
--

倍精度浮動小数点型数値は仮数部を表わすのに 52 ビットしかないため、安全に表現できる整数は -(253 – 1) と 253 – 1 との間です。この文脈で示している「安全」とは、整数を正確に表現し、正しく比較する能力を指します。たとえば、 `Number.MIN_SAFE_INTEGER - 1 === Number.MIN_SAFE_INTEGER - 2` は、数学的には不正確ですが true と評価されます。詳細については `Number.isSafeInteger()` を見てください。

`MIN_SAFE_INTEGER` は `Number` の静的プロパティですので、 数値のプロパティとしてではなく、常に `Number.MIN_SAFE_INTEGER` として使用してください。

例
-

### MIN\_SAFE\_INTEGER の使用

```js
Number.MIN\_SAFE\_INTEGER; // -9007199254740991
-(2 \*\* 53 - 1); // -9007199254740991
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.min\_safe\_integer |

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

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

関連情報
----

* `Number.MIN_SAFE_INTEGER` のポリフィル (`core-js`)
* `Number.MAX_SAFE_INTEGER`
* `Number.isSafeInteger()`
* `BigInt`


Number.isNaN() - JavaScript

Number.isNaN()
==============

**`Number.isNaN()`** は静的メソッドで、渡された値が数値型の `NaN` であるかどうかを判定します。入力が数値型でなかった場合は `false` を返します。元となるグローバルの `isNaN()` よりも堅牢な版です。

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

構文
--

```js
Number.isNaN(value)
```

### 引数

`value`

`NaN` かどうか検査される値です。

### 返値

論理値で、与えられた値が数値で、かつ値が `NaN` である場合は `true` を返します。そうでなければ `false` です。

解説
--

`Number.isNaN()` 関数は、`NaN` と等しいことをチェックする便利な方法を提供します。なお、`NaN` と等しいことは `==` 演算子でも `===` 演算子でも検査できません。JavaScript の他のすべての値との比較とは異なり、一方のオペランドが `NaN` であれば、もう一方のオペランドが `NaN` であっても `false` と評価します。

JavaScript の有効なすべての値の中で、`x !== x` は `NaN` だけが true になりますので、`Number.isNaN(x)` は `x !== x` の検査を置き換えることができますが、後者の方が可読性が低くなります。

グローバルの `isNaN()` 関数とは異なり、 `Number.isNaN()` は強制的に引数が数値に変換される問題の影響をうけません。これにより、通常 `NaN` に変換されるが実際には `NaN` ではない値が、安全に渡されます。つまりこの関数は、数値型であり、かつ `NaN` である値が渡されたときのみ、 `true` を返すということです。

例
-

### isNaN() の使用

```js
Number.isNaN(NaN); // true
Number.isNaN(Number.NaN); // true
Number.isNaN(0 / 0); // true
Number.isNaN(37); // false
```

### Number.isNaN() とグローバルの isNaN() の相違点

`Number.isNaN()` は引数を数値へ変換することを試みないので、数値でないものはすべて `false` を返します。以下のものはすべて `false` になります。

```js
Number.isNaN("NaN");
Number.isNaN(undefined);
Number.isNaN({});
Number.isNaN("blabla");
Number.isNaN(true);
Number.isNaN(null);
Number.isNaN("37");
Number.isNaN("37.37");
Number.isNaN("");
Number.isNaN(" ");
```

グローバルの `isNaN()` は、引数を数値に変換します。

```js
isNaN("NaN"); // true
isNaN(undefined); // true
isNaN({}); // true
isNaN("blabla"); // true
isNaN(true); // false、これは 1 に変換される
isNaN(null); // false、これは 0 に変換される
isNaN("37"); // false、これは 37 に変換される
isNaN("37.37"); // false、これは 37.37 に変換される
isNaN(""); // false、これは 0 に変換される
isNaN(" "); // false、これは 0 に変換される
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.isnan |

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

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

関連情報
----

* `Number.isNaN` のポリフィル (`core-js`)
* `Number`
* `isNaN()`


Number.NaN - JavaScript

Number.NaN
==========

**`Number.NaN`** 静的データプロパティは非数 (Not-A-Number) を表す値であり、`NaN` と同じです。`NaN` の動作についての詳しい情報は、グローバルプロパティの説明を参照してください。

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

値
-

数値 `NaN` です。

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

解説
--

`NaN` は `Number` の静的プロパティですので、数値のプロパティとしてではなく、常に `Number.NaN` として使用してください。

例
-

### 値が数値であるかどうかのチェック

```js
function sanitize(x) {
  if (isNaN(x)) {
    return Number.NaN;
  }
  return x;
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.nan |

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

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

関連情報
----

* `NaN`
* `Number.isNaN()`


Number.isInteger() - JavaScript

Number.isInteger()
==================

**`Number.isInteger()`** は静的メソッドで、渡された値が整数かどうかを判定します。

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

構文
--

```js
Number.isInteger(value)
```

### 引数

`value`

整数かどうかを判定される値です。

### 返値

論理値で、渡された値が整数であれば `true` です。それ以外の場合は `false` です。

解説
--

指定された値が整数の場合は `true` を返し、そうでない場合は `false` を返します。`NaN` もしくは `Infinity` の場合も `false` を返します。このメソッドは整数として表すことができる浮動小数点数も `true` を返します。値が数値でない場合は常に `false` を返します。

数値リテラルの中には、ECMAScript の浮動小数点数エンコーディング (IEEE-754) の精度制限により、整数でないように見えても実は整数を表しているものがあることに注意してください。例えば、`5.0000000000000001` は `5` と `1e-16` だけ異なりますが、これは小さすぎて表しきれません。（参考までに、`Number.EPSILON` は、1 と 1 より大きい次の表現可能な浮動小数点数の間の距離を格納しており、それはおよそ `2.22e-16` です）。したがって、`5.0000000000000001` は `5` と同じエンコーディングで表されますので、`Number.isInteger(5.000000000001)` は `true` を返すことになります。

同様の意味で、`Number.MAX_SAFE_INTEGER` の大きさ前後の数値は精度を失い、整数でなくても `Number.isInteger` が `true`を返すようになる。（実際の閾値は、10 進数を表すのに何ビット必要かによって変わります。例えば、 `Number.isInteger(450000000000.1)` は `true` ですが、 `Number.isInteger(450000000000.5)` は `false` です。）

例
-

### isInteger の使用

```js
Number.isInteger(0); // true
Number.isInteger(1); // true
Number.isInteger(-100000); // true
Number.isInteger(99999999999999999999999); // true

Number.isInteger(0.1); // false
Number.isInteger(Math.PI); // false

Number.isInteger(NaN); // false
Number.isInteger(Infinity); // false
Number.isInteger(-Infinity); // false
Number.isInteger("10"); // false
Number.isInteger(true); // false
Number.isInteger(false); // false
Number.isInteger([1]); // false

Number.isInteger(5.0); // true
Number.isInteger(5.000000000000001); // false
Number.isInteger(5.0000000000000001); // true（精度が落ちるため）
Number.isInteger(4500000000000000.1); // true（精度が落ちるため）
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.isinteger |

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

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

関連情報
----

* `Number.isInteger` のポリフィル (`core-js`)
* このメソッドが所属している `Number` オブジェクト。


Number.parseFloat() - JavaScript

Number.parseFloat()
===================

**`Number.parseFloat()`** は静的メソッドで、引数を解釈して浮動小数点値を返します。引数の数値が解釈できない場合は、 `NaN` を返します。

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

構文
--

```js
Number.parseFloat(string)
```

### 引数

`string`

解釈する値で、文字列に変換されます。先頭のホワイトスペースは無視されます。

### 返値

指定された `string` を解釈した浮動小数点値です。

または、最初のホワイトスペース以外の文字が数値に変換できなかった場合は `NaN` です。

例
-

### Number.parseFloat と parseFloat

このメソッドは、グローバルの `parseFloat()` 関数と同じ機能を持っています。

```js
Number.parseFloat === parseFloat; // true
```

この目的は、グローバルのモジュール化にあります。

さらなる詳細と例は `parseFloat()` を参照してください。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.parsefloat |

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

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

関連情報
----

* `Number.parseFloat` のポリフィル (`core-js`)
* `Number`: このメソッドが所属するオブジェクト
* グローバルの `parseFloat()` メソッド


Number.isFinite() - JavaScript

Number.isFinite()
=================

**`Number.isFinite()`** は静的メソッドで、渡された値が有限数であるかどうかを判断します。すなわち、指定された値が数値型であり、その数値が正の無限大 (`Infinity`)、負の無限大 (`Infinity`)、非数 (`NaN`) のどれでもないことをチェックします。

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

構文
--

```js
Number.isFinite(value)
```

### 引数

`value`

有限数かどうかテストされる値。

### 返値

与えられた値が有限数かどうかを示す論理値です。

例
-

### isFinite() の使用

```js
Number.isFinite(Infinity); // false
Number.isFinite(NaN); // false
Number.isFinite(-Infinity); // false

Number.isFinite(0); // true
Number.isFinite(2e64); // true
```

### Number.isFinite() とグローバルの isFinite() との違い

グローバルの `isFinite()` 関数と比較すると、このメソッドは最初に引数を数値に変換しません。すなわち、数値型の値で、それが有限数でもある場合のみ `true` を返し、非数については常に `false` を返すということです。

```js
isFinite("0"); // true; coerced to number 0
Number.isFinite("0"); // false
isFinite(null); // true; coerced to number 0
Number.isFinite(null); // false
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.isfinite |

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

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

関連情報
----

* `Number.isFinite` のポリフィル (`core-js`)
* このメソッドが所属している `Number` オブジェクト
* グローバル関数 `isFinite`


Number.prototype.toPrecision() - JavaScript

Number.prototype.toPrecision()
==============================

**`toPrecision()`** メソッドは `Number` オブジェクトを指定された精度で表した文字列を返します。

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

構文
--

```js
toPrecision()
toPrecision(precision)
```

### 引数

`precision` 省略可

有効数字の数を指定する整数です。

### 返値

`Number` オブジェクトを `precision` で指定された桁で概数化された、固定小数点数、または指数表記で表した文字列です。概数の表現方法については `Number.prototype.toFixed()` メソッドの説明を参照してください。それは `toPrecision()` にも適用されます。

引数 `precision` が省略された場合、 `Number.prototype.toString()` のように振舞います。 `precision` が整数の値ではない場合は、最も近い整数に概数化されます。

例外
--

`RangeError`

`precision` が `1` 以上 100 以下の範囲にない場合に発生します。

例
-

### `toPrecision` の使用

```js
let num = 5.123456;

console.log(num.toPrecision()); // '5.123456'
console.log(num.toPrecision(5)); // '5.1235'
console.log(num.toPrecision(2)); // '5.1'
console.log(num.toPrecision(1)); // '5'

num = 0.000123;

console.log(num.toPrecision()); // '0.000123'
console.log(num.toPrecision(5)); // '0.00012300'
console.log(num.toPrecision(2)); // '0.00012'
console.log(num.toPrecision(1)); // '0.0001'

// なお、場合によっては指数表記が返されることがあります。
console.log((1234.5).toPrecision(2)); // '1.2e+3'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.toprecision |

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

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

関連情報
----

* `Number.prototype.toFixed()`
* `Number.prototype.toExponential()`
* `Number.prototype.toString()`


Number.EPSILON - JavaScript

Number.EPSILON
==============

**`Number.EPSILON`** プロパティは、1 と 1 より大きな最小の浮動小数点数の差を表します。

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

値
-

2-52、またはおよそ `2.2204460492503130808472633361816E-16`。

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

解説
--

`Number.EPSILON` は、1 と数値形式で表現できる次に大きな数値との差です。これは、倍精度浮動小数点数形式では仮数部を 52 ビットでしか表現できず、最低ビットは 2-52 で表されるためです。

なお、浮動小数点数の絶対精度は、数が大きくなるにつれ、指数が大きくなる一方で仮数部の精度は変わらないため、低下します。`Number.MIN_VALUE` は表現可能な正の数の最小値であり、`Number.EPSILON` よりもはるかに小さいものです

`EPSILON` は `Number` の静的プロパティなので、数値のプロパティとしてではなく、常に `Number.EPSILON` として使用しています。

例
-

### 同等性のテスト

10 進数や 2 進数など、どのような基数を選んでも、有限のビット数を占める数字エンコーディングシステムは、必然的にすべての数字を正確に表すことができません。なぜなら、有限のメモリーを使用して、数直線上の無限の点を表現しようとすることになるからです。例えば、10 進法では 1/3 を正確に表せませんし、2 進法では `0.1`を正確に表せません。したがって、例えば、`0.1 + 0.2` は `0.3` と正確に等しくはなりません。

```js
console.log(0.1 + 0.2); // 0.30000000000000004
console.log(0.1 + 0.2 === 0.3); // false
```

このため、**浮動小数点数で `===` と比較してはいけない**というアドバイスがたくさんあります。その代わりに、異なる 2 種類の数値が十分に近い場合には、等しいとみなすことができます。`EPSILON`は、要するに `1` という数字がどの程度正確かを指定するものなので、演算結果が `1` 程度の大きさであれば、通常 `Number.EPSILON` 定数がエラーに対する妥当な閾値となります。

```js
function equal(x, y) {
  return Math.abs(x - y) < Number.EPSILON;
}

const x = 0.2;
const y = 0.3;
const z = 0.1;
console.log(equal(x + z, y)); // true
```

しかし、`Number.EPSILON` は、それ以上の大きさの演算処理を行う場合には不適切です。もしデータが 103 程度の大きさであれば、小数点以下の部分は `Number.EPSILON` よりもずっと小さな精度を持つことになります。

```js
function equal(x, y) {
  return Math.abs(x - y) < Number.EPSILON;
}

const x = 1000.1;
const y = 1000.2;
const z = 2000.3;
console.log(x + y); // 2000.3000000000002; error of 10^-13 instead of 10^-16
console.log(equal(x + y, z)); // false
```

この場合、より大きな公差が必要となります。比較する数値の大きさはおよそ `2000` であるので、`2000 * Number.EPSILON` のような乗数で、この例では十分な許容範囲を作ることができます。

```js
function equal(x, y, tolerance = Number.EPSILON) {
  return Math.abs(x - y) < tolerance;
}

const x = 1000.1;
const y = 1000.2;
const z = 2000.3;
console.log(equal(x + y, z, 2000 \* Number.EPSILON)); // true
```

大きさだけでなく、入力の*精度*も考慮することが重要です。例えば、数値がフォーム入力から収集され、入力値が `0.1` のステップでしか調整できない場合（すなわち `<input type="number" step="0.1">`）、データは `0.1` の精度しかないので通常は `0.01` など、はるかに大きな許容差を認めることを意味します。

**メモ:** 有益な教訓：等値検査の閾値として、単純に `Number.EPSILON` を使用しないでくださ い。比較する数値の大きさや精度に適した閾値を使用してください。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.epsilon |

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

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

関連情報
----

* `Number.EPSILON` のポリフィル (`core-js`)
* 所属先の `Number` オブジェクト


Symbol.match - JavaScript

Symbol.match
============

**`Symbol.match`** は、文字列に対して正規表現のマッチングを指定します。この関数は `String.prototype.match()` メソッドによって呼び出されます。

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

説明
--

この関数は、オブジェクトが正規表現の動作をするかどうかを識別するためにも使用されます。たとえば、`String.prototype.startsWith()`, `String.prototype.endsWith()`, `String.prototype.includes()` メソッドは、最初の引数が正規表現であるかどうかを確認し、正規表現である場合は `TypeError` を投げます。ここで、`一致`記号が `false`（または偽値）に設定されている場合、そのオブジェクトが正規表現オブジェクトとして使用されることを意図していないことを示します。

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

例
-

### `isRegExp` チェックを無効にする

以下のコードは `TypeError` を投げます。

```js
"/bar/".startsWith(/bar/);

// Throws TypeError, as /bar/ is a regular expression
// and Symbol.match is not modified.
```

ただし、`Symbol.match` を `false` に設定すると、（`match` プロパティを使用する）`isRegExp` チェックは、オブジェクトが正規表現オブジェクトではないことを示します。結果として、`startsWith` と `endsWith` メソッドは、TypeError を投げません。

```js
var re = /foo/;
re[Symbol.match] = false;
"/foo/".startsWith(re); // true
"/baz/".endsWith(re); // false
```

仕様
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.match |

ブラウザー実装状況
---------

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

関連情報
----

* `Symbol.replace`
* `Symbol.search`
* `Symbol.split`
* `RegExp.prototype[@@match]()`


Symbol.keyFor() - JavaScript

Symbol.keyFor()
===============

**`Symbol.keyFor(sym)`** メソッドは、指定されたシンボルについて、共有シンボルキーをグローバルシンボルレジストリから受け取ります。

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

構文
--
```

Symbol.keyFor(sym);
```

### 引数

`sym`

シンボル、必須。キーを探すシンボル。

### 返値

グローバルレジストリで見つかった場合は、与えられたシンボルのキーを表す文字列です。それ以外の場合は `undefined` です。

例
-

### keyFor() の使用

```js
var globalSym = Symbol.for("foo"); // create a new global symbol
Symbol.keyFor(globalSym); // "foo"

var localSym = Symbol();
Symbol.keyFor(localSym); // undefined

// well-known symbols are not symbols registered
// in the global symbol registry
Symbol.keyFor(Symbol.iterator); // undefined
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.keyfor |

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

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

関連情報
----

* `Symbol.for()`


Symbol.prototype.toString() - JavaScript

Symbol.prototype.toString()
===========================

**`toString()`** メソッドは、指定された `Symbol` オブジェクトを表す文字列を返します。

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

構文
--
```

Symbol().toString()
```

### 返値

指定された `Symbol` オブジェクトを表す文字列です。

解説
--

`Symbol` オブジェクトは `Object` オブジェクトの `toString` メソッドをオーバーライドします。 `Object.prototype.toString()` を継承していません。 `Symbol` オブジェクトでは `toString` メソッドはオブジェクトの文字列表現を返します。

### 文字列への型変換はない

シンボルに対しては `toString()` を呼び出すことができるため、文字列への型変換はありません。

```js
Symbol("foo") + "bar"; // TypeError: Can't convert symbol to string
```

例
-

### toString() の使用

```js
Symbol("desc").toString(); // "Symbol(desc)"

// ウェルノウンシンボル
Symbol.iterator.toString(); // "Symbol(Symbol.iterator)

// グローバルシンボル
Symbol.for("foo").toString(); // "Symbol(foo)"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.prototype.tostring |

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

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

関連情報
----

* `Object.prototype.toString()`


Symbol.matchAll - JavaScript

Symbol.matchAll
===============

**`Symbol.matchAll`** は、文字列に対する正規表現の一致を生成するイテレーターを返します。この関数は `String.prototype.matchAll()` メソッドによって呼び出されます。

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

説明
--

このシンボルは `String.prototype.matchAll()`、特に `RegExp.prototype[@@matchAll]()` で使用されます。以下の 2 つの例は同じ結果を返します。

```js
"abc".matchAll(/a/);

/a/[Symbol.matchAll]("abc");
```

このメソッドは、`RegExp` サブクラス内の一致動作をカスタマイズするために存在します。

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

例
-

### Symbol.matchAll を使用する

```js
let re = /[0-9]+/g;
let str = "2016-01-02|2019-03-07";

const numbers = {
  \*[Symbol.matchAll](str) {
    for (const n of str.matchAll(/[0-9]+/g)) yield n[0];
  },
};

console.log(Array.from(str.matchAll(numbers)));
// Array ["2016", "01", "02", "2019", "03", "07"]
```

その他の例については、`String.prototype.matchAll()` と `RegExp.prototype[@@matchAll]()` を参照してください。

仕様
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.matchall |

ブラウザー実装状況
---------

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

関連情報
----

* `String.prototype.matchAll()`
* `RegExp.prototype[@@matchAll]()`


Symbol.toStringTag - JavaScript

Symbol.toStringTag
==================

**`Symbol.toStringTag`** ウェルノウンシンボルは、オブジェクトを説明する既定の文字列の作成に使用される文字列値のプロパティです。 `Object.prototype.toString()` メソッドによって内部的にアクセスされます。

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

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

例
-

### 既定のタグ

```js
Object.prototype.toString.call("foo"); // "[object String]"
Object.prototype.toString.call([1, 2]); // "[object Array]"
Object.prototype.toString.call(3); // "[object Number]"
Object.prototype.toString.call(true); // "[object Boolean]"
Object.prototype.toString.call(undefined); // "[object Undefined]"
Object.prototype.toString.call(null); // "[object Null]"
// ... and more
```

### 組込み toStringTag シンボル

```js
Object.prototype.toString.call(new Map()); // "[object Map]"
Object.prototype.toString.call(function\* () {}); // "[object GeneratorFunction]"
Object.prototype.toString.call(Promise.resolve()); // "[object Promise]"
// ... and more
```

### 独自クラスの既定のオブジェクトタグ

クラスを作成すると、 JavaScript は既定で "Object" というタグをつけます。

```js
class ValidatorClass {}

Object.prototype.toString.call(new ValidatorClass()); // "[object Object]"
```

### toStringTag による独自タグ

`toStringTag` を使えば、独自のタグを設定することができます。

```js
class ValidatorClass {
  get [Symbol.toStringTag]() {
    return "Validator";
  }
}

Object.prototype.toString.call(new ValidatorClass()); // "[object Validator]"
```

### すべての DOM プロトタイプオブジェクトで利用可能な toStringTag

WebIDL の仕様変更が 2020 年半ばに行われた関係で、ブラウザーはすべての DOM プロトタイプオブジェクトに `Symbol.toStringTag` プロパティを追加するようになりました。例えば、`HTMLButtonElement` の `Symbol.toStringTag` プロパティにアクセスするには次のようにします。

```js
let test = document.createElement("button");
test.toString(); // Returns [object HTMLButtonElement]
test[Symbol.toStringTag]; // Returns HTMLButtonElement
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.tostringtag |

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

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

関連情報
----

* `Object.prototype.toString()`


Symbol.species - JavaScript

Symbol.species
==============

ウェルノウンシンボルの **`Symbol.species`** は、コンストラクター関数が派生オブジェクトを生成する際に使用する関数値プロパティを指定します。

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

解説
--

`species` アクセサープロパティを使用すると、オブジェクトの生成に使われるデフォルトコンストラクターを上書きすることができます。

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

例
-

### species の使用

`Array` オブジェクトを派生した配列クラス `MyArray` で返したいことがあるでしょう。例えば、デフォルトのコンストラクターを返す `map()` のようなメソッドを使用している場合、これらのメソッドは `MyArray` オブジェクトではなく親の `Array` オブジェクトを返したいとします。 `species` シンボルでこれを実現することができます。

```js
class MyArray extends Array {
  // Overwrite species to the parent Array constructor
  static get [Symbol.species]() {
    return Array;
  }
}
let a = new MyArray(1, 2, 3);
let mapped = a.map((x) => x \* x);

console.log(mapped instanceof MyArray); // false
console.log(mapped instanceof Array); // true
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.species |

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

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

関連情報
----

* `Map[@@species]`
* `Set[@@species]`


Symbol.iterator - JavaScript

Symbol.iterator
===============

**`Symbol.iterator`** はウェルノウンシンボルで、オブジェクトの既定のイテレーターを指定します。 `for...of` で使用されます。

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

解説
--

オブジェクトを反復処理する必要がある場合（`for..of` ループの開始時など）は常に、その `@@iterator` メソッドが引数なしで呼び出され、返された**イテレーター**を使用して反復処理される値が取得されます。

一部の組み込み型には既定の反復動作がありますが、他の型（`Object` など）にはありません。`@@iterator` メソッドの組み込み型は次のとおりです。

* `Array.prototype[@@iterator]()`
* `TypedArray.prototype[@@iterator]()`
* `String.prototype[@@iterator]()`
* `Map.prototype[@@iterator]()`
* `Set.prototype[@@iterator]()`

詳細については、反復処理プロトコルも参照してください。

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

例
-

### ユーザー定義の反復可能項目

次のように独自の反復可能オブジェクトを作成できます。

```js
const myIterable = {};
myIterable[Symbol.iterator] = function\* () {
  yield 1;
  yield 2;
  yield 3;
};
[...myIterable]; // [1, 2, 3]
```

または、計算されたプロパティを使用して、クラスやオブジェクト内で反復可能オブジェクトを直接定義できます。

```js
class Foo {
  \*[Symbol.iterator]() {
    yield 1;
    yield 2;
    yield 3;
  }
}

const someObj = {
  \*[Symbol.iterator]() {
    yield "a";
    yield "b";
  },
};

console.log(...new Foo()); // 1, 2, 3
console.log(...someObj); // 'a', 'b'
```

### 非整形反復処理

もし反復可能項目の `@@iterator` メソッドがイテレーターオブジェクトを返さない場合、それは非整形反復可能項目です。それを使用すると、実行時に例外が発生したり、バグが発生したりする可能性があります。

```js
const nonWellFormedIterable = {}
nonWellFormedIterable[Symbol.iterator] = () => 1
[...nonWellFormedIterable] // TypeError: [] is not a function
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.iterator |

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

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

関連情報
----

* `Symbol.iterator` のポリフィル (`core-js`)
* 反復処理プロトコル
* `Array.prototype[@@iterator]()`
* `TypedArray.prototype[@@iterator]()`
* `String.prototype[@@iterator]()`
* `Map.prototype[@@iterator]()`
* `Set.prototype[@@iterator]()`


Symbol.for() - JavaScript

Symbol.for()
============

**`Symbol.for(key)`** メソッドは、引数で与えられたキーでランタイム全体のシンボルレジストリ内に存在しているシンボルを検索し、見つかった場合はそれを返します。さもなければ、新しいシンボルがこのキーでグローバルシンボルレジストリ内に生成されます。

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

構文
--
```

Symbol.for(key);
```

### 引数

`key`

必須の文字列です。シンボルに対するキー（シンボルの説明のためにも使用されます）。

### 返値

見つかった場合は指定したキーを持つ既存のシンボルです。さもなければ新しいシンボルを作成して返します。

解説
--

`Symbol()` と対照的に、`Symbol.for()` 関数はグローバルシンボルレジストリリスト内で利用可能なシンボルを生成します。`Symbol.for()` は必ずしもすべての呼び出しで新しいシンボルを生成するわけでなく、引数で与えられた `key` をもつシンボルがレジストリ内にすでに存在しているかどうか最初に調べます。存在している場合は、そのシンボルが返されます。引数で与えられたキーをもつシンボルが見つからない場合、`Symbol.for()` は新しいグローバルシンボルを生成します。

### グローバルシンボルレジストリ

グローバルシンボルレジストリは次のレコード構造をもつリストで、値は空で初期化されます:

| フィールド名 | 値 |
| --- | --- |
| [[key]] | シンボルを識別するための文字列キー。 |
| [[symbol]] | グローバルに格納されているシンボル。 |

例
-

### Symbol.for() の使用

```js
Symbol.for("foo"); // create a new global symbol
Symbol.for("foo"); // retrieve the already created symbol

// Same global symbol, but not locally
Symbol.for("bar") === Symbol.for("bar"); // true
Symbol("bar") === Symbol("bar"); // false

// The key is also used as the description
var sym = Symbol.for("mario");
sym.toString(); // "Symbol(mario)"
```

グローバルシンボルキーや他の (ライブラリコードの) グローバルシンボルとの名前の衝突を避けるために、シンボルの前に接頭辞をつけると良いかもしれません。

```js
Symbol.for("mdn.foo");
Symbol.for("mdn.bar");
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.for |

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

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

関連情報
----

* `Symbol.keyFor()`


Symbol.search - JavaScript

Symbol.search
=============

**`Symbol.search`** はウェルノウンシンボルで、正規表現に一致する文字列内の位置を返すメソッドを指定します。この関数は `String.prototype.search()` メソッドによって呼び出されます。

詳しくは、 `RegExp.prototype[@@search]()` と `String.prototype.search()` を参照してください。

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

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

例
-

### 独自の文字列検索

```js
class caseInsensitiveSearch {
  constructor(value) {
    this.value = value.toLowerCase();
  }
  [Symbol.search](string) {
    return string.toLowerCase().indexOf(this.value);
  }
}

console.log("foobar".search(new caseInsensitiveSearch("BaR")));
// expected output: 3
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.search |

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

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

関連情報
----

* `Symbol.match`
* `Symbol.replace`
* `Symbol.split`
* `RegExp.prototype[@@search]()`


Symbol.hasInstance - JavaScript

Symbol.hasInstance
==================

**`Symbol.hasInstance`** は、コンストラクターオブジェクトが、そのインスタンスのオブジェクトとして認識されるかどうかを決定するために使用されます。このシンボルで、`instanceof` 演算子の動作をカスタマイズすることができます。

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

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

例
-

### 独自のインスタンスでの動作

たとえば、次のようにして `instanceof` の独自の動作を実装することができます。

```js
class MyArray {
  static [Symbol.hasInstance](instance) {
    return Array.isArray(instance);
  }
}
console.log([] instanceof MyArray); // true
```

```js
function MyArray() {}
Object.defineProperty(MyArray, Symbol.hasInstance, {
  value: function (instance) {
    return Array.isArray(instance);
  },
});
console.log([] instanceof MyArray); // true
```

### オブジェクトのインスタンスを確認する

`instanceof` キーワードを使ってオブジェクトがクラスのインスタンスであるかどうかを確認するのと同じ方法で、`Symbol.hasInstance` を使って確認することもできます。

```js
class Animal {
  constructor() {}
}

const cat = new Animal();

console.log(Animal[Symbol.hasInstance](cat)); // true
```

仕様
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.hasinstance |

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

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

関連情報
----

* `instanceof`


Symbol.prototype.valueOf() - JavaScript

Symbol.prototype.valueOf()
==========================

**`valueOf()`** メソッドは、 Symbol オブジェクトのプリミティブ値を返します。

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

構文
--
```

Symbol().valueOf()
```

### 返値

指定された `Symbol` オブジェクトのプリミティブ値です。

解説
--

`Symbol` オブジェクトの `valueOf()` メソッドは、 Symbol オブジェクトのプリミティブ値を Symbol データ型として返します。

JavaScript はオブジェクトをプリミティブ値に変換するために `valueOf()` メソッドを呼び出します。 `valueOf()` メソッドを自分で呼び出す必要はほとんどありません。 JavaScript は、プリミティブ値が期待されているオブジェクトに遭遇したときに、自動的にこれを呼び出します。

例
-

### valueOf() の使用

```js
const sym = Symbol("example");
sym === sym.valueOf(); // true
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.prototype.valueof |

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

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

関連情報
----

* `Object.prototype.valueOf()`


Symbol.isConcatSpreadable - JavaScript

Symbol.isConcatSpreadable
=========================

**`Symbol.isConcatSpreadable`** は、`Array.prototype.concat()` メソッドを使用してオブジェクトを配列の要素に平坦化する場合の設定として使用されます。

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

説明
--

`@@isConcatSpreadable` シンボル（`Symbol.isConcatSpreadable`）は直接、または継承されたプロパティとして定義でき、その値は boolean です。これは、配列や配列状のオブジェクトの振る舞いを制御します：

* 配列オブジェクトにとって、既定の動作は要素の展開（平坦化）です。`Symbol.isConcatSpreadable` はこれらの場合に平坦化を避けます。
* 配列状のオブジェクトにとって、既定の動作は展開や平坦化を行いません。`Symbol.isConcatSpreadable` はこれらの場合に平坦化を強制します。

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

例
-

### 配列

既定で、`Array.prototype.concat()` は配列を次の結果のように展開（平坦化）します：

```js
let alpha = ['a', 'b', 'c'],
let numeric = [1, 2, 3]

let alphaNumeric = alpha.concat(numeric)

console.log(alphaNumeric)  // Result: ['a', 'b', 'c', 1, 2, 3]
```

`Symbol.isConcatSpreadable` を `false` に設定した場合、既定の動作を使用できなくなります：

```js
let alpha = ['a', 'b', 'c'],
let numeric = [1, 2, 3]

numeric[Symbol.isConcatSpreadable] = false
let alphaNumeric = alpha.concat(numeric)

console.log(alphaNumeric)  // Result: ['a', 'b', 'c', [1, 2, 3] ]
```

### 配列状のオブジェクト

配列状のオブジェクトは、既定で展開しません。`Symbol.isConcatSpreadable` 平坦化した配列を取得するには、`true` に設定する必要があります：

```js
let x = [1, 2, 3];

let fakeArray = {
  [Symbol.isConcatSpreadable]: true,
  length: 2,
  0: "hello",
  1: "world",
};

x.concat(fakeArray); // [1, 2, 3, "hello", "world"]
```

**メモ:** `length` プロパティは、追加するオブジェクトプロパティの数を制御するために使用されます。上記の例では、`length:2` は 2 つのプロパティを追加する必要があることを示しています。

仕様
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.isconcatspreadable |

ブラウザー実装状況
---------

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

関連情報
----

* `Array.prototype.concat()`


Symbol.unscopables - JavaScript

Symbol.unscopables
==================

**`Symbol.unscopables`** ウェルノウンシンボルは、自身のプロパティ名と継承されたプロパティ名が、関連付けられたオブジェクトの `with` 環境バインディングから除外されているオブジェクトの値を指定するために使用されます。

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

解説
--

The `@@unscopables` シンボル (`Symbol.unscopables`) は、 `with` 環境バインディングでプロパティ名が語彙的変数として公開されないようにするために、任意のオブジェクトに定義することができます。厳格モードを使用している場合、 `with` 文は使用できず、このシンボルも必要ないことに注意してください。

`unscopables` オブジェクトでプロパティを `true` に設定すると、そのプロパティは*スコープ不能*になり、語彙的スコープ変数には表示されません。プロパティを `false` に設定すると、 `scopable` になり、語彙的スコープ変数に表示されます。

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

例
-

### with 文内のスコープ

次のコードは、ES5 以下であれば正しく動作します。しかし、 ECMAScript 2015（ES6）以降では、`Array.prototype.keys()` メソッドが導入されました。これは、`with` 環境内で "keys" はメソッドであり変数ではないことを意味します。これが `unscopable` シンボルを導入すべき時です。ビルトインの `unscopables` 設定は、配列のメソッドのいくつかが `with` 環境のスコープに入らないようにするために、`Array.prototype[@@unscopables]` として実装されています。

```js
var keys = [];

with (Array.prototype) {
  keys.push("something");
}

Object.keys(Array.prototype[Symbol.unscopables]);
// ["copyWithin", "entries", "fill", "find", "findIndex",
// "includes", "keys", "values"]
```

### オブジェクト内の unscopables

自分のオブジェクトに `unscopables` を設定することもできます。

```js
var obj = {
  foo: 1,
  bar: 2,
};

obj[Symbol.unscopables] = {
  foo: false,
  bar: true,
};

with (obj) {
  console.log(foo); // 1
  console.log(bar); // ReferenceError: bar is not defined
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.unscopables |

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

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

関連情報
----

* `Array.prototype[@@unscopables]`
* `with` 文 (厳格モードでは利用不可)


Symbol.toPrimitive - JavaScript

Symbol.toPrimitive
==================

**`Symbol.toPrimitive`** はシンボルで、あるオブジェクトを対応するプリミティブ値に変換するために呼び出される関数値のプロパティを指定します。

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

解説
--

`Symbol.toPrimitive` プロパティにより (関数値として使用して)、オブジェクトがプリミティブ値に変換することができるようになります。関数は、プリミティブ値の結果として好ましい型を指定する文字列引数の `hint` と一緒に呼び出されます。 `hint` 引数は、 "`number`", "`string`", "`default`" のいずれかになります。

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

例
-

### オブジェクトから変換されたプリミティブ値の修正

次の例は `Symbol.toPrimitive` プロパティがオブジェクトから変換されたプリミティブ値を修正する方法を説明します。

```js
// Symbol.toPrimitive プロパティを持たないオブジェクト。
var obj1 = {};
console.log(+obj1); // NaN
console.log(`${obj1}`); // "[object Object]"
console.log(obj1 + ""); // "[object Object]"

// Symbol.toPrimitive プロパティを持つオブジェクト。
var obj2 = {
  [Symbol.toPrimitive](hint) {
    if (hint == "number") {
      return 10;
    }
    if (hint == "string") {
      return "hello";
    }
    return true;
  },
};
console.log(+obj2); // 10 -- hint は "number"
console.log(`${obj2}`); // "hello" -- hint は "string"
console.log(obj2 + ""); // "true" -- hint は "default"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.toprimitive |

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

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

関連情報
----

* `Date.prototype[@@toPrimitive]`
* `Symbol.prototype[@@toPrimitive]`
* `Object.prototype.toString()`
* `Object.prototype.valueOf()`


Symbol.replace - JavaScript

Symbol.replace
==============

**`Symbol.replace`** ウェルノウンシンボルは、文字列の一致した部分を置き換えるメソッドを指定します。この関数は `String.prototype.replace()` メソッドから呼び出されます。

詳しくは、 `RegExp.prototype[@@replace]()` と `String.prototype.replace()` を参照してください。

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

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

例
-

### Symbol.replace の使用

```js
class CustomReplacer {
  constructor(value) {
    this.value = value;
  }
  [Symbol.replace](string) {
    return string.replace(this.value, "#!@?");
  }
}

console.log("football".replace(new CustomReplacer("foo")));
// expected output: "#!@?tball"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.replace |

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

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

関連情報
----

* `Symbol.match`
* `Symbol.search`
* `Symbol.split`
* `RegExp.prototype[@@replace]()`


Symbol.prototype[@@toPrimitive] - JavaScript

Symbol.prototype[@@toPrimitive]
===============================

**`[@@toPrimitive]()`** メソッドは、 Symbol オブジェクトをプリミティブ値に変換します。

構文
--
```

Symbol()[Symbol.toPrimitive](hint)
```

### 返値

`Symbol` オブジェクトで指定されたプリミティブ値です。

解説
--

`Symbol` オブジェクトの `[@@toPrimitive]()` メソッドは、 Symbol オブジェクトのプリミティブ値を Symbol データ型として返します。 `hint` 引数は使われません。

JavaScript はオブジェクトをプリミティブ値に変換するために `[@@toPrimitive]()` メソッドを呼び出します。 `[@@toPrimitive]()` メソッドを自分で呼び出す必要はほとんどありません。 JavaScript は、プリミティブ値が期待されているオブジェクトに遭遇したときに、自動的にこれを呼び出します。

例
-

### @@toPrimitive の使用

```js
const sym = Symbol("example");
sym === sym[Symbol.toPrimitive](); // true
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.prototype-@@toprimitive |

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

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

関連情報
----

* `Symbol.toPrimitive`


Symbol.asyncIterator - JavaScript

Symbol.asyncIterator
====================

**`Symbol.asyncIterator`** は、オブジェクトのデフォルトの AsyncIterator を指定します。このプロパティがオブジェクトに設定されている場合、それは非同期反復可能項目であり、`for await...of` ループで使用できます。

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

説明
--

`Symbol.asyncIterator` シンボルは、オブジェクトの `@@asyncIterator` メソッドにアクセスするための組み込みシンボルです。オブジェクトを非同期で反復可能にするには、`Symbol.asyncIterator` キーが必要です。

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

例
-

### ユーザー定義の非同期反復可能項目

オブジェクトに `[Symbol.asyncIterator]` プロパティを設定することで、独自の非同期イテレータを定義することができます。

```js
const myAsyncIterable = {
  async \*[Symbol.asyncIterator]() {
    yield "hello";
    yield "async";
    yield "iteration!";
  },
};

(async () => {
  for await (const x of myAsyncIterable) {
    console.log(x);
    // 期待される出力:
    // "hello"
    // "async"
    // "iteration!"
  }
})();
```

API を作成するとき、非同期反復可能項目はデータのストリームやリストのような、*反復可能*なものを表すために設計されたものであり、ほとんどの状況でコールバックやイベントを完全に置き換えるものではないことに注意してください。

### 組み込みの非同期反復処理

現在のところ、デフォルトで `[Symbol.asyncIterator]` キーが設定されている組み込み JavaScript オブジェクトはありません。しかし、WHATWG Streams は非同期反復可能な最初の組み込みオブジェクトになるように設定されており、最近 `[Symbol.asyncIterator]` が仕様に組み込まれました。

仕様
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.asynciterator |

ブラウザー実装状況
---------

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

関連情報
----

* 反復処理プロトコル
* for await... of


Symbol() コンストラクター - JavaScript

Symbol() コンストラクター
=================

`Symbol()` コンストラクターは **symbol** 型の値を返しますが、 "`new Symbol()`" という構文に対応しておらず、サブクラス化を意図していないため、コンストラクターとしては不完全です。 `class` 定義の `extends` 句の値として使用することもできますが、 `super` の呼び出しを行うと例外が発生します。

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

構文
--
```

Symbol([description])
```

### 引数

`description` 省略可

文字列。デバッグには使用できるこのシンボルの説明ですが、シンボル自体にはアクセスできません。

例
-

### シンボルの作成

新しいプリミティブであるシンボルを生成するには、解説にあるように `Symbol()` を任意の文字列とともに書きます。

```js
let sym1 = Symbol();
let sym2 = Symbol("foo");
let sym3 = Symbol("foo");
```

上記のコードは 3 つの新しいシンボルを生成します。なお、 `Symbol("foo")` は `"foo"` と言う文字列を強制的に記号にするわけではないことに注意してください。毎回新しいシンボルを生成します。

```js
Symbol("foo") === Symbol("foo"); // false
```

### new Symbol(...)

以下のように `new` 演算子を伴う構文では、 `TypeError` が発生します。

```js
let sym = new Symbol(); // TypeError
```

このため、新しいシンボル値の代わりに明示的なシンボルラッパーオブジェクトを作成することができず、プリミティブなデータ型の周りに明示的なラッパーオブジェクトを作成することは一般的に可能です (例えば、 `new Boolean`, `new String`, `new Number` です)。

本当に `Symbol` のラッパーオブジェクトを生成したい場合は、 `Object()` 関数を使用することができます。

```js
let sym = Symbol("foo");
let symObj = Object(sym);
typeof sym; // => "symbol"
typeof symObj; // => "object"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol-constructor |

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

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

関連情報
----

* 用語集: Symbol データ型


Symbol.prototype.description - JavaScript

Symbol.prototype.description
============================

読み取り専用 **`description`** プロパティは、 `Symbol` オブジェクトのオプションの説明を返す文字列です。

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

解説
--

`Symbol` オブジェクトは、オプションの説明を使用して作成できます。これはデバッグには使用できますが、シンボル自体にはアクセスできません。 `Symbol.prototype.description` プロパティを使用して、その説明を読み取ることができます。囲んでいる "`Symbol()`" 文字列が含まれていないため、 `Symbol.prototype.toString()` とは異なります。例を参照してください。

例
-

### description を使用する

```js
Symbol("desc").toString(); // "Symbol(desc)"
Symbol("desc").description; // "desc"
Symbol("").description; // ""
Symbol().description; // undefined

// well-known symbols
Symbol.iterator.toString(); // "Symbol(Symbol.iterator)"
Symbol.iterator.description; // "Symbol.iterator"

// global symbols
Symbol.for("foo").toString(); // "Symbol(foo)"
Symbol.for("foo").description; // "foo"
```

仕様
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.prototype.description |

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

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

関連項目
----

* `Symbol.prototype.toString()`
* Polyfill: https://npmjs.com/symbol.prototype.description


Symbol.split - JavaScript

Symbol.split
============

**`Symbol.split`** ウェルノウンシンボルは、正規表現に一致する位置で文字列を分割するメソッドを指定します。この関数は `String.prototype.split()` メソッドによって呼び出されます。

詳しくは、 `RegExp.prototype[@@split]()` と `String.prototype.split()` を参照してください。

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

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

例
-

### 独自の逆方向の分割

```js
class ReverseSplit {
  [Symbol.split](string) {
    const array = string.split(" ");
    return array.reverse();
  }
}

console.log("Another one bites the dust".split(new ReverseSplit()));
// expected output: [ "dust", "the", "bites", "one", "Another" ]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.split |

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

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

関連情報
----

* `Symbol.match`
* `Symbol.replace`
* `Symbol.search`
* `RegExp.prototype[@@split]()`


EvalError() コンストラクター - JavaScript

EvalError() コンストラクター
====================

**`EvalError`** コンストラクターは、グローバルの `eval()` 関数に関する新しいエラーを生成します。この例外はもう JavaScript からは使用されていませんが、 `EvalError` オブジェクトは互換性のために残っています。object

構文
--
```

new EvalError([message[, fileName[, lineNumber]]])
```

### 引数

`message` 省略可

人間が読むためのエラーの説明です。

`fileName` 省略可

例外が発生したコードを含むファイルの名前です。

`lineNumber` 省略可

例外が発生したコードの行番号です。

例
-

`EvalError` は現在の ECMAScript 仕様書では使用されておらず、ランタイムから発生することもありません。しかし、このオブジェクト自身は仕様書の以前のバージョンとの後方互換性のために残っています。

### EvalError の生成

```js
try {
  throw new EvalError("Hello", "someFile.js", 10);
} catch (e) {
  console.log(e instanceof EvalError); // true
  console.log(e.message); // "Hello"
  console.log(e.name); // "EvalError"
  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-nativeerror-constructors |

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

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

関連情報
----

* `Error`
* `eval()`


Map.prototype[@@iterator]() - JavaScript

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

**`@@iterator`** は `Map` オブジェクトのプロパティで、反復可能プロトコルを実装します。これにより、マップが反復可能プロトコルを受け入れるほとんどの構文、たとえばスプレッド構文や `for...of` ループなどで使用できるようになります。マップのキーと値のペアを返すイテレーターを返します。

初期値は、 `entries` メソッドの初期値と同じ関数オブジェクトです。

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

構文
--

```js
map[Symbol.iterator]()
```

### 返値

返値は `Map.prototype.entries()` と同じ、マップのキーと値のペアを生成する新しい反復可能なイテレーターオブジェクトを返します。

例
-

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

このメソッドを直接呼び出す必要があることはめったにないことに注意してください。`iterator` メソッドが存在することで `Map` オブジェクトを反復可能にし、 `for...of` ループなどの反復処理構文が、自動的にこのメソッドを呼び出してループのためのイテレータを取得することができます。

```js
const myMap = new Map();
myMap.set("0", "foo");
myMap.set(1, "bar");
myMap.set({}, "baz");

for (const entry of myMap) {
  console.log(entry);
}
// ["0", "foo"]
// [1, "bar"]
// [{}, "baz"]

for (const [key, value] of myMap) {
  console.log(`${key}: ${value}`);
}
// 0: foo
// 1: bar
// [Object]: baz
```

### 手動でイテレーターを手繰る

返されたイテレーターオブジェクトの `next()` メソッドを手動で呼び出すと、反復処理を最大限に制御することができます。

```js
const myMap = new Map();
myMap.set("0", "foo");
myMap.set(1, "bar");
myMap.set({}, "baz");

const mapIter = myMap[Symbol.iterator]();

console.log(mapIter.next().value); // ["0", "foo"]
console.log(mapIter.next().value); // [1, "bar"]
console.log(mapIter.next().value); // [Object, "baz"]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype-@@iterator |

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

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

関連情報
----

* `Map.prototype.entries()`
* `Map.prototype.keys()`
* `Map.prototype.values()`


Map.prototype.size - JavaScript

Map.prototype.size
==================

**`size`** アクセサープロパティは、 `Map` オブジェクトにある要素の数を返します。

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

解説
--

`size` の値は `Map` オブジェクトにいくつの項目があるかを表す整数値です。 `size` の set アクセサー関数は `undefined` です。このプロパティを変更することはできません。

例
-

### size の使用

```js
const myMap = new Map();
myMap.set("a", "alpha");
myMap.set("b", "beta");
myMap.set("g", "gamma");

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

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-get-map.prototype.size |

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

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

関連情報
----

* `Map`


Map.prototype.values() - JavaScript

Map.prototype.values()
======================

**`values()`** メソッドは、 `Map` オブジェクトに挿入された要素を挿入順に列挙する新しい **イテレーター** オブジェクトを返します。

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

構文
--

```js
values()
```

### 返値

`Map` の新しいイテレーターオブジェクト。

例
-

### values() の使用

```js
const myMap = new Map();
myMap.set("0", "foo");
myMap.set(1, "bar");
myMap.set({}, "baz");

const mapIter = myMap.values();

console.log(mapIter.next().value); // "foo"
console.log(mapIter.next().value); // "bar"
console.log(mapIter.next().value); // "baz"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.values |

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

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

関連情報
----

* `Map.prototype.entries()`
* `Map.prototype.keys()`


Map.prototype.keys() - JavaScript

Map.prototype.keys()
====================

**`keys()`** メソッドは、 `Map` オブジェクトに挿入された要素のキーを挿入順に列挙する新しいイテレーターオブジェクトを返します。この具体的な用途では、このイテレーターオブジェクトは反復可能オブジェクトでもあるので、 for...of ループを使用することができます。

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

構文
--

```js
keys()
```

### 返値

`Map` の新しいイテレーターオブジェクト。

例
-

### keys() の使用

```js
const myMap = new Map();
myMap.set("0", "foo");
myMap.set(1, "bar");
myMap.set({}, "baz");

const mapIter = myMap.keys();

console.log(mapIter.next().value); // "0"
console.log(mapIter.next().value); // 1
console.log(mapIter.next().value); // {}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.keys |

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

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

関連情報
----

* `Map.prototype.entries()`
* `Map.prototype.values()`


Map.prototype.entries() - JavaScript

Map.prototype.entries()
=======================

**`entries()`** メソッドは、挿入順で `Map` オブジェクトのそれぞれの要素に対する `[key, value]` のペアを含む新しい イテレーター オブジェクトを返します。この具体的な例では、このイテレーターオブジェクトは反復可能オブジェクトでもあるので、 for-of ループを使用することができます。プロトコル `[Symbol.iterator]` が使用されると、呼び出されたときにこのイテレーター自身を返す関数を返します。

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

構文
--

```js
entries()
```

### 返値

新しい `Map` のイテレーターオブジェクトです。

例
-

### entries() の使用

```js
const myMap = new Map();
myMap.set("0", "foo");
myMap.set(1, "bar");
myMap.set({}, "baz");

const mapIter = myMap.entries();

console.log(mapIter.next().value); // ["0", "foo"]
console.log(mapIter.next().value); // [1, "bar"]
console.log(mapIter.next().value); // [Object, "baz"]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.entries |

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

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

関連情報
----

* `Map.prototype.keys()`
* `Map.prototype.values()`


Map.prototype.get() - JavaScript

Map.prototype.get()
===================

**`get()`** メソッドは、指定された要素を `Map` オブジェクトから返します。指定されたキーに関連付けられた値がオブジェクトである場合は、そのオブジェクトの参照を受け取ることになり、そのオブジェクトに対して変更を行った場合は、 `Map` オブジェクトの中にあるものに変更が行われます。

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

構文
--

```js
get(key)
```

### 引数

`key`

`Map` オブジェクトから返される要素のキーです。

### 返値

指定されたキーに関連付けられた要素を返します。 `Map` オブジェクト内にキーが見つからない場合は、`undefined` を返します。

例
-

### get() の使用

```js
const myMap = new Map();
myMap.set("bar", "foo");

console.log(myMap.get("bar")); // "foo" を返す
console.log(myMap.get("baz")); // undefined を返す
```

### get() を使用して、オブジェクトの参照を取得

```js
const arr = [];
const myMap = new Map();
myMap.set("bar", arr);

myMap.get("bar").push("foo");

console.log(arr); // ["foo"]
console.log(myMap.get("bar")); // ["foo"]
```

マップが元のオブジェクトへの参照を保持することで、実質的にオブジェクトがガベージコレクトされないことを意味し、予期せぬメモリー問題を引き起こす可能性があることに注意してください。もし、マップに格納されるオブジェクトが元のオブジェクトと同じ寿命を持つようにしたい場合は、 `WeakMap` を使用することを検討してください。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.get |

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

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

関連情報
----

* `Map`
* `Map.prototype.set()`
* `Map.prototype.has()`


Map.prototype.has() - JavaScript

Map.prototype.has()
===================

**`has()`** メソッドは、指定されたキーに対する要素が存在するかどうかを示す論理値を返します。

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

構文
--

```js
has(key)
```

### 引数

`key`

`Map` オブジェクト内に存在するかテストする要素のキーです。

### 返値

特定のキーに対する要素が `Map` オブジェクト内に存在していたら、`true` を返します。さもなければ、`false` を返します。

例
-

### has() の使用

```js
const myMap = new Map();
myMap.set("bar", "foo");

console.log(myMap.has("bar")); // true
console.log(myMap.has("baz")); // false
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.has |

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

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

関連情報
----

* `Map`
* `Map.prototype.set()`
* `Map.prototype.get()`


Map.prototype.clear() - JavaScript

Map.prototype.clear()
=====================

**`clear()`** メソッドは `Map` オブジェクトからすべての要素を削除します。

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

構文
--

```js
clear()
```

### 返値

`undefined`.

例
-

### clear() の使用

```js
const myMap = new Map();
myMap.set("bar", "baz");
myMap.set(1, "foo");

console.log(myMap.size); // 2
console.log(myMap.has("bar")); // true

myMap.clear();

console.log(myMap.size); // 0
console.log(myMap.has("bar")); // false
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.clear |

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

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

関連情報
----

* `Map`


Map.prototype.set() - JavaScript

Map.prototype.set()
===================

**`set()`** メソッドは、指定されたキーと値を持つ要素を `Map` オブジェクトに追加したり、更新したりします。

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

構文
--

```js
set(key, value)
```

### 引数

`key`

`Map` オブジェクトに追加する要素のキーです。キーはいずれかの JavaScript 型 （いずれかのプリミティブ値または任意の型の JavaScript オブジェクト）です。

`value`

`Map` オブジェクトに追加する要素の値です。値はいずれかの JavaScript 型 （いずれかのプリミティブ値または任意の型の JavaScript オブジェクト）です。

### 返値

`Map` オブジェクトです。

例
-

### set() の使用

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

// マップに新しい要素を追加する
myMap.set("bar", "foo");
myMap.set(1, "foobar");

// マップにある要素を更新する
myMap.set("bar", "baz");
```

### set() のメソッドチェーンの使用

`set()` メソッドは `Map` オブジェクトを返すため、以下のようにメソッドチェーンを作ることができます。

```js
// チェーンを使用してマップに新しい要素を追加する
myMap.set("bar", "foo").set(1, "foobar").set(2, "baz");
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.set |

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

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

関連情報
----

* `Map`
* `Map.prototype.get()`
* `Map.prototype.has()`


Map() コンストラクター - JavaScript

Map() コンストラクター
==============

**`Map()` コンストラクター**は、 `Map` オブジェクトを生成します。

構文
--
```

new Map([iterable])
```

### 引数

`iterable`

`Array` または他の反復処理可能 (en-US)なオブジェクトで、要素はキーと値の組です。 (たとえば、 `[[ 1, 'one' ],[ 2, 'two' ]]` のような 2 つの要素を持つ配列。) それぞれのそれぞれのキーと値の組が新しい `Map` に追加されます。

例
-

### 新しい Map の生成

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

仕様書
---

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

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

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

関連情報
----

* `Set`
* `WeakMap`
* `WeakSet`


get Map[@@species] - JavaScript

get Map[@@species]
==================

**`Map[@@species]`** は静的アクセサープロパティで、 `Map` オブジェクトをコピーする方法を示す未使用のアクセサープロパティです。

構文
--

```js
Map[Symbol.species]
```

### 返値

`get @@species` が呼び出されたコンストラクター (`this`) の値です。返さる値は、 `Map` インスタンスのコピーを構築するために使用されます。

解説
--

species アクセサープロパティは `Map` オブジェクトのデフォルトコンストラクターを返します。サブクラスのコンストラクターは、コンストラクターに代入して変更することによりオーバーライドすることができます。

**メモ:** このプロパティは現在、どの `Map` のメソッドからも使われていません。

例
-

### 通常のオブジェクトの species

species プロパティはデフォルトコンストラクター関数を返しますので、 `Map` オブジェクトには `Map` コンストラクターを返します。

```js
Map[Symbol.species]; // function Map()
```

### 派生オブジェクトの species

`Map` の独自サブクラスのインスタンス、例えば `MyMap` では、`MyMap` の species は `MyMap` コンストラクターになっています。しかし、これをオーバーライドして、派生クラスのメソッド内で親の `Map` オブジェクトを返したい場合があります。

```js
class MyMap extends Map {
  // MyMap の species を親の Map コンストラクターで上書き
  static get [Symbol.species]() {
    return Map;
  }
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-get-map-@@species |

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

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

関連情報
----

* `Map`
* `Symbol.species`


Map.prototype.forEach() - JavaScript

Map.prototype.forEach()
=======================

**`forEach()`** メソッドは、指定された関数を `Map` オブジェクト内にあるキーと値のペアそれぞれに対して 1 回ずつ、挿入順に実行します。

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

構文
--

```js
// アロー関数
forEach(() => { /\* … \*/ } )
forEach((value) => { /\* … \*/ } )
forEach((value, key) => { /\* … \*/ } )
forEach((value, key, map) => { /\* … \*/ } )

// コールバック関数
forEach(callbackFn)
forEach(callbackFn, thisArg)

// インラインコールバック関数
forEach(function() { /\* … \*/ })
forEach(function(value) { /\* … \*/ })
forEach(function(value, key) { /\* … \*/ })
forEach(function(value, key, map) { /\* … \*/ })
forEach(function(value, key, map) { /\* … \*/ }, thisArg)
```

### 引数

`callbackFn`

マップのそれぞれの項目に対して実行される関数。以下の引数を取ります。

`value` 省略可

それぞれの反復処理における値です。

`key` 省略可

それぞれの反復処理におけるキーです。

`map` 省略可

反復処理されるマップです。

`thisArg` 省略可

`callbackFn` の実行時に `this` として使用される値です。

### 返値

`undefined` です。

解説
--

`forEach` メソッドは、指定された関数 `callbackFn` を、マップの実在するそれぞれのキーに対して一度ずつ呼び出します。これは削除されたキーに対しては呼び出しません。ただし、存在していて `undefined` である値に対しては呼び出します。

`callbackFn` は次の **3 つの引数**で呼び出されます。

* 項目の値 (`value`)
* 項目のキー (`key`)
* 走査中の **`Map` オブジェクト**

`thisArg` 引数が `forEach` に指定されると、 `callbackFn` の呼び出し時にそのオブジェクトが `this` の値として使用されます。与えられなかった場合は、 `undefined` が `this` の値として渡されます。 `callback` によって究極に管理される `this` の値は、関数から見える `this` を特定する一般規則に従います。

それぞれの値に対して一度ずつ実行されますが、 `forEach` が終了するまでに削除され再追加された場合は除きます。 `callback` はその前に削除された値に対しては実行されません。 `forEach` が終了する前に追加された新しい値に対しては実行されます。

例
-

### Map オブジェクトの内容を表示

以下のコードは `Map` オブジェクト内の各要素を 1 行ずつ出力します。

```js
function logMapElements(value, key, map) {
  console.log(`map.get('${key}') = ${value}`);
}
new Map([
  ["foo", 3],
  ["bar", {}],
  ["baz", undefined],
]).forEach(logMapElements);
// ログ出力:
// "map.get('foo') = 3"
// "map.get('bar') = [object Object]"
// "map.get('baz') = undefined"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.foreach |

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

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

関連情報
----

* `Array.prototype.forEach()`
* `Set.prototype.forEach()`


Map.prototype.delete() - JavaScript

Map.prototype.delete()
======================

**`delete()`** メソッドは `Map` オブジェクトから特定の要素を削除します。

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

構文
--

```js
delete(key)
```

### 引数

`key`

`Map` オブジェクトから削除する要素のキーです。

### 返値

`Map` オブジェクトの要素が削除されたら `true` を、要素が存在しなければ `false` を返します。

例
-

### delete() メソッドの使用

```js
const myMap = new Map();
myMap.set("bar", "foo");

console.log(myMap.delete("bar")); // true を返す。正常に削除された。
console.log(myMap.has("bar")); // false を返す。 "bar" の要素がもう存在しない。
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.delete |

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

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

関連情報
----

* `Map`


Map.groupBy() - JavaScript

Map.groupBy()
=============

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback

**メモ:** 一部のブラウザーのあるバージョンでは、このメソッドは `Array.prototype.groupToMap()` というメソッドとして実装されていました。ウェブの互換性の問題により、現在は静的メソッドとして実装されています。詳細はブラウザーの互換性を確認してください

**Map.groupBy()** 静的メソッドは、指定されたコールバック関数によって返された値を使用して、指定された反復可能な要素をグループ化します。最終的に返される `Map` は、テスト関数からの一意な値をキーとして使用し、各グループの要素の配列を取得するために使用できます。

このメソッドは主に、あるオブジェクトに関連する要素をグループ化するときに便利で、特にそのオブジェクトが時間の経過とともに変化する可能性がある場合に便利です。オブジェクトが不変である場合は、代わりに文字列を使用してそれを表現し、`Object.groupBy()` で要素をグループ化することができます。

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

構文
--

```js
Map.groupBy(items, callbackFn)
```

### 引数

`items`

要素がグループ化される反復可能な要素（`Array` など）。

`callbackFn`

反復可能な各要素に対して実行される関数。これは、現在の要素のグループを示す値（オブジェクトまたはプリミティブ）を返す必要があります。この関数は以下の引数で呼び出されます。

`element`

現在処理中の要素。

`index`

現在処理中の要素のインデックス。

### 返値

各グループのキーを持つ `Map` オブジェクトで、それぞれに関連するグループの要素を含む配列が割り当てられたものです。

解説
--

`Map.groupBy()` は、指定された `callbackFn` 関数を反復可能な要素ごとに 1 回呼び出します。コールバック関数は、関連付けられた要素のグループを示す値を返す必要があります。`callbackFn` が返す値は、`Map.groupBy()` が返す `Map` のキーとして使用されます。各キーには、コールバックが同じ値を返したすべての要素を含む関連配列があります。

返された `Map` と元の反復可能な要素は同じです（ディープコピーではありません）。要素の内部構造を変更すると、元の反復可能な要素と返された `Map` の両方に反映されます。

このメソッドは、時間の経過とともに変更される可能性のある特定のオブジェクトに関連する情報をグループ化する必要がある場合に便利です。オブジェクトが変更されても、返される `Map` のキーとして機能し続けるからです。代わりにオブジェクトの文字列表現を作成し、それを `Object.groupBy()` のグループ化キーとして使用する場合は、オブジェクトが変更されても元のオブジェクトとその表現との間のマッピングを維持する必要があります。

**メモ:** 返された `Map` のグループにアクセスするには、`Map` のキーとして元々使用されていたのと同じオブジェクトを使用する必要があります（ただし、そのオブジェクトのプロパティを変更することはできます）。たまたま同じ名前とプロパティを持つ別のオブジェクトを使うことはできません。

`Map.groupBy` は `this` の値を読みません。どんなオブジェクトでも呼び出すことができ、新しい `Map` インスタンスが返されます。

例
-

### Map.groupBy() の使用

最初に、さまざまな食品の在庫を表すオブジェクトを含む配列を定義します。 それぞれの食品は `type` （種類）と `quantity` （量）を保有しています。

```js
const inventory = [
  { name: "asparagus", type: "vegetables", quantity: 9 },
  { name: "bananas", type: "fruit", quantity: 5 },
  { name: "goat", type: "meat", quantity: 23 },
  { name: "cherries", type: "fruit", quantity: 12 },
  { name: "fish", type: "meat", quantity: 22 },
];
```

以下のコードでは、`Map.groupBy()` とアロー関数を使用しています。この関数は、要素が `quantity < 6` であるかどうかに応じて、`restock` または `enough` というオブジェクトであるキーを返します。返された `result` オブジェクトは `Map` なので、配列を取得するためにキーで `get()` を呼び出す必要があります。

```js
const restock = { restock: true };
const sufficient = { restock: false };
const result = Map.groupBy(inventory, ({ quantity }) =>
  quantity < 6 ? restock : sufficient,
);
console.log(result.get(restock));
// [{ name: "bananas", type: "fruit", quantity: 5 }]
```

関数の引数 `{ quantity }` は、関数の引数に対するオブジェクトの分割構文の基本例であることに注意してください。これは、引数として渡されたオブジェクトの `quantity` プロパティを展開し、関数本体の `quantity` という変数に代入します。これは、関数内の要素に関連する値にアクセスするためのとても簡潔な方法です。

キーである `Map` は内容を変更しても使用し続けることができます。しかし、キーを再作成して使用することはできません。このため、`Map` を使用する必要があるものは、そのキーへの参照を保持し続けることが重要です。

```js
// キーの内容を変更しても使用し続けられます
restock["fast"] = true;
console.log(result.get(restock));
// [{ name: "bananas", type: "fruit", quantity: 5 }]

// 新しいキーは、たとえ同じ構造の map であっても使用できません
const restock2 = { restock: true };
console.log(result.get(restock2)); // undefined
```

仕様書
---

| Specification |
| --- |
| Array Grouping # sec-map.groupby |

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

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

関連情報
----

* `Map.groupBy` のポリフィル (`core-js`)
* インデックス付きコレクション
* `Array.prototype.reduce()`
* `Map()`
* `Object.groupBy()`


Uint16Array() コンストラクター - JavaScript

Uint16Array() コンストラクター
======================

**`Uint16Array()`** は型付き配列のコンストラクターで、プラットフォームのバイト順による 16 ビット符号なし整数値の配列を生成します。

構文
--
```

new Uint16Array(); // new in ES2017
new Uint16Array(length);
new Uint16Array(typedArray);
new Uint16Array(object);
new Uint16Array(buffer [, byteOffset [, length]]);
```

### 引数

`length`

`length` 引数付きで呼び出されると、メモリ内に内部的な配列バッファーを作成し、大きさは `length` *を `BYTES_PER_ELEMENT`* で乗じたバイト数になり、ゼロになることもあります。

`typedArray`

`typedArray` 引数付きで呼び出されると、これはあらゆる型付き配列型 (例えば `Int32Array`) にすることができますが、 `typedArray` を新しい型付き配列にコピーします。 `typedArray` の中のそれぞれの値は、新しい配列にコピーされる前にコンストラクターの対応する型に変換されます。新しい型付き配列の長さは `typedArray` 引数の長さと同じになります。

`object`

`object` 引数付きで呼び出されると、あたかも `TypedArray.from()` メソッドであるかのように新しい型付き配列が生成されます。

`buffer`, `byteOffset`, `length`

`buffer` と、オプションで `byteOffset` と `length` 引数を指定して呼び出されると、指定された `ArrayBuffer` を表示する型付き配列ビューが生成されます。 `byteOffset` および `length` 引数は、型付き配列ビューが表示するメモリ範囲を指定する。 両方を省略した場合は `buffer` の全てを表示し、 `length` のみを省略した場合は `buffer` の残りを表示します。

解説
--

**`Uint16Array()`** は型付き配列のコンストラクターで、プラットフォームのバイト順による 16 ビット符号なし整数値の配列を生成します。バイト順の制御が必要な場合は、代わりに `DataView` を使用してください。中身は `0` で初期化されます。生成されると、配列の中の要素はオブジェクトのメソッドを使用するか、配列の標準的な添字の構文を使用するか (すなわち、ブラケット構文を使用するか) して参照することができます。

ECMAScript 2015 から、 `Uint16Array` コンストラクターは構築に `new` 演算子が必要になりました。 `Uint16Array` コンストラクターを `new` なしで関数として呼び出すと、 `TypeError` が発生するようになりました。

```js
var dv = Uint16Array([1, 2, 3]);
// TypeError: calling a builtin Uint16Array constructor
// without new is forbidden
```

```js
var dv = new Uint16Array([1, 2, 3]);
```

例
-

### 様々な方法による Uint16Array の生成

```js
// From a length
var uint16 = new Uint16Array(2);
uint16[0] = 42;
console.log(uint16[0]); // 42
console.log(uint16.length); // 2
console.log(uint16.BYTES\_PER\_ELEMENT); // 2

// From an array
var arr = new Uint16Array([21, 31]);
console.log(arr[1]); // 31

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

// From an ArrayBuffer
var buffer = new ArrayBuffer(8);
var z = new Uint16Array(buffer, 0, 4);

// From an iterable
var iterable = (function\* () {
  yield\* [1, 2, 3];
})();
var uint16 = new Uint16Array(iterable);
// Uint16Array[1, 2, 3]
```

仕様書
---

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

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

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

関連情報
----

* JavaScript 型付き配列
* `ArrayBuffer`
* `DataView`


Boolean() コンストラクター - JavaScript

Boolean() コンストラクター
==================

**`Boolean()`** コンストラクターは `Boolean` オブジェクトを生成するために使用します。

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

構文
--

```js
new Boolean();
new Boolean(value);
```

### 引数

`value` 省略可

この `Boolean` オブジェクトの初期値です。

例
-

### `Boolean` を生成して初期値を `false` とする

```js
var bNoParam = new Boolean();
var bZero = new Boolean(0);
var bNull = new Boolean(null);
var bEmptyString = new Boolean("");
var bfalse = new Boolean(false);
```

### `Boolean` を生成して初期値を `true` とする

```js
var btrue = new Boolean(true);
var btrueString = new Boolean("true");
var bfalseString = new Boolean("false");
var bSuLin = new Boolean("Su Lin");
var bArrayProto = new Boolean([]);
var bObjProto = new Boolean({});
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-boolean-constructor |

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

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

関連情報
----

* Boolean


Boolean.prototype.valueOf() - JavaScript

Boolean.prototype.valueOf()
===========================

**`valueOf()`** メソッドは、`Boolean` オブジェクトのプリミティブ値を返します。

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

構文
--

```js
valueOf();
```

### 返値

この `Boolean` オブジェクトのプリミティブ値です。

解説
--

`valueOf()` は `Boolean` のメソッドで、 `Boolean` オブジェクトのプリミティブ値または論理値データ型としての `Boolean` リテラルを返します。

このメソッドはたいてい JavaScript によって内部的に呼び出され、コードで明示的に呼び出されることはありません。

例
-

### `valueOf()` の使用

```js
x = new Boolean();
myVar = x.valueOf(); // false を myVar に代入
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-boolean.prototype.valueof |

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

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

関連情報
----

* `Object.prototype.valueOf()`


Boolean.prototype.toString() - JavaScript

Boolean.prototype.toString()
============================

**`toString()`** メソッドは、指定された Boolean オブジェクトを表す文字列を返します。

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

構文
--

```js
toString();
```

### 返値

指定された `Boolean` オブジェクトを表す文字列です。

解説
--

`Boolean` オブジェクトは `Object` オブジェクトの `toString` メソッドを上書きしており、 `Object.prototype.toString()` を継承していません。 `Boolean` オブジェクトでは、 `toString` メソッドはオブジェクトを文字列で表したものを返します。

JavaScript は `toString()` メソッドを、 `Boolean` が文字列値として表現されるべき場合や、 `Boolean` が文字列の結合で参照されたときに自動的に呼び出します。

`Boolean` オブジェクトと論理値では、組み込みの `toString` メソッドはその `Boolean` オブジェクトの値によって "`true`" か "`false`" の文字列を返します。

例
-

### `toString` の使用

以下のコードでは、`flag.toString()` は "`true`" を返します。

```js
var flag = new Boolean(true);
var myVar = flag.toString();
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-boolean.prototype.tostring |

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

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

関連情報
----

* `Object.prototype.toString()`


InternalError() コンストラクター - JavaScript

InternalError() コンストラクター
========================

**非標準:** この機能は標準ではなく、標準化の予定もありません。公開されているウェブサイトには使用しないでください。ユーザーによっては使用できないことがあります。実装ごとに大きな差があることもあり、将来は振る舞いが変わるかもしれません。

**`InternalError()`** コンストラクターは、 JavaScript エンジンで内部的に発生したエラーを示すエラーを生成します。例えば、 "**InternalError**: too much recursion" などです。

構文
--
```

new InternalError([message[, fileName[, lineNumber]]])
```

### 引数

`message` 省略可

人間が読むためのエラーの説明です。

`fileName` 省略可

例外が発生したコードを含むファイルの名前です。

`lineNumber` 省略可

例外が発生したコードの行番号です。

例
-

### 新しい InternalError の生成

```js
new InternalError("Engine failure");
```

仕様書
---

標準の一部ではありません。

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

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

関連情報
----

* `Error`