recursal/MDN huggingface dataset:
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()
===========================

**`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
===============

**`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
==================

**`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
==============

ウェルノウンシンボルの **`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
===============

**`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()
============

**`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
=============

**`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
==================

**`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()
==========================

**`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
=========================

**`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
==================

**`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
==================

**`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
==============

**`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]
===============================

**`[@@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
====================

**`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() コンストラクター
=================

`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
============================

読み取り専用 **`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
============

**`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]()`