Symbol

symbolは、ユニークで不変なデータ型で、オブジェクトのプロパティ識別子として使われたりします。symbolオブジェクトは、Symbolプリミティブデータ型をラップした暗黙的なオブジェクトです。

構文

Symbol([description])

パラメーター

description Optional

オプションの、文字列。デバックのために使われるが、シンボル自体にはアクセスしないシンボルの説明。

説明

新しいプリミティブsymbolを生成するために、説明のためのオプション文字列とともにSymbol()を記述します。

var sym1 = Symbol();
var sym2 = Symbol("foo");
var sym3 = Symbol("foo");

上述のコードは、新しいsymbolを3つ生成しています。 Symbol("foo")は、同一のsymbolに文字列"foo"を強制していません。毎回新しいsymbolを生成しています。

Symbol("foo") === Symbol("foo"); // false

次のnew 演算子を用いた構文は、 TypeErrorを生成するでしょう。

var sym = new Symbol(); // TypeError

これは、記述者が新しいsymbolの値を生成する代わりに明示的なsymbolラッパーオブジェクトを生成することを防ぎます。プリミティブデータ型の周りに明示的なラッパーオブジェクトを生成することは、もはやECMAScript6ではサポートされていません。しかし、new Booleanやnew String、new Numbeのような既存のプリミティブラッパーオブジェクトは、歴史的な理由からまだ生成できます。

そして、もし本当にSymbolラッパーオブジェクトを生成したいなら、Object()関数を使用できます。

var sym = Symbol("foo");
typeof sym;     // "symbol" 
var symObj = Object(sym);
typeof symObj;  // "object"

グローバルsymbolレジストリの共有Symbol

上述のSymbol()関数を使用した構文は、あなたのコード全体で使用できるグローバルsymbolは生成しません。ファイルを跨いでグローバルスコープのような環境で使用できるsymbolを生成するには、グローバルsymbolレジストリーからsymbolを設定したり扱ったりするための Symbol.for() と Symbol.keyFor() メソッドを使用します。

オブジェクトのsymbolプロパティを見つける

Object.getOwnPropertySymbols() メソッドは、symbol配列を返却し、与えられたオブジェクトのsymbolプロパティを見つけられるようにしてくれます。すべてのオブジェクトは、symbolなしで初期化されます。そのため、オブジェクトにsymbolプロパティを設定しないかぎり、この配列は空だということに注意してください。

プロパティ

Symbol.length

値が1のLengthプロパティ

Symbol.prototype

Symbolコンストラクターのためのプロトタイプを表す。

ウェルノウンsymbol

自分のSymbolに加えて、JavaScriptはECMAScript5とそれ以前では開発者に公開されていなかった言語内部のふるまいを表すビルトインsymbolを持っています。これらのはつぎのプロパティを使用することでアクセスできます。

イテレーションsymbol

Symbol.iterator

オブジェクトのための既定のイテレーターを返すメソッド。for...ofを使用する。

正規表現symbol

Symbol.match

文字列にマッチするメソッド、また、オブジェクトが正規表現として使用できるか決定するためにも使用される。String.prototype.match()を使用する。

Symbol.replace

マッチした文字列の部分を置き換えるメソッド。String.prototype.replace()を使用する。

Symbol.search

A method that returns the index within a string that matches the regular expression. Used by String.prototype.search().

Symbol.split

A method that splits a string at the indices that match a regular expression. Used by String.prototype.split().

Other symbols

Symbol.hasInstance

A method determining if a constructor object recognizes an object as its instance. Used by instanceof.

Symbol.isConcatSpreadable

A Boolean value indicating if an object should be flattened to its array elements. Used by Array.prototype.concat().

Symbol.unscopables

An Array of string values that are property values. These are excluded from the with environment bindings of the associated objects.

Symbol.species

A constructor function that is used to create derived objects.

Symbol.toPrimitive

A method converting an object to a primitive value.

Symbol.toStringTag

A string value used for the default description of an object. Used by Object.prototype.toString().

Methods

Symbol.for(key)

Searches for existing symbols with the given key and returns it if found. Otherwise a new symbol gets created in the global symbol registry with this key.

Symbol.keyFor(sym)

Retrieves a shared symbol key from the global symbol registry for the given symbol.

Symbol prototype

All Symbols inherit from Symbol.prototype.

Properties

Symbol.prototype.constructor

Returns the function that created an instance's prototype. This is the Symbol function by default.

Methods

Symbol.prototype.toSource()

Returns a string containing the source of the Symbol object. Overrides the Object.prototype.toSource() method.

Symbol.prototype.toString()

Returns a string of containing the description of the Symbol. Overrides the Object.prototype.toString() method.

Symbol.prototype.valueOf()

Returns the primitive value of the Symbol object. Overrides the Object.prototype.valueOf() method.

Examples

Using the typeof operator with symbols

The typeof operator can help you to identify symbols.

typeof Symbol() === 'symbol'
typeof Symbol('foo') === 'symbol'
typeof Symbol.iterator === 'symbol'

Symbol type conversions

Some things to note when working with type conversion of symbols.

• When trying to convert a symbol to a number, a TypeError will be thrown
  (e.g. +sym or sym | 0).
• When using loose equality, Object(sym) == sym returns true.
• Symbol("foo") + "bar" throws a TypeError (can't convert symbol to string). This prevents you from silently creating a new string property name from a symbol, for example.
• The "safer" String(sym) conversion works like a call to Symbol.prototype.toString() with symbols, but note that new String(sym) will throw.

Symbols and for...in iteration

Symbols are not visible in for...in iterations. In addition, Object.getOwnPropertyNames() will not return symbol object properties, however, you can use Object.getOwnPropertySymbols() to get these.

var obj = {};

obj[Symbol("a")] = "a";
obj[Symbol.for("b")] = "b";
obj["c"] = "c";
obj.d = "d";

for (var i in obj) {
   console.log(i); // logs "c" and "d"
}

Symbols and JSON.stringify()

Symbol-keyed properties will be completely ignored when using JSON.stringify():

JSON.stringify({[Symbol("foo")]: "foo"});                 
// '{}'

For more details, see JSON.stringify().

Symbol wrapper objects as property keys

When a Symbol wrapper object is used as a property key, this object will be coerced to its wrapped symbol:

var sym = Symbol("foo");
var obj = {[sym]: 1};
obj[sym];            // 1
obj[Object(sym)];    // still 1

Specifications

Browser compatibility

関連項目

• Glossary: Symbol data type
• typeof
• Data types and data structures