From 6e93ec8fc9e1f3bd83bf2f77e84e1a39637734f8 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Fri, 12 Jul 2024 20:55:27 -0400 Subject: [PATCH] Remove all @@notation in JS prose (#34817) * Remove all @@notation in JS prose * Fixes --- .../web/javascript/data_structures/index.md | 16 ++++----- .../guide/iterators_and_generators/index.md | 8 ++--- .../reference/classes/extends/index.md | 2 +- .../errors/requires_global_regexp/index.md | 4 +-- .../functions/arguments/@@iterator/index.md | 8 ++--- .../reference/functions/arguments/index.md | 2 +- .../global_objects/array/@@iterator/index.md | 12 +++---- .../global_objects/array/@@species/index.md | 18 +++++----- .../array/@@unscopables/index.md | 10 +++--- .../global_objects/array/concat/index.md | 2 +- .../global_objects/array/entries/index.md | 2 +- .../reference/global_objects/array/index.md | 6 ++-- .../global_objects/array/keys/index.md | 2 +- .../global_objects/array/splice/index.md | 2 +- .../global_objects/array/values/index.md | 4 +-- .../arraybuffer/@@species/index.md | 16 ++++----- .../global_objects/arraybuffer/index.md | 6 ++-- .../global_objects/asyncfunction/index.md | 4 +-- .../global_objects/asyncgenerator/index.md | 4 +-- .../asyncgeneratorfunction/index.md | 4 +-- .../asynciterator/@@asynciterator/index.md | 6 ++-- .../global_objects/asynciterator/index.md | 8 ++--- .../reference/global_objects/atomics/index.md | 4 +-- .../reference/global_objects/bigint/index.md | 6 ++-- .../global_objects/bigint/tostring/index.md | 2 +- .../global_objects/boolean/tostring/index.md | 2 +- .../global_objects/dataview/index.md | 4 +-- .../date/@@toprimitive/index.md | 10 +++--- .../reference/global_objects/date/index.md | 6 ++-- .../global_objects/date/tojson/index.md | 2 +- .../global_objects/date/tostring/index.md | 2 +- .../global_objects/date/valueof/index.md | 2 +- .../finalizationregistry/index.md | 4 +-- .../function/@@hasinstance/index.md | 10 +++--- .../global_objects/function/index.md | 2 +- .../global_objects/generator/index.md | 4 +-- .../global_objects/generatorfunction/index.md | 4 +-- .../global_objects/intl/collator/index.md | 4 +-- .../intl/datetimeformat/index.md | 4 +-- .../global_objects/intl/displaynames/index.md | 4 +-- .../intl/durationformat/index.md | 4 +-- .../reference/global_objects/intl/index.md | 4 +-- .../global_objects/intl/listformat/index.md | 4 +-- .../global_objects/intl/locale/index.md | 4 +-- .../global_objects/intl/numberformat/index.md | 4 +-- .../global_objects/intl/pluralrules/index.md | 4 +-- .../intl/relativetimeformat/index.md | 4 +-- .../global_objects/intl/segmenter/index.md | 4 +-- .../segment/segments/@@iterator/index.md | 6 ++-- .../intl/segmenter/segment/segments/index.md | 2 +- .../iterator/@@iterator/index.md | 6 ++-- .../global_objects/iterator/flatmap/index.md | 6 ++-- .../global_objects/iterator/from/index.md | 6 ++-- .../global_objects/iterator/index.md | 28 +++++++-------- .../global_objects/iterator/iterator/index.md | 4 +-- .../reference/global_objects/json/index.md | 4 +-- .../global_objects/map/@@iterator/index.md | 6 ++-- .../global_objects/map/@@species/index.md | 10 +++--- .../reference/global_objects/map/index.md | 10 +++--- .../reference/global_objects/math/index.md | 4 +-- .../reference/global_objects/number/index.md | 2 +- .../global_objects/number/tostring/index.md | 2 +- .../object/constructor/index.md | 2 +- .../object/fromentries/index.md | 2 +- .../reference/global_objects/object/index.md | 2 +- .../global_objects/object/tostring/index.md | 2 +- .../global_objects/object/valueof/index.md | 4 +-- .../global_objects/promise/@@species/index.md | 16 ++++----- .../global_objects/promise/finally/index.md | 2 +- .../reference/global_objects/promise/index.md | 6 ++-- .../global_objects/promise/then/index.md | 2 +- .../reference/global_objects/reflect/index.md | 4 +-- .../global_objects/regexp/@@match/index.md | 26 +++++++------- .../global_objects/regexp/@@matchall/index.md | 22 ++++++------ .../global_objects/regexp/@@replace/index.md | 24 ++++++------- .../global_objects/regexp/@@search/index.md | 24 ++++++------- .../global_objects/regexp/@@species/index.md | 20 +++++------ .../global_objects/regexp/@@split/index.md | 26 +++++++------- .../global_objects/regexp/exec/index.md | 2 +- .../global_objects/regexp/global/index.md | 2 +- .../reference/global_objects/regexp/index.md | 20 +++++------ .../global_objects/regexp/sticky/index.md | 14 ++++---- .../global_objects/set/@@iterator/index.md | 6 ++-- .../global_objects/set/@@species/index.md | 10 +++--- .../reference/global_objects/set/index.md | 12 +++---- .../sharedarraybuffer/@@species/index.md | 16 ++++----- .../global_objects/sharedarraybuffer/index.md | 6 ++-- .../global_objects/string/@@iterator/index.md | 8 ++--- .../string/codepointat/index.md | 2 +- .../reference/global_objects/string/index.md | 6 ++-- .../global_objects/string/match/index.md | 6 ++-- .../global_objects/string/matchall/index.md | 6 ++-- .../global_objects/string/replace/index.md | 6 ++-- .../global_objects/string/replaceall/index.md | 4 +-- .../global_objects/string/search/index.md | 6 ++-- .../global_objects/string/split/index.md | 2 +- .../global_objects/string/tostring/index.md | 2 +- .../symbol/@@toprimitive/index.md | 12 +++---- .../symbol/asynciterator/index.md | 6 ++-- .../symbol/hasinstance/index.md | 12 +++---- .../reference/global_objects/symbol/index.md | 8 ++--- .../symbol/isconcatspreadable/index.md | 6 ++-- .../global_objects/symbol/iterator/index.md | 34 +++++++++--------- .../global_objects/symbol/match/index.md | 8 ++--- .../global_objects/symbol/matchall/index.md | 8 ++--- .../global_objects/symbol/replace/index.md | 8 ++--- .../global_objects/symbol/search/index.md | 8 ++--- .../global_objects/symbol/species/index.md | 24 ++++++------- .../global_objects/symbol/split/index.md | 8 ++--- .../symbol/toprimitive/index.md | 12 +++---- .../global_objects/symbol/tostring/index.md | 4 +-- .../symbol/tostringtag/index.md | 8 ++--- .../symbol/unscopables/index.md | 27 +++++++------- .../typedarray/@@iterator/index.md | 8 ++--- .../typedarray/@@species/index.md | 18 +++++----- .../typedarray/entries/index.md | 2 +- .../global_objects/typedarray/index.md | 8 ++--- .../global_objects/typedarray/keys/index.md | 2 +- .../global_objects/typedarray/values/index.md | 2 +- .../reference/global_objects/weakmap/index.md | 4 +-- .../global_objects/weakmap/weakmap/index.md | 2 +- .../reference/global_objects/weakref/index.md | 4 +-- .../reference/global_objects/weakset/index.md | 4 +-- .../reference/iteration_protocols/index.md | 36 +++++++++---------- .../reference/operators/addition/index.md | 2 +- .../reference/operators/import/index.md | 2 +- .../reference/operators/in/index.md | 2 +- .../reference/operators/instanceof/index.md | 8 ++--- .../reference/operators/less_than/index.md | 2 +- .../reference/operators/yield_star_/index.md | 2 +- .../statements/for-await...of/index.md | 2 +- .../reference/statements/for...of/index.md | 8 ++--- .../reference/statements/with/index.md | 6 ++-- 133 files changed, 494 insertions(+), 493 deletions(-) diff --git a/files/en-us/web/javascript/data_structures/index.md b/files/en-us/web/javascript/data_structures/index.md index 37a8b4f418df05f..5d21bd6f5ce82fc 100644 --- a/files/en-us/web/javascript/data_structures/index.md +++ b/files/en-us/web/javascript/data_structures/index.md @@ -235,17 +235,17 @@ The [primitive coercion](https://tc39.es/ecma262/multipage/abstract-operations.h - The [`+`](/en-US/docs/Web/JavaScript/Reference/Operators/Addition) operator — if one operand is a string, string concatenation is performed; otherwise, numeric addition is performed. - The [`==`](/en-US/docs/Web/JavaScript/Reference/Operators/Equality) operator — if one operand is a primitive while the other is an object, the object is converted to a primitive value with no preferred type. -This operation does not do any conversion if the value is already a primitive. Objects are converted to primitives by calling its [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"default"` as hint), `valueOf()`, and `toString()` methods, in that order. Note that primitive conversion calls `valueOf()` before `toString()`, which is similar to the behavior of [number coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) but different from [string coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). +This operation does not do any conversion if the value is already a primitive. Objects are converted to primitives by calling its [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"default"` as hint), `valueOf()`, and `toString()` methods, in that order. Note that primitive conversion calls `valueOf()` before `toString()`, which is similar to the behavior of [number coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) but different from [string coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). -The `[@@toPrimitive]()` method, if present, must return a primitive — returning an object results in a {{jsxref("TypeError")}}. For `valueOf()` and `toString()`, if one returns an object, the return value is ignored and the other's return value is used instead; if neither is present, or neither returns a primitive, a {{jsxref("TypeError")}} is thrown. For example, in the following code: +The `[Symbol.toPrimitive]()` method, if present, must return a primitive — returning an object results in a {{jsxref("TypeError")}}. For `valueOf()` and `toString()`, if one returns an object, the return value is ignored and the other's return value is used instead; if neither is present, or neither returns a primitive, a {{jsxref("TypeError")}} is thrown. For example, in the following code: ```js console.log({} + []); // "[object Object]" ``` -Neither `{}` nor `[]` have a `[@@toPrimitive]()` method. Both `{}` and `[]` inherit `valueOf()` from {{jsxref("Object.prototype.valueOf")}}, which returns the object itself. Since the return value is an object, it is ignored. Therefore, `toString()` is called instead. [`{}.toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) returns `"[object Object]"`, while [`[].toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString) returns `""`, so the result is their concatenation: `"[object Object]"`. +Neither `{}` nor `[]` have a `[Symbol.toPrimitive]()` method. Both `{}` and `[]` inherit `valueOf()` from {{jsxref("Object.prototype.valueOf")}}, which returns the object itself. Since the return value is an object, it is ignored. Therefore, `toString()` is called instead. [`{}.toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) returns `"[object Object]"`, while [`[].toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString) returns `""`, so the result is their concatenation: `"[object Object]"`. -The `[@@toPrimitive]()` method always takes precedence when doing conversion to any primitive type. Primitive conversion generally behaves like number conversion, because `valueOf()` is called in priority; however, objects with custom `[@@toPrimitive]()` methods can choose to return any primitive. {{jsxref("Date")}} and {{jsxref("Symbol")}} objects are the only built-in objects that override the `[@@toPrimitive]()` method. [`Date.prototype[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) treats the `"default"` hint as if it's `"string"`, while [`Symbol.prototype[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) ignores the hint and always returns a symbol. +The `[Symbol.toPrimitive]()` method always takes precedence when doing conversion to any primitive type. Primitive conversion generally behaves like number conversion, because `valueOf()` is called in priority; however, objects with custom `[Symbol.toPrimitive]()` methods can choose to return any primitive. {{jsxref("Date")}} and {{jsxref("Symbol")}} objects are the only built-in objects that override the `[Symbol.toPrimitive]()` method. [`Date.prototype[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) treats the `"default"` hint as if it's `"string"`, while [`Symbol.prototype[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) ignores the hint and always returns a symbol. ### Numeric coercion @@ -259,11 +259,11 @@ All data types, except Null, Undefined, and Symbol, have their respective coerci As you may have noticed, there are three distinct paths through which objects may be converted to primitives: -- [Primitive coercion](#primitive_coercion): `[@@toPrimitive]("default")` → `valueOf()` → `toString()` -- [Numeric coercion](#numeric_coercion), [number coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion), [BigInt coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#bigint_coercion): `[@@toPrimitive]("number")` → `valueOf()` → `toString()` -- [String coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion): `[@@toPrimitive]("string")` → `toString()` → `valueOf()` +- [Primitive coercion](#primitive_coercion): `[Symbol.toPrimitive]("default")` → `valueOf()` → `toString()` +- [Numeric coercion](#numeric_coercion), [number coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion), [BigInt coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#bigint_coercion): `[Symbol.toPrimitive]("number")` → `valueOf()` → `toString()` +- [String coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion): `[Symbol.toPrimitive]("string")` → `toString()` → `valueOf()` -In all cases, `[@@toPrimitive]()`, if present, must be callable and return a primitive, while `valueOf` or `toString` will be ignored if they are not callable or return an object. At the end of the process, if successful, the result is guaranteed to be a primitive. The resulting primitive is then subject to further coercions depending on the context. +In all cases, `[Symbol.toPrimitive]()`, if present, must be callable and return a primitive, while `valueOf` or `toString` will be ignored if they are not callable or return an object. At the end of the process, if successful, the result is guaranteed to be a primitive. The resulting primitive is then subject to further coercions depending on the context. ## See also diff --git a/files/en-us/web/javascript/guide/iterators_and_generators/index.md b/files/en-us/web/javascript/guide/iterators_and_generators/index.md index d233fbf9643a5d7..8dff9e3be1f8b3d 100644 --- a/files/en-us/web/javascript/guide/iterators_and_generators/index.md +++ b/files/en-us/web/javascript/guide/iterators_and_generators/index.md @@ -96,11 +96,11 @@ function* makeRangeIterator(start = 0, end = Infinity, step = 1) { An object is **iterable** if it defines its iteration behavior, such as what values are looped over in a {{jsxref("Statements/for...of", "for...of")}} construct. Some built-in types, such as {{jsxref("Array")}} or {{jsxref("Map")}}, have a default iteration behavior, while other types (such as {{jsxref("Object")}}) do not. -In order to be **iterable**, an object must implement the **@@iterator** method. This means that the object (or one of the objects up its [prototype chain](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain)) must have a property with a {{jsxref("Symbol.iterator")}} key. +In order to be **iterable**, an object must implement the `[Symbol.iterator]()` method. This means that the object (or one of the objects up its [prototype chain](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain)) must have a property with a {{jsxref("Symbol.iterator")}} key. It may be possible to iterate over an iterable more than once, or only once. It is up to the programmer to know which is the case. -Iterables which can iterate only once (such as Generators) customarily return `this` from their **@@iterator** method, whereas iterables which can be iterated many times must return a new iterator on each invocation of **@@iterator**. +Iterables which can iterate only once (such as Generators) customarily return `this` from their `[Symbol.iterator]()` method, whereas iterables which can be iterated many times must return a new iterator on each invocation of `[Symbol.iterator]()`. ```js function* makeIterator() { @@ -117,10 +117,10 @@ for (const itItem of iter) { console.log(iter[Symbol.iterator]() === iter); // true // This example show us generator(iterator) is iterable object, -// which has the @@iterator method return the `iter` (itself), +// which has the [Symbol.iterator]() method return the `iter` (itself), // and consequently, the it object can iterate only _once_. -// If we change the @@iterator method of `iter` to a function/generator +// If we change the [Symbol.iterator]() method of `iter` to a function/generator // which returns a new iterator/generator object, `iter` // can iterate many times diff --git a/files/en-us/web/javascript/reference/classes/extends/index.md b/files/en-us/web/javascript/reference/classes/extends/index.md index 63846fe96de562f..6570ef3495159f8 100644 --- a/files/en-us/web/javascript/reference/classes/extends/index.md +++ b/files/en-us/web/javascript/reference/classes/extends/index.md @@ -131,7 +131,7 @@ Here are some things you may expect when extending a class: However, the above expectations take non-trivial efforts to implement properly. - The first one requires the static method to read the value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this) to get the constructor for constructing the returned instance. This means `[p1, p2, p3].map(Promise.resolve)` throws an error because the `this` inside `Promise.resolve` is `undefined`. A way to fix this is to fall back to the base class if `this` is not a constructor, like {{jsxref("Array.from()")}} does, but that still means the base class is special-cased. -- The second one requires the instance method to read [`this.constructor`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor) to get the constructor function. However, `new this.constructor()` may break legacy code, because the `constructor` property is both writable and configurable and is not protected in any way. Therefore, many copying built-in methods use the constructor's [`@@species`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/species) property instead (which by default just returns `this`, the constructor itself). However, `@@species` allows running arbitrary code and creating instances of arbitrary type, which poses a security concern and greatly complicates subclassing semantics. +- The second one requires the instance method to read [`this.constructor`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor) to get the constructor function. However, `new this.constructor()` may break legacy code, because the `constructor` property is both writable and configurable and is not protected in any way. Therefore, many copying built-in methods use the constructor's [`[Symbol.species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/species) property instead (which by default just returns `this`, the constructor itself). However, `[Symbol.species]` allows running arbitrary code and creating instances of arbitrary type, which poses a security concern and greatly complicates subclassing semantics. - The third one leads to visible invocations of custom code, which makes a lot of optimizations harder to implement. For example, if the `Map()` constructor is called with an iterable of _x_ elements, then it must visibly invoke the `set()` method _x_ times, instead of just copying the elements into the internal storage. These problems are not unique to built-in classes. For your own classes, you will likely have to make the same decisions. However, for built-in classes, optimizability and security are a much bigger concern. New built-in methods always construct the base class and call as few custom methods as possible. If you want to subclass built-ins while achieving the above expectations, you need to override all methods that have the default behavior baked into them. Any addition of new methods on the base class may also break the semantics of your subclass because they are inherited by default. Therefore, a better way to extend built-ins is to use [_composition_](#avoiding_inheritance). diff --git a/files/en-us/web/javascript/reference/errors/requires_global_regexp/index.md b/files/en-us/web/javascript/reference/errors/requires_global_regexp/index.md index 321f29dc7dc9f02..3b0da2376171e9f 100644 --- a/files/en-us/web/javascript/reference/errors/requires_global_regexp/index.md +++ b/files/en-us/web/javascript/reference/errors/requires_global_regexp/index.md @@ -27,7 +27,7 @@ TypeError: String.prototype.replaceAll argument must not be a non-global regular The {{jsxref("String.prototype.matchAll()")}} and {{jsxref("String.prototype.replaceAll()")}} methods require a {{jsxref("RegExp")}} object with the {{jsxref("RegExp/global", "global")}} flag set. This flag indicates that the regular expression can match all locations of the input string, instead of stopping at the first match. Although the `g` flag is redundant when using these methods (because these methods always do a global replacement), they are still required to make the intention clear. -It's worth noting that the `g` flag validation is done in the `matchAll` and `replaceAll` methods. If you use the [`@@matchAll`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) method of `RegExp` instead, you won't get this error, but there will only be a single match. +It's worth noting that the `g` flag validation is done in the `matchAll` and `replaceAll` methods. If you use the [`[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) method of `RegExp` instead, you won't get this error, but there will only be a single match. ## Examples @@ -54,7 +54,7 @@ const newPattern = new RegExp( "abc".replaceAll(newPattern, "f"); // "fff" ``` -If you only intend to do a single matching/replacement: use {{jsxref("String.prototype.match()")}} or {{jsxref("String.prototype.replace()")}} instead. You can also use the `@@matchAll` method if you want an iterator like `matchAll` returns that only contains one match, but doing so will be very confusing. +If you only intend to do a single matching/replacement: use {{jsxref("String.prototype.match()")}} or {{jsxref("String.prototype.replace()")}} instead. You can also use the `[Symbol.matchAll]()` method if you want an iterator like `matchAll` returns that only contains one match, but doing so will be very confusing. ```js example-good "abc".match(/./); // [ "a" ] diff --git a/files/en-us/web/javascript/reference/functions/arguments/@@iterator/index.md b/files/en-us/web/javascript/reference/functions/arguments/@@iterator/index.md index 6e5794c97b6d67b..0b92ad2bd5d6939 100644 --- a/files/en-us/web/javascript/reference/functions/arguments/@@iterator/index.md +++ b/files/en-us/web/javascript/reference/functions/arguments/@@iterator/index.md @@ -1,5 +1,5 @@ --- -title: arguments[@@iterator]() +title: arguments[Symbol.iterator]() slug: Web/JavaScript/Reference/Functions/arguments/@@iterator page-type: javascript-instance-method browser-compat: javascript.functions.arguments.@@iterator @@ -7,9 +7,9 @@ browser-compat: javascript.functions.arguments.@@iterator {{jsSidebar("Functions")}} -The **`[@@iterator]()`** method of {{jsxref("Functions/arguments", "arguments")}} objects implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `arguments` objects to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns an [array iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the value of each index in the `arguments` object. +The **`[Symbol.iterator]()`** method of {{jsxref("Functions/arguments", "arguments")}} objects implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `arguments` objects to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns an [array iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the value of each index in the `arguments` object. -The initial value of this property is the same function object as the initial value of the {{jsxref("Array.prototype.values")}} property (and also the same as [`Array.prototype[@@iterator]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator)). +The initial value of this property is the same function object as the initial value of the {{jsxref("Array.prototype.values")}} property (and also the same as [`Array.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator)). ## Syntax @@ -29,7 +29,7 @@ The same return value as {{jsxref("Array.prototype.values()")}}: a new [iterable ### Iteration using for...of loop -Note that you seldom need to call this method directly. The existence of the `@@iterator` method makes `arguments` objects [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. +Note that you seldom need to call this method directly. The existence of the `[Symbol.iterator]()` method makes `arguments` objects [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. ```js function f() { diff --git a/files/en-us/web/javascript/reference/functions/arguments/index.md b/files/en-us/web/javascript/reference/functions/arguments/index.md index c1f635936ce355d..765aed6cadfb48c 100644 --- a/files/en-us/web/javascript/reference/functions/arguments/index.md +++ b/files/en-us/web/javascript/reference/functions/arguments/index.md @@ -122,7 +122,7 @@ console.log(midpoint(3, 1, 4, 1, 5)); // 3 - : Reference to the currently executing function that the arguments belong to. Forbidden in strict mode. - {{jsxref("Functions/arguments/length", "arguments.length")}} - : The number of arguments that were passed to the function. -- {{jsxref("Functions/arguments/@@iterator", "arguments[@@iterator]")}} +- [`arguments[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments/@@iterator) - : Returns a new {{jsxref("Array/@@iterator", "Array iterator", "", 0)}} object that contains the values for each index in `arguments`. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/array/@@iterator/index.md b/files/en-us/web/javascript/reference/global_objects/array/@@iterator/index.md index 54aa63484f5b4de..0e562bac2d7e2a8 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/@@iterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/@@iterator/index.md @@ -1,5 +1,5 @@ --- -title: Array.prototype[@@iterator]() +title: Array.prototype[Symbol.iterator]() slug: Web/JavaScript/Reference/Global_Objects/Array/@@iterator page-type: javascript-instance-method browser-compat: javascript.builtins.Array.@@iterator @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Array.@@iterator {{JSRef}} -The **`[@@iterator]()`** method of {{jsxref("Array")}} instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows arrays to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns an [array iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the value of each index in the array. +The **`[Symbol.iterator]()`** method of {{jsxref("Array")}} instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows arrays to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns an [array iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the value of each index in the array. The initial value of this property is the same function object as the initial value of the {{jsxref("Array.prototype.values")}} property. @@ -31,7 +31,7 @@ The same return value as {{jsxref("Array.prototype.values()")}}: a new [iterable ### Iteration using for...of loop -Note that you seldom need to call this method directly. The existence of the `@@iterator` method makes arrays [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. +Note that you seldom need to call this method directly. The existence of the `[Symbol.iterator]()` method makes arrays [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. #### HTML @@ -111,13 +111,13 @@ logIterable(123); ## See also -- [Polyfill of `Array.prototype[@@iterator]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-array) +- [Polyfill of `Array.prototype[Symbol.iterator]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-array) - [Indexed collections](/en-US/docs/Web/JavaScript/Guide/Indexed_collections) guide - {{jsxref("Array")}} - {{jsxref("Array.prototype.keys()")}} - {{jsxref("Array.prototype.entries()")}} - {{jsxref("Array.prototype.values()")}} -- [`TypedArray.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) -- [`String.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) +- [`TypedArray.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) +- [`String.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) - {{jsxref("Symbol.iterator")}} - [Iteration protocols](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) diff --git a/files/en-us/web/javascript/reference/global_objects/array/@@species/index.md b/files/en-us/web/javascript/reference/global_objects/array/@@species/index.md index fb537cefb22abac..3f2b964f4a20ecd 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/@@species/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/@@species/index.md @@ -1,5 +1,5 @@ --- -title: Array[@@species] +title: Array[Symbol.species] slug: Web/JavaScript/Reference/Global_Objects/Array/@@species page-type: javascript-static-accessor-property browser-compat: javascript.builtins.Array.@@species @@ -7,9 +7,9 @@ browser-compat: javascript.builtins.Array.@@species {{JSRef}} -The **`Array[@@species]`** static accessor property returns the constructor used to construct return values from array methods. +The **`Array[Symbol.species]`** static accessor property returns the constructor used to construct return values from array methods. -> **Warning:** The existence of `@@species` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. Modern array methods, such as {{jsxref("Array/toReversed", "toReversed()")}}, do not use `@@species` and always return a new `Array` base class instance. +> **Warning:** The existence of `[Symbol.species]` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. Modern array methods, such as {{jsxref("Array/toReversed", "toReversed()")}}, do not use `[Symbol.species]` and always return a new `Array` base class instance. ## Syntax @@ -19,11 +19,11 @@ Array[Symbol.species] ### Return value -The value of the constructor (`this`) on which `get @@species` was called. The return value is used to construct return values from array methods that create new arrays. +The value of the constructor (`this`) on which `get [Symbol.species]` was called. The return value is used to construct return values from array methods that create new arrays. ## Description -The `@@species` accessor property returns the default constructor for `Array` objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: +The `[Symbol.species]` accessor property returns the default constructor for `Array` objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: ```js // Hypothetical underlying implementation for illustration @@ -34,14 +34,14 @@ class Array { } ``` -Because of this polymorphic implementation, `@@species` of derived subclasses would also return the constructor itself by default. +Because of this polymorphic implementation, `[Symbol.species]` of derived subclasses would also return the constructor itself by default. ```js class SubArray extends Array {} SubArray[Symbol.species] === SubArray; // true ``` -When calling array methods that do not mutate the existing array but return a new array instance (for example, [`filter()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) and [`map()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)), the array's `constructor[@@species]` will be accessed. The returned constructor will be used to construct the return value of the array method. This makes it technically possible to make array methods return objects unrelated to arrays. +When calling array methods that do not mutate the existing array but return a new array instance (for example, [`filter()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) and [`map()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)), the array's `constructor[Symbol.species]` will be accessed. The returned constructor will be used to construct the return value of the array method. This makes it technically possible to make array methods return objects unrelated to arrays. ```js class NotAnArray { @@ -61,7 +61,7 @@ arr.concat([1, 2]); // NotAnArray { '0': 0, '1': 1, '2': 2, '3': 1, '4': 2, leng ### Species in ordinary objects -The `@@species` property returns the default constructor function, which is the `Array` constructor for `Array`. +The `[Symbol.species]` property returns the default constructor function, which is the `Array` constructor for `Array`. ```js Array[Symbol.species]; // [Function: Array] @@ -90,7 +90,7 @@ class MyArray extends Array { ## See also -- [Polyfill of `Array[@@species]` and support of `@@species` in all affected `Array` methods in `core-js`](https://github.com/zloirock/core-js#ecmascript-array) +- [Polyfill of `Array[Symbol.species]` and support of `[Symbol.species]` in all affected `Array` methods in `core-js`](https://github.com/zloirock/core-js#ecmascript-array) - [Indexed collections](/en-US/docs/Web/JavaScript/Guide/Indexed_collections) guide - {{jsxref("Array")}} - {{jsxref("Symbol.species")}} diff --git a/files/en-us/web/javascript/reference/global_objects/array/@@unscopables/index.md b/files/en-us/web/javascript/reference/global_objects/array/@@unscopables/index.md index 27bd371eb7c2e58..f31e5b6c37dde9d 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/@@unscopables/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/@@unscopables/index.md @@ -1,5 +1,5 @@ --- -title: Array.prototype[@@unscopables] +title: Array.prototype[Symbol.unscopables] slug: Web/JavaScript/Reference/Global_Objects/Array/@@unscopables page-type: javascript-instance-data-property browser-compat: javascript.builtins.Array.@@unscopables @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Array.@@unscopables {{JSRef}} -The **`@@unscopables`** data property of `Array.prototype` is shared by all {{jsxref("Array")}} instances. It contains property names that were not included in the ECMAScript standard prior to the ES2015 version and that are ignored for [`with`](/en-US/docs/Web/JavaScript/Reference/Statements/with) statement-binding purposes. +The **`[Symbol.unscopables]`** data property of `Array.prototype` is shared by all {{jsxref("Array")}} instances. It contains property names that were not included in the ECMAScript standard prior to the ES2015 version and that are ignored for [`with`](/en-US/docs/Web/JavaScript/Reference/Statements/with) statement-binding purposes. ## Value @@ -36,7 +36,7 @@ The default `Array` properties that are ignored for `with` statement-binding pur - [`toSpliced()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toSpliced) - [`values()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values) -`Array.prototype[@@unscopables]` is an empty object only containing all the above property names with the value `true`. Its [prototype is `null`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects), so `Object.prototype` properties like [`toString`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) won't accidentally be made unscopable, and a `toString()` within the `with` statement will continue to be called on the array. +`Array.prototype[Symbol.unscopables]` is an empty object only containing all the above property names with the value `true`. Its [prototype is `null`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects), so `Object.prototype` properties like [`toString`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) won't accidentally be made unscopable, and a `toString()` within the `with` statement will continue to be called on the array. See {{jsxref("Symbol.unscopables")}} for how to set unscopable properties for your own objects. @@ -54,7 +54,7 @@ with (values) { When ECMAScript 2015 introduced the {{jsxref("Array.prototype.values()")}} method, the `with` statement in the above code started to interpret `values` as the `values.values` array method instead of the external `values` variable. The `values.push('something')` call would break because it's now accessing `push` on the `values.values` method. This caused a bug to be reported to Firefox ([Firefox Bug 883914](https://bugzil.la/883914)). -So the `@@unscopables` data property for `Array.prototype` causes the `Array` properties introduced in ECMAScript 2015 to be ignored for `with` statement-binding purposes — allowing code that was written prior to ECMAScript 2015 to continue working as expected, rather than breaking. +So the `[Symbol.unscopables]` data property for `Array.prototype` causes the `Array` properties introduced in ECMAScript 2015 to be ignored for `with` statement-binding purposes — allowing code that was written prior to ECMAScript 2015 to continue working as expected, rather than breaking. ## Specifications @@ -66,7 +66,7 @@ So the `@@unscopables` data property for `Array.prototype` causes the `Array` pr ## See also -- [Polyfill of `Array.prototype[@@unscopables]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-array) +- [Polyfill of `Array.prototype[Symbol.unscopables]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-array) - [Indexed collections](/en-US/docs/Web/JavaScript/Guide/Indexed_collections) guide - {{jsxref("Array")}} - {{jsxref("Statements/with", "with")}} diff --git a/files/en-us/web/javascript/reference/global_objects/array/concat/index.md b/files/en-us/web/javascript/reference/global_objects/array/concat/index.md index 48e1d351de4a60f..de25af08ef871b5 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/concat/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/concat/index.md @@ -41,7 +41,7 @@ The `concat()` method is a [copying method](/en-US/docs/Web/JavaScript/Reference The `concat()` method preserves empty slots if any of the source arrays is [sparse](/en-US/docs/Web/JavaScript/Guide/Indexed_collections#sparse_arrays). -The `concat()` method is [generic](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#generic_array_methods). The `this` value is treated in the same way as the other arguments (except it will be converted to an object first), which means plain objects will be directly prepended to the resulting array, while array-like objects with truthy `@@isConcatSpreadable` will be spread into the resulting array. +The `concat()` method is [generic](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#generic_array_methods). The `this` value is treated in the same way as the other arguments (except it will be converted to an object first), which means plain objects will be directly prepended to the resulting array, while array-like objects with truthy `[Symbol.isConcatSpreadable]` will be spread into the resulting array. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/array/entries/index.md b/files/en-us/web/javascript/reference/global_objects/array/entries/index.md index 58d7d5a0bde6136..df42b9652a041bc 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/entries/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/entries/index.md @@ -109,6 +109,6 @@ for (const entry of Array.prototype.entries.call(arrayLike)) { - {{jsxref("Array")}} - {{jsxref("Array.prototype.keys()")}} - {{jsxref("Array.prototype.values()")}} -- [`Array.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) +- [`Array.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) - {{jsxref("TypedArray.prototype.entries()")}} - [Iteration protocols](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) diff --git a/files/en-us/web/javascript/reference/global_objects/array/index.md b/files/en-us/web/javascript/reference/global_objects/array/index.md index 0b9031ed43f9ea8..91cb9446a653e12 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/index.md @@ -264,7 +264,7 @@ f("a", "b"); // 'a+b' ## Static properties -- {{jsxref("Array/@@species", "Array[@@species]")}} +- {{jsxref("Array/@@species", "Array[Symbol.species]")}} - : Returns the `Array` constructor. ## Static methods @@ -284,7 +284,7 @@ These properties are defined on `Array.prototype` and shared by all `Array` inst - {{jsxref("Object/constructor", "Array.prototype.constructor")}} - : The constructor function that created the instance object. For `Array` instances, the initial value is the {{jsxref("Array/Array", "Array")}} constructor. -- {{jsxref("Array/@@unscopables", "Array.prototype[@@unscopables]")}} +- {{jsxref("Array/@@unscopables", "Array.prototype[Symbol.unscopables]")}} - : Contains property names that were not included in the ECMAScript standard prior to the ES2015 version and that are ignored for [`with`](/en-US/docs/Web/JavaScript/Reference/Statements/with) statement-binding purposes. These properties are own properties of each `Array` instance. @@ -370,7 +370,7 @@ These properties are own properties of each `Array` instance. - : Returns a new [_array iterator_](/en-US/docs/Web/JavaScript/Guide/Iterators_and_generators) object that contains the values for each index in the array. - {{jsxref("Array.prototype.with()")}} - : Returns a new array with the element at the given index replaced with the given value, without modifying the original array. -- [`Array.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) +- [`Array.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) - : An alias for the [`values()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values) method by default. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/array/keys/index.md b/files/en-us/web/javascript/reference/global_objects/array/keys/index.md index 58477be15f568cb..8fdf0c85106f5e3 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/keys/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/keys/index.md @@ -76,6 +76,6 @@ for (const entry of Array.prototype.keys.call(arrayLike)) { - {{jsxref("Array")}} - {{jsxref("Array.prototype.entries()")}} - {{jsxref("Array.prototype.values()")}} -- [`Array.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) +- [`Array.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) - {{jsxref("TypedArray.prototype.keys()")}} - [Iteration protocols](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) diff --git a/files/en-us/web/javascript/reference/global_objects/array/splice/index.md b/files/en-us/web/javascript/reference/global_objects/array/splice/index.md index e64c301ea2548cb..f8c31f7f1f4f928 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/splice/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/splice/index.md @@ -59,7 +59,7 @@ If no elements are removed, an empty array is returned. ## Description -The `splice()` method is a [mutating method](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#copying_methods_and_mutating_methods). It may change the content of `this`. If the specified number of elements to insert differs from the number of elements being removed, the array's `length` will be changed as well. At the same time, it uses [`@@species`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@species) to create a new array instance to be returned. +The `splice()` method is a [mutating method](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#copying_methods_and_mutating_methods). It may change the content of `this`. If the specified number of elements to insert differs from the number of elements being removed, the array's `length` will be changed as well. At the same time, it uses [`[Symbol.species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@species) to create a new array instance to be returned. If the deleted portion is [sparse](/en-US/docs/Web/JavaScript/Guide/Indexed_collections#sparse_arrays), the array returned by `splice()` is sparse as well, with those corresponding indices being empty slots. diff --git a/files/en-us/web/javascript/reference/global_objects/array/values/index.md b/files/en-us/web/javascript/reference/global_objects/array/values/index.md index fd63fb184c9c25d..b2e4a6942af6ea0 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/values/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/values/index.md @@ -27,7 +27,7 @@ A new [iterable iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Obj ## Description -`Array.prototype.values()` is the default implementation of [`Array.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator). +`Array.prototype.values()` is the default implementation of [`Array.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator). ```js Array.prototype.values === Array.prototype[Symbol.iterator]; // true @@ -176,6 +176,6 @@ for (const entry of Array.prototype.values.call(arrayLike)) { - {{jsxref("Array")}} - {{jsxref("Array.prototype.entries()")}} - {{jsxref("Array.prototype.keys()")}} -- [`Array.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) +- [`Array.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) - {{jsxref("TypedArray.prototype.values()")}} - [Iteration protocols](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) diff --git a/files/en-us/web/javascript/reference/global_objects/arraybuffer/@@species/index.md b/files/en-us/web/javascript/reference/global_objects/arraybuffer/@@species/index.md index 934ca63e925cfa1..16c2887df727698 100644 --- a/files/en-us/web/javascript/reference/global_objects/arraybuffer/@@species/index.md +++ b/files/en-us/web/javascript/reference/global_objects/arraybuffer/@@species/index.md @@ -1,5 +1,5 @@ --- -title: ArrayBuffer[@@species] +title: ArrayBuffer[Symbol.species] slug: Web/JavaScript/Reference/Global_Objects/ArrayBuffer/@@species page-type: javascript-static-accessor-property browser-compat: javascript.builtins.ArrayBuffer.@@species @@ -7,9 +7,9 @@ browser-compat: javascript.builtins.ArrayBuffer.@@species {{JSRef}} -The **`ArrayBuffer[@@species]`** static accessor property returns the constructor used to construct return values from array buffer methods. +The **`ArrayBuffer[Symbol.species]`** static accessor property returns the constructor used to construct return values from array buffer methods. -> **Warning:** The existence of `@@species` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. +> **Warning:** The existence of `[Symbol.species]` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. ## Syntax @@ -19,11 +19,11 @@ ArrayBuffer[Symbol.species] ### Return value -The value of the constructor (`this`) on which `get @@species` was called. The return value is used to construct return values from array buffer methods that create new array buffers. +The value of the constructor (`this`) on which `get [Symbol.species]` was called. The return value is used to construct return values from array buffer methods that create new array buffers. ## Description -The `@@species` accessor property returns the default constructor for `ArrayBuffer` objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: +The `[Symbol.species]` accessor property returns the default constructor for `ArrayBuffer` objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: ```js // Hypothetical underlying implementation for illustration @@ -34,20 +34,20 @@ class ArrayBuffer { } ``` -Because of this polymorphic implementation, `@@species` of derived subclasses would also return the constructor itself by default. +Because of this polymorphic implementation, `[Symbol.species]` of derived subclasses would also return the constructor itself by default. ```js class SubArrayBuffer extends ArrayBuffer {} SubArrayBuffer[Symbol.species] === SubArrayBuffer; // true ``` -When calling array buffer methods that do not mutate the existing object but return a new array buffer instance (for example, [`slice()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/slice)), the object's `constructor[@@species]` will be accessed. The returned constructor will be used to construct the return value of the array buffer method. +When calling array buffer methods that do not mutate the existing object but return a new array buffer instance (for example, [`slice()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/slice)), the object's `constructor[Symbol.species]` will be accessed. The returned constructor will be used to construct the return value of the array buffer method. ## Examples ### Species in ordinary objects -The `@@species` property returns the default constructor function, which is the `ArrayBuffer` constructor for `ArrayBuffer`. +The `[Symbol.species]` property returns the default constructor function, which is the `ArrayBuffer` constructor for `ArrayBuffer`. ```js ArrayBuffer[Symbol.species]; // function ArrayBuffer() diff --git a/files/en-us/web/javascript/reference/global_objects/arraybuffer/index.md b/files/en-us/web/javascript/reference/global_objects/arraybuffer/index.md index 10c726705abe8b3..df791a79d2a7da7 100644 --- a/files/en-us/web/javascript/reference/global_objects/arraybuffer/index.md +++ b/files/en-us/web/javascript/reference/global_objects/arraybuffer/index.md @@ -41,7 +41,7 @@ You can check whether an `ArrayBuffer` is detached by its {{jsxref("ArrayBuffer/ ## Static properties -- {{jsxref("ArrayBuffer/@@species", "ArrayBuffer[@@species]")}} +- {{jsxref("ArrayBuffer/@@species", "ArrayBuffer[Symbol.species]")}} - : The constructor function that is used to create derived objects. ## Static methods @@ -63,8 +63,8 @@ These properties are defined on `ArrayBuffer.prototype` and shared by all `Array - : The read-only maximum length, in bytes, that the `ArrayBuffer` can be resized to. This is established when the array is constructed and cannot be changed. - {{jsxref("ArrayBuffer.prototype.resizable")}} - : Read-only. Returns `true` if the `ArrayBuffer` can be resized, or `false` if not. -- `ArrayBuffer.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"ArrayBuffer"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `ArrayBuffer.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"ArrayBuffer"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/asyncfunction/index.md b/files/en-us/web/javascript/reference/global_objects/asyncfunction/index.md index d785ae249b19760..0e18149c9c2eb26 100644 --- a/files/en-us/web/javascript/reference/global_objects/asyncfunction/index.md +++ b/files/en-us/web/javascript/reference/global_objects/asyncfunction/index.md @@ -30,8 +30,8 @@ These properties are defined on `AsyncFunction.prototype` and shared by all `Asy - {{jsxref("Object/constructor", "AsyncFunction.prototype.constructor")}} - : The constructor function that created the instance object. For `AsyncFunction` instances, the initial value is the {{jsxref("AsyncFunction/AsyncFunction", "AsyncFunction")}} constructor. -- `AsyncFunction.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"AsyncFunction"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `AsyncFunction.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"AsyncFunction"`. This property is used in {{jsxref("Object.prototype.toString()")}}. > **Note:** `AsyncFunction` instances do not have the [`prototype`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/prototype) property. diff --git a/files/en-us/web/javascript/reference/global_objects/asyncgenerator/index.md b/files/en-us/web/javascript/reference/global_objects/asyncgenerator/index.md index cf3d7d1fc0b61e9..91117b47dc25f65 100644 --- a/files/en-us/web/javascript/reference/global_objects/asyncgenerator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/asyncgenerator/index.md @@ -43,8 +43,8 @@ These properties are defined on `AsyncGenerator.prototype` and shared by all `As > **Note:** `AsyncGenerator` objects do not store a reference to the async generator function that created them. -- `AsyncGenerator.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"AsyncGenerator"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `AsyncGenerator.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"AsyncGenerator"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/asyncgeneratorfunction/index.md b/files/en-us/web/javascript/reference/global_objects/asyncgeneratorfunction/index.md index 623048ba0ced06c..2d54ec81e668888 100644 --- a/files/en-us/web/javascript/reference/global_objects/asyncgeneratorfunction/index.md +++ b/files/en-us/web/javascript/reference/global_objects/asyncgeneratorfunction/index.md @@ -34,8 +34,8 @@ These properties are defined on `AsyncGeneratorFunction.prototype` and shared by - : The constructor function that created the instance object. For `AsyncGeneratorFunction` instances, the initial value is the {{jsxref("AsyncGeneratorFunction/AsyncGeneratorFunction", "AsyncGeneratorFunction")}} constructor. - `AsyncGeneratorFunction.prototype.prototype` - : All async generator functions share the same [`prototype`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/prototype) property, which is [`AsyncGenerator.prototype`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator). Each async generator function created with the `async function*` syntax or the `AsyncGeneratorFunction()` constructor also has its own `prototype` property, whose prototype is `AsyncGeneratorFunction.prototype.prototype`. When the async generator function is called, its `prototype` property becomes the prototype of the returned async generator object. -- `AsyncGeneratorFunction.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"AsyncGeneratorFunction"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `AsyncGeneratorFunction.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"AsyncGeneratorFunction"`. This property is used in {{jsxref("Object.prototype.toString()")}}. These properties are own properties of each `AsyncGeneratorFunction` instance. diff --git a/files/en-us/web/javascript/reference/global_objects/asynciterator/@@asynciterator/index.md b/files/en-us/web/javascript/reference/global_objects/asynciterator/@@asynciterator/index.md index 0906b4f258b4707..3f17b6caca11618 100644 --- a/files/en-us/web/javascript/reference/global_objects/asynciterator/@@asynciterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/asynciterator/@@asynciterator/index.md @@ -1,5 +1,5 @@ --- -title: AsyncIterator.prototype[@@asyncIterator]() +title: AsyncIterator.prototype[Symbol.asyncIterator]() slug: Web/JavaScript/Reference/Global_Objects/AsyncIterator/@@asyncIterator page-type: javascript-instance-method browser-compat: javascript.builtins.AsyncIterator.@@asyncIterator @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.AsyncIterator.@@asyncIterator {{JSRef}} -The **`[@@asyncIterator]()`** method of {{jsxref("AsyncIterator")}} instances implements the [async iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) and allows built-in async iterators to be consumed by most syntaxes expecting async iterables, such as [`for await...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) loops. It returns the value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), which is the async iterator object itself. +The **`[Symbol.asyncIterator]()`** method of {{jsxref("AsyncIterator")}} instances implements the [async iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) and allows built-in async iterators to be consumed by most syntaxes expecting async iterables, such as [`for await...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) loops. It returns the value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), which is the async iterator object itself. {{EmbedInteractiveExample("pages/js/map-prototype-@@iterator.html")}} @@ -29,7 +29,7 @@ The value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), whic ### Iteration using for await...of loop -Note that you seldom need to call this method directly. The existence of the `@@asyncIterator` method makes all built-in async iterators [async iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols), and iterating syntaxes like the `for await...of` loop automatically calls this method to obtain the async iterator to loop over. +Note that you seldom need to call this method directly. The existence of the `[Symbol.asyncIterator]()` method makes all built-in async iterators [async iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols), and iterating syntaxes like the `for await...of` loop automatically calls this method to obtain the async iterator to loop over. ```js const asyncIterator = (async function* () { diff --git a/files/en-us/web/javascript/reference/global_objects/asynciterator/index.md b/files/en-us/web/javascript/reference/global_objects/asynciterator/index.md index c5a4bafe70b7fe8..d7b2a54ebe5d91c 100644 --- a/files/en-us/web/javascript/reference/global_objects/asynciterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/asynciterator/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.AsyncIterator {{JSRef}} -An **`AsyncIterator`** object is an object that conforms to the [async iterator protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) by providing a `next()` method that returns a promise fulfilling to an iterator result object. The `AsyncIterator.prototype` object is a hidden global object that all built-in async iterators inherit from. It provides an [`@@asyncIterator`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator/@@asyncIterator) method that returns the async iterator object itself, making the async iterator also [async iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols). +An **`AsyncIterator`** object is an object that conforms to the [async iterator protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) by providing a `next()` method that returns a promise fulfilling to an iterator result object. The `AsyncIterator.prototype` object is a hidden global object that all built-in async iterators inherit from. It provides an [`[Symbol.asyncIterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator/@@asyncIterator) method that returns the async iterator object itself, making the async iterator also [async iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols). Note that `AsyncIterator` is _not_ a global object, although it will be in the future with the [async iterator helpers proposal](https://github.com/tc39/proposal-async-iterator-helpers). The `AsyncIterator.prototype` object shared by all built-in async iterators can be obtained with the following code: @@ -21,13 +21,13 @@ const AsyncIteratorPrototype = Object.getPrototypeOf( Currently, the only built-in JavaScript async iterator is the {{jsxref("AsyncGenerator")}} object returned by [async generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/async_function*). There are some other built-in async iterators in web API, such as the one of a {{domxref("ReadableStream")}}. -Each of these async iterators have a distinct prototype object, which defines the `next()` method used by the particular async iterator. All of these prototype objects inherit from `AsyncIterator.prototype`, which provides an [`@@asyncIterator`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator) method that returns the async iterator object itself, making the async iterator also [async iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols). +Each of these async iterators have a distinct prototype object, which defines the `next()` method used by the particular async iterator. All of these prototype objects inherit from `AsyncIterator.prototype`, which provides an [`[Symbol.asyncIterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator) method that returns the async iterator object itself, making the async iterator also [async iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols). -> **Note:** `AsyncIterator.prototype` does not implement [`@@iterator`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator), so async iterators are not [sync iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) by default. +> **Note:** `AsyncIterator.prototype` does not implement [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator), so async iterators are not [sync iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) by default. ## Instance methods -- [`AsyncIterator.prototype[@@asyncIterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator/@@asyncIterator) +- [`AsyncIterator.prototype[Symbol.asyncIterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator/@@asyncIterator) - : Returns the async iterator object itself. This allows async iterator objects to also be async iterable. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/atomics/index.md b/files/en-us/web/javascript/reference/global_objects/atomics/index.md index f71e46a4a36c941..298a16c68b4c3b2 100644 --- a/files/en-us/web/javascript/reference/global_objects/atomics/index.md +++ b/files/en-us/web/javascript/reference/global_objects/atomics/index.md @@ -23,8 +23,8 @@ The `wait()` and `notify()` methods are modeled on Linux futexes ("fast user-spa ## Static properties -- `Atomics[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Atomics"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Atomics[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Atomics"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Static methods diff --git a/files/en-us/web/javascript/reference/global_objects/bigint/index.md b/files/en-us/web/javascript/reference/global_objects/bigint/index.md index e206739850e801e..41a7ee7ef0ae402 100644 --- a/files/en-us/web/javascript/reference/global_objects/bigint/index.md +++ b/files/en-us/web/javascript/reference/global_objects/bigint/index.md @@ -237,7 +237,7 @@ Many built-in operations that expect BigInts first coerce their arguments to Big - Strings are converted by parsing them as if they contain an integer literal. Any parsing failure results in a {{jsxref("SyntaxError")}}. The syntax is a subset of [string numeric literals](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion), where decimal points or exponent indicators are not allowed. - [Numbers](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) throw a {{jsxref("TypeError")}} to prevent unintended implicit coercion causing loss of precision. - [Symbols](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) throw a {{jsxref("TypeError")}}. -- Objects are first [converted to a primitive](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) by calling their [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"number"` as hint), `valueOf()`, and `toString()` methods, in that order. The resulting primitive is then converted to a BigInt. +- Objects are first [converted to a primitive](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) by calling their [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"number"` as hint), `valueOf()`, and `toString()` methods, in that order. The resulting primitive is then converted to a BigInt. The best way to achieve nearly the same effect in JavaScript is through the [`BigInt()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/BigInt) function: `BigInt(x)` uses the same algorithm to convert `x`, except that [Numbers](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) don't throw a {{jsxref("TypeError")}}, but are converted to BigInts if they are integers. @@ -261,8 +261,8 @@ These properties are defined on `BigInt.prototype` and shared by all `BigInt` in - {{jsxref("Object/constructor", "BigInt.prototype.constructor")}} - : The constructor function that created the instance object. For `BigInt` instances, the initial value is the {{jsxref("BigInt/BigInt", "BigInt")}} constructor. -- `BigInt.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"BigInt"`. This property is used in {{jsxref("Object.prototype.toString()")}}. However, because `BigInt` also has its own [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/toString) method, this property is not used unless you call [`Object.prototype.toString.call()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/call) with a BigInt as `thisArg`. +- `BigInt.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"BigInt"`. This property is used in {{jsxref("Object.prototype.toString()")}}. However, because `BigInt` also has its own [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/toString) method, this property is not used unless you call [`Object.prototype.toString.call()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/call) with a BigInt as `thisArg`. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/bigint/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/bigint/tostring/index.md index 5c9ec8f7be070ab..af5f4206ed514bb 100644 --- a/files/en-us/web/javascript/reference/global_objects/bigint/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/bigint/tostring/index.md @@ -43,7 +43,7 @@ If the specified BigInt value is negative, the sign is preserved. This is the ca The `toString()` method requires its `this` value to be a `BigInt` primitive or wrapper object. It throws a {{jsxref("TypeError")}} for other `this` values without attempting to coerce them to BigInt values. -Because `BigInt` doesn't have a [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, JavaScript calls the `toString()` method automatically when a `BigInt` _object_ is used in a context expecting a string, such as in a [template literal](/en-US/docs/Web/JavaScript/Reference/Template_literals). However, BigInt _primitive_ values do not consult the `toString()` method to be [coerced to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) — rather, they are directly converted using the same algorithm as the initial `toString()` implementation. +Because `BigInt` doesn't have a [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, JavaScript calls the `toString()` method automatically when a `BigInt` _object_ is used in a context expecting a string, such as in a [template literal](/en-US/docs/Web/JavaScript/Reference/Template_literals). However, BigInt _primitive_ values do not consult the `toString()` method to be [coerced to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) — rather, they are directly converted using the same algorithm as the initial `toString()` implementation. ```js BigInt.prototype.toString = () => "Overridden"; diff --git a/files/en-us/web/javascript/reference/global_objects/boolean/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/boolean/tostring/index.md index 794c25f80748d14..fcaae56e3f3b0a8 100644 --- a/files/en-us/web/javascript/reference/global_objects/boolean/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/boolean/tostring/index.md @@ -32,7 +32,7 @@ The {{jsxref("Boolean")}} object overrides the `toString` method of {{jsxref("Ob The `toString()` method requires its `this` value to be a `Boolean` primitive or wrapper object. It throws a {{jsxref("TypeError")}} for other `this` values without attempting to coerce them to boolean values. -Because `Boolean` doesn't have a [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, JavaScript calls the `toString()` method automatically when a `Boolean` _object_ is used in a context expecting a string, such as in a [template literal](/en-US/docs/Web/JavaScript/Reference/Template_literals). However, boolean _primitive_ values do not consult the `toString()` method to be [coerced to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) — rather, they are directly converted using the same algorithm as the initial `toString()` implementation. +Because `Boolean` doesn't have a [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, JavaScript calls the `toString()` method automatically when a `Boolean` _object_ is used in a context expecting a string, such as in a [template literal](/en-US/docs/Web/JavaScript/Reference/Template_literals). However, boolean _primitive_ values do not consult the `toString()` method to be [coerced to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) — rather, they are directly converted using the same algorithm as the initial `toString()` implementation. ```js Boolean.prototype.toString = () => "Overridden"; diff --git a/files/en-us/web/javascript/reference/global_objects/dataview/index.md b/files/en-us/web/javascript/reference/global_objects/dataview/index.md index 3882b9ec7c40df1..5ea70c0f3d897d0 100644 --- a/files/en-us/web/javascript/reference/global_objects/dataview/index.md +++ b/files/en-us/web/javascript/reference/global_objects/dataview/index.md @@ -86,8 +86,8 @@ These properties are defined on `DataView.prototype` and shared by all `DataView - : The offset (in bytes) of this view from the start of its {{jsxref("ArrayBuffer")}}. Fixed at construction time and thus **read only.** - {{jsxref("Object/constructor", "DataView.prototype.constructor")}} - : The constructor function that created the instance object. For `DataView` instances, the initial value is the {{jsxref("DataView/DataView", "DataView")}} constructor. -- `DataView.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"DataView"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `DataView.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"DataView"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/date/@@toprimitive/index.md b/files/en-us/web/javascript/reference/global_objects/date/@@toprimitive/index.md index cd7bcd9824c8cb7..abcd37d54ee57f6 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/@@toprimitive/index.md +++ b/files/en-us/web/javascript/reference/global_objects/date/@@toprimitive/index.md @@ -1,5 +1,5 @@ --- -title: Date.prototype[@@toPrimitive]() +title: Date.prototype[Symbol.toPrimitive]() slug: Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive page-type: javascript-instance-method browser-compat: javascript.builtins.Date.@@toPrimitive @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Date.@@toPrimitive {{JSRef}} -The **`[@@toPrimitive]()`** method of {{jsxref("Date")}} instances returns a primitive value representing this date. It may either be a string or a number, depending on the hint given. +The **`[Symbol.toPrimitive]()`** method of {{jsxref("Date")}} instances returns a primitive value representing this date. It may either be a string or a number, depending on the hint given. {{EmbedInteractiveExample("pages/js/date-toprimitive.html")}} @@ -37,13 +37,13 @@ If `hint` is `"number"`, this method returns a number by [coercing the `this` va ## Description -The `[@@toPrimitive]()` method is part of the [type coercion protocol](/en-US/docs/Web/JavaScript/Data_structures#type_coercion). JavaScript always calls the `[@@toPrimitive]()` method in priority to convert an object to a primitive value. You rarely need to invoke the `[@@toPrimitive]()` method yourself; JavaScript automatically invokes it when encountering an object where a primitive value is expected. +The `[Symbol.toPrimitive]()` method is part of the [type coercion protocol](/en-US/docs/Web/JavaScript/Data_structures#type_coercion). JavaScript always calls the `[Symbol.toPrimitive]()` method in priority to convert an object to a primitive value. You rarely need to invoke the `[Symbol.toPrimitive]()` method yourself; JavaScript automatically invokes it when encountering an object where a primitive value is expected. -The `[@@toPrimitive]()` method of the {{jsxref("Date")}} object returns a primitive value by either invoking {{jsxref("Date/valueOf", "this.valueOf()")}} and returning a number, or invoking {{jsxref("Date/toString", "this.toString()")}} and returning a string. It exists to override the default [primitive coercion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) process to return a string instead of a number, because primitive coercion, by default, calls {{jsxref("Date/valueOf", "valueOf()")}} before {{jsxref("Date/toString", "toString()")}}. With the custom `[@@toPrimitive]()`, `new Date(0) + 1` returns `"Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)1"` (a string) instead of `1` (a number). +The `[Symbol.toPrimitive]()` method of the {{jsxref("Date")}} object returns a primitive value by either invoking {{jsxref("Date/valueOf", "this.valueOf()")}} and returning a number, or invoking {{jsxref("Date/toString", "this.toString()")}} and returning a string. It exists to override the default [primitive coercion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) process to return a string instead of a number, because primitive coercion, by default, calls {{jsxref("Date/valueOf", "valueOf()")}} before {{jsxref("Date/toString", "toString()")}}. With the custom `[Symbol.toPrimitive]()`, `new Date(0) + 1` returns `"Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)1"` (a string) instead of `1` (a number). ## Examples -### Using \[@@toPrimitive]() +### Using \[Symbol.toPrimitive]() ```js const d = new Date(0); // 1970-01-01T00:00:00.000Z diff --git a/files/en-us/web/javascript/reference/global_objects/date/index.md b/files/en-us/web/javascript/reference/global_objects/date/index.md index 5f62c2e78bd25f0..34b58c7633f02c3 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/index.md +++ b/files/en-us/web/javascript/reference/global_objects/date/index.md @@ -29,7 +29,7 @@ console.log(new Date(8.64e15 + 1).toString()); // "Invalid Date" There are various methods that allow you to interact with the timestamp stored in the date: - You can interact with the timestamp value directly using the {{jsxref("Date/getTime", "getTime()")}} and {{jsxref("Date/setTime", "setTime()")}} methods. -- The {{jsxref("Date/valueOf", "valueOf()")}} and [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) (when passed `"number"`) methods — which are automatically called in [number coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) — return the timestamp, causing `Date` objects to behave like their timestamps when used in number contexts. +- The {{jsxref("Date/valueOf", "valueOf()")}} and [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) (when passed `"number"`) methods — which are automatically called in [number coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) — return the timestamp, causing `Date` objects to behave like their timestamps when used in number contexts. - All static methods ({{jsxref("Date.now()")}}, {{jsxref("Date.parse()")}}, and {{jsxref("Date.UTC()")}}) return timestamps instead of `Date` objects. - The {{jsxref("Date/Date", "Date()")}} constructor can be called with a timestamp as the only argument. @@ -166,7 +166,7 @@ Non-standard strings can be parsed in any way as desired by the implementation, ### Other ways to format a date - {{jsxref("Date/toISOString", "toISOString()")}} returns a string in the format `1970-01-01T00:00:00.000Z` (the date time string format introduced above, which is simplified [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). {{jsxref("Date/toJSON", "toJSON()")}} calls `toISOString()` and returns the result. -- {{jsxref("Date/toString", "toString()")}} returns a string in the format `Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)`, while {{jsxref("Date/toDateString", "toDateString()")}} and {{jsxref("Date/toTimeString", "toTimeString()")}} return the date and time parts of the string, respectively. [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) (when passed `"string"` or `"default"`) calls `toString()` and returns the result. +- {{jsxref("Date/toString", "toString()")}} returns a string in the format `Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)`, while {{jsxref("Date/toDateString", "toDateString()")}} and {{jsxref("Date/toTimeString", "toTimeString()")}} return the date and time parts of the string, respectively. [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) (when passed `"string"` or `"default"`) calls `toString()` and returns the result. - {{jsxref("Date/toUTCString", "toUTCString()")}} returns a string in the format `Thu, 01 Jan 1970 00:00:00 GMT` (generalized {{rfc(7231)}}). - {{jsxref("Date/toLocaleDateString", "toLocaleDateString()")}}, {{jsxref("Date/toLocaleTimeString", "toLocaleTimeString()")}}, and {{jsxref("Date/toLocaleString", "toLocaleString()")}} use locale-specific date and time formats, usually provided by the [`Intl`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API. @@ -285,7 +285,7 @@ These properties are defined on `Date.prototype` and shared by all `Date` instan - : Converts a date to a string using the UTC timezone. - {{jsxref("Date.prototype.valueOf()")}} - : Returns the primitive value of a {{jsxref("Date")}} object. Overrides the {{jsxref("Object.prototype.valueOf()")}} method. -- [`Date.prototype[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) +- [`Date.prototype[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) - : Converts this `Date` object to a primitive value. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/date/tojson/index.md b/files/en-us/web/javascript/reference/global_objects/date/tojson/index.md index e912c8b5a5177ea..869e7fc763d7b2b 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/tojson/index.md +++ b/files/en-us/web/javascript/reference/global_objects/date/tojson/index.md @@ -29,7 +29,7 @@ A string representing the given date in the [date time string format](/en-US/doc The `toJSON()` method is automatically called by {{jsxref("JSON.stringify()")}} when a `Date` object is stringified. This method is generally intended to, by default, usefully serialize {{jsxref("Date")}} objects during [JSON](/en-US/docs/Glossary/JSON) serialization, which can then be deserialized using the {{jsxref("Date/Date", "Date()")}} constructor as the reviver of {{jsxref("JSON.parse()")}}. -The method first attempts to convert its `this` value [to a primitive](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) by calling its [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"number"` as hint), {{jsxref("Object/valueOf", "valueOf()")}}, and {{jsxref("Object/toString", "toString()")}} methods, in that order. If the result is a [non-finite](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite) number, `null` is returned. (This generally corresponds to an invalid date, whose {{jsxref("Date/valueOf", "valueOf()")}} returns {{jsxref("NaN")}}.) Otherwise, if the converted primitive is not a number or is a finite number, the return value of {{jsxref("Date/toISOString", "this.toISOString()")}} is returned. +The method first attempts to convert its `this` value [to a primitive](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) by calling its [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"number"` as hint), {{jsxref("Object/valueOf", "valueOf()")}}, and {{jsxref("Object/toString", "toString()")}} methods, in that order. If the result is a [non-finite](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite) number, `null` is returned. (This generally corresponds to an invalid date, whose {{jsxref("Date/valueOf", "valueOf()")}} returns {{jsxref("NaN")}}.) Otherwise, if the converted primitive is not a number or is a finite number, the return value of {{jsxref("Date/toISOString", "this.toISOString()")}} is returned. Note that the method does not check whether the `this` value is a valid {{jsxref("Date")}} object. However, calling `Date.prototype.toJSON()` on non-`Date` objects fails unless the object's number primitive representation is `NaN`, or the object also has a `toISOString()` method. diff --git a/files/en-us/web/javascript/reference/global_objects/date/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/date/tostring/index.md index 50f7c996521d50b..18a62a748b1afe0 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/date/tostring/index.md @@ -27,7 +27,7 @@ A string representing the given date (see description for the format). Returns ` ## Description -The `toString()` method is part of the [type coercion protocol](/en-US/docs/Web/JavaScript/Data_structures#type_coercion). Because `Date` has a [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) method, that method always takes priority over `toString()` when a `Date` object is implicitly [coerced to a string](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). However, `Date.prototype[@@toPrimitive]()` still calls `this.toString()` internally. +The `toString()` method is part of the [type coercion protocol](/en-US/docs/Web/JavaScript/Data_structures#type_coercion). Because `Date` has a [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) method, that method always takes priority over `toString()` when a `Date` object is implicitly [coerced to a string](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). However, `Date.prototype[Symbol.toPrimitive]()` still calls `this.toString()` internally. The {{jsxref("Date")}} object overrides the {{jsxref("Object/toString", "toString()")}} method of {{jsxref("Object")}}. `Date.prototype.toString()` returns a string representation of the Date as interpreted in the local timezone, containing both the date and the time — it joins the string representation specified in {{jsxref("Date/toDateString", "toDateString()")}} and {{jsxref("Date/toTimeString", "toTimeString()")}} together, adding a space in between. For example: "Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)". diff --git a/files/en-us/web/javascript/reference/global_objects/date/valueof/index.md b/files/en-us/web/javascript/reference/global_objects/date/valueof/index.md index 0d3ea5efcb07a05..1e33fe07f6c0a6c 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/valueof/index.md +++ b/files/en-us/web/javascript/reference/global_objects/date/valueof/index.md @@ -27,7 +27,7 @@ A number representing the [timestamp](/en-US/docs/Web/JavaScript/Reference/Globa ## Description -The `valueOf()` method is part of the [type coercion protocol](/en-US/docs/Web/JavaScript/Data_structures#type_coercion). Because `Date` has a [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) method, that method always takes priority over `valueOf()` when a `Date` object is implicitly [coerced to a number](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion). However, `Date.prototype[@@toPrimitive]()` still calls `this.valueOf()` internally. +The `valueOf()` method is part of the [type coercion protocol](/en-US/docs/Web/JavaScript/Data_structures#type_coercion). Because `Date` has a [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) method, that method always takes priority over `valueOf()` when a `Date` object is implicitly [coerced to a number](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion). However, `Date.prototype[Symbol.toPrimitive]()` still calls `this.valueOf()` internally. The {{jsxref("Date")}} object overrides the {{jsxref("Object/valueOf", "valueOf()")}} method of {{jsxref("Object")}}. `Date.prototype.valueOf()` returns the timestamp of the date, which is functionally equivalent to the {{jsxref("Date.prototype.getTime()")}} method. diff --git a/files/en-us/web/javascript/reference/global_objects/finalizationregistry/index.md b/files/en-us/web/javascript/reference/global_objects/finalizationregistry/index.md index f2f99f61a2518cf..413229901aac7d9 100644 --- a/files/en-us/web/javascript/reference/global_objects/finalizationregistry/index.md +++ b/files/en-us/web/javascript/reference/global_objects/finalizationregistry/index.md @@ -92,8 +92,8 @@ These properties are defined on `FinalizationRegistry.prototype` and shared by a - {{jsxref("Object/constructor", "FinalizationRegistry.prototype.constructor")}} - : The constructor function that created the instance object. For `FinalizationRegistry` instances, the initial value is the {{jsxref("FinalizationRegistry/FinalizationRegistry", "FinalizationRegistry")}} constructor. -- `FinalizationRegistry.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"FinalizationRegistry"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `FinalizationRegistry.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"FinalizationRegistry"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/function/@@hasinstance/index.md b/files/en-us/web/javascript/reference/global_objects/function/@@hasinstance/index.md index 4b7ed2cbe1ef2e0..3aa7e5f3321143f 100644 --- a/files/en-us/web/javascript/reference/global_objects/function/@@hasinstance/index.md +++ b/files/en-us/web/javascript/reference/global_objects/function/@@hasinstance/index.md @@ -1,5 +1,5 @@ --- -title: Function.prototype[@@hasInstance]() +title: Function.prototype[Symbol.hasInstance]() slug: Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance page-type: javascript-instance-method browser-compat: javascript.builtins.Function.@@hasInstance @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Function.@@hasInstance {{JSRef}} -The **`[@@hasInstance]()`** method of {{jsxref("Function")}} instances specifies the default procedure for determining if a constructor function recognizes an object as one of the constructor's instances. It is called by the [`instanceof`](/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) operator. +The **`[Symbol.hasInstance]()`** method of {{jsxref("Function")}} instances specifies the default procedure for determining if a constructor function recognizes an object as one of the constructor's instances. It is called by the [`instanceof`](/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) operator. ## Syntax @@ -31,9 +31,9 @@ func[Symbol.hasInstance](value) ## Description -The [`instanceof`](/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) operator calls the [`[@@hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance) method of the right-hand side whenever such a method exists. Because all functions inherit from `Function.prototype` by default, they would all have the `[@@hasInstance]()` method, so most of the time, the `Function.prototype[@@hasInstance]` method specifies the behavior of `instanceof` when the right-hand side is a function. This method implements the default behavior of the `instanceof` operator (the same algorithm when `constructor` has no `@@hasInstance` method). +The [`instanceof`](/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) operator calls the [`[Symbol.hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance) method of the right-hand side whenever such a method exists. Because all functions inherit from `Function.prototype` by default, they would all have the `[Symbol.hasInstance]()` method, so most of the time, the `Function.prototype[Symbol.hasInstance]()` method specifies the behavior of `instanceof` when the right-hand side is a function. This method implements the default behavior of the `instanceof` operator (the same algorithm when `constructor` has no `[Symbol.hasInstance]()` method). -Unlike most methods, the `Function.prototype[@@hasInstance]()` property is non-configurable and non-writable. This is a security feature to prevent the underlying target function of a bound function from being obtainable. See [this StackOverflow answer](https://stackoverflow.com/questions/38215027/trying-to-understand-the-official-es6-spec-regarding-symbol-hasinstance/38215392#38215392) for an example. +Unlike most methods, the `Function.prototype[Symbol.hasInstance]()` property is non-configurable and non-writable. This is a security feature to prevent the underlying target function of a bound function from being obtainable. See [this StackOverflow answer](https://stackoverflow.com/questions/38215027/trying-to-understand-the-official-es6-spec-regarding-symbol-hasinstance/38215392#38215392) for an example. ## Examples @@ -47,7 +47,7 @@ const foo = new Foo(); console.log(foo instanceof Foo === Foo[Symbol.hasInstance](foo)); // true ``` -You may want to use this method if you want to invoke the default `instanceof` behavior, but you don't know if a constructor has a overridden `[@@hasInstance]()` method. +You may want to use this method if you want to invoke the default `instanceof` behavior, but you don't know if a constructor has a overridden `[Symbol.hasInstance]()` method. ```js class Foo { diff --git a/files/en-us/web/javascript/reference/global_objects/function/index.md b/files/en-us/web/javascript/reference/global_objects/function/index.md index 9afe9be7a65245b..7242a52e55940a5 100644 --- a/files/en-us/web/javascript/reference/global_objects/function/index.md +++ b/files/en-us/web/javascript/reference/global_objects/function/index.md @@ -47,7 +47,7 @@ These properties are own properties of each `Function` instance. - {{jsxref("Function.prototype.toString()")}} - : Returns a string representing the source code of the function. Overrides the {{jsxref("Object.prototype.toString")}} method. -- [`Function.prototype[@@hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance) +- [`Function.prototype[Symbol.hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance) - : Specifies the default procedure for determining if a constructor function recognizes an object as one of the constructor's instances. Called by the [`instanceof`](/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) operator. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/generator/index.md b/files/en-us/web/javascript/reference/global_objects/generator/index.md index 633b65b3c3fcc70..fa574a227eed025 100644 --- a/files/en-us/web/javascript/reference/global_objects/generator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/generator/index.md @@ -43,8 +43,8 @@ These properties are defined on `Generator.prototype` and shared by all `Generat > **Note:** `Generator` objects do not store a reference to the generator function that created them. -- `Generator.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Generator"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Generator.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Generator"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/generatorfunction/index.md b/files/en-us/web/javascript/reference/global_objects/generatorfunction/index.md index 8fac0d10d832a82..d2522507d9fa215 100644 --- a/files/en-us/web/javascript/reference/global_objects/generatorfunction/index.md +++ b/files/en-us/web/javascript/reference/global_objects/generatorfunction/index.md @@ -34,8 +34,8 @@ These properties are defined on `GeneratorFunction.prototype` and shared by all - : The constructor function that created the instance object. For `GeneratorFunction` instances, the initial value is the {{jsxref("GeneratorFunction/GeneratorFunction", "GeneratorFunction")}} constructor. - {{jsxref("GeneratorFunction.prototype.prototype")}} - : All generator functions share the same [`prototype`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/prototype) property, which is [`Generator.prototype`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator). Each generator function created with the `function*` syntax or the `GeneratorFunction()` constructor also has its own `prototype` property, whose prototype is `GeneratorFunction.prototype.prototype`. When the generator function is called, its `prototype` property becomes the prototype of the returned generator object. -- `GeneratorFunction.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"GeneratorFunction"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `GeneratorFunction.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"GeneratorFunction"`. This property is used in {{jsxref("Object.prototype.toString()")}}. These properties are own properties of each `GeneratorFunction` instance. diff --git a/files/en-us/web/javascript/reference/global_objects/intl/collator/index.md b/files/en-us/web/javascript/reference/global_objects/intl/collator/index.md index e4ccc4c29ecbf07..b9d4c5833b5b41d 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/collator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/collator/index.md @@ -27,8 +27,8 @@ These properties are defined on `Intl.Collator.prototype` and shared by all `Int - {{jsxref("Object/constructor", "Intl.Collator.prototype.constructor")}} - : The constructor function that created the instance object. For `Intl.Collator` instances, the initial value is the {{jsxref("Intl/Collator/Collator", "Intl.Collator")}} constructor. -- `Intl.Collator.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.Collator"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl.Collator.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.Collator"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/index.md b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/index.md index 6d01924f86d4bd0..3819b99baa8379c 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/index.md @@ -27,8 +27,8 @@ These properties are defined on `Intl.DateTimeFormat.prototype` and shared by al - {{jsxref("Object/constructor", "Intl.DateTimeFormat.prototype.constructor")}} - : The constructor function that created the instance object. For `Intl.DateTimeFormat` instances, the initial value is the {{jsxref("Intl/DateTimeFormat/DateTimeFormat", "Intl.DateTimeFormat")}} constructor. -- `Intl.DateTimeFormat.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.DateTimeFormat"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl.DateTimeFormat.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.DateTimeFormat"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/displaynames/index.md b/files/en-us/web/javascript/reference/global_objects/intl/displaynames/index.md index 94a6b8211761cb5..f5a8ef66eecabe4 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/displaynames/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/displaynames/index.md @@ -27,8 +27,8 @@ These properties are defined on `Intl.DisplayNames.prototype` and shared by all - {{jsxref("Object/constructor", "Intl.DisplayNames.prototype.constructor")}} - : The constructor function that created the instance object. For `Intl.DisplayNames` instances, the initial value is the {{jsxref("Intl/DisplayNames/DisplayNames", "Intl.DisplayNames")}} constructor. -- `Intl.DisplayNames.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.DisplayNames"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl.DisplayNames.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.DisplayNames"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/durationformat/index.md b/files/en-us/web/javascript/reference/global_objects/intl/durationformat/index.md index 4c0b4588ce603cc..4b1a3b30bf90ea3 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/durationformat/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/durationformat/index.md @@ -27,8 +27,8 @@ These properties are defined on `Intl.DurationFormat.prototype` and shared by al - {{jsxref("Object/constructor", "Intl.DurationFormat.prototype.constructor")}} - : The constructor function that created the instance object. For `Intl.DurationFormat` instances, the initial value is the {{jsxref("Intl/DurationFormat/DurationFormat", "Intl.DurationFormat")}} constructor. -- `Intl.DurationFormat.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.DurationFormat"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl.DurationFormat.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.DurationFormat"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/index.md b/files/en-us/web/javascript/reference/global_objects/intl/index.md index 192dd3bd4db0273..580abdc24b629ca 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/index.md @@ -90,8 +90,8 @@ If the selected locale identifier had a Unicode extension sequence, that extensi - : Constructor for objects that enable language-sensitive relative time formatting. - {{jsxref("Intl.Segmenter")}} - : Constructor for objects that enable locale-sensitive text segmentation. -- `Intl[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Static methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/listformat/index.md b/files/en-us/web/javascript/reference/global_objects/intl/listformat/index.md index 3e5d12962798c6a..9c2c19da3ecd714 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/listformat/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/listformat/index.md @@ -27,8 +27,8 @@ These properties are defined on `Intl.ListFormat.prototype` and shared by all `I - {{jsxref("Object/constructor", "Intl.ListFormat.prototype.constructor")}} - : The constructor function that created the instance object. For `Intl.ListFormat` instances, the initial value is the {{jsxref("Intl/ListFormat/ListFormat", "Intl.ListFormat")}} constructor. -- `Intl.ListFormat.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.ListFormat"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl.ListFormat.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.ListFormat"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/locale/index.md b/files/en-us/web/javascript/reference/global_objects/intl/locale/index.md index 611971073ffe5a5..d0fbb89d84e55c1 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/locale/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/locale/index.md @@ -62,8 +62,8 @@ These properties are defined on `Intl.Locale.prototype` and shared by all `Intl. - : Returns the region of the world (usually a country) associated with the locale. - {{jsxref("Intl/Locale/script", "Intl.Locale.prototype.script")}} - : Returns the script used for writing the particular language used in the locale. -- `Intl.Locale.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.Locale"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl.Locale.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.Locale"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/index.md b/files/en-us/web/javascript/reference/global_objects/intl/numberformat/index.md index 31d3cb7cd60efd7..f83a356fee0c881 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/numberformat/index.md @@ -27,8 +27,8 @@ These properties are defined on `Intl.NumberFormat.prototype` and shared by all - {{jsxref("Object/constructor", "Intl.NumberFormat.prototype.constructor")}} - : The constructor function that created the instance object. For `Intl.NumberFormat` instances, the initial value is the {{jsxref("Intl/NumberFormat/NumberFormat", "Intl.NumberFormat")}} constructor. -- `Intl.NumberFormat.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.NumberFormat"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl.NumberFormat.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.NumberFormat"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md index 03e5795b42e24b1..bcfcd5f7d3e0c06 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md @@ -53,8 +53,8 @@ These properties are defined on `Intl.PluralRules.prototype` and shared by all ` - {{jsxref("Object/constructor", "Intl.PluralRules.prototype.constructor")}} - : The constructor function that created the instance object. For `Intl.PluralRules` instances, the initial value is the {{jsxref("Intl/PluralRules/PluralRules", "Intl.PluralRules")}} constructor. -- `Intl.PluralRules.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.PluralRules"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl.PluralRules.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.PluralRules"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/relativetimeformat/index.md b/files/en-us/web/javascript/reference/global_objects/intl/relativetimeformat/index.md index 1380d53002ceb7f..9369e752ad62bcb 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/relativetimeformat/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/relativetimeformat/index.md @@ -27,8 +27,8 @@ These properties are defined on `Intl.RelativeTimeFormat.prototype` and shared b - {{jsxref("Object/constructor", "Intl.RelativeTimeFormat.prototype.constructor")}} - : The constructor function that created the instance object. For `Intl.RelativeTimeFormat` instances, the initial value is the {{jsxref("Intl/RelativeTimeFormat/RelativeTimeFormat", "Intl.RelativeTimeFormat")}} constructor. -- `Intl.RelativeTimeFormat.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.RelativeTimeFormat"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl.RelativeTimeFormat.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.RelativeTimeFormat"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/segmenter/index.md b/files/en-us/web/javascript/reference/global_objects/intl/segmenter/index.md index 2ccd8821d35aa8e..7fae0e746f85aa8 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/segmenter/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/segmenter/index.md @@ -27,8 +27,8 @@ These properties are defined on `Intl.Segmenter.prototype` and shared by all `In - {{jsxref("Object/constructor", "Intl.Segmenter.prototype.constructor")}} - : The constructor function that created the instance object. For `Intl.Segmenter` instances, the initial value is the {{jsxref("Intl/Segmenter/Segmenter", "Intl.Segmenter")}} constructor. -- `Intl.Segmenter.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.Segmenter"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Intl.Segmenter.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Intl.Segmenter"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/intl/segmenter/segment/segments/@@iterator/index.md b/files/en-us/web/javascript/reference/global_objects/intl/segmenter/segment/segments/@@iterator/index.md index c4819037553dbc1..d565cf1832a62b5 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/segmenter/segment/segments/@@iterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/segmenter/segment/segments/@@iterator/index.md @@ -1,5 +1,5 @@ --- -title: Segments.prototype[@@iterator]() +title: Segments.prototype[Symbol.iterator]() slug: Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/@@iterator page-type: javascript-instance-method browser-compat: javascript.builtins.Intl.Segments.@@iterator @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Intl.Segments.@@iterator {{JSRef}} -The **`[@@iterator]()`** method of [`Segments`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments) instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `Segments` objects to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns a [segments iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields data about each segment. +The **`[Symbol.iterator]()`** method of [`Segments`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments) instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `Segments` objects to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns a [segments iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields data about each segment. {{EmbedInteractiveExample("pages/js/segments-prototype-@@iterator.html")}} @@ -29,7 +29,7 @@ A new [iterable iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Obj ### Iteration using for...of loop -Note that you seldom need to call this method directly. The existence of the `@@iterator` method makes `Segments` objects [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. +Note that you seldom need to call this method directly. The existence of the `[Symbol.iterator]()` method makes `Segments` objects [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. ```js const segmenter = new Intl.Segmenter("zh-CN", { granularity: "word" }); diff --git a/files/en-us/web/javascript/reference/global_objects/intl/segmenter/segment/segments/index.md b/files/en-us/web/javascript/reference/global_objects/intl/segmenter/segment/segments/index.md index 64b0716e852d5ac..cd24993968ea520 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/segmenter/segment/segments/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/segmenter/segment/segments/index.md @@ -15,7 +15,7 @@ A **`Segments`** object is an iterable collection of the segments of a text stri - [`Segments.prototype.containing()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/containing) - : Returns an object describing the segment in the original string that includes the code unit at a specified index. -- [`Segments.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/@@iterator) +- [`Segments.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/@@iterator) - : Returns an iterator to iterate over the segments. ## Specifications diff --git a/files/en-us/web/javascript/reference/global_objects/iterator/@@iterator/index.md b/files/en-us/web/javascript/reference/global_objects/iterator/@@iterator/index.md index 1e251b9591fb3e8..7ad22334b656212 100644 --- a/files/en-us/web/javascript/reference/global_objects/iterator/@@iterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/iterator/@@iterator/index.md @@ -1,5 +1,5 @@ --- -title: Iterator.prototype[@@iterator]() +title: Iterator.prototype[Symbol.iterator]() slug: Web/JavaScript/Reference/Global_Objects/Iterator/@@iterator page-type: javascript-instance-method browser-compat: javascript.builtins.Iterator.@@iterator @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Iterator.@@iterator {{JSRef}} -The **`[@@iterator]()`** method of {{jsxref("Iterator")}} instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows built-in iterators to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns the value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), which is the iterator object itself. +The **`[Symbol.iterator]()`** method of {{jsxref("Iterator")}} instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows built-in iterators to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns the value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), which is the iterator object itself. ## Syntax @@ -27,7 +27,7 @@ The value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), whic ### Iteration using for...of loop -Note that you seldom need to call this method directly. The existence of the `@@iterator` method makes built-in iterators [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. +Note that you seldom need to call this method directly. The existence of the `[Symbol.iterator]()` method makes built-in iterators [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. ```js const arrIterator = [1, 2, 3].values(); diff --git a/files/en-us/web/javascript/reference/global_objects/iterator/flatmap/index.md b/files/en-us/web/javascript/reference/global_objects/iterator/flatmap/index.md index 3c1b4a61be37e2f..9a03a7e5ea06da1 100644 --- a/files/en-us/web/javascript/reference/global_objects/iterator/flatmap/index.md +++ b/files/en-us/web/javascript/reference/global_objects/iterator/flatmap/index.md @@ -37,7 +37,7 @@ A new [iterator helper](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iter ## Description -`flatMap` accepts two kinds of return values from `callbackFn`: an iterator or iterable. They are handled in the same way as {{jsxref("Iterator.from()")}}: if the return value is iterable, the `@@iterator` method is called and the return value is used; otherwise, the return value is treated as an iterator and its `next()` method is called. +`flatMap` accepts two kinds of return values from `callbackFn`: an iterator or iterable. They are handled in the same way as {{jsxref("Iterator.from()")}}: if the return value is iterable, the `[Symbol.iterator]()` method is called and the return value is used; otherwise, the return value is treated as an iterator and its `next()` method is called. ```js [1, 2, 3] @@ -65,14 +65,14 @@ A new [iterator helper](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iter return { ...it, [Symbol.iterator]() { - console.log("@@iterator called"); + console.log("Symbol.iterator called"); return it; }, }; } }) .toArray(); -// Logs "@@iterator called" +// Logs "Symbol.iterator called" // Returns [1, 2, 3] ``` diff --git a/files/en-us/web/javascript/reference/global_objects/iterator/from/index.md b/files/en-us/web/javascript/reference/global_objects/iterator/from/index.md index d23a363c9dada6d..6bcfb7e3a259358 100644 --- a/files/en-us/web/javascript/reference/global_objects/iterator/from/index.md +++ b/files/en-us/web/javascript/reference/global_objects/iterator/from/index.md @@ -24,7 +24,7 @@ from(object) ### Return value -If `object` is an iterable, its `@@iterator` method is called to obtain the iterator. Otherwise, `object` is assumed to be an iterator. If the iterator is already {{jsxref("Operators/instanceof", "instanceof")}} {{jsxref("Iterator")}} (which means it has `Iterator.prototype` in its prototype chain), it is returned directly. Otherwise, a new {{jsxref("Iterator")}} object is created that wraps the original iterator. +If `object` is an iterable, its `[Symbol.iterator]()` method is called to obtain the iterator. Otherwise, `object` is assumed to be an iterator. If the iterator is already {{jsxref("Operators/instanceof", "instanceof")}} {{jsxref("Iterator")}} (which means it has `Iterator.prototype` in its prototype chain), it is returned directly. Otherwise, a new {{jsxref("Iterator")}} object is created that wraps the original iterator. ## Description @@ -39,7 +39,7 @@ This method exists to convert custom iterators, probably exported by libraries, ### Converting an iterable to a proper iterator -Because `obj` is already an iterable that returns a proper iterator when its `@@iterator` method is called, `Iterator.from(obj)` returns the same iterator. +Because `obj` is already an iterable that returns a proper iterator when its `[Symbol.iterator]()` method is called, `Iterator.from(obj)` returns the same iterator. ```js const iterator = (function* () { @@ -58,7 +58,7 @@ const iterator2 = Iterator.from(obj); console.log(iterator2 === iterator); // true ``` -Because `obj2` is an iterable that returns a non-proper iterator when its `@@iterator` method is called, `Iterator.from(obj2)` returns a new iterator that wraps the original iterator. +Because `obj2` is an iterable that returns a non-proper iterator when its `[Symbol.iterator]()` method is called, `Iterator.from(obj2)` returns a new iterator that wraps the original iterator. ```js const iterator = { diff --git a/files/en-us/web/javascript/reference/global_objects/iterator/index.md b/files/en-us/web/javascript/reference/global_objects/iterator/index.md index 7f674831b06c1bc..604d63ddc9574eb 100644 --- a/files/en-us/web/javascript/reference/global_objects/iterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/iterator/index.md @@ -7,28 +7,28 @@ browser-compat: javascript.builtins.Iterator {{JSRef}} -An **`Iterator`** object is an object that conforms to the [iterator protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol) by providing a `next()` method that returns an iterator result object. All built-in iterators inherit from the `Iterator` class. The `Iterator` class provides a [`@@iterator`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator/@@iterator) method that returns the iterator object itself, making the iterator also [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol). It also provides some helper methods for working with iterators. +An **`Iterator`** object is an object that conforms to the [iterator protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol) by providing a `next()` method that returns an iterator result object. All built-in iterators inherit from the `Iterator` class. The `Iterator` class provides a [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator/@@iterator) method that returns the iterator object itself, making the iterator also [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol). It also provides some helper methods for working with iterators. ## Description The following are all built-in JavaScript iterators: -- The _Array Iterator_ returned by {{jsxref("Array.prototype.values()")}}, {{jsxref("Array.prototype.keys()")}}, {{jsxref("Array.prototype.entries()")}}, [`Array.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator), {{jsxref("TypedArray.prototype.values()")}}, {{jsxref("TypedArray.prototype.keys()")}}, {{jsxref("TypedArray.prototype.entries()")}}, [`TypedArray.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator), and [`arguments[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments/@@iterator). -- The _String Iterator_ returned by [`String.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator). -- The _Map Iterator_ returned by {{jsxref("Map.prototype.values()")}}, {{jsxref("Map.prototype.keys()")}}, {{jsxref("Map.prototype.entries()")}}, and [`Map.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator). -- The _Set Iterator_ returned by {{jsxref("Set.prototype.values()")}}, {{jsxref("Set.prototype.keys()")}}, {{jsxref("Set.prototype.entries()")}}, and [`Set.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator). -- The _RegExp String Iterator_ returned by [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) and {{jsxref("String.prototype.matchAll()")}}. +- The _Array Iterator_ returned by {{jsxref("Array.prototype.values()")}}, {{jsxref("Array.prototype.keys()")}}, {{jsxref("Array.prototype.entries()")}}, [`Array.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator), {{jsxref("TypedArray.prototype.values()")}}, {{jsxref("TypedArray.prototype.keys()")}}, {{jsxref("TypedArray.prototype.entries()")}}, [`TypedArray.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator), and [`arguments[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments/@@iterator). +- The _String Iterator_ returned by [`String.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator). +- The _Map Iterator_ returned by {{jsxref("Map.prototype.values()")}}, {{jsxref("Map.prototype.keys()")}}, {{jsxref("Map.prototype.entries()")}}, and [`Map.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator). +- The _Set Iterator_ returned by {{jsxref("Set.prototype.values()")}}, {{jsxref("Set.prototype.keys()")}}, {{jsxref("Set.prototype.entries()")}}, and [`Set.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator). +- The _RegExp String Iterator_ returned by [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) and {{jsxref("String.prototype.matchAll()")}}. - The {{jsxref("Generator")}} object returned by [generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/function*). -- The _Segments Iterator_ returned by the [`[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/@@iterator) method of the [`Segments`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments) object returned by [`Intl.Segmenter.prototype.segment()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment). +- The _Segments Iterator_ returned by the [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/@@iterator) method of the [`Segments`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments) object returned by [`Intl.Segmenter.prototype.segment()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment). - The _Iterator Helper_ returned by iterator helper methods such as {{jsxref("Iterator.prototype.filter()")}} and {{jsxref("Iterator.prototype.map()")}}. -Each of these iterators have a distinct prototype object, which defines the `next()` method used by the particular iterator. For example, all string iterator objects inherit from a hidden object `StringIteratorPrototype`, which has a `next()` method that iterates this string by code points. `StringIteratorPrototype` also has a [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property whose initial value is the string `"String Iterator"`. This property is used in {{jsxref("Object.prototype.toString()")}}. Similarly, other iterator prototypes also have their own `@@toStringTag` values, which are the same as the names given above. +Each of these iterators have a distinct prototype object, which defines the `next()` method used by the particular iterator. For example, all string iterator objects inherit from a hidden object `StringIteratorPrototype`, which has a `next()` method that iterates this string by code points. `StringIteratorPrototype` also has a [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property whose initial value is the string `"String Iterator"`. This property is used in {{jsxref("Object.prototype.toString()")}}. Similarly, other iterator prototypes also have their own `[Symbol.toStringTag]` values, which are the same as the names given above. -All of these prototype objects inherit from `Iterator.prototype`, which provides a [`@@iterator`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator) method that returns the iterator object itself, making the iterator also [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol). +All of these prototype objects inherit from `Iterator.prototype`, which provides a [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator) method that returns the iterator object itself, making the iterator also [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol). ### Iterator helpers -> **Note:** These methods are _iterator_ helpers, not _iterable_ helpers, because the only requirement for an object to be iterable is just the presence of a `@@iterator` method. There is no shared prototype to install these methods on. +> **Note:** These methods are _iterator_ helpers, not _iterable_ helpers, because the only requirement for an object to be iterable is just the presence of a `[Symbol.iterator]()` method. There is no shared prototype to install these methods on. The `Iterator` class itself provides some helper methods for working with iterators. For example, you may be tempted to do the following: @@ -132,11 +132,11 @@ These properties are defined on `Iterator.prototype` and shared by all `Iterator - {{jsxref("Object/constructor", "Iterator.prototype.constructor")}} - : The constructor function that created the instance object. For `Iterator` instances, the initial value is the {{jsxref("Iterator/Iterator", "Iterator")}} constructor. -- `Iterator.prototype[@@toStringTag]` +- `Iterator.prototype[Symbol.toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Iterator"`. This property is used in {{jsxref("Object.prototype.toString()")}}. + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Iterator"`. This property is used in {{jsxref("Object.prototype.toString()")}}. - > **Note:** Unlike the `@@toStringTag` on most built-in classes, `Iterator.prototype[@@toStringTag]` is writable for web compatibility reasons. + > **Note:** Unlike the `[Symbol.toStringTag]` on most built-in classes, `Iterator.prototype[Symbol.toStringTag]` is writable for web compatibility reasons. ## Instance methods @@ -162,7 +162,7 @@ These properties are defined on `Iterator.prototype` and shared by all `Iterator - : Returns a new iterator helper that yields the given number of elements in this iterator and then terminates. - {{jsxref("Iterator.prototype.toArray()")}} {{experimental_inline}} - : Creates a new {{jsxref("Array")}} instance populated with the elements yielded from the iterator. -- [`Iterator.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator/@@iterator) +- [`Iterator.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator/@@iterator) - : Returns the iterator object itself. This allows iterator objects to also be iterable. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/iterator/iterator/index.md b/files/en-us/web/javascript/reference/global_objects/iterator/iterator/index.md index 15907e4216481c3..cf2cd439677dc06 100644 --- a/files/en-us/web/javascript/reference/global_objects/iterator/iterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/iterator/iterator/index.md @@ -42,7 +42,7 @@ You can also use {{jsxref("Iterator.from()")}} to create an `Iterator` instance ### Subclassing Iterator -The following example defines a custom data structure, `Range`, which allows iteration. The simplest way to make an object iterable is to provide an [`[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator) method in the form of a generator function: +The following example defines a custom data structure, `Range`, which allows iteration. The simplest way to make an object iterable is to provide an [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator) method in the form of a generator function: ```js class Range { @@ -74,7 +74,7 @@ This works, but it isn't as nice as how built-in iterators work. There are two p - The returned iterator inherits from {{jsxref("Generator")}}, which means modifications to `Generator.prototype` are going to affect the returned iterator, which is a leak of abstraction. - The returned iterator does not inherit from a custom prototype, which makes it harder if we intend to add extra methods to the iterator. -We can mimic the implementation of built-in iterators, such as [map iterators](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator), by subclassing `Iterator`. This enables us to define extra properties, such as [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag), while making the iterator helper methods available on the returned iterator. +We can mimic the implementation of built-in iterators, such as [map iterators](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator), by subclassing `Iterator`. This enables us to define extra properties, such as [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag), while making the iterator helper methods available on the returned iterator. ```js class Range { diff --git a/files/en-us/web/javascript/reference/global_objects/json/index.md b/files/en-us/web/javascript/reference/global_objects/json/index.md index 26776c1d2705502..c02c54ab56fd614 100644 --- a/files/en-us/web/javascript/reference/global_objects/json/index.md +++ b/files/en-us/web/javascript/reference/global_objects/json/index.md @@ -89,8 +89,8 @@ Insignificant {{Glossary("whitespace")}} may be present anywhere except within a ## Static properties -- `JSON[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"JSON"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `JSON[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"JSON"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Static methods diff --git a/files/en-us/web/javascript/reference/global_objects/map/@@iterator/index.md b/files/en-us/web/javascript/reference/global_objects/map/@@iterator/index.md index ffc614d90fabb01..d706d3857f43d59 100644 --- a/files/en-us/web/javascript/reference/global_objects/map/@@iterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/map/@@iterator/index.md @@ -1,5 +1,5 @@ --- -title: Map.prototype[@@iterator]() +title: Map.prototype[Symbol.iterator]() slug: Web/JavaScript/Reference/Global_Objects/Map/@@iterator page-type: javascript-instance-method browser-compat: javascript.builtins.Map.@@iterator @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Map.@@iterator {{JSRef}} -The **`[@@iterator]()`** method of {{jsxref("Map")}} instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `Map` objects to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns a [map iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the key-value pairs of the map in insertion order. +The **`[Symbol.iterator]()`** method of {{jsxref("Map")}} instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `Map` objects to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns a [map iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the key-value pairs of the map in insertion order. The initial value of this property is the same function object as the initial value of the {{jsxref("Map.prototype.entries")}} property. @@ -31,7 +31,7 @@ The same return value as {{jsxref("Map.prototype.entries()")}}: a new [iterable ### Iteration using for...of loop -Note that you seldom need to call this method directly. The existence of the `@@iterator` method makes `Map` objects [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. +Note that you seldom need to call this method directly. The existence of the `[Symbol.iterator]()` method makes `Map` objects [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. ```js const myMap = new Map(); diff --git a/files/en-us/web/javascript/reference/global_objects/map/@@species/index.md b/files/en-us/web/javascript/reference/global_objects/map/@@species/index.md index 52dd014d1b593fe..49d87afddc06517 100644 --- a/files/en-us/web/javascript/reference/global_objects/map/@@species/index.md +++ b/files/en-us/web/javascript/reference/global_objects/map/@@species/index.md @@ -1,5 +1,5 @@ --- -title: Map[@@species] +title: Map[Symbol.species] slug: Web/JavaScript/Reference/Global_Objects/Map/@@species page-type: javascript-static-accessor-property browser-compat: javascript.builtins.Map.@@species @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Map.@@species {{JSRef}} -The **`Map[@@species]`** static accessor property is an unused accessor property specifying how to copy `Map` objects. +The **`Map[Symbol.species]`** static accessor property is an unused accessor property specifying how to copy `Map` objects. ## Syntax @@ -17,11 +17,11 @@ Map[Symbol.species] ### Return value -The value of the constructor (`this`) on which `get @@species` was called. The return value is used to construct copied `Map` instances. +The value of the constructor (`this`) on which `get [Symbol.species]` was called. The return value is used to construct copied `Map` instances. ## Description -The `@@species` accessor property returns the default constructor for `Map` objects. Subclass constructors may override it to change the constructor assignment. +The `[Symbol.species]` accessor property returns the default constructor for `Map` objects. Subclass constructors may override it to change the constructor assignment. > **Note:** This property is currently unused by all `Map` methods. @@ -29,7 +29,7 @@ The `@@species` accessor property returns the default constructor for `Map` obje ### Species in ordinary objects -The `@@species` property returns the default constructor function, which is the `Map` constructor for `Map`. +The `[Symbol.species]` property returns the default constructor function, which is the `Map` constructor for `Map`. ```js Map[Symbol.species]; // function Map() diff --git a/files/en-us/web/javascript/reference/global_objects/map/index.md b/files/en-us/web/javascript/reference/global_objects/map/index.md index 7dc22708daf4727..7043a1033a438c6 100644 --- a/files/en-us/web/javascript/reference/global_objects/map/index.md +++ b/files/en-us/web/javascript/reference/global_objects/map/index.md @@ -278,7 +278,7 @@ interface RTCStatsReport { `Map`-like objects are either read-only or read-writable (see the `readonly` keyword in the IDL above). -- Read-only `Map`-like objects have the property [`size`](#map.prototype.size), and the methods: [`entries()`](#map.prototype.entries), [`forEach()`](#map.prototype.foreach), [`get()`](#map.prototype.get), [`has()`](#map.prototype.has), [`keys()`](#map.prototype.keys), [`values()`](#map.prototype.values), and [`@@iterator`](#map.prototypeiterator). +- Read-only `Map`-like objects have the property [`size`](#map.prototype.size), and the methods: [`entries()`](#map.prototype.entries), [`forEach()`](#map.prototype.foreach), [`get()`](#map.prototype.get), [`has()`](#map.prototype.has), [`keys()`](#map.prototype.keys), [`values()`](#map.prototype.values), and [`[Symbol.iterator]()`](#map.prototypeiterator). - Writeable `Map`-like objects additionally have the methods: [`clear()`](#map.prototype.clear), [`delete()`](#map.prototype.delete), and [`set()`](#map.prototype.set). The methods and properties have the same behavior as the equivalent entities in `Map`, except for the restriction on the types of the keys and values. @@ -299,7 +299,7 @@ The following are examples of read-only `Map`-like browser objects: ## Static properties -- {{jsxref("Map/@@species", "Map[@@species]")}} +- {{jsxref("Map/@@species", "Map[Symbol.species]")}} - : The constructor function that is used to create derived objects. ## Static methods @@ -315,8 +315,8 @@ These properties are defined on `Map.prototype` and shared by all `Map` instance - : The constructor function that created the instance object. For `Map` instances, the initial value is the {{jsxref("Map/Map", "Map")}} constructor. - {{jsxref("Map.prototype.size")}} - : Returns the number of key/value pairs in the `Map` object. -- `Map.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Map"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Map.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Map"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods @@ -340,7 +340,7 @@ These properties are defined on `Map.prototype` and shared by all `Map` instance - : Sets the value for the passed key in the `Map` object. Returns the `Map` object. - {{jsxref("Map.prototype.values()")}} - : Returns a new Iterator object that contains the values for each element in the `Map` object in insertion order. -- [`Map.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator) +- [`Map.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator) - : Returns a new Iterator object that contains a two-member array of `[key, value]` for each element in the `Map` object in insertion order. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/math/index.md b/files/en-us/web/javascript/reference/global_objects/math/index.md index 64e7dd996dab1c5..4a3855cf6b24cd8 100644 --- a/files/en-us/web/javascript/reference/global_objects/math/index.md +++ b/files/en-us/web/javascript/reference/global_objects/math/index.md @@ -37,8 +37,8 @@ Unlike most global objects, `Math` is not a constructor. You cannot use it with - : Square root of ½; approximately `0.707`. - {{jsxref("Math.SQRT2")}} - : Square root of `2`; approximately `1.414`. -- `Math[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Math"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Math[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Math"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Static methods diff --git a/files/en-us/web/javascript/reference/global_objects/number/index.md b/files/en-us/web/javascript/reference/global_objects/number/index.md index 01bac07f6c32e1a..ae836bf77c25ef3 100644 --- a/files/en-us/web/javascript/reference/global_objects/number/index.md +++ b/files/en-us/web/javascript/reference/global_objects/number/index.md @@ -75,7 +75,7 @@ Many built-in operations that expect numbers first coerce their arguments to num - [Numeric separators](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#numeric_separators) are not allowed. - [BigInts](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) throw a {{jsxref("TypeError")}} to prevent unintended implicit coercion causing loss of precision. - [Symbols](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) throw a {{jsxref("TypeError")}}. -- Objects are first [converted to a primitive](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) by calling their [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"number"` as hint), `valueOf()`, and `toString()` methods, in that order. The resulting primitive is then converted to a number. +- Objects are first [converted to a primitive](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) by calling their [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"number"` as hint), `valueOf()`, and `toString()` methods, in that order. The resulting primitive is then converted to a number. There are two ways to achieve nearly the same effect in JavaScript. diff --git a/files/en-us/web/javascript/reference/global_objects/number/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/number/tostring/index.md index d7ed7054ee56bf9..168d0c7d1175106 100644 --- a/files/en-us/web/javascript/reference/global_objects/number/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/number/tostring/index.md @@ -63,7 +63,7 @@ On the other hand, {{jsxref("Number.prototype.toFixed()")}} and {{jsxref("Number The `toString()` method requires its `this` value to be a `Number` primitive or wrapper object. It throws a {{jsxref("TypeError")}} for other `this` values without attempting to coerce them to number values. -Because `Number` doesn't have a [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, JavaScript calls the `toString()` method automatically when a `Number` _object_ is used in a context expecting a string, such as in a [template literal](/en-US/docs/Web/JavaScript/Reference/Template_literals). However, Number _primitive_ values do not consult the `toString()` method to be [coerced to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) — rather, they are directly converted using the same algorithm as the initial `toString()` implementation. +Because `Number` doesn't have a [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, JavaScript calls the `toString()` method automatically when a `Number` _object_ is used in a context expecting a string, such as in a [template literal](/en-US/docs/Web/JavaScript/Reference/Template_literals). However, Number _primitive_ values do not consult the `toString()` method to be [coerced to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) — rather, they are directly converted using the same algorithm as the initial `toString()` implementation. ```js Number.prototype.toString = () => "Overridden"; diff --git a/files/en-us/web/javascript/reference/global_objects/object/constructor/index.md b/files/en-us/web/javascript/reference/global_objects/object/constructor/index.md index fff5fbe2e53520e..644b328d1e4f75c 100644 --- a/files/en-us/web/javascript/reference/global_objects/object/constructor/index.md +++ b/files/en-us/web/javascript/reference/global_objects/object/constructor/index.md @@ -136,7 +136,7 @@ Child.prototype = Object.create(Parent.prototype); The `constructor` of instances of `Child` will be `Parent` due to `Child.prototype` being re-assigned. -This is usually not a big deal — the language almost never reads the `constructor` property of an object. The only exception is when using [`@@species`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/species) to create new instances of a class, but such cases are rare, and you should be using the [`extends`](/en-US/docs/Web/JavaScript/Reference/Classes/extends) syntax to subclass builtins anyway. +This is usually not a big deal — the language almost never reads the `constructor` property of an object. The only exception is when using [`[Symbol.species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/species) to create new instances of a class, but such cases are rare, and you should be using the [`extends`](/en-US/docs/Web/JavaScript/Reference/Classes/extends) syntax to subclass builtins anyway. However, ensuring that `Child.prototype.constructor` always points to `Child` itself is crucial when some caller is using `constructor` to access the original class from an instance. Take the following case: the object has the `create()` method to create itself. diff --git a/files/en-us/web/javascript/reference/global_objects/object/fromentries/index.md b/files/en-us/web/javascript/reference/global_objects/object/fromentries/index.md index 22ef6ff3196426b..fd0dc52d782749c 100644 --- a/files/en-us/web/javascript/reference/global_objects/object/fromentries/index.md +++ b/files/en-us/web/javascript/reference/global_objects/object/fromentries/index.md @@ -36,7 +36,7 @@ A new object whose properties are given by the entries of the iterable. ## Description -The `Object.fromEntries()` method takes a list of key-value pairs and returns a new object whose properties are given by those entries. The `iterable` argument is expected to be an object that implements an `@@iterator` method. The method returns an iterator object that produces two-element array-like objects. The first element is a value that will be used as a property key, and the second element is the value to associate with that property key. +The `Object.fromEntries()` method takes a list of key-value pairs and returns a new object whose properties are given by those entries. The `iterable` argument is expected to be an object that implements an `[Symbol.iterator]()` method. The method returns an iterator object that produces two-element array-like objects. The first element is a value that will be used as a property key, and the second element is the value to associate with that property key. `Object.fromEntries()` performs the reverse of {{jsxref("Object.entries()")}}, except that `Object.entries()` only returns string-keyed properties, while `Object.fromEntries()` can also create symbol-keyed properties. diff --git a/files/en-us/web/javascript/reference/global_objects/object/index.md b/files/en-us/web/javascript/reference/global_objects/object/index.md index 07d52c363f3d368..a7831832572cd8a 100644 --- a/files/en-us/web/javascript/reference/global_objects/object/index.md +++ b/files/en-us/web/javascript/reference/global_objects/object/index.md @@ -145,7 +145,7 @@ JavaScript also has built-in APIs that produce `null`-prototype objects, especia - The return value of {{jsxref("Object.groupBy()")}} - The `groups` and `indices.groups` properties of the result of {{jsxref("RegExp.prototype.exec()")}} -- [`Array.prototype[@@unscopables]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@unscopables) (all `@@unscopables` objects should have `null`-prototype) +- [`Array.prototype[Symbol.unscopables]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@unscopables) (all `[Symbol.unscopables]` objects should have `null`-prototype) - [`import.meta`](/en-US/docs/Web/JavaScript/Reference/Operators/import.meta) - Module namespace objects, obtained through [`import * as ns from "module";`](/en-US/docs/Web/JavaScript/Reference/Statements/import#namespace_import) or [`import()`](/en-US/docs/Web/JavaScript/Reference/Operators/import) diff --git a/files/en-us/web/javascript/reference/global_objects/object/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/object/tostring/index.md index 608cb03be15d7ce..63a2500051658ee 100644 --- a/files/en-us/web/javascript/reference/global_objects/object/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/object/tostring/index.md @@ -31,7 +31,7 @@ JavaScript calls the `toString` method to [convert an object to a primitive valu This method is called in priority by [string conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion), but [numeric conversion](/en-US/docs/Web/JavaScript/Data_structures#numeric_coercion) and [primitive conversion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) call `valueOf()` in priority. However, because the base [`valueOf()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf) method returns an object, the `toString()` method is usually called in the end, unless the object overrides `valueOf()`. For example, `+[1]` returns `1`, because its [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString) method returns `"1"`, which is then converted to a number. -All objects that inherit from `Object.prototype` (that is, all except [`null`-prototype objects](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects)) inherit the `toString()` method. When you create a custom object, you can override `toString()` to call a custom method, so that your custom object can be converted to a string value. Alternatively, you can add a [`@@toPrimitive`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, which allows even more control over the conversion process, and will always be preferred over `valueOf` or `toString` for any type conversion. +All objects that inherit from `Object.prototype` (that is, all except [`null`-prototype objects](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects)) inherit the `toString()` method. When you create a custom object, you can override `toString()` to call a custom method, so that your custom object can be converted to a string value. Alternatively, you can add a [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, which allows even more control over the conversion process, and will always be preferred over `valueOf` or `toString` for any type conversion. To use the base `Object.prototype.toString()` with an object that has it overridden (or to invoke it on `null` or `undefined`), you need to call {{jsxref("Function.prototype.call()")}} or {{jsxref("Function.prototype.apply()")}} on it, passing the object you want to inspect as the first parameter (called `thisArg`). diff --git a/files/en-us/web/javascript/reference/global_objects/object/valueof/index.md b/files/en-us/web/javascript/reference/global_objects/object/valueof/index.md index c54f8c837b63d61..51102b1408d8a75 100644 --- a/files/en-us/web/javascript/reference/global_objects/object/valueof/index.md +++ b/files/en-us/web/javascript/reference/global_objects/object/valueof/index.md @@ -33,7 +33,7 @@ JavaScript calls the `valueOf` method to [convert an object to a primitive value This method is called in priority by [numeric conversion](/en-US/docs/Web/JavaScript/Data_structures#numeric_coercion) and [primitive conversion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion), but [string conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) calls `toString()` in priority, and `toString()` is very likely to return a string value (even for the {{jsxref("Object.prototype.toString()")}} base implementation), so `valueOf()` is usually not called in this case. -All objects that inherit from `Object.prototype` (that is, all except [`null`-prototype objects](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects)) inherit the `toString()` method. The `Object.prototype.valueOf()` base implementation is deliberately useless: by returning an object, its return value will never be used by any [primitive conversion algorithm](/en-US/docs/Web/JavaScript/Data_structures#type_coercion). Many built-in objects override this method to return an appropriate primitive value. When you create a custom object, you can override `valueOf()` to call a custom method, so that your custom object can be converted to a primitive value. Generally, `valueOf()` is used to return a value that is most meaningful for the object — unlike `toString()`, it does not need to be a string. Alternatively, you can add a [`@@toPrimitive`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, which allows even more control over the conversion process, and will always be preferred over `valueOf` or `toString` for any type conversion. +All objects that inherit from `Object.prototype` (that is, all except [`null`-prototype objects](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects)) inherit the `toString()` method. The `Object.prototype.valueOf()` base implementation is deliberately useless: by returning an object, its return value will never be used by any [primitive conversion algorithm](/en-US/docs/Web/JavaScript/Data_structures#type_coercion). Many built-in objects override this method to return an appropriate primitive value. When you create a custom object, you can override `valueOf()` to call a custom method, so that your custom object can be converted to a primitive value. Generally, `valueOf()` is used to return a value that is most meaningful for the object — unlike `toString()`, it does not need to be a string. Alternatively, you can add a [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, which allows even more control over the conversion process, and will always be preferred over `valueOf` or `toString` for any type conversion. ## Examples @@ -83,7 +83,7 @@ box.valueOf(); ### Using unary plus on objects -[Unary plus](/en-US/docs/Web/JavaScript/Reference/Operators/Unary_plus) performs [number coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) on its operand, which, for most objects without [`@@toPrimitive`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive), means calling its `valueOf()`. However, if the object doesn't have a custom `valueOf()` method, the base implementation will cause `valueOf()` to be ignored and the return value of `toString()` to be used instead. +[Unary plus](/en-US/docs/Web/JavaScript/Reference/Operators/Unary_plus) performs [number coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) on its operand, which, for most objects without [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive), means calling its `valueOf()`. However, if the object doesn't have a custom `valueOf()` method, the base implementation will cause `valueOf()` to be ignored and the return value of `toString()` to be used instead. ```js +new Date(); // the current timestamp; same as new Date().getTime() diff --git a/files/en-us/web/javascript/reference/global_objects/promise/@@species/index.md b/files/en-us/web/javascript/reference/global_objects/promise/@@species/index.md index 5fe2985351bee89..de43673aac208a3 100644 --- a/files/en-us/web/javascript/reference/global_objects/promise/@@species/index.md +++ b/files/en-us/web/javascript/reference/global_objects/promise/@@species/index.md @@ -1,5 +1,5 @@ --- -title: Promise[@@species] +title: Promise[Symbol.species] slug: Web/JavaScript/Reference/Global_Objects/Promise/@@species page-type: javascript-static-accessor-property browser-compat: javascript.builtins.Promise.@@species @@ -7,9 +7,9 @@ browser-compat: javascript.builtins.Promise.@@species {{JSRef}} -The **`Promise[@@species]`** static accessor property returns the constructor used to construct return values from promise methods. +The **`Promise[Symbol.species]`** static accessor property returns the constructor used to construct return values from promise methods. -> **Warning:** The existence of `@@species` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. +> **Warning:** The existence of `[Symbol.species]` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. ## Syntax @@ -19,11 +19,11 @@ Promise[Symbol.species] ### Return value -The value of the constructor (`this`) on which `get @@species` was called. The return value is used to construct return values from promise chaining methods that create new promises. +The value of the constructor (`this`) on which `get [Symbol.species]` was called. The return value is used to construct return values from promise chaining methods that create new promises. ## Description -The `@@species` accessor property returns the default constructor for `Promise` objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: +The `[Symbol.species]` accessor property returns the default constructor for `Promise` objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: ```js // Hypothetical underlying implementation for illustration @@ -34,14 +34,14 @@ class Promise { } ``` -Because of this polymorphic implementation, `@@species` of derived subclasses would also return the constructor itself by default. +Because of this polymorphic implementation, `[Symbol.species]` of derived subclasses would also return the constructor itself by default. ```js class SubPromise extends Promise {} SubPromise[Symbol.species] === SubPromise; // true ``` -Promise chaining methods — [`then()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then), [`catch()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch), and [`finally()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/finally) — return new promise objects. They get the constructor to construct the new promise through `this.constructor[@@species]`. If `this.constructor` is `undefined`, or if `this.constructor[@@species]` is `undefined` or `null`, the default {{jsxref("Promise/Promise", "Promise()")}} constructor is used. Otherwise, the constructor returned by `this.constructor[@@species]` is used to construct the new promise object. +Promise chaining methods — [`then()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then), [`catch()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch), and [`finally()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/finally) — return new promise objects. They get the constructor to construct the new promise through `this.constructor[Symbol.species]`. If `this.constructor` is `undefined`, or if `this.constructor[Symbol.species]` is `undefined` or `null`, the default {{jsxref("Promise/Promise", "Promise()")}} constructor is used. Otherwise, the constructor returned by `this.constructor[Symbol.species]` is used to construct the new promise object. ## Examples @@ -76,7 +76,7 @@ class MyPromise extends Promise { console.log(MyPromise.resolve(1).then(() => {}).someValue); // 1 ``` -By overriding `@@species`, the promise methods will return the base `Promise` type. +By overriding `[Symbol.species]`, the promise methods will return the base `Promise` type. ```js class MyPromise extends Promise { diff --git a/files/en-us/web/javascript/reference/global_objects/promise/finally/index.md b/files/en-us/web/javascript/reference/global_objects/promise/finally/index.md index 3b16cfb16ea1280..e674fd96d3e0ba1 100644 --- a/files/en-us/web/javascript/reference/global_objects/promise/finally/index.md +++ b/files/en-us/web/javascript/reference/global_objects/promise/finally/index.md @@ -56,7 +56,7 @@ promise.then( ); ``` -Because `finally()` calls `then()`, it supports subclassing. Moreover, notice the {{jsxref("Promise.resolve()")}} call above — in reality, `onFinally()`'s return value is resolved using the same algorithm as `Promise.resolve()`, but the actual constructor used to construct the resolved promise will be the subclass. `finally()` gets this constructor through [`promise.constructor[@@species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/@@species). +Because `finally()` calls `then()`, it supports subclassing. Moreover, notice the {{jsxref("Promise.resolve()")}} call above — in reality, `onFinally()`'s return value is resolved using the same algorithm as `Promise.resolve()`, but the actual constructor used to construct the resolved promise will be the subclass. `finally()` gets this constructor through [`promise.constructor[Symbol.species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/@@species). ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/promise/index.md b/files/en-us/web/javascript/reference/global_objects/promise/index.md index d04bbd52951763e..d71c28829d81148 100644 --- a/files/en-us/web/javascript/reference/global_objects/promise/index.md +++ b/files/en-us/web/javascript/reference/global_objects/promise/index.md @@ -175,7 +175,7 @@ Note that JavaScript is [single-threaded](/en-US/docs/Glossary/Thread) by nature ## Static properties -- {{jsxref("Promise/@@species", "Promise[@@species]")}} +- {{jsxref("Promise/@@species", "Promise[Symbol.species]")}} - : Returns the constructor used to construct return values from promise methods. ## Static methods @@ -201,8 +201,8 @@ These properties are defined on `Promise.prototype` and shared by all `Promise` - {{jsxref("Object/constructor", "Promise.prototype.constructor")}} - : The constructor function that created the instance object. For `Promise` instances, the initial value is the {{jsxref("Promise/Promise", "Promise")}} constructor. -- `Promise.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Promise"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Promise.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Promise"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/promise/then/index.md b/files/en-us/web/javascript/reference/global_objects/promise/then/index.md index 560f93a91b5f28e..f87af7f67c77812 100644 --- a/files/en-us/web/javascript/reference/global_objects/promise/then/index.md +++ b/files/en-us/web/javascript/reference/global_objects/promise/then/index.md @@ -61,7 +61,7 @@ For more information about the `onRejected` handler, see the {{jsxref("Promise/c [Thenable](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables) objects that arise along the `then()` chain are always [resolved](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise#the_resolve_function) — the `onFulfilled` handler never receives a thenable object, and any thenable returned by either handler are always resolved before being passed to the next handler. This is because when constructing the new promise, the `resolve` and `reject` functions passed by the `executor` are saved, and when the current promise settles, the respective function will be called with the fulfillment value or rejection reason. The resolving logic comes from the `resolve` function passed by the {{jsxref("Promise/Promise", "Promise()")}} constructor. -`then()` supports subclassing, which means it can be called on instances of subclasses of `Promise`, and the result will be a promise of the subclass type. You can customize the type of the return value through the [`@@species`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/@@species) property. +`then()` supports subclassing, which means it can be called on instances of subclasses of `Promise`, and the result will be a promise of the subclass type. You can customize the type of the return value through the [`[Symbol.species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/@@species) property. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/reflect/index.md b/files/en-us/web/javascript/reference/global_objects/reflect/index.md index bf92e8d2db5ae3b..77cdb02380135db 100644 --- a/files/en-us/web/javascript/reference/global_objects/reflect/index.md +++ b/files/en-us/web/javascript/reference/global_objects/reflect/index.md @@ -38,8 +38,8 @@ Nearly every `Reflect` method's behavior can be done with some other syntax or m ## Static properties -- `Reflect[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Reflect"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Reflect[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Reflect"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Static methods diff --git a/files/en-us/web/javascript/reference/global_objects/regexp/@@match/index.md b/files/en-us/web/javascript/reference/global_objects/regexp/@@match/index.md index 69bacb1e74d0926..15d60afa962f3d0 100644 --- a/files/en-us/web/javascript/reference/global_objects/regexp/@@match/index.md +++ b/files/en-us/web/javascript/reference/global_objects/regexp/@@match/index.md @@ -1,5 +1,5 @@ --- -title: RegExp.prototype[@@match]() +title: RegExp.prototype[Symbol.match]() slug: Web/JavaScript/Reference/Global_Objects/RegExp/@@match page-type: javascript-instance-method browser-compat: javascript.builtins.RegExp.@@match @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.RegExp.@@match {{JSRef}} -The **`[@@match]()`** method of {{jsxref("RegExp")}} instances specifies how [`String.prototype.match()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) should behave. In addition, its presence (or absence) can influence whether an object is regarded as a regular expression. +The **`[Symbol.match]()`** method of {{jsxref("RegExp")}} instances specifies how [`String.prototype.match()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) should behave. In addition, its presence (or absence) can influence whether an object is regarded as a regular expression. {{EmbedInteractiveExample("pages/js/regexp-prototype-@@match.html")}} @@ -41,9 +41,9 @@ For example, the following two examples return same result. /a/[Symbol.match]("abc"); ``` -If the regex is global (with the `g` flag), the regex's [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) method will be repeatedly called until `exec()` returns `null`. Otherwise, `exec()` would only be called once and its result becomes the return value of `@@match`. +If the regex is global (with the `g` flag), the regex's [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) method will be repeatedly called until `exec()` returns `null`. Otherwise, `exec()` would only be called once and its result becomes the return value of `[Symbol.match]()`. -Because `@@match` would keep calling `exec()` until it returns `null`, and `exec()` would automatically reset the regex's [`lastIndex`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) to 0 when the last match fails, `@@match` would typically not have side effects when it exits. However, when the regex is [sticky](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) but not global, `lastIndex` would not be reset. In this case, each call to `match()` may return a different result. +Because `[Symbol.match]()` would keep calling `exec()` until it returns `null`, and `exec()` would automatically reset the regex's [`lastIndex`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) to 0 when the last match fails, `[Symbol.match]()` would typically not have side effects when it exits. However, when the regex is [sticky](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) but not global, `lastIndex` would not be reset. In this case, each call to `match()` may return a different result. ```js const re = /[abc]/y; @@ -72,7 +72,7 @@ console.log("😄".match(/(?:)/gu)); // [ '', '' ] This method exists for customizing match behavior within `RegExp` subclasses. -In addition, the `@@match` property is used to check [whether an object is a regular expression](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#special_handling_for_regexes). +In addition, the `[Symbol.match]` property is used to check [whether an object is a regular expression](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#special_handling_for_regexes). ## Examples @@ -87,9 +87,9 @@ const result = re[Symbol.match](str); console.log(result); // ["2016", "01", "02"] ``` -### Using @@match in subclasses +### Using `[Symbol.match]()` in subclasses -Subclasses of {{jsxref("RegExp")}} can override the `[@@match]()` method to modify the default behavior. +Subclasses of {{jsxref("RegExp")}} can override the `[Symbol.match]()` method to modify the default behavior. ```js class MyRegExp extends RegExp { @@ -106,7 +106,7 @@ class MyRegExp extends RegExp { const re = new MyRegExp("([0-9]+)-([0-9]+)-([0-9]+)"); const str = "2016-01-02"; -const result = str.match(re); // String.prototype.match calls re[@@match]. +const result = str.match(re); // String.prototype.match calls re[Symbol.match](). console.log(result.group(1)); // 2016 console.log(result.group(2)); // 01 console.log(result.group(3)); // 02 @@ -122,12 +122,12 @@ console.log(result.group(3)); // 02 ## See also -- [Polyfill of `RegExp.prototype[@@match]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) +- [Polyfill of `RegExp.prototype[Symbol.match]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) - {{jsxref("String.prototype.match()")}} -- [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) -- [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) -- [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) -- [`RegExp.prototype[@@split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) +- [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) +- [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) +- [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) +- [`RegExp.prototype[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) - {{jsxref("RegExp.prototype.exec()")}} - {{jsxref("RegExp.prototype.test()")}} - {{jsxref("Symbol.match")}} diff --git a/files/en-us/web/javascript/reference/global_objects/regexp/@@matchall/index.md b/files/en-us/web/javascript/reference/global_objects/regexp/@@matchall/index.md index 710a87a1cc12f12..2dde4972776c20c 100644 --- a/files/en-us/web/javascript/reference/global_objects/regexp/@@matchall/index.md +++ b/files/en-us/web/javascript/reference/global_objects/regexp/@@matchall/index.md @@ -1,5 +1,5 @@ --- -title: RegExp.prototype[@@matchAll]() +title: RegExp.prototype[Symbol.matchAll]() slug: Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll page-type: javascript-instance-method browser-compat: javascript.builtins.RegExp.@@matchAll @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.RegExp.@@matchAll {{JSRef}} -The **`[@@matchAll]()`** method of {{jsxref("RegExp")}} instances specifies how [`String.prototype.matchAll`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll) should behave. +The **`[Symbol.matchAll]()`** method of {{jsxref("RegExp")}} instances specifies how [`String.prototype.matchAll`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll) should behave. {{EmbedInteractiveExample("pages/js/regexp-prototype-@@matchall.html", "taller")}} @@ -36,7 +36,7 @@ This method is called internally in {{jsxref("String.prototype.matchAll()")}}. F /a/g[Symbol.matchAll]("abc"); ``` -Like [`@@split`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split), `@@matchAll` starts by using [`@@species`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@species) to construct a new regex, thus avoiding mutating the original regexp in any way. [`lastIndex`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) starts as the original regex's value. +Like [`[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split), `[Symbol.matchAll]()` starts by using [`[Symbol.species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@species) to construct a new regex, thus avoiding mutating the original regexp in any way. [`lastIndex`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) starts as the original regex's value. ```js const regexp = /[a-c]/g; @@ -46,7 +46,7 @@ Array.from(str.matchAll(regexp), (m) => `${regexp.lastIndex} ${m[0]}`); // [ "1 b", "1 c" ] ``` -The validation that the input is a global regex happens in [`String.prototype.matchAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll). `@@matchAll` does not validate the input. If the regex is not global, the returned iterator yields the [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) result once and then returns `undefined`. If the regexp is global, each time the returned iterator's `next()` method is called, the regex's [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) is called and the result is yielded. +The validation that the input is a global regex happens in [`String.prototype.matchAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll). `[Symbol.matchAll]()` does not validate the input. If the regex is not global, the returned iterator yields the [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) result once and then returns `undefined`. If the regexp is global, each time the returned iterator's `next()` method is called, the regex's [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) is called and the result is yielded. When the regex is sticky and global, it will still perform sticky matches — i.e. it will not match any occurrences beyond the `lastIndex`. @@ -82,9 +82,9 @@ console.log(Array.from(result, (x) => x[0])); // [ "2016", "01", "02" ] ``` -### Using @@matchAll in subclasses +### Using `[Symbol.matchAll]()` in subclasses -Subclasses of {{jsxref("RegExp")}} can override the `[@@matchAll]()` method to modify the default behavior. +Subclasses of {{jsxref("RegExp")}} can override the `[Symbol.matchAll]()` method to modify the default behavior. For example, to return an {{jsxref("Array")}} instead of an [iterator](/en-US/docs/Web/JavaScript/Guide/Iterators_and_generators): @@ -117,10 +117,10 @@ console.log(result[1]); ## See also -- [Polyfill of `RegExp.prototype[@@matchAll]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) +- [Polyfill of `RegExp.prototype[Symbol.matchAll]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) - {{jsxref("String.prototype.matchAll()")}} -- [`RegExp.prototype[@@match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) -- [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) -- [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) -- [`RegExp.prototype[@@split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) +- [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) +- [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) +- [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) +- [`RegExp.prototype[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) - {{jsxref("Symbol.matchAll")}} diff --git a/files/en-us/web/javascript/reference/global_objects/regexp/@@replace/index.md b/files/en-us/web/javascript/reference/global_objects/regexp/@@replace/index.md index 6f3d2636c315ec5..39b481cc28690d9 100644 --- a/files/en-us/web/javascript/reference/global_objects/regexp/@@replace/index.md +++ b/files/en-us/web/javascript/reference/global_objects/regexp/@@replace/index.md @@ -1,5 +1,5 @@ --- -title: RegExp.prototype[@@replace]() +title: RegExp.prototype[Symbol.replace]() slug: Web/JavaScript/Reference/Global_Objects/RegExp/@@replace page-type: javascript-instance-method browser-compat: javascript.builtins.RegExp.@@replace @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.RegExp.@@replace {{JSRef}} -The **`[@@replace]()`** method of {{jsxref("RegExp")}} instances specifies how [`String.prototype.replace()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) and [`String.prototype.replaceAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) should behave when the regular expression is passed in as the pattern. +The **`[Symbol.replace]()`** method of {{jsxref("RegExp")}} instances specifies how [`String.prototype.replace()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) and [`String.prototype.replaceAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) should behave when the regular expression is passed in as the pattern. {{EmbedInteractiveExample("pages/js/regexp-prototype-@@replace.html")}} @@ -42,7 +42,7 @@ This method is called internally in {{jsxref("String.prototype.replace()")}} and If the regex is global (with the `g` flag), the regex's [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) method will be repeatedly called until `exec()` returns `null`. Otherwise, `exec()` would only be called once. For each `exec()` result, the substitution will be prepared based on the description in [`String.prototype.replace()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#description). -Because `@@replace` would keep calling `exec()` until it returns `null`, and `exec()` would automatically reset the regex's [`lastIndex`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) to 0 when the last match fails, `@@replace` would typically not have side effects when it exits. However, when the regex is [sticky](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) but not global, `lastIndex` would not be reset. In this case, each call to `replace()` may return a different result. +Because `[Symbol.replace]()` would keep calling `exec()` until it returns `null`, and `exec()` would automatically reset the regex's [`lastIndex`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) to 0 when the last match fails, `[Symbol.replace]()` would typically not have side effects when it exits. However, when the regex is [sticky](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) but not global, `lastIndex` would not be reset. In this case, each call to `replace()` may return a different result. ```js const re = /a/y; @@ -86,9 +86,9 @@ const newstr = re[Symbol.replace](str, "."); console.log(newstr); // 2016.01.01 ``` -### Using @@replace in subclasses +### Using `[Symbol.replace]()` in subclasses -Subclasses of {{jsxref("RegExp")}} can override the `[@@replace]()` method to modify the default behavior. +Subclasses of {{jsxref("RegExp")}} can override the `[Symbol.replace]()` method to modify the default behavior. ```js class MyRegExp extends RegExp { @@ -97,7 +97,7 @@ class MyRegExp extends RegExp { this.count = count; } [Symbol.replace](str, replacement) { - // Perform @@replace |count| times. + // Perform [Symbol.replace]() `count` times. let result = str; for (let i = 0; i < this.count; i++) { result = RegExp.prototype[Symbol.replace].call(this, result, replacement); @@ -108,7 +108,7 @@ class MyRegExp extends RegExp { const re = new MyRegExp("\\d", "", 3); const str = "01234567"; -const newstr = str.replace(re, "#"); // String.prototype.replace calls re[@@replace]. +const newstr = str.replace(re, "#"); // String.prototype.replace calls re[Symbol.replace](). console.log(newstr); // ###34567 ``` @@ -122,13 +122,13 @@ console.log(newstr); // ###34567 ## See also -- [Polyfill of `RegExp.prototype[@@replace]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) +- [Polyfill of `RegExp.prototype[Symbol.replace]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) - {{jsxref("String.prototype.replace()")}} - {{jsxref("String.prototype.replaceAll()")}} -- [`RegExp.prototype[@@match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) -- [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) -- [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) -- [`RegExp.prototype[@@split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) +- [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) +- [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) +- [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) +- [`RegExp.prototype[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) - {{jsxref("RegExp.prototype.exec()")}} - {{jsxref("RegExp.prototype.test()")}} - {{jsxref("Symbol.replace")}} diff --git a/files/en-us/web/javascript/reference/global_objects/regexp/@@search/index.md b/files/en-us/web/javascript/reference/global_objects/regexp/@@search/index.md index ecd8ee9620e141c..e5790af2df994fa 100644 --- a/files/en-us/web/javascript/reference/global_objects/regexp/@@search/index.md +++ b/files/en-us/web/javascript/reference/global_objects/regexp/@@search/index.md @@ -1,5 +1,5 @@ --- -title: RegExp.prototype[@@search]() +title: RegExp.prototype[Symbol.search]() slug: Web/JavaScript/Reference/Global_Objects/RegExp/@@search page-type: javascript-instance-method browser-compat: javascript.builtins.RegExp.@@search @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.RegExp.@@search {{JSRef}} -The **`[@@search]()`** method of {{jsxref("RegExp")}} instances specifies how [`String.prototype.search`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/search) should behave. +The **`[Symbol.search]()`** method of {{jsxref("RegExp")}} instances specifies how [`String.prototype.search`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/search) should behave. {{EmbedInteractiveExample("pages/js/regexp-prototype-@@search.html")}} @@ -36,7 +36,7 @@ This method is called internally in {{jsxref("String.prototype.search()")}}. For /a/[Symbol.search]("abc"); ``` -This method does not copy the regular expression, unlike [`@@split`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) or [`@@matchAll`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll). However, unlike [`@@match`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) or [`@@replace`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace), it will set [`lastIndex`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) to 0 when execution starts and restore it to the previous value when it exits, therefore generally avoiding side effects. This means that the `g` flag has no effect with this method, and it always returns the first match in the string even when `lastIndex` is non-zero. This also means sticky regexps will always search strictly at the beginning of the string. +This method does not copy the regular expression, unlike [`[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) or [`[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll). However, unlike [`[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) or [`[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace), it will set [`lastIndex`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) to 0 when execution starts and restore it to the previous value when it exits, therefore generally avoiding side effects. This means that the `g` flag has no effect with this method, and it always returns the first match in the string even when `lastIndex` is non-zero. This also means sticky regexps will always search strictly at the beginning of the string. ```js const re = /[abc]/g; @@ -49,7 +49,7 @@ console.log("abc".search(re2)); // -1 console.log("abc".match(re2)); // [ 'b' ] ``` -`@@search` always calls the regex's [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) method exactly once, and returns the `index` property of the result, or `-1` if the result is `null`. +`[Symbol.search]()` always calls the regex's [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) method exactly once, and returns the `index` property of the result, or `-1` if the result is `null`. This method exists for customizing the search behavior in `RegExp` subclasses. @@ -66,9 +66,9 @@ const result = re[Symbol.search](str); console.log(result); // 4 ``` -### Using @@search in subclasses +### Using `[Symbol.search]()` in subclasses -Subclasses of {{jsxref("RegExp")}} can override `[@@search]()` method to modify the behavior. +Subclasses of {{jsxref("RegExp")}} can override `[Symbol.search]()` method to modify the behavior. ```js class MyRegExp extends RegExp { @@ -83,7 +83,7 @@ class MyRegExp extends RegExp { const re = new MyRegExp("a+b"); const str = "ab a+b"; -const result = str.search(re); // String.prototype.search calls re[@@search]. +const result = str.search(re); // String.prototype.search calls re[Symbol.search](). console.log(result); // 3 ``` @@ -97,12 +97,12 @@ console.log(result); // 3 ## See also -- [Polyfill of `RegExp.prototype[@@search]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) +- [Polyfill of `RegExp.prototype[Symbol.search]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) - {{jsxref("String.prototype.search()")}} -- [`RegExp.prototype[@@match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) -- [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) -- [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) -- [`RegExp.prototype[@@split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) +- [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) +- [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) +- [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) +- [`RegExp.prototype[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) - {{jsxref("RegExp.prototype.exec()")}} - {{jsxref("RegExp.prototype.test()")}} - {{jsxref("Symbol.search")}} diff --git a/files/en-us/web/javascript/reference/global_objects/regexp/@@species/index.md b/files/en-us/web/javascript/reference/global_objects/regexp/@@species/index.md index 3e68b4358acc6c2..272fc7640fb07d3 100644 --- a/files/en-us/web/javascript/reference/global_objects/regexp/@@species/index.md +++ b/files/en-us/web/javascript/reference/global_objects/regexp/@@species/index.md @@ -1,5 +1,5 @@ --- -title: RegExp[@@species] +title: RegExp[Symbol.species] slug: Web/JavaScript/Reference/Global_Objects/RegExp/@@species page-type: javascript-static-accessor-property browser-compat: javascript.builtins.RegExp.@@species @@ -7,9 +7,9 @@ browser-compat: javascript.builtins.RegExp.@@species {{JSRef}} -The **`RegExp[@@species]`** static accessor property returns the constructor used to construct copied regular expressions in certain `RegExp` methods. +The **`RegExp[Symbol.species]`** static accessor property returns the constructor used to construct copied regular expressions in certain `RegExp` methods. -> **Warning:** The existence of `@@species` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. +> **Warning:** The existence of `[Symbol.species]` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. {{EmbedInteractiveExample("pages/js/regexp-getregexp-@@species.html")}} @@ -21,11 +21,11 @@ RegExp[Symbol.species] ### Return value -The value of the constructor (`this`) on which `get @@species` was called. The return value is used to construct copied `RegExp` instances. +The value of the constructor (`this`) on which `get [Symbol.species]` was called. The return value is used to construct copied `RegExp` instances. ## Description -The `@@species` accessor property returns the default constructor for `RegExp` objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: +The `[Symbol.species]` accessor property returns the default constructor for `RegExp` objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: ```js // Hypothetical underlying implementation for illustration @@ -36,23 +36,23 @@ class RegExp { } ``` -Because of this polymorphic implementation, `@@species` of derived subclasses would also return the constructor itself by default. +Because of this polymorphic implementation, `[Symbol.species]` of derived subclasses would also return the constructor itself by default. ```js class SubRegExp extends SubRegExp {} SubRegExp[Symbol.species] === SubRegExp; // true ``` -Some `RegExp` methods create a copy of the current regex instance before running {{jsxref("RegExp/exec", "exec()")}}, so that side effects such as changes to {{jsxref("RegExp/lastIndex", "lastIndex")}} are not retained. The `@@species` property is used to determine the constructor of the new instance. The methods that copy the current regex instance are: +Some `RegExp` methods create a copy of the current regex instance before running {{jsxref("RegExp/exec", "exec()")}}, so that side effects such as changes to {{jsxref("RegExp/lastIndex", "lastIndex")}} are not retained. The `[Symbol.species]` property is used to determine the constructor of the new instance. The methods that copy the current regex instance are: -- [`[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) -- [`[@@split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) +- [`[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) +- [`[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) ## Examples ### Species in ordinary objects -The `@@species` property returns the default constructor function, which is the `RegExp` constructor for `RegExp` objects: +The `[Symbol.species]` property returns the default constructor function, which is the `RegExp` constructor for `RegExp` objects: ```js RegExp[Symbol.species]; // function RegExp() diff --git a/files/en-us/web/javascript/reference/global_objects/regexp/@@split/index.md b/files/en-us/web/javascript/reference/global_objects/regexp/@@split/index.md index 8ed93c6ae468b84..615587307f08d88 100644 --- a/files/en-us/web/javascript/reference/global_objects/regexp/@@split/index.md +++ b/files/en-us/web/javascript/reference/global_objects/regexp/@@split/index.md @@ -1,5 +1,5 @@ --- -title: RegExp.prototype[@@split]() +title: RegExp.prototype[Symbol.split]() slug: Web/JavaScript/Reference/Global_Objects/RegExp/@@split page-type: javascript-instance-method browser-compat: javascript.builtins.RegExp.@@split @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.RegExp.@@split {{JSRef}} -The **`[@@split]()`** method of {{jsxref("RegExp")}} instances specifies how [`String.prototype.split`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) should behave when the regular expression is passed in as the separator. +The **`[Symbol.split]()`** method of {{jsxref("RegExp")}} instances specifies how [`String.prototype.split`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) should behave when the regular expression is passed in as the separator. {{EmbedInteractiveExample("pages/js/regexp-prototype-@@split.html")}} @@ -23,7 +23,7 @@ regexp[Symbol.split](str, limit) - `str` - : The target of the split operation. - `limit` {{optional_inline}} - - : Integer specifying a limit on the number of splits to be found. The `[@@split]()` method still splits on every match of `this` RegExp pattern (or, in the Syntax above, `regexp`), until the number of split items match the `limit` or the string falls short of `this` pattern. + - : Integer specifying a limit on the number of splits to be found. The `[Symbol.split]()` method still splits on every match of `this` RegExp pattern (or, in the Syntax above, `regexp`), until the number of split items match the `limit` or the string falls short of `this` pattern. ### Return value @@ -41,9 +41,9 @@ This method is called internally in {{jsxref("String.prototype.split()")}} when This method exists for customizing the behavior of `split()` in `RegExp` subclasses. -The `RegExp.prototype[@@split]()` base method exhibits the following behaviors: +The `RegExp.prototype[Symbol.split]()` base method exhibits the following behaviors: -- It starts by using [`@@species`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@species) to construct a new regexp, thus avoiding mutating the original regexp in any way. +- It starts by using [`[Symbol.species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@species) to construct a new regexp, thus avoiding mutating the original regexp in any way. - The regexp's `g` ("global") flag is ignored, and the `y` ("sticky") flag is always applied even when it was not originally present. - If the target string is empty, and the regexp can match empty strings (for example, `/a?/`), an empty array is returned. Otherwise, if the regexp can't match an empty string, `[""]` is returned. - The matching proceeds by continuously calling `this.exec()`. Since the regexp is always sticky, this will move along the string, each time yielding a matching string, index, and any capturing groups. @@ -67,9 +67,9 @@ const result = re[Symbol.split](str); console.log(result); // ["2016", "01", "02"] ``` -### Using @@split in subclasses +### Using `[Symbol.split]()` in subclasses -Subclasses of {{jsxref("RegExp")}} can override the `[@@split]()` method to +Subclasses of {{jsxref("RegExp")}} can override the `[Symbol.split]()` method to modify the default behavior. ```js @@ -82,7 +82,7 @@ class MyRegExp extends RegExp { const re = new MyRegExp("-"); const str = "2016-01-02"; -const result = str.split(re); // String.prototype.split calls re[@@split]. +const result = str.split(re); // String.prototype.split calls re[Symbol.split](). console.log(result); // ["(2016)", "(01)", "(02)"] ``` @@ -96,12 +96,12 @@ console.log(result); // ["(2016)", "(01)", "(02)"] ## See also -- [Polyfill of `RegExp.prototype[@@split]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) +- [Polyfill of `RegExp.prototype[Symbol.split]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) - {{jsxref("String.prototype.split()")}} -- [`RegExp.prototype[@@match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) -- [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) -- [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) -- [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) +- [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) +- [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) +- [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) +- [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) - {{jsxref("RegExp.prototype.exec()")}} - {{jsxref("RegExp.prototype.test()")}} - {{jsxref("Symbol.split")}} diff --git a/files/en-us/web/javascript/reference/global_objects/regexp/exec/index.md b/files/en-us/web/javascript/reference/global_objects/regexp/exec/index.md index 200b5c3185c1e6d..d85c8ccf4da16ed 100644 --- a/files/en-us/web/javascript/reference/global_objects/regexp/exec/index.md +++ b/files/en-us/web/javascript/reference/global_objects/regexp/exec/index.md @@ -46,7 +46,7 @@ JavaScript {{jsxref("RegExp")}} objects are _stateful_ when they have the [globa When using `exec()`, the global flag has no effect when the sticky flag is set — the match is always sticky. -`exec()` is the primitive method of regexps. Many other regexp methods call `exec()` internally — including those called by string methods, like [`@@replace`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace). While `exec()` itself is powerful (and is the most efficient), it often does not convey the intent most clearly. +`exec()` is the primitive method of regexps. Many other regexp methods call `exec()` internally — including those called by string methods, like [`[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace). While `exec()` itself is powerful (and is the most efficient), it often does not convey the intent most clearly. - If you only care whether the regex matches a string, but not what is actually being matched, use {{jsxref("RegExp.prototype.test()")}} instead. - If you are finding all occurrences of a global regex and you don't care about information like capturing groups, use {{jsxref("String.prototype.match()")}} instead. In addition, {{jsxref("String.prototype.matchAll()")}} helps to simplify matching multiple parts of a string (with capture groups) by allowing you to iterate over the matches. diff --git a/files/en-us/web/javascript/reference/global_objects/regexp/global/index.md b/files/en-us/web/javascript/reference/global_objects/regexp/global/index.md index ee531bcb1da0e48..da59f1a40b5f489 100644 --- a/files/en-us/web/javascript/reference/global_objects/regexp/global/index.md +++ b/files/en-us/web/javascript/reference/global_objects/regexp/global/index.md @@ -15,7 +15,7 @@ The **`global`** accessor property of {{jsxref("RegExp")}} instances returns whe `RegExp.prototype.global` has the value `true` if the `g` flag was used; otherwise, `false`. The `g` flag indicates that the regular expression should be tested against all possible matches in a string. Each call to [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) will update its [`lastIndex`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) property, so that the next call to `exec()` will start at the next character. -Some methods, such as [`String.prototype.matchAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll) and [`String.prototype.replaceAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll), will validate that, if the parameter is a regex, it is global. The regex's [`@@match`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) and [`@@replace`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) methods (called by [`String.prototype.match()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) and [`String.prototype.replace()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)) would also have different behaviors when the regex is global. +Some methods, such as [`String.prototype.matchAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll) and [`String.prototype.replaceAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll), will validate that, if the parameter is a regex, it is global. The regex's [`[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) and [`[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) methods (called by [`String.prototype.match()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) and [`String.prototype.replace()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)) would also have different behaviors when the regex is global. The set accessor of `global` is `undefined`. You cannot change this property directly. diff --git a/files/en-us/web/javascript/reference/global_objects/regexp/index.md b/files/en-us/web/javascript/reference/global_objects/regexp/index.md index caf105c3a827d0a..d1381e972a9dbd0 100644 --- a/files/en-us/web/javascript/reference/global_objects/regexp/index.md +++ b/files/en-us/web/javascript/reference/global_objects/regexp/index.md @@ -62,13 +62,13 @@ Some built-in methods would treat regexes specially. They decide whether `x` is Note that in most cases, it would go through the `Symbol.match` check, which means: -- An actual `RegExp` object whose `Symbol.match` property's value is [falsy](/en-US/docs/Glossary/Falsy) but not `undefined` (even with everything else intact, like [`exec`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) and [`@@replace`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace)) can be used as if it's not a regex. +- An actual `RegExp` object whose `Symbol.match` property's value is [falsy](/en-US/docs/Glossary/Falsy) but not `undefined` (even with everything else intact, like [`exec`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) and [`[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace)) can be used as if it's not a regex. - A non-`RegExp` object with a `Symbol.match` property will be treated as if it's a regex. -This choice was made because `@@match` is the most indicative property that something is intended to be used for matching. (`exec` could also be used, but because it's not a symbol property, there would be too many false positives.) The places that treat regexes specially include: +This choice was made because `[Symbol.match]()` is the most indicative property that something is intended to be used for matching. (`exec` could also be used, but because it's not a symbol property, there would be too many false positives.) The places that treat regexes specially include: - [`String.prototype.endsWith()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith), [`startsWith()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith), and [`includes()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) throw a {{jsxref("TypeError")}} if the first argument is a regex. -- [`String.prototype.matchAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll) and [`replaceAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) check whether the [global](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/global) flag is set if the first argument is a regex before invoking its [`@@matchAll`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/matchAll) or [`@@replace`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) method. +- [`String.prototype.matchAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll) and [`replaceAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) check whether the [global](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/global) flag is set if the first argument is a regex before invoking its [`[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/matchAll) or [`[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) method. - The [`RegExp()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor directly returns the `pattern` argument only if `pattern` is a regex (among a few other conditions). If `pattern` is a regex, it would also interrogate `pattern`'s `source` and `flags` properties instead of coercing `pattern` to a string. For example, [`String.prototype.endsWith()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith) would coerce all inputs to strings, but it would throw if the argument is a regex, because it's only designed to match strings, and using a regex is likely a developer mistake. @@ -78,7 +78,7 @@ For example, [`String.prototype.endsWith()`](/en-US/docs/Web/JavaScript/Referenc "foobar".endsWith(/bar/); // TypeError: First argument to String.prototype.endsWith must not be a regular expression ``` -You can get around the check by setting `@@match` to a [falsy](/en-US/docs/Glossary/Falsy) value that's not `undefined`. This would mean that the regex cannot be used for `String.prototype.match()` (since without `@@match`, `match()` would construct a new `RegExp` object with the two enclosing slashes added by [`re.toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/toString)), but it can be used for virtually everything else. +You can get around the check by setting `[Symbol.match]` to a [falsy](/en-US/docs/Glossary/Falsy) value that's not `undefined`. This would mean that the regex cannot be used for `String.prototype.match()` (since without `[Symbol.match]`, `match()` would construct a new `RegExp` object with the two enclosing slashes added by [`re.toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/toString)), but it can be used for virtually everything else. ```js const re = /bar/g; @@ -111,7 +111,7 @@ Note that several of the {{jsxref("RegExp")}} properties have both long and shor - : A static read-only property that contains the substring preceding the most recent match. - {{jsxref("RegExp/rightContext", "RegExp.rightContext ($')")}} {{deprecated_inline}} - : A static read-only property that contains the substring following the most recent match. -- {{jsxref("RegExp/@@species", "RegExp[@@species]")}} +- {{jsxref("RegExp/@@species", "RegExp[Symbol.species]")}} - : The constructor function that is used to create derived objects. ## Instance properties @@ -156,15 +156,15 @@ These properties are own properties of each `RegExp` instance. - : Tests for a match in its string parameter. - {{jsxref("RegExp.prototype.toString()")}} - : Returns a string representing the specified object. Overrides the {{jsxref("Object.prototype.toString()")}} method. -- [`RegExp.prototype[@@match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) +- [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) - : Performs match to given string and returns match result. -- [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) +- [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) - : Returns all matches of the regular expression against a string. -- [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) +- [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) - : Replaces matches in given string with new substring. -- [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) +- [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) - : Searches the match in given string and returns the index the pattern found in the string. -- [`RegExp.prototype[@@split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) +- [`RegExp.prototype[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) - : Splits given string into an array by separating the string into substrings. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/regexp/sticky/index.md b/files/en-us/web/javascript/reference/global_objects/regexp/sticky/index.md index ef427918cf9e9af..4800ea26003106e 100644 --- a/files/en-us/web/javascript/reference/global_objects/regexp/sticky/index.md +++ b/files/en-us/web/javascript/reference/global_objects/regexp/sticky/index.md @@ -30,20 +30,20 @@ However, for the [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/ For the [`exec()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) method, a regex that's both sticky and global behaves the same as a sticky and non-global regex. Because [`test()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test) is a simple wrapper around `exec()`, `test()` would ignore the global flag and perform sticky matches as well. However, due to many other methods special-casing the behavior of global regexes, the global flag is, in general, orthogonal to the sticky flag. -- [`String.prototype.matchAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll) (which calls [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll)): `y`, `g` and `gy` are all different. - - For `y` regexes: `matchAll()` throws; `[@@matchAll]()` yields the `exec()` result exactly once, without updating the regex's `lastIndex`. +- [`String.prototype.matchAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll) (which calls [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll)): `y`, `g` and `gy` are all different. + - For `y` regexes: `matchAll()` throws; `[Symbol.matchAll]()` yields the `exec()` result exactly once, without updating the regex's `lastIndex`. - For `g` or `gy` regexes: returns an iterator that yields a sequence of `exec()` results. -- [`String.prototype.match()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) (which calls [`RegExp.prototype[@@match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match)): `y`, `g` and `gy` are all different. +- [`String.prototype.match()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) (which calls [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match)): `y`, `g` and `gy` are all different. - For `y` regexes: returns the `exec()` result and updates the regex's `lastIndex`. - For `g` or `gy` regexes: returns an array of all `exec()` results. -- [`String.prototype.search()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/search) (which calls [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search)): the `g` flag is always irrelevant. +- [`String.prototype.search()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/search) (which calls [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search)): the `g` flag is always irrelevant. - For `y` or `gy` regexes: always returns `0` (if the very beginning of the string matches) or `-1` (if the beginning doesn't match), without updating the regex's `lastIndex` when it exits. - For `g` regexes: returns the index of the first match in the string, or `-1` if no match is found. -- [`String.prototype.split()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) (which calls [`RegExp.prototype[@@split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split)): `y`, `g`, and `gy` all have the same behavior. -- [`String.prototype.replace()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) (which calls [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace)): `y`, `g` and `gy` are all different. +- [`String.prototype.split()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) (which calls [`RegExp.prototype[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split)): `y`, `g`, and `gy` all have the same behavior. +- [`String.prototype.replace()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) (which calls [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace)): `y`, `g` and `gy` are all different. - For `y` regexes: replaces once at the current `lastIndex` and updates `lastIndex`. - For `g` and `gy` regexes: replaces all occurrences matched by `exec()`. -- [`String.prototype.replaceAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) (which calls [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace)): `y`, `g` and `gy` are all different. +- [`String.prototype.replaceAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) (which calls [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace)): `y`, `g` and `gy` are all different. - For `y` regexes: `replaceAll()` throws. - For `g` and `gy` regexes: replaces all occurrences matched by `exec()`. diff --git a/files/en-us/web/javascript/reference/global_objects/set/@@iterator/index.md b/files/en-us/web/javascript/reference/global_objects/set/@@iterator/index.md index 7e66e8da44117df..2e945147d1b09e7 100644 --- a/files/en-us/web/javascript/reference/global_objects/set/@@iterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/set/@@iterator/index.md @@ -1,5 +1,5 @@ --- -title: Set.prototype[@@iterator]() +title: Set.prototype[Symbol.iterator]() slug: Web/JavaScript/Reference/Global_Objects/Set/@@iterator page-type: javascript-instance-method browser-compat: javascript.builtins.Set.@@iterator @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Set.@@iterator {{JSRef}} -The **`[@@iterator]()`** method of {{jsxref("Set")}} instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `Set` objects to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns a [set iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the values of the set in insertion order. +The **`[Symbol.iterator]()`** method of {{jsxref("Set")}} instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `Set` objects to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns a [set iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the values of the set in insertion order. The initial value of this property is the same function object as the initial value of the {{jsxref("Set.prototype.values")}} property. @@ -31,7 +31,7 @@ The same return value as {{jsxref("Set.prototype.values()")}}: a new [iterable i ### Iteration using for...of loop -Note that you seldom need to call this method directly. The existence of the `@@iterator` method makes `Set` objects [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. +Note that you seldom need to call this method directly. The existence of the `[Symbol.iterator]()` method makes `Set` objects [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. ```js const mySet = new Set(); diff --git a/files/en-us/web/javascript/reference/global_objects/set/@@species/index.md b/files/en-us/web/javascript/reference/global_objects/set/@@species/index.md index 1c888efd298fb2d..a641a858ffa46b1 100644 --- a/files/en-us/web/javascript/reference/global_objects/set/@@species/index.md +++ b/files/en-us/web/javascript/reference/global_objects/set/@@species/index.md @@ -1,5 +1,5 @@ --- -title: Set[@@species] +title: Set[Symbol.species] slug: Web/JavaScript/Reference/Global_Objects/Set/@@species page-type: javascript-static-accessor-property browser-compat: javascript.builtins.Set.@@species @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Set.@@species {{JSRef}} -The **`Set[@@species]`** static accessor property is an unused accessor property specifying how to copy `Set` objects. +The **`Set[Symbol.species]`** static accessor property is an unused accessor property specifying how to copy `Set` objects. ## Syntax @@ -17,11 +17,11 @@ Set[Symbol.species] ### Return value -The value of the constructor (`this`) on which `get @@species` was called. The return value is used to construct copied `Set` instances. +The value of the constructor (`this`) on which `get [Symbol.species]` was called. The return value is used to construct copied `Set` instances. ## Description -The `@@species` accessor property returns the default constructor for `Set` objects. Subclass constructors may override it to change the constructor assignment. +The `[Symbol.species]` accessor property returns the default constructor for `Set` objects. Subclass constructors may override it to change the constructor assignment. > **Note:** This property is currently unused by all `Set` methods. @@ -29,7 +29,7 @@ The `@@species` accessor property returns the default constructor for `Set` obje ### Species in ordinary objects -The `@@species` property returns the default constructor function, which is the `Set` constructor for `Set`. +The `[Symbol.species]` property returns the default constructor function, which is the `Set` constructor for `Set`. ```js Set[Symbol.species]; // function Set() diff --git a/files/en-us/web/javascript/reference/global_objects/set/index.md b/files/en-us/web/javascript/reference/global_objects/set/index.md index e322cb8dd044993..e58976598878f69 100644 --- a/files/en-us/web/javascript/reference/global_objects/set/index.md +++ b/files/en-us/web/javascript/reference/global_objects/set/index.md @@ -118,7 +118,7 @@ const b = new Map([ console.log(a.union(b)); // Set(4) {1, 2, 3, 4} ``` -> **Note:** The set-like protocol invokes the `keys()` method instead of [`[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator) to produce elements. This is to make maps valid set-like objects, because for maps, the iterator produces _entries_ but the `has()` method takes _keys_. +> **Note:** The set-like protocol invokes the `keys()` method instead of [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator) to produce elements. This is to make maps valid set-like objects, because for maps, the iterator produces _entries_ but the `has()` method takes _keys_. [Arrays](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) are not set-like because they don't have a `has()` method or the `size` property, and their `keys()` method produces indices instead of elements. {{jsxref("WeakSet")}} objects are also not set-like because they don't have a `keys()` method. @@ -142,7 +142,7 @@ interface GPUSupportedFeatures { `Set`-like objects are either read-only or read-writable (see the `readonly` keyword in the IDL above). -- Read-only `Set`-like objects have the property [`size`](#set.prototype.size), and the methods: [`entries()`](#set.prototype.entries), [`forEach()`](#set.prototype.foreach), [`has()`](#set.prototype.has), [`keys()`](#set.prototype.keys), [`values()`](#set.prototype.values), and [`@@iterator`](#set.prototypeiterator). +- Read-only `Set`-like objects have the property [`size`](#set.prototype.size), and the methods: [`entries()`](#set.prototype.entries), [`forEach()`](#set.prototype.foreach), [`has()`](#set.prototype.has), [`keys()`](#set.prototype.keys), [`values()`](#set.prototype.values), and [`[Symbol.iterator]()`](#set.prototypeiterator). - Writeable `Set`-like objects additionally have the methods: [`clear()`](#set.prototype.clear), [`delete()`](#set.prototype.delete), and [`add()`](#set.prototype.add). The methods and properties have the same behavior as the equivalent entities in `Set`, except for the restriction on the types of the entry. @@ -165,7 +165,7 @@ The following are examples of writable `Set`-like browser objects: ## Static properties -- {{jsxref("Set/@@species", "Set[@@species]")}} +- {{jsxref("Set/@@species", "Set[Symbol.species]")}} - : The constructor function that is used to create derived objects. ## Instance properties @@ -176,8 +176,8 @@ These properties are defined on `Set.prototype` and shared by all `Set` instance - : The constructor function that created the instance object. For `Set` instances, the initial value is the {{jsxref("Set/Set", "Set")}} constructor. - {{jsxref("Set.prototype.size")}} - : Returns the number of values in the `Set` object. -- `Set.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Set"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `Set.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Set"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods @@ -211,7 +211,7 @@ These properties are defined on `Set.prototype` and shared by all `Set` instance - : Takes a set and returns a new set containing elements which are in either or both of this set and the given set. - {{jsxref("Set.prototype.values()")}} - : Returns a new iterator object that yields the **values** for each element in the `Set` object in insertion order. -- [`Set.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator) +- [`Set.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator) - : Returns a new iterator object that yields the **values** for each element in the `Set` object in insertion order. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/sharedarraybuffer/@@species/index.md b/files/en-us/web/javascript/reference/global_objects/sharedarraybuffer/@@species/index.md index acc95a67e2ef3e0..2fe15b2e677c38a 100644 --- a/files/en-us/web/javascript/reference/global_objects/sharedarraybuffer/@@species/index.md +++ b/files/en-us/web/javascript/reference/global_objects/sharedarraybuffer/@@species/index.md @@ -1,5 +1,5 @@ --- -title: SharedArrayBuffer[@@species] +title: SharedArrayBuffer[Symbol.species] slug: Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/@@species page-type: javascript-static-accessor-property browser-compat: javascript.builtins.SharedArrayBuffer.@@species @@ -7,9 +7,9 @@ browser-compat: javascript.builtins.SharedArrayBuffer.@@species {{JSRef}} -The **`SharedArrayBuffer[@@species]`** static accessor property returns the constructor used to construct return values from `SharedArrayBuffer` methods. +The **`SharedArrayBuffer[Symbol.species]`** static accessor property returns the constructor used to construct return values from `SharedArrayBuffer` methods. -> **Warning:** The existence of `@@species` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. +> **Warning:** The existence of `[Symbol.species]` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. ## Syntax @@ -19,11 +19,11 @@ SharedArrayBuffer[Symbol.species] ### Return value -The value of the constructor (`this`) on which `get @@species` was called. The return value is used to construct return values from array buffer methods that create new array buffer. +The value of the constructor (`this`) on which `get [Symbol.species]` was called. The return value is used to construct return values from array buffer methods that create new array buffer. ## Description -The `@@species` accessor property returns the default constructor for `SharedArrayBuffer` objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: +The `[Symbol.species]` accessor property returns the default constructor for `SharedArrayBuffer` objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: ```js // Hypothetical underlying implementation for illustration @@ -34,20 +34,20 @@ class SharedArrayBuffer { } ``` -Because of this polymorphic implementation, `@@species` of derived subclasses would also return the constructor itself by default. +Because of this polymorphic implementation, `[Symbol.species]` of derived subclasses would also return the constructor itself by default. ```js class SubArrayBuffer extends SharedArrayBuffer {} SubArrayBuffer[Symbol.species] === SharedArrayBuffer; // true ``` -When calling array buffer methods that do not mutate the existing array but return a new array buffer instance (for example, [`slice()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/slice)), the array's `constructor[@@species]` will be accessed. The returned constructor will be used to construct the return value of the array buffer method. +When calling array buffer methods that do not mutate the existing array but return a new array buffer instance (for example, [`slice()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/slice)), the array's `constructor[Symbol.species]` will be accessed. The returned constructor will be used to construct the return value of the array buffer method. ## Examples ### Species in ordinary objects -The `@@species` property returns the default constructor function, which is the `SharedArrayBuffer` constructor for `SharedArrayBuffer`. +The `[Symbol.species]` property returns the default constructor function, which is the `SharedArrayBuffer` constructor for `SharedArrayBuffer`. ```js SharedArrayBuffer[Symbol.species]; // function SharedArrayBuffer() diff --git a/files/en-us/web/javascript/reference/global_objects/sharedarraybuffer/index.md b/files/en-us/web/javascript/reference/global_objects/sharedarraybuffer/index.md index d515b542b2893f5..116c586b5b4e2c0 100644 --- a/files/en-us/web/javascript/reference/global_objects/sharedarraybuffer/index.md +++ b/files/en-us/web/javascript/reference/global_objects/sharedarraybuffer/index.md @@ -93,7 +93,7 @@ For security reasons, `SharedArrayBuffer`s cannot be reduced in size, only grown ## Static properties -- {{jsxref("SharedArrayBuffer/@@species", "SharedArrayBuffer[@@species]")}} +- {{jsxref("SharedArrayBuffer/@@species", "SharedArrayBuffer[Symbol.species]")}} - : Returns the constructor used to construct return values from `SharedArrayBuffer` methods. ## Instance properties @@ -108,8 +108,8 @@ These properties are defined on `SharedArrayBuffer.prototype` and shared by all - : Read-only. Returns `true` if the `SharedArrayBuffer` can be grown, or `false` if not. - {{jsxref("SharedArrayBuffer.prototype.maxByteLength")}} - : The read-only maximum length, in bytes, that the `SharedArrayBuffer` can be grown to. This is established when the array is constructed and cannot be changed. -- `SharedArrayBuffer.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"SharedArrayBuffer"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `SharedArrayBuffer.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"SharedArrayBuffer"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/string/@@iterator/index.md b/files/en-us/web/javascript/reference/global_objects/string/@@iterator/index.md index d3a116e9c9f227e..8cf7710e032697c 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/@@iterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/@@iterator/index.md @@ -1,5 +1,5 @@ --- -title: String.prototype[@@iterator]() +title: String.prototype[Symbol.iterator]() slug: Web/JavaScript/Reference/Global_Objects/String/@@iterator page-type: javascript-instance-method browser-compat: javascript.builtins.String.@@iterator @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.String.@@iterator {{JSRef}} -The **`[@@iterator]()`** method of {{jsxref("String")}} values implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows strings to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns a [string iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the Unicode code points of the string value as individual strings. +The **`[Symbol.iterator]()`** method of {{jsxref("String")}} values implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows strings to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns a [string iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the Unicode code points of the string value as individual strings. {{EmbedInteractiveExample("pages/js/string-prototype-@@iterator.html")}} @@ -44,7 +44,7 @@ Strings are iterated by Unicode code points. This means grapheme clusters will b ### Iteration using for...of loop -Note that you seldom need to call this method directly. The existence of the `@@iterator` method makes strings [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. +Note that you seldom need to call this method directly. The existence of the `[Symbol.iterator]()` method makes strings [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. ```js const str = "A\uD835\uDC68B\uD835\uDC69C\uD835\uDC6A"; @@ -83,7 +83,7 @@ console.log(strIter.next().value); // "\uD835\uDC68" ## See also -- [Polyfill of `String.prototype[@@iterator]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) +- [Polyfill of `String.prototype[Symbol.iterator]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) - [Text formatting](/en-US/docs/Web/JavaScript/Guide/Text_formatting) guide - {{jsxref("Symbol.iterator")}} - [Iteration protocols](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) diff --git a/files/en-us/web/javascript/reference/global_objects/string/codepointat/index.md b/files/en-us/web/javascript/reference/global_objects/string/codepointat/index.md index 8ab0f64b7a0ab5f..1118617a638000e 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/codepointat/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/codepointat/index.md @@ -68,7 +68,7 @@ for (let i = 0; i < str.length; i++) { // '1f40e', 'dc0e', '1f471', 'dc71', '2764' ``` -Instead, use a [`for...of`](/en-US/docs/Web/JavaScript/Guide/Loops_and_iteration#for...of_statement) statement or [spread the string](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax), both of which invoke the string's [`@@iterator`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator), which iterates by code points. Then, use `codePointAt(0)` to get the code point of each element. +Instead, use a [`for...of`](/en-US/docs/Web/JavaScript/Guide/Loops_and_iteration#for...of_statement) statement or [spread the string](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax), both of which invoke the string's [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator), which iterates by code points. Then, use `codePointAt(0)` to get the code point of each element. ```js for (const codePoint of str) { diff --git a/files/en-us/web/javascript/reference/global_objects/string/index.md b/files/en-us/web/javascript/reference/global_objects/string/index.md index cfb1dcff1d4e8c9..d05e48c62b85bc0 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/index.md @@ -170,7 +170,7 @@ Many built-in operations that expect strings first coerce their arguments to str - Numbers are converted with the same algorithm as [`toString(10)`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString). - [BigInts](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) are converted with the same algorithm as [`toString(10)`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/toString). - [Symbols](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) throw a {{jsxref("TypeError")}}. -- Objects are first [converted to a primitive](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) by calling its [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"string"` as hint), `toString()`, and `valueOf()` methods, in that order. The resulting primitive is then converted to a string. +- Objects are first [converted to a primitive](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) by calling its [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"string"` as hint), `toString()`, and `valueOf()` methods, in that order. The resulting primitive is then converted to a string. There are several ways to achieve nearly the same effect in JavaScript. @@ -195,7 +195,7 @@ Lone surrogates do not represent any Unicode character. Although most JavaScript On top of Unicode characters, there are certain sequences of Unicode characters that should be treated as one visual unit, known as a _grapheme cluster_. The most common case is emojis: many emojis that have a range of variations are actually formed by multiple emojis, usually joined by the \ (`U+200D`) character. -You must be careful which level of characters you are iterating on. For example, [`split("")`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) will split by UTF-16 code units and will separate surrogate pairs. String indexes also refer to the index of each UTF-16 code unit. On the other hand, [`@@iterator()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) iterates by Unicode code points. Iterating through grapheme clusters will require some custom code. +You must be careful which level of characters you are iterating on. For example, [`split("")`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) will split by UTF-16 code units and will separate surrogate pairs. String indexes also refer to the index of each UTF-16 code unit. On the other hand, [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) iterates by Unicode code points. Iterating through grapheme clusters will require some custom code. ```js "😄".split(""); // ['\ud83d', '\ude04']; splits into two lone surrogates @@ -348,7 +348,7 @@ These properties are own properties of each `String` instance. - {{jsxref("String.prototype.valueOf()")}} - : Returns the primitive value of the specified object. Overrides the {{jsxref("Object.prototype.valueOf()")}} method. -- [`String.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) +- [`String.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) - : Returns a new iterator object that iterates over the code points of a String value, returning each code point as a String value. diff --git a/files/en-us/web/javascript/reference/global_objects/string/match/index.md b/files/en-us/web/javascript/reference/global_objects/string/match/index.md index 0631cf802c44b56..d7701ea9c223db0 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/match/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/match/index.md @@ -36,13 +36,13 @@ An {{jsxref("Array")}} whose contents depend on the presence or absence of the g ## Description -The implementation of `String.prototype.match` itself is very simple — it simply calls the `Symbol.match` method of the argument with the string as the first parameter. The actual implementation comes from [`RegExp.prototype[@@match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match). +The implementation of `String.prototype.match` itself is very simple — it simply calls the `Symbol.match` method of the argument with the string as the first parameter. The actual implementation comes from [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match). - If you need to know if a string matches a regular expression {{jsxref("RegExp")}}, use {{jsxref("RegExp.prototype.test()")}}. - If you only want the first match found, you might want to use {{jsxref("RegExp.prototype.exec()")}} instead. - If you want to obtain capture groups and the global flag is set, you need to use {{jsxref("RegExp.prototype.exec()")}} or {{jsxref("String.prototype.matchAll()")}} instead. -For more information about the semantics of `match()` when a regex is passed, see [`RegExp.prototype[@@match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match). +For more information about the semantics of `match()` when a regex is passed, see [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match). ## Examples @@ -105,7 +105,7 @@ const str = "Nothing will come of nothing."; str.match(); // returns [""] ``` -### Using match() with a non-RegExp implementing @@match +### Using match() with a non-RegExp implementing `[Symbol.match]()` If an object has a `Symbol.match` method, it can be used as a custom matcher. The return value of `Symbol.match` becomes the return value of `match()`. diff --git a/files/en-us/web/javascript/reference/global_objects/string/matchall/index.md b/files/en-us/web/javascript/reference/global_objects/string/matchall/index.md index 3cfada72d5a0a3b..308c6134a827470 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/matchall/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/matchall/index.md @@ -38,7 +38,7 @@ An [iterable iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Object ## Description -The implementation of `String.prototype.matchAll` itself is very simple — it simply calls the `Symbol.matchAll` method of the argument with the string as the first parameter (apart from the extra input validation that the regex is global). The actual implementation comes from [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll). +The implementation of `String.prototype.matchAll` itself is very simple — it simply calls the `Symbol.matchAll` method of the argument with the string as the first parameter (apart from the extra input validation that the regex is global). The actual implementation comes from [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll). ## Examples @@ -128,7 +128,7 @@ array[1]; // ['test2', 'e', 'st2', '2', index: 5, input: 'test1test2', length: 4] ``` -### Using matchAll() with a non-RegExp implementing @@matchAll +### Using matchAll() with a non-RegExp implementing `[Symbol.matchAll]()` If an object has a `Symbol.matchAll` method, it can be used as a custom matcher. The return value of `Symbol.matchAll` becomes the return value of `matchAll()`. @@ -159,4 +159,4 @@ str.matchAll({ - {{jsxref("RegExp")}} - {{jsxref("RegExp.prototype.exec()")}} - {{jsxref("RegExp.prototype.test()")}} -- [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) +- [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) diff --git a/files/en-us/web/javascript/reference/global_objects/string/replace/index.md b/files/en-us/web/javascript/reference/global_objects/string/replace/index.md index c978fc6051ba454..01bd68ee7c6ee26 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/replace/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/replace/index.md @@ -36,7 +36,7 @@ This method does not mutate the string value it's called on. It returns a new st A string pattern will only be replaced once. To perform a global search and replace, use a regular expression with the `g` flag, or use [`replaceAll()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) instead. -If `pattern` is an object with a [`Symbol.replace`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) method (including `RegExp` objects), that method is called with the target string and `replacement` as arguments. Its return value becomes the return value of `replace()`. In this case the behavior of `replace()` is entirely encoded by the `@@replace` method — for example, any mention of "capturing groups" in the description below is actually functionality provided by [`RegExp.prototype[@@replace]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace). +If `pattern` is an object with a [`Symbol.replace`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) method (including `RegExp` objects), that method is called with the target string and `replacement` as arguments. Its return value becomes the return value of `replace()`. In this case the behavior of `replace()` is entirely encoded by the `[Symbol.replace]()` method — for example, any mention of "capturing groups" in the description below is actually functionality provided by [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace). If the `pattern` is an empty string, the replacement is prepended to the start of the string. @@ -44,7 +44,7 @@ If the `pattern` is an empty string, the replacement is prepended to the start o "xxx".replace("", "_"); // "_xxx" ``` -A regexp with the `g` flag is the only case where `replace()` replaces more than once. For more information about how regex properties (especially the [sticky](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) flag) interact with `replace()`, see [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace). +A regexp with the `g` flag is the only case where `replace()` replaces more than once. For more information about how regex properties (especially the [sticky](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) flag) interact with `replace()`, see [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace). ### Specifying a string as the replacement @@ -251,4 +251,4 @@ console.log("abcd".replace(/(?bc)/, addOffset)); // "abc (1) d" - {{jsxref("RegExp.prototype.exec()")}} - {{jsxref("RegExp.prototype.test()")}} - [`Symbol.replace`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) -- [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) +- [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) diff --git a/files/en-us/web/javascript/reference/global_objects/string/replaceall/index.md b/files/en-us/web/javascript/reference/global_objects/string/replaceall/index.md index b8106f04fa9742a..bcbedb251f2c32b 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/replaceall/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/replaceall/index.md @@ -58,7 +58,7 @@ console.log(unsafeRedactName(report, "ha.*er")); // "A [REDACTED]s in their name console.log(safeRedactName(report, "ha.*er")); // "A hacker called [REDACTED] used special characters in their name to breach the system." ``` -If `pattern` is an object with a [`Symbol.replace`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) method (including `RegExp` objects), that method is called with the target string and `replacement` as arguments. Its return value becomes the return value of `replaceAll()`. In this case the behavior of `replaceAll()` is entirely encoded by the `@@replace` method, and therefore will have the same result as `replace()` (apart from the extra input validation that the regex is global). +If `pattern` is an object with a [`Symbol.replace`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) method (including `RegExp` objects), that method is called with the target string and `replacement` as arguments. Its return value becomes the return value of `replaceAll()`. In this case the behavior of `replaceAll()` is entirely encoded by the `[Symbol.replace]()` method, and therefore will have the same result as `replace()` (apart from the extra input validation that the regex is global). If the `pattern` is an empty string, the replacement will be inserted in between every UTF-16 code unit, similar to [`split()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) behavior. @@ -66,7 +66,7 @@ If the `pattern` is an empty string, the replacement will be inserted in between "xxx".replaceAll("", "_"); // "_x_x_x_" ``` -For more information about how regex properties (especially the [sticky](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) flag) interact with `replaceAll()`, see [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace). +For more information about how regex properties (especially the [sticky](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) flag) interact with `replaceAll()`, see [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace). ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/string/search/index.md b/files/en-us/web/javascript/reference/global_objects/string/search/index.md index 3af8d0c9cc81f6b..c11807f59773705 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/search/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/search/index.md @@ -31,9 +31,9 @@ The index of the first match between the regular expression and the given string ## Description -The implementation of `String.prototype.search()` itself is very simple — it simply calls the `Symbol.search` method of the argument with the string as the first parameter. The actual implementation comes from [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search). +The implementation of `String.prototype.search()` itself is very simple — it simply calls the `Symbol.search` method of the argument with the string as the first parameter. The actual implementation comes from [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search). -The `g` flag of `regexp` has no effect on the `search()` result, and the search always happens as if the regex's `lastIndex` is 0. For more information on the behavior of `search()`, see [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search). +The `g` flag of `regexp` has no effect on the `search()` result, and the search always happens as if the regex's `lastIndex` is 0. For more information on the behavior of `search()`, see [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search). When you want to know whether a pattern is found, and _also_ know its index within a string, use `search()`. @@ -68,4 +68,4 @@ console.log(str.search(reDot)); // returns -1 cannot find '.' dot punctuation - [Regular expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) guide - {{jsxref("String.prototype.match()")}} - {{jsxref("RegExp.prototype.exec()")}} -- [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) +- [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) diff --git a/files/en-us/web/javascript/reference/global_objects/string/split/index.md b/files/en-us/web/javascript/reference/global_objects/string/split/index.md index 624ddacd33881ed..563e0827d60ecf8 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/split/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/split/index.md @@ -21,7 +21,7 @@ split(separator, limit) ### Parameters - `separator` - - : The pattern describing where each split should occur. Can be `undefined`, a string, or an object with a [`Symbol.split`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/split) method — the typical example being a {{jsxref("RegExp", "regular expression", "", 1)}}. Omitting `separator` or passing `undefined` causes `split()` to return an array with the calling string as a single element. All values that are not `undefined` or objects with a `@@split` method are [coerced to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). + - : The pattern describing where each split should occur. Can be `undefined`, a string, or an object with a [`Symbol.split`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/split) method — the typical example being a {{jsxref("RegExp", "regular expression", "", 1)}}. Omitting `separator` or passing `undefined` causes `split()` to return an array with the calling string as a single element. All values that are not `undefined` or objects with a `[Symbol.split]()` method are [coerced to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). - `limit` {{optional_inline}} - : A non-negative integer specifying a limit on the number of substrings to be included in the array. If provided, splits the string at each occurrence of the specified `separator`, but stops when `limit` entries have been placed in the array. Any leftover text is not included in the array at all. - The array may contain fewer entries than `limit` if the end of the string is reached before the limit is reached. diff --git a/files/en-us/web/javascript/reference/global_objects/string/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/string/tostring/index.md index ff8a563b19fbc8d..f411c0d2b3065c2 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/tostring/index.md @@ -32,7 +32,7 @@ The {{jsxref("String")}} object overrides the `toString` method of {{jsxref("Obj The `toString()` method requires its `this` value to be a `String` primitive or wrapper object. It throws a {{jsxref("TypeError")}} for other `this` values without attempting to coerce them to string values. -Because `String` doesn't have a [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, JavaScript calls the `toString()` method automatically when a `String` _object_ is used in a context expecting a string, such as in a [template literal](/en-US/docs/Web/JavaScript/Reference/Template_literals). However, String _primitive_ values do not consult the `toString()` method to be [coerced to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) — since they are already strings, no conversion is performed. +Because `String` doesn't have a [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, JavaScript calls the `toString()` method automatically when a `String` _object_ is used in a context expecting a string, such as in a [template literal](/en-US/docs/Web/JavaScript/Reference/Template_literals). However, String _primitive_ values do not consult the `toString()` method to be [coerced to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) — since they are already strings, no conversion is performed. ```js String.prototype.toString = () => "Overridden"; diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/@@toprimitive/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/@@toprimitive/index.md index 315e9175ee08083..b7f0d7da6042344 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/@@toprimitive/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/@@toprimitive/index.md @@ -1,5 +1,5 @@ --- -title: Symbol.prototype[@@toPrimitive]() +title: Symbol.prototype[Symbol.toPrimitive]() slug: Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive page-type: javascript-instance-method browser-compat: javascript.builtins.Symbol.@@toPrimitive @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Symbol.@@toPrimitive {{JSRef}} -The **`[@@toPrimitive]()`** method of {{jsxref("Symbol")}} values returns this symbol value. +The **`[Symbol.toPrimitive]()`** method of {{jsxref("Symbol")}} values returns this symbol value. ## Syntax @@ -26,18 +26,18 @@ The primitive value of the specified {{jsxref("Symbol")}} object. ## Description -The `[@@toPrimitive]()` method of {{jsxref("Symbol")}} returns the primitive +The `[Symbol.toPrimitive]()` method of {{jsxref("Symbol")}} returns the primitive value of a Symbol object as a Symbol data type. The `hint` argument is not used. -JavaScript calls the `[@@toPrimitive]()` method to convert an object to a -primitive value. You rarely need to invoke the `[@@toPrimitive]()` method +JavaScript calls the `[Symbol.toPrimitive]()` method to convert an object to a +primitive value. You rarely need to invoke the `[Symbol.toPrimitive]()` method yourself; JavaScript automatically invokes it when encountering an object where a primitive value is expected. ## Examples -### Using @@toPrimitive +### Using `[Symbol.toPrimitive]()` ```js const sym = Symbol("example"); diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/asynciterator/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/asynciterator/index.md index 46847651676ee81..806f2e02678a04c 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/asynciterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/asynciterator/index.md @@ -7,13 +7,13 @@ browser-compat: javascript.builtins.Symbol.asyncIterator {{JSRef}} -The **`Symbol.asyncIterator`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@asyncIterator`. The [async iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) looks up this symbol for the method that returns the async iterator for an object. In order for an object to be async iterable, it must have an `@@asyncIterator` key. +The **`Symbol.asyncIterator`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.asyncIterator`. The [async iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) looks up this symbol for the method that returns the async iterator for an object. In order for an object to be async iterable, it must have an `[Symbol.asyncIterator]` key. {{EmbedInteractiveExample("pages/js/symbol-asynciterator.html", "taller")}} ## Value -The well-known symbol `@@asyncIterator`. +The well-known symbol `Symbol.asyncIterator`. {{js_property_attributes(0, 0, 0)}} @@ -21,7 +21,7 @@ The well-known symbol `@@asyncIterator`. ### User-defined async iterables -You can define your own async iterable by setting the `[Symbol.asyncIterator]` property on an object. +You can define your own async iterable by setting the `[Symbol.asyncIterator]()` property on an object. ```js const myAsyncIterable = { diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/hasinstance/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/hasinstance/index.md index 29e6095392a2aae..d3eefe1f69a4f4a 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/hasinstance/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/hasinstance/index.md @@ -7,13 +7,13 @@ browser-compat: javascript.builtins.Symbol.hasInstance {{JSRef}} -The **`Symbol.hasInstance`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@hasInstance`. The {{jsxref("Operators/instanceof", "instanceof")}} operator looks up this symbol on its right-hand operand for the method used to determine if the constructor object recognizes an object as its instance. +The **`Symbol.hasInstance`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.hasInstance`. The {{jsxref("Operators/instanceof", "instanceof")}} operator looks up this symbol on its right-hand operand for the method used to determine if the constructor object recognizes an object as its instance. {{EmbedInteractiveExample("pages/js/symbol-hasinstance.html")}} ## Value -The well-known symbol `@@hasInstance`. +The well-known symbol `Symbol.hasInstance`. {{js_property_attributes(0, 0, 0)}} @@ -21,10 +21,10 @@ The well-known symbol `@@hasInstance`. The `instanceof` operator uses the following algorithm to calculate the return value of `object instanceof constructor`: -1. If `constructor` has a `@@hasInstance` method, then call it with `object` as the first argument and return the result, [coerced to a boolean](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean#boolean_coercion). Throw a {{jsxref("TypeError")}} if `constructor` is not an object, or if `constructor[@@hasInstance]` is not one of `null`, `undefined`, or a function. -2. Otherwise, if `constructor` doesn't have a `@@hasInstance` method (`constructor[@@hasInstance]` is `null` or `undefined`), then determine the result using the same algorithm as [`Function.prototype[@@hasInstance]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance). Throw a {{jsxref("TypeError")}} if `constructor` is not a function. +1. If `constructor` has a `[Symbol.hasInstance]()` method, then call it with `object` as the first argument and return the result, [coerced to a boolean](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean#boolean_coercion). Throw a {{jsxref("TypeError")}} if `constructor` is not an object, or if `constructor[Symbol.hasInstance]` is not one of `null`, `undefined`, or a function. +2. Otherwise, if `constructor` doesn't have a `[Symbol.hasInstance]()` method (`constructor[Symbol.hasInstance]` is `null` or `undefined`), then determine the result using the same algorithm as [`Function.prototype[Symbol.hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance). Throw a {{jsxref("TypeError")}} if `constructor` is not a function. -Because all functions inherit from `Function.prototype` by default, most of the time, the [`Function.prototype[@@hasInstance]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance) method specifies the behavior of `instanceof` when the right-hand side is a function. +Because all functions inherit from `Function.prototype` by default, most of the time, the [`Function.prototype[Symbol.hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance) method specifies the behavior of `instanceof` when the right-hand side is a function. ## Examples @@ -76,4 +76,4 @@ console.log(Animal[Symbol.hasInstance](cat)); // true ## See also - {{jsxref("Operators/instanceof", "instanceof")}} -- [`Function.prototype[@@hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance) +- [`Function.prototype[Symbol.hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance) diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/index.md index d72f2d14f9f3c2b..7c5d214f9938448 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/index.md @@ -66,7 +66,7 @@ All static properties of the `Symbol` constructor are Symbols themselves, whose Prior to well-known Symbols, JavaScript used normal properties to implement certain built-in operations. For example, the [`JSON.stringify`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) function will attempt to call each object's `toJSON()` method, and the [`String`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String) function will call the object's `toString()` and `valueOf()` methods. However, as more operations are added to the language, designating each operation a "magic property" can break backward compatibility and make the language's behavior harder to reason with. Well-known Symbols allow the customizations to be "invisible" from normal code, which typically only read string properties. -In MDN and other sources, well-known symbol values are stylized by prefixing `@@`. For example, {{jsxref("Symbol.hasInstance")}} is written as `@@hasInstance`. This is because symbols don't have actual literal formats, but using `Symbol.hasInstance` does not reflect the ability of using other aliases to refer to the same symbol. This is like the difference between `Function.name` and `"Function"`. +> **Note:** The spec used to use the notation `@@` to denote well-known symbols. For example, {{jsxref("Symbol.hasInstance")}} was written as `@@hasInstance`, and the `Array.prototype[Symbol.iterator]()` method would be called `Array.prototype[@@iterator]()`. This notation is no longer used in the spec, but you may still see it in older documentation or discussions. Well-known symbols do not have the concept of garbage collectability, because they come in a fixed set and are unique throughout the lifetime of the program, similar to intrinsic objects such as `Array.prototype`, so they are also allowed in {{jsxref("WeakMap")}}, {{jsxref("WeakSet")}}, {{jsxref("WeakRef")}}, and {{jsxref("FinalizationRegistry")}} objects. @@ -125,8 +125,8 @@ These properties are defined on `Symbol.prototype` and shared by all `Symbol` in - : The constructor function that created the instance object. For `Symbol` instances, the initial value is the {{jsxref("Symbol/Symbol", "Symbol")}} constructor. - {{jsxref("Symbol.prototype.description")}} - : A read-only string containing the description of the Symbol. -- `Symbol.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Symbol"`. This property is used in {{jsxref("Object.prototype.toString()")}}. However, because `Symbol` also has its own [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toString) method, this property is not used unless you call [`Object.prototype.toString.call()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/call) with a symbol as `thisArg`. +- `Symbol.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Symbol"`. This property is used in {{jsxref("Object.prototype.toString()")}}. However, because `Symbol` also has its own [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toString) method, this property is not used unless you call [`Object.prototype.toString.call()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/call) with a symbol as `thisArg`. ## Instance methods @@ -134,7 +134,7 @@ These properties are defined on `Symbol.prototype` and shared by all `Symbol` in - : Returns a string containing the description of the Symbol. Overrides the {{jsxref("Object.prototype.toString()")}} method. - {{jsxref("Symbol.prototype.valueOf()")}} - : Returns the Symbol. Overrides the {{jsxref("Object.prototype.valueOf()")}} method. -- [`Symbol.prototype[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) +- [`Symbol.prototype[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) - : Returns the Symbol. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/isconcatspreadable/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/isconcatspreadable/index.md index d1ac2a5c40dbaf5..29c32754cf54943 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/isconcatspreadable/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/isconcatspreadable/index.md @@ -7,19 +7,19 @@ browser-compat: javascript.builtins.Symbol.isConcatSpreadable {{JSRef}} -The **`Symbol.isConcatSpreadable`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@isConcatSpreadable`. The {{jsxref("Array.prototype.concat()")}} method looks up this symbol on each object being concatenated to determine if it should be treated as an array-like object and flattened to its array elements. +The **`Symbol.isConcatSpreadable`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.isConcatSpreadable`. The {{jsxref("Array.prototype.concat()")}} method looks up this symbol on each object being concatenated to determine if it should be treated as an array-like object and flattened to its array elements. {{EmbedInteractiveExample("pages/js/symbol-isconcatspreadable.html")}} ## Value -The well-known symbol `@@isConcatSpreadable`. +The well-known symbol `Symbol.isConcatSpreadable`. {{js_property_attributes(0, 0, 0)}} ## Description -The `@@isConcatSpreadable` symbol (`Symbol.isConcatSpreadable`) can be defined as an own or inherited property and its value is a boolean. It can control behavior for arrays and array-like objects: +The `[Symbol.isConcatSpreadable]` property can be defined as an own or inherited property and its value is a boolean. It can control behavior for arrays and array-like objects: - For array objects, the default behavior is to spread (flatten) elements. `Symbol.isConcatSpreadable` can avoid flattening in these cases. - For array-like objects, the default behavior is no spreading or flattening. `Symbol.isConcatSpreadable` can force flattening in these cases. diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/iterator/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/iterator/index.md index 534a1dec71b8a79..07bf2f5b3ae89fb 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/iterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/iterator/index.md @@ -7,27 +7,27 @@ browser-compat: javascript.builtins.Symbol.iterator {{JSRef}} -The **`Symbol.iterator`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@iterator`. The [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) looks up this symbol for the method that returns the iterator for an object. In order for an object to be iterable, it must have an `@@iterator` key. +The **`Symbol.iterator`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.iterator`. The [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) looks up this symbol for the method that returns the iterator for an object. In order for an object to be iterable, it must have an `[Symbol.iterator]` key. {{EmbedInteractiveExample("pages/js/symbol-iterator.html")}} ## Value -The well-known symbol `@@iterator`. +The well-known symbol `Symbol.iterator`. {{js_property_attributes(0, 0, 0)}} ## Description -Whenever an object needs to be iterated (such as at the beginning of a `for...of` loop), its `@@iterator` method is called with no arguments, and the returned **iterator** is used to obtain the values to be iterated. +Whenever an object needs to be iterated (such as at the beginning of a `for...of` loop), its `[Symbol.iterator]()` method is called with no arguments, and the returned **iterator** is used to obtain the values to be iterated. -Some built-in types have a default iteration behavior, while other types (such as {{jsxref("Object")}}) do not. Some built-in types with a `@@iterator` method are: +Some built-in types have a default iteration behavior, while other types (such as {{jsxref("Object")}}) do not. Some built-in types with a `[Symbol.iterator]()` method are: -- [`Array.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) -- [`TypedArray.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) -- [`String.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) -- [`Map.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator) -- [`Set.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator) +- [`Array.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) +- [`TypedArray.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) +- [`String.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) +- [`Map.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator) +- [`Set.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator) See also [Iteration protocols](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) for more information. @@ -71,7 +71,7 @@ console.log(...someObj); // 'a', 'b' ### Non-well-formed iterables -If an iterable's `@@iterator` method does not return an iterator object, then it is a non-well-formed iterable. Using it as such is likely to result in runtime exceptions or buggy behavior: +If an iterable's `[Symbol.iterator]()` method does not return an iterator object, then it is a non-well-formed iterable. Using it as such is likely to result in runtime exceptions or buggy behavior: ```js example-bad const nonWellFormedIterable = {}; @@ -91,10 +91,10 @@ nonWellFormedIterable[Symbol.iterator] = () => 1; - [Polyfill of `Symbol.iterator` in `core-js`](https://github.com/zloirock/core-js#ecmascript-symbol) - [Iteration protocols](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) -- [`Array.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) -- [`TypedArray.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) -- [`String.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) -- [`Map.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator) -- [`Set.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator) -- [`arguments[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments/@@iterator) -- [`Segments.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/@@iterator) +- [`Array.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) +- [`TypedArray.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) +- [`String.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) +- [`Map.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator) +- [`Set.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator) +- [`arguments[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments/@@iterator) +- [`Segments.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/@@iterator) diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/match/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/match/index.md index e246545adb91092..29a25c72341373f 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/match/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/match/index.md @@ -7,15 +7,15 @@ browser-compat: javascript.builtins.Symbol.match {{JSRef}} -The **`Symbol.match`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@match`. The {{jsxref("String.prototype.match()")}} method looks up this symbol on its first argument for the method used to match an input string against the current object. This symbol is also used to determine if an object should be [treated as a regex](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#special_handling_for_regexes). +The **`Symbol.match`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.match`. The {{jsxref("String.prototype.match()")}} method looks up this symbol on its first argument for the method used to match an input string against the current object. This symbol is also used to determine if an object should be [treated as a regex](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#special_handling_for_regexes). -For more information, see [`RegExp.prototype[@@match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) and {{jsxref("String.prototype.match()")}}. +For more information, see [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) and {{jsxref("String.prototype.match()")}}. {{EmbedInteractiveExample("pages/js/symbol-match.html", "taller")}} ## Value -The well-known symbol `@@match`. +The well-known symbol `Symbol.match`. {{js_property_attributes(0, 0, 0)}} @@ -61,4 +61,4 @@ re[Symbol.match] = false; - {{jsxref("Symbol.search")}} - {{jsxref("Symbol.split")}} - {{jsxref("String.prototype.match()")}} -- [`RegExp.prototype[@@match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) +- [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/matchall/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/matchall/index.md index 8289b4771f1c11a..61aa958ade72be1 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/matchall/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/matchall/index.md @@ -7,15 +7,15 @@ browser-compat: javascript.builtins.Symbol.matchAll {{JSRef}} -The **`Symbol.matchAll`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@matchAll`. The {{jsxref("String.prototype.matchAll()")}} method looks up this symbol on its first argument for the method that returns an iterator, that yields matches of the current object against a string. +The **`Symbol.matchAll`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.matchAll`. The {{jsxref("String.prototype.matchAll()")}} method looks up this symbol on its first argument for the method that returns an iterator, that yields matches of the current object against a string. -For more information, see [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) and {{jsxref("String.prototype.matchAll()")}}. +For more information, see [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) and {{jsxref("String.prototype.matchAll()")}}. {{EmbedInteractiveExample("pages/js/symbol-matchall.html")}} ## Value -The well-known symbol `@@matchAll`. +The well-known symbol `Symbol.matchAll`. {{js_property_attributes(0, 0, 0)}} @@ -52,4 +52,4 @@ console.log(Array.from(str.matchAll(numbers))); - {{jsxref("Symbol.search")}} - {{jsxref("Symbol.split")}} - {{jsxref("String.prototype.matchAll()")}} -- [`RegExp.prototype[@@matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) +- [`RegExp.prototype[Symbol.matchAll]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/replace/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/replace/index.md index a5da704e4534d2a..3ccd6192d77a387 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/replace/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/replace/index.md @@ -7,15 +7,15 @@ browser-compat: javascript.builtins.Symbol.replace {{JSRef}} -The **`Symbol.replace`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@replace`. The {{jsxref("String.prototype.replace()")}} and {{jsxref("String.prototype.replaceAll()")}} methods look up this symbol on their first argument for the method that replaces substrings matched by the current object. +The **`Symbol.replace`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.replace`. The {{jsxref("String.prototype.replace()")}} and {{jsxref("String.prototype.replaceAll()")}} methods look up this symbol on their first argument for the method that replaces substrings matched by the current object. -For more information, see [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace), {{jsxref("String.prototype.replace()")}}, and {{jsxref("String.prototype.replaceAll()")}}. +For more information, see [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace), {{jsxref("String.prototype.replace()")}}, and {{jsxref("String.prototype.replaceAll()")}}. {{EmbedInteractiveExample("pages/js/symbol-replace.html")}} ## Value -The well-known symbol `@@replace`. +The well-known symbol `Symbol.replace`. {{js_property_attributes(0, 0, 0)}} @@ -53,4 +53,4 @@ console.log("football".replace(new CustomReplacer("foo"))); // "#!@?tball" - {{jsxref("Symbol.split")}} - {{jsxref("String.prototype.replace()")}} - {{jsxref("String.prototype.replaceAll()")}} -- [`RegExp.prototype[@@replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) +- [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/search/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/search/index.md index fd776b118de9644..53c0c1eb6d400bc 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/search/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/search/index.md @@ -7,15 +7,15 @@ browser-compat: javascript.builtins.Symbol.search {{JSRef}} -The **`Symbol.search`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@search`. The {{jsxref("String.prototype.search()")}} method looks up this symbol on its first argument for the method that returns the index within a string that matches the current object. +The **`Symbol.search`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.search`. The {{jsxref("String.prototype.search()")}} method looks up this symbol on its first argument for the method that returns the index within a string that matches the current object. -For more information, see [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) and {{jsxref("String.prototype.search()")}}. +For more information, see [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) and {{jsxref("String.prototype.search()")}}. {{EmbedInteractiveExample("pages/js/symbol-search.html")}} ## Value -The well-known symbol `@@search`. +The well-known symbol `Symbol.search`. {{js_property_attributes(0, 0, 0)}} @@ -52,4 +52,4 @@ console.log("foobar".search(new caseInsensitiveSearch("BaR"))); // 3 - {{jsxref("Symbol.replace")}} - {{jsxref("Symbol.split")}} - {{jsxref("String.prototype.search()")}} -- [`RegExp.prototype[@@search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) +- [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/species/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/species/index.md index dbbd185f693e4be..6f9642cfe260570 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/species/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/species/index.md @@ -7,23 +7,23 @@ browser-compat: javascript.builtins.Symbol.species {{JSRef}} -The **`Symbol.species`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@species`. Methods that create copies of an object may look up this symbol on the object for the constructor function to use when creating the copy. +The **`Symbol.species`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.species`. Methods that create copies of an object may look up this symbol on the object for the constructor function to use when creating the copy. -> **Warning:** The existence of `@@species` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. +> **Warning:** The existence of `[Symbol.species]` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. {{EmbedInteractiveExample("pages/js/symbol-species.html")}} ## Value -The well-known symbol `@@species`. +The well-known symbol `Symbol.species`. {{js_property_attributes(0, 0, 0)}} ## Description -The `@@species` accessor property allows subclasses to override the default constructor for objects. This specifies a protocol about how instances should be copied. For example, when you use copying methods of arrays, such as {{jsxref("Array/map", "map()")}}. the `map()` method uses `instance.constructor[Symbol.species]` to get the constructor for constructing the new array. For more information, see [subclassing built-ins](/en-US/docs/Web/JavaScript/Reference/Classes/extends#subclassing_built-ins). +The `[Symbol.species]` accessor property allows subclasses to override the default constructor for objects. This specifies a protocol about how instances should be copied. For example, when you use copying methods of arrays, such as {{jsxref("Array/map", "map()")}}. the `map()` method uses `instance.constructor[Symbol.species]` to get the constructor for constructing the new array. For more information, see [subclassing built-ins](/en-US/docs/Web/JavaScript/Reference/Classes/extends#subclassing_built-ins). -All built-in implementations of `@@species` return the `this` value, which is the current instance's constructor. This allows copying methods to create instances of derived classes rather than the base class — for example, `map()` will return an array of the same type as the original array. +All built-in implementations of `[Symbol.species]` return the `this` value, which is the current instance's constructor. This allows copying methods to create instances of derived classes rather than the base class — for example, `map()` will return an array of the same type as the original array. ## Examples @@ -55,10 +55,10 @@ console.log(mapped instanceof Array); // true ## See also -- {{jsxref("Array/@@species", "Array[@@species]")}} -- {{jsxref("ArrayBuffer/@@species", "ArrayBuffer[@@species]")}} -- {{jsxref("Map/@@species", "Map[@@species]")}} -- {{jsxref("Promise/@@species", "Promise[@@species]")}} -- {{jsxref("RegExp/@@species", "RegExp[@@species]")}} -- {{jsxref("Set/@@species", "Set[@@species]")}} -- {{jsxref("TypedArray/@@species", "TypedArray[@@species]")}} +- {{jsxref("Array/@@species", "Array[Symbol.species]")}} +- {{jsxref("ArrayBuffer/@@species", "ArrayBuffer[Symbol.species]")}} +- {{jsxref("Map/@@species", "Map[Symbol.species]")}} +- {{jsxref("Promise/@@species", "Promise[Symbol.species]")}} +- {{jsxref("RegExp/@@species", "RegExp[Symbol.species]")}} +- {{jsxref("Set/@@species", "Set[Symbol.species]")}} +- {{jsxref("TypedArray/@@species", "TypedArray[Symbol.species]")}} diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/split/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/split/index.md index 86d541b4eccb537..d0e3dd144929017 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/split/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/split/index.md @@ -7,15 +7,15 @@ browser-compat: javascript.builtins.Symbol.split {{JSRef}} -The **`Symbol.split`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@split`. The {{jsxref("String.prototype.split()")}} method looks up this symbol on its first argument for the method that splits a string at the indices that match the current object. +The **`Symbol.split`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.split`. The {{jsxref("String.prototype.split()")}} method looks up this symbol on its first argument for the method that splits a string at the indices that match the current object. -For more information, see[`RegExp.prototype[@@split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) and {{jsxref("String.prototype.split()")}}. +For more information, see[`RegExp.prototype[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) and {{jsxref("String.prototype.split()")}}. {{EmbedInteractiveExample("pages/js/symbol-split.html", "taller")}} ## Value -The well-known symbol `@@split`. +The well-known symbol `Symbol.split`. {{js_property_attributes(0, 0, 0)}} @@ -51,4 +51,4 @@ console.log("Another one bites the dust".split(new ReverseSplit())); - {{jsxref("Symbol.replace")}} - {{jsxref("Symbol.search")}} - {{jsxref("String.prototype.split()")}} -- [`RegExp.prototype[@@split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) +- [`RegExp.prototype[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@split) diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/toprimitive/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/toprimitive/index.md index c01c6aeddbf3586..07ef1e003c0cf44 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/toprimitive/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/toprimitive/index.md @@ -7,13 +7,13 @@ browser-compat: javascript.builtins.Symbol.toPrimitive {{JSRef}} -The **`Symbol.toPrimitive`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@toPrimitive`. All [type coercion](/en-US/docs/Web/JavaScript/Data_structures#type_coercion) algorithms look up this symbol on objects for the method that accepts a preferred type and returns a primitive representation of the object, before falling back to using the object's `valueOf()` and `toString()` methods. +The **`Symbol.toPrimitive`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.toPrimitive`. All [type coercion](/en-US/docs/Web/JavaScript/Data_structures#type_coercion) algorithms look up this symbol on objects for the method that accepts a preferred type and returns a primitive representation of the object, before falling back to using the object's `valueOf()` and `toString()` methods. {{EmbedInteractiveExample("pages/js/symbol-toprimitive.html")}} ## Value -The well-known symbol `@@toPrimitive`. +The well-known symbol `Symbol.toPrimitive`. {{js_property_attributes(0, 0, 0)}} @@ -21,9 +21,9 @@ The well-known symbol `@@toPrimitive`. With the help of the `Symbol.toPrimitive` property (used as a function value), an object can be converted to a primitive value. The function is called with a string argument `hint`, which specifies the preferred type of the result primitive value. The `hint` argument can be one of `"number"`, `"string"`, and `"default"`. -The `"number"` hint is used by [numeric coercion](/en-US/docs/Web/JavaScript/Data_structures#numeric_coercion) algorithms. The `"string"` hint is used by the [string coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) algorithm. The `"default"` hint is used by the [primitive coercion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) algorithm. The `hint` only acts as a weak signal of preference, and the implementation is free to ignore it (as [`Symbol.prototype[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) does). The language does not enforce alignment between the `hint` and the result type, although `[@@toPrimitive]()` must return a primitive, or a {{jsxref("TypeError")}} is thrown. +The `"number"` hint is used by [numeric coercion](/en-US/docs/Web/JavaScript/Data_structures#numeric_coercion) algorithms. The `"string"` hint is used by the [string coercion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) algorithm. The `"default"` hint is used by the [primitive coercion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) algorithm. The `hint` only acts as a weak signal of preference, and the implementation is free to ignore it (as [`Symbol.prototype[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) does). The language does not enforce alignment between the `hint` and the result type, although `[Symbol.toPrimitive]()` must return a primitive, or a {{jsxref("TypeError")}} is thrown. -Objects without the `@@toPrimitive` property are converted to primitives by calling the `valueOf()` and `toString()` methods in different orders, which is explained in more detail in the [type coercion](/en-US/docs/Web/JavaScript/Data_structures#type_coercion) section. `@@toPrimitive` allows full control over the primitive conversion process. For example, [`Date.prototype[@@toPrimitive]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) treats `"default"` as if it's `"string"` and calls `toString()` instead of `valueOf()`. [`Symbol.prototype[@@toPrimitive]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) ignores the hint and always returns a symbol, which means even in string contexts, {{jsxref("Symbol.prototype.toString()")}} won't be called, and `Symbol` objects must always be explicitly converted to strings through [`String()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String). +Objects without the `[Symbol.toPrimitive]` property are converted to primitives by calling the `valueOf()` and `toString()` methods in different orders, which is explained in more detail in the [type coercion](/en-US/docs/Web/JavaScript/Data_structures#type_coercion) section. `[Symbol.toPrimitive]()` allows full control over the primitive conversion process. For example, [`Date.prototype[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) treats `"default"` as if it's `"string"` and calls `toString()` instead of `valueOf()`. [`Symbol.prototype[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) ignores the hint and always returns a symbol, which means even in string contexts, {{jsxref("Symbol.prototype.toString()")}} won't be called, and `Symbol` objects must always be explicitly converted to strings through [`String()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String). ## Examples @@ -66,7 +66,7 @@ console.log(obj2 + ""); // "true" — hint is "default" ## See also - [Polyfill of `Symbol.toPrimitive` in `core-js`](https://github.com/zloirock/core-js#ecmascript-symbol) -- [`Date.prototype[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) -- [`Symbol.prototype[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) +- [`Date.prototype[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive) +- [`Symbol.prototype[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) - {{jsxref("Object.prototype.toString()")}} - {{jsxref("Object.prototype.valueOf()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/tostring/index.md index 2c08c7b765800b1..5f9507e69329db5 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/tostring/index.md @@ -32,7 +32,7 @@ The {{jsxref("Symbol")}} object overrides the `toString` method of {{jsxref("Obj The `toString()` method requires its `this` value to be a `Symbol` primitive or wrapper object. It throws a {{jsxref("TypeError")}} for other `this` values without attempting to coerce them to symbol values. -Because `Symbol` has a [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) method, that method always takes priority over `toString()` when a `Symbol` object is [coerced to a string](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). However, because `Symbol.prototype[@@toPrimitive]()` returns a symbol primitive, and symbol primitives throw a {{jsxref("TypeError")}} when implicitly converted to a string, the `toString()` method is never implicitly called by the language. To stringify a symbol, you must explicitly call its `toString()` method or use the [`String()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String#using_string_to_stringify_a_symbol) function. +Because `Symbol` has a [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) method, that method always takes priority over `toString()` when a `Symbol` object is [coerced to a string](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). However, because `Symbol.prototype[Symbol.toPrimitive]()` returns a symbol primitive, and symbol primitives throw a {{jsxref("TypeError")}} when implicitly converted to a string, the `toString()` method is never implicitly called by the language. To stringify a symbol, you must explicitly call its `toString()` method or use the [`String()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String#using_string_to_stringify_a_symbol) function. ## Examples @@ -50,7 +50,7 @@ Symbol.for("foo").toString(); // "Symbol(foo)" ### Implicitly calling toString() -The only way to make JavaScript implicitly call `toString()` instead of [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) on a symbol wrapper object is by [deleting](/en-US/docs/Web/JavaScript/Reference/Operators/delete) the `@@toPrimitive` method first. +The only way to make JavaScript implicitly call `toString()` instead of [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive) on a symbol wrapper object is by [deleting](/en-US/docs/Web/JavaScript/Reference/Operators/delete) the `[Symbol.toPrimitive]()` method first. > **Warning:** You should not do this in practice. Never mutate built-in objects unless you know exactly what you're doing. diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/tostringtag/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/tostringtag/index.md index ddac37983123d3d..9d091ad63c0c18f 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/tostringtag/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/tostringtag/index.md @@ -7,13 +7,13 @@ browser-compat: javascript.builtins.Symbol.toStringTag {{JSRef}} -The **`Symbol.toStringTag`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@toStringTag`. {{jsxref("Object.prototype.toString()")}} looks up this symbol on the `this` value for the property containing a string that represents the type of the object. +The **`Symbol.toStringTag`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.toStringTag`. {{jsxref("Object.prototype.toString()")}} looks up this symbol on the `this` value for the property containing a string that represents the type of the object. {{EmbedInteractiveExample("pages/js/symbol-tostringtag.html")}} ## Value -The well-known symbol `@@toStringTag`. +The well-known symbol `Symbol.toStringTag`. {{js_property_attributes(0, 0, 0)}} @@ -35,9 +35,9 @@ Object.prototype.toString.call(null); // "[object Null]" ### Built-in toStringTag symbols -Most built-in objects provide their own `@@toStringTag` property. Almost all built-in objects' `@@toStringTag` property is not writable, not enumerable, and configurable; the exception is {{jsxref("Iterator")}}, which is writable for compatibility reasons. +Most built-in objects provide their own `[Symbol.toStringTag]` property. Almost all built-in objects' `[Symbol.toStringTag]` property is not writable, not enumerable, and configurable; the exception is {{jsxref("Iterator")}}, which is writable for compatibility reasons. -For constructor objects like {{jsxref("Promise")}}, the property is installed on `Constructor.prototype`, so that all instances of the constructor inherit `@@toStringTag` and can be stringified. For non-constructor objects like {{jsxref("Math")}} and {{jsxref("JSON")}}, the property is installed as a static property, so that the namespace object itself can be stringified. Sometimes, the constructor also provides its own `toString` method (for example, {{jsxref("Intl.Locale")}}), in which case the `@@toStringTag` property is only used when you explicitly call `Object.prototype.toString` on it. +For constructor objects like {{jsxref("Promise")}}, the property is installed on `Constructor.prototype`, so that all instances of the constructor inherit `[Symbol.toStringTag]` and can be stringified. For non-constructor objects like {{jsxref("Math")}} and {{jsxref("JSON")}}, the property is installed as a static property, so that the namespace object itself can be stringified. Sometimes, the constructor also provides its own `toString` method (for example, {{jsxref("Intl.Locale")}}), in which case the `[Symbol.toStringTag]` property is only used when you explicitly call `Object.prototype.toString` on it. ```js Object.prototype.toString.call(new Map()); // "[object Map]" diff --git a/files/en-us/web/javascript/reference/global_objects/symbol/unscopables/index.md b/files/en-us/web/javascript/reference/global_objects/symbol/unscopables/index.md index 90ff9929dd3ded3..fa70532acd89618 100644 --- a/files/en-us/web/javascript/reference/global_objects/symbol/unscopables/index.md +++ b/files/en-us/web/javascript/reference/global_objects/symbol/unscopables/index.md @@ -7,23 +7,23 @@ browser-compat: javascript.builtins.Symbol.unscopables {{JSRef}} -The **`Symbol.unscopables`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `@@unscopables`. The {{jsxref("Statements/with", "with")}} statement looks up this symbol on the scope object for a property containing a collection of properties that should not become bindings within the `with` environment. +The **`Symbol.unscopables`** static data property represents the [well-known symbol](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) `Symbol.unscopables`. The {{jsxref("Statements/with", "with")}} statement looks up this symbol on the scope object for a property containing a collection of properties that should not become bindings within the `with` environment. {{EmbedInteractiveExample("pages/js/symbol-unscopables.html")}} ## Value -The well-known symbol `@@unscopables`. +The well-known symbol `Symbol.unscopables`. {{js_property_attributes(0, 0, 0)}} ## Description -The `@@unscopables` symbol (accessed via `Symbol.unscopables`) can be defined on any object to exclude property names from being exposed as lexical variables in [`with`](/en-US/docs/Web/JavaScript/Reference/Statements/with) environment bindings. Note that when using [strict mode](/en-US/docs/Web/JavaScript/Reference/Strict_mode), `with` statements are not available, and this symbol is likely not needed. +The `[Symbol.unscopables]` symbol (accessed via `Symbol.unscopables`) can be defined on any object to exclude property names from being exposed as lexical variables in [`with`](/en-US/docs/Web/JavaScript/Reference/Statements/with) environment bindings. Note that when using [strict mode](/en-US/docs/Web/JavaScript/Reference/Strict_mode), `with` statements are not available, and this symbol is likely not needed. -Setting a property of the `@@unscopables` object to `true` (or any [truthy](/en-US/docs/Glossary/Truthy) value) will make the corresponding property of the `with` scope object _unscopable_ and therefore won't be introduced to the `with` body scope. Setting a property to `false` (or any [falsy](/en-US/docs/Glossary/Falsy) value) will make it _scopable_ and thus appear as lexical scope variables. +Setting a property of the `[Symbol.unscopables]` object to `true` (or any [truthy](/en-US/docs/Glossary/Truthy) value) will make the corresponding property of the `with` scope object _unscopable_ and therefore won't be introduced to the `with` body scope. Setting a property to `false` (or any [falsy](/en-US/docs/Glossary/Falsy) value) will make it _scopable_ and thus appear as lexical scope variables. -When deciding whether `x` is unscopable, the entire prototype chain of the `@@unscopables` property is looked up for a property called `x`. This means if you declared `@@unscopables` as a plain object, `Object.prototype` properties like [`toString`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) would become unscopable as well, which may cause backward incompatibility for legacy code assuming those properties are normally scoped (see [an example below](#avoid_using_a_non-null-prototype_object_as_unscopables)). You are advised to make your custom `@@unscopables` property have `null` as its prototype, like [`Array.prototype[@@unscopables]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@unscopables) does. +When deciding whether `x` is unscopable, the entire prototype chain of the `[Symbol.unscopables]` property is looked up for a property called `x`. This means if you declared `[Symbol.unscopables]` as a plain object, `Object.prototype` properties like [`toString`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) would become unscopable as well, which may cause backward incompatibility for legacy code assuming those properties are normally scoped (see [an example below](#avoid_using_a_non-null-prototype_object_as_symbol.unscopables)). You are advised to make your custom `[Symbol.unscopables]` property have `null` as its prototype, like [`Array.prototype[Symbol.unscopables]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@unscopables) does. This protocol is also utilized by DOM APIs, such as [`Element.prototype.append()`](/en-US/docs/Web/API/Element/append). @@ -37,17 +37,18 @@ The following code works fine in ES5 and below. However, in ECMAScript 2015, the var values = []; with (values) { - // If @@unscopables did not exist, values would become Array.prototype.values starting with ECMAScript 2015. + // If [Symbol.unscopables] did not exist, values would become + // Array.prototype.values starting with ECMAScript 2015. // And an error would have occurred. values.push("something"); } ``` -The code containing `with (values)` caused some websites to malfunction in Firefox when `Array.prototype.values()` was added ([Firefox Bug 883914](https://bugzil.la/883914)). Furthermore, this implies that any future array method addition may be breaking if it implicitly changes the `with` scope. Therefore, the `@@unscopables` symbol was introduced and implemented on `Array` as {{jsxref("Array/@@unscopables", "Array.prototype[@@unscopables]")}} to prevent some of the Array methods being scoped into the `with` statement. +The code containing `with (values)` caused some websites to malfunction in Firefox when `Array.prototype.values()` was added ([Firefox Bug 883914](https://bugzil.la/883914)). Furthermore, this implies that any future array method addition may be breaking if it implicitly changes the `with` scope. Therefore, the `[Symbol.unscopables]` symbol was introduced and implemented on `Array` as {{jsxref("Array/@@unscopables", "Array.prototype[Symbol.unscopables]")}} to prevent some of the Array methods being scoped into the `with` statement. ### Unscopables in objects -You can also set `@@unscopables` for your own objects. +You can also set `[Symbol.unscopables]` for your own objects. ```js const obj = { @@ -74,9 +75,9 @@ with (obj) { } ``` -### Avoid using a non-null-prototype object as @@unscopables +### Avoid using a non-null-prototype object as `[Symbol.unscopables]` -Declaring `@@unscopables` as a plain object without eliminating its prototype may cause subtle bugs. Consider the following code working before `@@unscopables`: +Declaring `[Symbol.unscopables]` as a plain object without eliminating its prototype may cause subtle bugs. Consider the following code working before `[Symbol.unscopables]`: ```js const character = { @@ -91,7 +92,7 @@ with (character) { } ``` -To preserve backward compatibility, you decided to add an `@@unscopables` property when adding more properties to `character`. You may naïvely do it like: +To preserve backward compatibility, you decided to add an `[Symbol.unscopables]` property when adding more properties to `character`. You may naïvely do it like: ```js example-bad const character = { @@ -135,7 +136,7 @@ with (proto) { } ``` -To fix this, always make sure `@@unscopables` only contains properties you wish to be unscopable, without `Object.prototype` properties. +To fix this, always make sure `[Symbol.unscopables]` only contains properties you wish to be unscopable, without `Object.prototype` properties. ```js example-good const character = { @@ -164,6 +165,6 @@ const character = { ## See also -- {{jsxref("Array/@@unscopables", "Array.prototype[@@unscopables]")}} +- {{jsxref("Array/@@unscopables", "Array.prototype[Symbol.unscopables]")}} - [`with`](/en-US/docs/Web/JavaScript/Reference/Statements/with) - [`Element.prototype.append()`](/en-US/docs/Web/API/Element/append) diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/@@iterator/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/@@iterator/index.md index b9870207d10669c..7072666bd1b325d 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/@@iterator/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/@@iterator/index.md @@ -1,5 +1,5 @@ --- -title: TypedArray.prototype[@@iterator]() +title: TypedArray.prototype[Symbol.iterator]() slug: Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator page-type: javascript-instance-method browser-compat: javascript.builtins.TypedArray.@@iterator @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.TypedArray.@@iterator {{JSRef}} -The **`[@@iterator]()`** method of {{jsxref("TypedArray")}} instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows typed arrays to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns an [array iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the value of each index in the typed array. +The **`[Symbol.iterator]()`** method of {{jsxref("TypedArray")}} instances implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows typed arrays to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and {{jsxref("Statements/for...of", "for...of")}} loops. It returns an [array iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the value of each index in the typed array. The initial value of this property is the same function object as the initial value of the {{jsxref("TypedArray.prototype.values")}} property. @@ -31,7 +31,7 @@ The same return value as {{jsxref("TypedArray.prototype.values()")}}: a new [ite ### Iteration using for...of loop -Note that you seldom need to call this method directly. The existence of the `@@iterator` method makes typed arrays [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. +Note that you seldom need to call this method directly. The existence of the `[Symbol.iterator]()` method makes typed arrays [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically call this method to obtain the iterator to loop over. ```js const arr = new Uint8Array([10, 20, 30, 40, 50]); @@ -64,7 +64,7 @@ console.log(arrIter.next().value); // 50 ## See also -- [Polyfill of `TypedArray.prototype[@@iterator]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-typed-arrays) +- [Polyfill of `TypedArray.prototype[Symbol.iterator]` in `core-js`](https://github.com/zloirock/core-js#ecmascript-typed-arrays) - [JavaScript typed arrays](/en-US/docs/Web/JavaScript/Guide/Typed_arrays) guide - {{jsxref("TypedArray")}} - {{jsxref("TypedArray.prototype.entries()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/@@species/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/@@species/index.md index 4b4abb0c21212b4..aa362d2ca8b871e 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/@@species/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/@@species/index.md @@ -1,5 +1,5 @@ --- -title: TypedArray[@@species] +title: TypedArray[Symbol.species] slug: Web/JavaScript/Reference/Global_Objects/TypedArray/@@species page-type: javascript-static-accessor-property browser-compat: javascript.builtins.TypedArray.@@species @@ -7,9 +7,9 @@ browser-compat: javascript.builtins.TypedArray.@@species {{JSRef}} -The **`TypedArray[@@species]`** static accessor property returns the constructor used to construct return values from typed array methods. +The **`TypedArray[Symbol.species]`** static accessor property returns the constructor used to construct return values from typed array methods. -> **Warning:** The existence of `@@species` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. +> **Warning:** The existence of `[Symbol.species]` allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are [investigating whether to remove this feature](https://github.com/tc39/proposal-rm-builtin-subclassing). Avoid relying on it if possible. ## Syntax @@ -19,11 +19,11 @@ TypedArray[Symbol.species] ### Return value -The value of the constructor (`this`) on which `get @@species` was called. The return value is used to construct return values from typed array methods that create new typed arrays. +The value of the constructor (`this`) on which `get [Symbol.species]` was called. The return value is used to construct return values from typed array methods that create new typed arrays. ## Description -The `@@species` accessor property returns the default constructor for [typed array](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#typedarray_objects) objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: +The `[Symbol.species]` accessor property returns the default constructor for [typed array](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#typedarray_objects) objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically: ```js // Hypothetical underlying implementation for illustration @@ -34,16 +34,16 @@ class TypedArray { } ``` -Because of this polymorphic implementation, `@@species` of derived subclasses would also return the constructor itself by default. +Because of this polymorphic implementation, `[Symbol.species]` of derived subclasses would also return the constructor itself by default. ```js class SubTypedArray extends Int8Array {} SubTypedArray[Symbol.species] === SubTypedArray; // true ``` -When calling typed array methods that do not mutate the existing array but return a new array instance (for example, [`filter()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/filter) and [`map()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/map)), the array's `constructor[@@species]` will be accessed. The returned constructor will be used to construct the return value of the typed array method. +When calling typed array methods that do not mutate the existing array but return a new array instance (for example, [`filter()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/filter) and [`map()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/map)), the array's `constructor[Symbol.species]` will be accessed. The returned constructor will be used to construct the return value of the typed array method. -However, unlike [`Array[@@species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@species), when using `@@species` to create new typed arrays, the language will make sure that the newly created array is a proper typed array and has the same content type as the original array — for example, you can't create a {{jsxref("BigInt64Array")}} from a {{jsxref("Float64Array")}}, or create a non-BigInt array from a BigInt array. Doing so throws a {{jsxref("TypeError")}}. +However, unlike [`Array[Symbol.species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@species), when using `[Symbol.species]` to create new typed arrays, the language will make sure that the newly created array is a proper typed array and has the same content type as the original array — for example, you can't create a {{jsxref("BigInt64Array")}} from a {{jsxref("Float64Array")}}, or create a non-BigInt array from a BigInt array. Doing so throws a {{jsxref("TypeError")}}. ```js class BadArray extends Int8Array { @@ -67,7 +67,7 @@ new BadArray2(1).map(() => 0n); // TypeError: TypedArray.prototype.map construct ### Species in ordinary objects -The `@@species` property returns the default constructor function, which is one of the typed array constructors itself for any given [typed array](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#typedarray_objects) constructor. +The `[Symbol.species]` property returns the default constructor function, which is one of the typed array constructors itself for any given [typed array](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#typedarray_objects) constructor. ```js Int8Array[Symbol.species]; // function Int8Array() diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/entries/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/entries/index.md index dc13b74d69d6a93..1fa1001f66c056f 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/entries/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/entries/index.md @@ -69,6 +69,6 @@ console.log(arrayEntries.next().value); // [4, 50] - {{jsxref("TypedArray")}} - {{jsxref("TypedArray.prototype.keys()")}} - {{jsxref("TypedArray.prototype.values()")}} -- [`TypedArray.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) +- [`TypedArray.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) - {{jsxref("Array.prototype.entries()")}} - [Iteration protocols](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/index.md index 1cc863e35a74420..5316ef71fd8bc5f 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/index.md @@ -184,7 +184,7 @@ All `TypeArray` subclass constructors operate in the same way. They would all th These properties are defined on the `TypedArray` constructor object and are thus shared by all `TypedArray` subclass constructors. -- {{jsxref("TypedArray/@@species", "TypedArray[@@species]")}} +- {{jsxref("TypedArray/@@species", "TypedArray[Symbol.species]")}} - : The constructor function used to create derived objects. All `TypedArray` subclasses also have the following static properties: @@ -215,8 +215,8 @@ These properties are defined on `TypedArray.prototype` and shared by all `TypedA - : The constructor function that created the instance object. `TypedArray.prototype.constructor` is the hidden `TypedArray` constructor function, but each typed array subclass also defines its own `constructor` property. - {{jsxref("TypedArray.prototype.length")}} - : Returns the number of elements held in the typed array. -- `TypedArray.prototype[@@toStringTag]` - - : The initial value of the [`TypedArray.prototype[@@toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is a getter that returns the same string as the typed array constructor's name. It returns `undefined` if the `this` value is not one of the typed array subclasses. This property is used in {{jsxref("Object.prototype.toString()")}}. However, because `TypedArray` also has its own [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/toString) method, this property is not used unless you call [`Object.prototype.toString.call()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/call) with a typed array as `thisArg`. +- `TypedArray.prototype[Symbol.toStringTag]` + - : The initial value of the [`TypedArray.prototype[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is a getter that returns the same string as the typed array constructor's name. It returns `undefined` if the `this` value is not one of the typed array subclasses. This property is used in {{jsxref("Object.prototype.toString()")}}. However, because `TypedArray` also has its own [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/toString) method, this property is not used unless you call [`Object.prototype.toString.call()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/call) with a typed array as `thisArg`. All `TypedArray` subclasses also have the following instance properties: @@ -289,7 +289,7 @@ These methods are defined on the `TypedArray` prototype object and are thus shar - : Returns a new _array iterator_ object that contains the values for each index in the array. See also {{jsxref("Array.prototype.values()")}}. - {{jsxref("TypedArray.prototype.with()")}} - : Returns a new array with the element at the given index replaced with the given value, without modifying the original array. -- [`TypedArray.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) +- [`TypedArray.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) - : Returns a new _array iterator_ object that contains the values for each index in the array. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/keys/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/keys/index.md index 287ba4b44112aeb..78804fd5b0f05b0 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/keys/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/keys/index.md @@ -68,6 +68,6 @@ console.log(arrKeys.next().value); // 4 - {{jsxref("TypedArray")}} - {{jsxref("TypedArray.prototype.entries()")}} - {{jsxref("TypedArray.prototype.values()")}} -- [`TypedArray.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) +- [`TypedArray.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) - {{jsxref("Array.prototype.keys()")}} - [Iteration protocols](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/values/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/values/index.md index 574862a2700b78d..0c9eb04a7bdb406 100644 --- a/files/en-us/web/javascript/reference/global_objects/typedarray/values/index.md +++ b/files/en-us/web/javascript/reference/global_objects/typedarray/values/index.md @@ -68,6 +68,6 @@ console.log(values.next().value); // 50 - {{jsxref("TypedArray")}} - {{jsxref("TypedArray.prototype.entries()")}} - {{jsxref("TypedArray.prototype.keys()")}} -- [`TypedArray.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) +- [`TypedArray.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/@@iterator) - {{jsxref("Array.prototype.values()")}} - [Iteration protocols](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) diff --git a/files/en-us/web/javascript/reference/global_objects/weakmap/index.md b/files/en-us/web/javascript/reference/global_objects/weakmap/index.md index 81243502b440f8c..0a90c4f04939feb 100644 --- a/files/en-us/web/javascript/reference/global_objects/weakmap/index.md +++ b/files/en-us/web/javascript/reference/global_objects/weakmap/index.md @@ -46,8 +46,8 @@ These properties are defined on `WeakMap.prototype` and shared by all `WeakMap` - {{jsxref("Object/constructor", "WeakMap.prototype.constructor")}} - : The constructor function that created the instance object. For `WeakMap` instances, the initial value is the {{jsxref("WeakMap/WeakMap", "WeakMap")}} constructor. -- `WeakMap.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"WeakMap"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `WeakMap.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"WeakMap"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/weakmap/weakmap/index.md b/files/en-us/web/javascript/reference/global_objects/weakmap/weakmap/index.md index 7fce5d1c9cb016c..8a502064460a8bb 100644 --- a/files/en-us/web/javascript/reference/global_objects/weakmap/weakmap/index.md +++ b/files/en-us/web/javascript/reference/global_objects/weakmap/weakmap/index.md @@ -21,7 +21,7 @@ new WeakMap(iterable) ### Parameters - `iterable` - - : An [`Array`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) or other iterable object that implements an [@@iterator](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator) method that returns an iterator object that produces a two-element array-like object whose first element is a value that will be used as a `WeakMap` key and whose second element is the value to associate with that key. Each key-value pair will be added to the new `WeakMap`. null is treated as undefined. + - : An [`Array`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) or other [iterable object](<(/en-US/docs/Web/JavaScript/Reference/Iteration_protocols)>) that produces a two-element array-like object whose first element is a value that will be used as a `WeakMap` key and whose second element is the value to associate with that key. Each key-value pair will be added to the new `WeakMap`. null is treated as undefined. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/weakref/index.md b/files/en-us/web/javascript/reference/global_objects/weakref/index.md index 8043d2fa16aae83..e6fe9a34d6dd6e6 100644 --- a/files/en-us/web/javascript/reference/global_objects/weakref/index.md +++ b/files/en-us/web/javascript/reference/global_objects/weakref/index.md @@ -53,8 +53,8 @@ These properties are defined on `WeakRef.prototype` and shared by all `WeakRef` > **Note:** This property is marked as "normative optional" in the specification, which means a conforming implementation may not expose the `constructor` property. This prevents arbitrary code from obtaining the `WeakRef` constructor and being able to observe garbage collection. However, all major engines do expose it by default. -- `WeakRef.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"WeakRef"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `WeakRef.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"WeakRef"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/global_objects/weakset/index.md b/files/en-us/web/javascript/reference/global_objects/weakset/index.md index 13aa42522d2680c..9ec43e11614b675 100644 --- a/files/en-us/web/javascript/reference/global_objects/weakset/index.md +++ b/files/en-us/web/javascript/reference/global_objects/weakset/index.md @@ -70,8 +70,8 @@ These properties are defined on `WeakSet.prototype` and shared by all `WeakSet` - {{jsxref("Object/constructor", "WeakSet.prototype.constructor")}} - : The constructor function that created the instance object. For `WeakSet` instances, the initial value is the {{jsxref("WeakSet/WeakSet", "WeakSet")}} constructor. -- `WeakSet.prototype[@@toStringTag]` - - : The initial value of the [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"WeakSet"`. This property is used in {{jsxref("Object.prototype.toString()")}}. +- `WeakSet.prototype[Symbol.toStringTag]` + - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"WeakSet"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods diff --git a/files/en-us/web/javascript/reference/iteration_protocols/index.md b/files/en-us/web/javascript/reference/iteration_protocols/index.md index d5420534984fd05..6d770ea445b56b0 100644 --- a/files/en-us/web/javascript/reference/iteration_protocols/index.md +++ b/files/en-us/web/javascript/reference/iteration_protocols/index.md @@ -15,12 +15,12 @@ There are two protocols: The [iterable protocol](#the_iterable_protocol) and the **The iterable protocol** allows JavaScript objects to define or customize their iteration behavior, such as what values are looped over in a {{jsxref("Statements/for...of", "for...of")}} construct. Some built-in types are [built-in iterables](#built-in_iterables) with a default iteration behavior, such as {{jsxref("Array")}} or {{jsxref("Map")}}, while other types (such as {{jsxref("Object")}}) are not. -In order to be **iterable**, an object must implement the **`@@iterator`** method, meaning that the object (or one of the objects up its [prototype chain](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain)) must have a property with a `@@iterator` key which is available via constant {{jsxref("Symbol.iterator")}}: +In order to be **iterable**, an object must implement the **`[Symbol.iterator]()`** method, meaning that the object (or one of the objects up its [prototype chain](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain)) must have a property with a `[Symbol.iterator]` key which is available via constant {{jsxref("Symbol.iterator")}}: -- `[Symbol.iterator]` +- `[Symbol.iterator]()` - : A zero-argument function that returns an object, conforming to the [iterator protocol](#the_iterator_protocol). -Whenever an object needs to be iterated (such as at the beginning of a {{jsxref("Statements/for...of", "for...of")}} loop), its `@@iterator` method is called with no arguments, and the returned **iterator** is used to obtain the values to be iterated. +Whenever an object needs to be iterated (such as at the beginning of a {{jsxref("Statements/for...of", "for...of")}} loop), its `[Symbol.iterator]()` method is called with no arguments, and the returned **iterator** is used to obtain the values to be iterated. Note that when this zero-argument function is called, it is invoked as a method on the iterable object. Therefore inside of the function, the `this` keyword can be used to access the properties of the iterable object, to decide what to provide during the iteration. @@ -61,7 +61,7 @@ Optionally, the iterator can also implement the **`return(value)`** and **`throw > **Note:** It is not possible to know reflectively (i.e. without actually calling `next()` and validating the returned result) whether a particular object implements the iterator protocol. -It is very easy to make an iterator also iterable: just implement an `[@@iterator]()` method that returns `this`. +It is very easy to make an iterator also iterable: just implement an `[Symbol.iterator]()` method that returns `this`. ```js // Satisfies both the Iterator Protocol and Iterable @@ -88,15 +88,15 @@ console.log(typeof aGeneratorObject.next); // "function" — it has a next method (which returns the right result), so it's an iterator console.log(typeof aGeneratorObject[Symbol.iterator]); -// "function" — it has an @@iterator method (which returns the right iterator), so it's an iterable +// "function" — it has an [Symbol.iterator] method (which returns the right iterator), so it's an iterable console.log(aGeneratorObject[Symbol.iterator]() === aGeneratorObject); -// true — its @@iterator method returns itself (an iterator), so it's an iterable iterator +// true — its [Symbol.iterator] method returns itself (an iterator), so it's an iterable iterator ``` -All built-in iterators inherit from {{jsxref("Iterator", "Iterator.prototype")}}, which implements the `[@@iterator]()` method as returning `this`, so that built-in iterators are also iterable. +All built-in iterators inherit from {{jsxref("Iterator", "Iterator.prototype")}}, which implements the `[Symbol.iterator]()` method as returning `this`, so that built-in iterators are also iterable. -However, when possible, it's better for `iterable[Symbol.iterator]` to return different iterators that always start from the beginning, like [`Set.prototype[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator) does. +However, when possible, it's better for `iterable[Symbol.iterator]()` to return different iterators that always start from the beginning, like [`Set.prototype[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/@@iterator) does. ## The async iterator and async iterable protocols @@ -104,7 +104,7 @@ There are another pair of protocols used for async iteration, named **async iter An object implements the async iterable protocol when it implements the following methods: -- [`[Symbol.asyncIterator]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator) +- [`[Symbol.asyncIterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator) - : A zero-argument function that returns an object, conforming to the async iterator protocol. An object implements the async iterator protocol when it implements the following methods: @@ -122,7 +122,7 @@ The language specifies APIs that either produce or consume iterables and iterato ### Built-in iterables -{{jsxref("String")}}, {{jsxref("Array")}}, {{jsxref("TypedArray")}}, {{jsxref("Map")}}, {{jsxref("Set")}}, and [`Segments`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments) (returned by [`Intl.Segmenter.prototype.segment()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment)) are all built-in iterables, because each of their `prototype` objects implements an `@@iterator` method. In addition, the [`arguments`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments) object and some DOM collection types such as {{domxref("NodeList")}} are also iterables. +{{jsxref("String")}}, {{jsxref("Array")}}, {{jsxref("TypedArray")}}, {{jsxref("Map")}}, {{jsxref("Set")}}, and [`Segments`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments) (returned by [`Intl.Segmenter.prototype.segment()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment)) are all built-in iterables, because each of their `prototype` objects implements an `[Symbol.iterator]()` method. In addition, the [`arguments`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments) object and some DOM collection types such as {{domxref("NodeList")}} are also iterables. There is no object in the core JavaScript language that is async iterable. Some web APIs, such as {{domxref("ReadableStream")}}, have the `Symbol.asyncIterator` method set by default. [Generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/function*) return [generator objects](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator), which are iterable iterators. [Async generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/async_function*) return [async generator objects](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator), which are async iterable iterators. @@ -232,7 +232,7 @@ for (const b of obj) { // Closing ``` -The [`for await...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) loop and [`yield*`](/en-US/docs/Web/JavaScript/Reference/Operators/yield*) in [async generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/async_function*) (but not [sync generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/function*)) are the only ways to interact with async iterables. Using `for...of`, array spreading, etc. on an async iterable that's not also a sync iterable (i.e. it has `[@@asyncIterator]()` but no `[@@iterator]()`) will throw a TypeError: x is not iterable. +The [`for await...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) loop and [`yield*`](/en-US/docs/Web/JavaScript/Reference/Operators/yield*) in [async generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/async_function*) (but not [sync generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/function*)) are the only ways to interact with async iterables. Using `for...of`, array spreading, etc. on an async iterable that's not also a sync iterable (i.e. it has `[Symbol.asyncIterator]()` but no `[Symbol.iterator]()`) will throw a TypeError: x is not iterable. ## Error handling @@ -242,9 +242,9 @@ Because iteration involves transferring control back and forth between the itera Errors may happen when acquiring the iterator from the iterable. The language invariant enforced here is that the iterable must produce a valid iterator: -- It has a callable `[@@iterator]()` method. -- The `[@@iterator]()` method returns an object. -- The object returned by `[@@iterator]()` has a callable `next()` method. +- It has a callable `[Symbol.iterator]()` method. +- The `[Symbol.iterator]()` method returns an object. +- The object returned by `[Symbol.iterator]()` has a callable `next()` method. When using built-in syntax to initiate iteration on a non-well-formed iterable, a TypeError is thrown. @@ -257,7 +257,7 @@ nonWellFormedIterable[Symbol.iterator] = () => ({}); [...nonWellFormedIterable]; // TypeError: nonWellFormedIterable[Symbol.iterator]().next is not a function ``` -For async iterables, if its `@@asyncIterator` property has value `undefined` or `null`, JavaScript falls back to using the `@@iterator` property instead (and wraps the resulting iterator into an async iterator by [forwarding](#forwarding_errors) the methods). Otherwise, the `@@asyncIterator` property must conform to the above invariants too. +For async iterables, if its `[Symbol.asyncIterator]()` property has value `undefined` or `null`, JavaScript falls back to using the `[Symbol.iterator]` property instead (and wraps the resulting iterator into an async iterator by [forwarding](#forwarding_errors) the methods). Otherwise, the `[Symbol.asyncIterator]` property must conform to the above invariants too. This type of errors can be prevented by first validating the iterable before attempting to iterate it. However, it's fairly rare because usually you know the type of the object you are iterating over. If you are receiving this iterable from some other code, you should just let the error propagate to the caller so they know an invalid input was provided. @@ -428,7 +428,7 @@ class SimpleClass { return { // Note: using an arrow function allows `this` to point to the - // one of `[@@iterator]()` instead of `next()` + // one of `[Symbol.iterator]()` instead of `next()` next: () => { if (index < this.#data.length) { return { value: this.#data[index++], done: false }; @@ -467,7 +467,7 @@ console.log(iterator.next()); // { value: "i", done: false } console.log(iterator.next()); // { value: undefined, done: true } ``` -You can redefine the iteration behavior by supplying our own `@@iterator`: +You can redefine the iteration behavior by supplying our own `[Symbol.iterator]()`: ```js // need to construct a String object explicitly to avoid auto-boxing @@ -486,7 +486,7 @@ someString[Symbol.iterator] = function () { }; ``` -Notice how redefining `@@iterator` affects the behavior of built-in constructs that use the iteration protocol: +Notice how redefining `[Symbol.iterator]()` affects the behavior of built-in constructs that use the iteration protocol: ```js console.log([...someString]); // ["bye"] diff --git a/files/en-us/web/javascript/reference/operators/addition/index.md b/files/en-us/web/javascript/reference/operators/addition/index.md index b2f4cb62c54f2f2..03327dcdb90ccd3 100644 --- a/files/en-us/web/javascript/reference/operators/addition/index.md +++ b/files/en-us/web/javascript/reference/operators/addition/index.md @@ -25,7 +25,7 @@ The `+` operator is overloaded for two distinct operations: numeric addition and - If they are both [BigInts](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt), BigInt addition is performed. If one side is a BigInt but the other is not, a {{jsxref("TypeError")}} is thrown. - Otherwise, both sides are [converted to numbers](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion), and numeric addition is performed. -String concatenation is often thought to be equivalent with [template literals](/en-US/docs/Web/JavaScript/Reference/Template_literals) or [`String.prototype.concat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat), but they are not. Addition coerces the expression to a _primitive_, which calls [`valueOf()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf) in priority; on the other hand, template literals and `concat()` coerce the expression to a _string_, which calls [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) in priority. If the expression has a [`@@toPrimitive`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, string concatenation calls it with `"default"` as hint, while template literals use `"string"`. This is important for objects that have different string and primitive representations — such as [Temporal](https://github.com/tc39/proposal-temporal), whose `valueOf()` method throws. +String concatenation is often thought to be equivalent with [template literals](/en-US/docs/Web/JavaScript/Reference/Template_literals) or [`String.prototype.concat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat), but they are not. Addition coerces the expression to a _primitive_, which calls [`valueOf()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf) in priority; on the other hand, template literals and `concat()` coerce the expression to a _string_, which calls [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) in priority. If the expression has a [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, string concatenation calls it with `"default"` as hint, while template literals use `"string"`. This is important for objects that have different string and primitive representations — such as [Temporal](https://github.com/tc39/proposal-temporal), whose `valueOf()` method throws. ```js const t = Temporal.Now.instant(); diff --git a/files/en-us/web/javascript/reference/operators/import/index.md b/files/en-us/web/javascript/reference/operators/import/index.md index 32ed32fb4be23f8..ab193a3e30f6a06 100644 --- a/files/en-us/web/javascript/reference/operators/import/index.md +++ b/files/en-us/web/javascript/reference/operators/import/index.md @@ -56,7 +56,7 @@ For example, `import()` can be used in the main thread, a shared worker, or a de A _module namespace object_ is an object that describes all exports from a module. It is a static object that is created when the module is evaluated. There are two ways to access the module namespace object of a module: through a [namespace import](/en-US/docs/Web/JavaScript/Reference/Statements/import#namespace_import) (`import * as name from moduleName`), or through the fulfillment value of a dynamic import. -The module namespace object is a [sealed](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/isSealed) object with [`null` prototype](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects). This means all string keys of the object correspond to the exports of the module and there are never extra keys. All keys are [enumerable](/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties) in lexicographic order (i.e. the default behavior of [`Array.prototype.sort()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#description)), with the default export available as a key called `default`. In addition, the module namespace object has a [`@@toStringTag`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property with the value `"Module"`, used in {{jsxref("Object.prototype.toString()")}}. +The module namespace object is a [sealed](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/isSealed) object with [`null` prototype](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects). This means all string keys of the object correspond to the exports of the module and there are never extra keys. All keys are [enumerable](/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties) in lexicographic order (i.e. the default behavior of [`Array.prototype.sort()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#description)), with the default export available as a key called `default`. In addition, the module namespace object has a [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property with the value `"Module"`, used in {{jsxref("Object.prototype.toString()")}}. The string properties are non-configurable and writable when you use {{jsxref("Object.getOwnPropertyDescriptors()")}} to get their descriptors. However, they are effectively read-only, because you cannot re-assign a property to a new value. This behavior mirrors the fact that static imports create "[live bindings](/en-US/docs/Web/JavaScript/Reference/Statements/import#imported_values_can_only_be_modified_by_the_exporter)" — the values can be re-assigned by the module exporting them, but not by the module importing them. The writability of the properties reflects the possibility of the values changing, because non-configurable and non-writable properties must be constant. For example, you can re-assign the exported value of a variable, and the new value can be observed in the module namespace object. diff --git a/files/en-us/web/javascript/reference/operators/in/index.md b/files/en-us/web/javascript/reference/operators/in/index.md index 0f2759acdeb3717..daa52846a525e35 100644 --- a/files/en-us/web/javascript/reference/operators/in/index.md +++ b/files/en-us/web/javascript/reference/operators/in/index.md @@ -241,7 +241,7 @@ p1.ageDifference(p2); // TypeError: Cannot read private member #age from an obje Without the `in` operator, you would have to use a `try...catch` block to check if the object has the private property. -You can also implement this as a [`@@hasInstance`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance) method of the class, so that you can use the [`instanceof`](/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) operator to perform the same check (which, by default, only checks for the existence of `Person.prototype` in the object's prototype chain). +You can also implement this as a [`[Symbol.hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance) method of the class, so that you can use the [`instanceof`](/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) operator to perform the same check (which, by default, only checks for the existence of `Person.prototype` in the object's prototype chain). ```js class Person { diff --git a/files/en-us/web/javascript/reference/operators/instanceof/index.md b/files/en-us/web/javascript/reference/operators/instanceof/index.md index 4e54da73a445e9b..62066fe241d6d03 100644 --- a/files/en-us/web/javascript/reference/operators/instanceof/index.md +++ b/files/en-us/web/javascript/reference/operators/instanceof/index.md @@ -27,7 +27,7 @@ object instanceof constructor ### Exceptions - {{jsxref("TypeError")}} - - : Thrown if `constructor` is not an object. If `constructor` doesn't have a [`@@hasInstance`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance) method, it must also be a function. + - : Thrown if `constructor` is not an object. If `constructor` doesn't have a [`[Symbol.hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance) method, it must also be a function. ## Description @@ -95,7 +95,7 @@ const BoundBase = Base.bind(null, 1, 2); console.log(new Base() instanceof BoundBase); // true ``` -### instanceof and @@hasInstance +### instanceof and Symbol.hasInstance If `constructor` has a [`Symbol.hasInstance`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance) method, the method will be called in priority, with `object` as its only argument and `constructor` as `this`. @@ -114,7 +114,7 @@ const obj = { [Forgeable.isInstanceFlag]: true }; console.log(obj instanceof Forgeable); // true ``` -Because all functions inherit from `Function.prototype` by default, most of the time, the [`Function.prototype[@@hasInstance]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance) method specifies the behavior of `instanceof` when the right-hand side is a function. See the {{jsxref("Symbol.hasInstance")}} page for the exact algorithm of `instanceof`. +Because all functions inherit from `Function.prototype` by default, most of the time, the [`Function.prototype[Symbol.hasInstance]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/@@hasInstance) method specifies the behavior of `instanceof` when the right-hand side is a function. See the {{jsxref("Symbol.hasInstance")}} page for the exact algorithm of `instanceof`. ### instanceof and multiple realms @@ -268,7 +268,7 @@ Note that you may want to limit this behavior to the current class; otherwise, i ```js class D extends C {} -console.log(new C() instanceof D); // true; because D inherits @@hasInstance from C +console.log(new C() instanceof D); // true; because D inherits [Symbol.hasInstance] from C ``` You could do this by checking that `this` is the current constructor: diff --git a/files/en-us/web/javascript/reference/operators/less_than/index.md b/files/en-us/web/javascript/reference/operators/less_than/index.md index 8e8f676b09f1892..edc4dd95da1ebe3 100644 --- a/files/en-us/web/javascript/reference/operators/less_than/index.md +++ b/files/en-us/web/javascript/reference/operators/less_than/index.md @@ -21,7 +21,7 @@ x < y The operands are compared with multiple rounds of coercion, which can be summarized as follows: -- First, objects are [converted to primitives](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) by calling its [`[@@toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"number"` as hint), [`valueOf()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf), and [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) methods, in that order. The left operand is always coerced before the right one. Note that although `[@@toPrimitive]()` is called with the `"number"` hint (meaning there's a slight preference for the object to become a number), the return value is not [converted to a number](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion), since strings are still specially handled. +- First, objects are [converted to primitives](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) by calling its [`[Symbol.toPrimitive]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) (with `"number"` as hint), [`valueOf()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf), and [`toString()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) methods, in that order. The left operand is always coerced before the right one. Note that although `[Symbol.toPrimitive]()` is called with the `"number"` hint (meaning there's a slight preference for the object to become a number), the return value is not [converted to a number](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion), since strings are still specially handled. - If both values are strings, they are compared as strings, based on the values of the UTF-16 code units (not Unicode code points) they contain. - Otherwise JavaScript attempts to convert non-numeric types to numeric values: - Boolean values `true` and `false` are converted to 1 and 0 respectively. diff --git a/files/en-us/web/javascript/reference/operators/yield_star_/index.md b/files/en-us/web/javascript/reference/operators/yield_star_/index.md index d78d78f2f5bc47c..d37b7ff5f7cb0e6 100644 --- a/files/en-us/web/javascript/reference/operators/yield_star_/index.md +++ b/files/en-us/web/javascript/reference/operators/yield_star_/index.md @@ -28,7 +28,7 @@ Returns the value returned by that iterator when it's closed (when `done` is `tr ## Description -The `yield*` expression iterates over the operand and yields each value returned by it. It delegates iteration of the current generator to an underlying iterator — which we will refer to as "generator" and "iterator", respectively. `yield*` first gets the iterator from the operand by calling the latter's [`@@iterator`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator) method. Then, each time the `next()` method of the generator is called, `yield*` calls the iterator's `next()` method, passing the argument received by the generator's `next()` method (always `undefined` for the first call), and yielding the same result object as what's returned from the iterator's `next()` method. If the iterator result has `done: true`, then the `yield*` expression stops executing and returns the `value` of that result. +The `yield*` expression iterates over the operand and yields each value returned by it. It delegates iteration of the current generator to an underlying iterator — which we will refer to as "generator" and "iterator", respectively. `yield*` first gets the iterator from the operand by calling the latter's [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator) method. Then, each time the `next()` method of the generator is called, `yield*` calls the iterator's `next()` method, passing the argument received by the generator's `next()` method (always `undefined` for the first call), and yielding the same result object as what's returned from the iterator's `next()` method. If the iterator result has `done: true`, then the `yield*` expression stops executing and returns the `value` of that result. The `yield*` operator forwards the current generator's {{jsxref("Generator/throw", "throw()")}} and {{jsxref("Generator/return", "return()")}} methods to the underlying iterator as well. If the current generator is prematurely closed through one of these methods, the underlying iterator will be notified. If the generator's `throw()`/`return()` method is called, the `throw()`/`return()` method of the underlying iterator is called with the same argument. The return value of `throw()`/`return()` is handled like the `next()` method's result, and if the method throws, the exception is propagated from the `yield*` expression. diff --git a/files/en-us/web/javascript/reference/statements/for-await...of/index.md b/files/en-us/web/javascript/reference/statements/for-await...of/index.md index e437846377f5600..4911b2f32fc70ff 100644 --- a/files/en-us/web/javascript/reference/statements/for-await...of/index.md +++ b/files/en-us/web/javascript/reference/statements/for-await...of/index.md @@ -27,7 +27,7 @@ for await (variable of iterable) ## Description -When a `for await...of` loop iterates over an iterable, it first gets the iterable's [`[@@asyncIterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator) method and calls it, which returns an [async iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols). If the `@asyncIterator` method does not exist, it then looks for an [`[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator) method, which returns a [sync iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol). The sync iterator returned is then wrapped into an async iterator by wrapping every object returned from the `next()`, `return()`, and `throw()` methods into a resolved or rejected promise, with the `value` property resolved if it's also a promise. The loop then repeatedly calls the final async iterator's [`next()`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol) method and [awaits](/en-US/docs/Web/JavaScript/Reference/Operators/await) the returned promise, producing the sequence of values to be assigned to `variable`. +When a `for await...of` loop iterates over an iterable, it first gets the iterable's [`[Symbol.asyncIterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator) method and calls it, which returns an [async iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols). If the `@asyncIterator` method does not exist, it then looks for an [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator) method, which returns a [sync iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol). The sync iterator returned is then wrapped into an async iterator by wrapping every object returned from the `next()`, `return()`, and `throw()` methods into a resolved or rejected promise, with the `value` property resolved if it's also a promise. The loop then repeatedly calls the final async iterator's [`next()`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol) method and [awaits](/en-US/docs/Web/JavaScript/Reference/Operators/await) the returned promise, producing the sequence of values to be assigned to `variable`. A `for await...of` loop exits when the iterator has completed (the awaited `next()` result is an object with `done: true`). Like other looping statements, you can use [control flow statements](/en-US/docs/Web/JavaScript/Reference/Statements#control_flow) inside `statement`: diff --git a/files/en-us/web/javascript/reference/statements/for...of/index.md b/files/en-us/web/javascript/reference/statements/for...of/index.md index c53379264373861..d7b6ac1d1781579 100644 --- a/files/en-us/web/javascript/reference/statements/for...of/index.md +++ b/files/en-us/web/javascript/reference/statements/for...of/index.md @@ -29,7 +29,7 @@ for (variable of iterable) A `for...of` loop operates on the values sourced from an iterable one by one in sequential order. Each operation of the loop on a value is called an _iteration_, and the loop is said to _iterate over the iterable_. Each iteration executes statements that may refer to the current sequence value. -When a `for...of` loop iterates over an iterable, it first calls the iterable's [`[@@iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator) method, which returns an [iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol), and then repeatedly calls the resulting iterator's [`next()`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol) method to produce the sequence of values to be assigned to `variable`. +When a `for...of` loop iterates over an iterable, it first calls the iterable's [`[Symbol.iterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator) method, which returns an [iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol), and then repeatedly calls the resulting iterator's [`next()`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol) method to produce the sequence of values to be assigned to `variable`. A `for...of` loop exits when the iterator has completed (the `next()` result is an object with `done: true`). Like other looping statements, you can use [control flow statements](/en-US/docs/Web/JavaScript/Reference/Statements#control_flow) inside `statement`: @@ -174,7 +174,7 @@ for (const paragraph of articleParagraphs) { ### Iterating over a user-defined iterable -Iterating over an object with an `@@iterator` method that returns a custom iterator: +Iterating over an object with an `[Symbol.iterator]()` method that returns a custom iterator: ```js const iterable = { @@ -199,7 +199,7 @@ for (const value of iterable) { // 3 ``` -Iterating over an object with an `@@iterator` generator method: +Iterating over an object with an `[Symbol.iterator]()` generator method: ```js const iterable = { @@ -218,7 +218,7 @@ for (const value of iterable) { // 3 ``` -_Iterable iterators_ (iterators with a `[@@iterator]()` method that returns `this`) are a fairly common technique to make iterators usable in syntaxes expecting iterables, such as `for...of`. +_Iterable iterators_ (iterators with a `[Symbol.iterator]()` method that returns `this`) are a fairly common technique to make iterators usable in syntaxes expecting iterables, such as `for...of`. ```js let i = 1; diff --git a/files/en-us/web/javascript/reference/statements/with/index.md b/files/en-us/web/javascript/reference/statements/with/index.md index 8d5502c27c70ce5..437753832dca5a8 100644 --- a/files/en-us/web/javascript/reference/statements/with/index.md +++ b/files/en-us/web/javascript/reference/statements/with/index.md @@ -59,7 +59,7 @@ with ([1, 2, 3]) { } ``` -The object may have an [`@@unscopables`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/unscopables) property, which defines a list of properties that should not be added to the scope chain (for backward compatibility). See the [`Symbol.unscopables`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/unscopables) documentation for more information. +The object may have an [`[Symbol.unscopables]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/unscopables) property, which defines a list of properties that should not be added to the scope chain (for backward compatibility). See the [`Symbol.unscopables`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/unscopables) documentation for more information. The reasons to use a `with` statement include saving one temporary variable and reducing file size by avoiding repeating a lengthy object reference. However, there are far more reasons why `with` statements are not desirable: @@ -88,7 +88,7 @@ The reasons to use a `with` statement include saving one temporary variable and If you call `f([1, 2, 3], obj)` in an ECMAScript 5 environment, the `values` reference inside the `with` statement will resolve to `obj`. However, ECMAScript 2015 introduces a [`values`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values) property on `Array.prototype` (so it will be available on every array). So, after upgrading the environment, the `values` reference inside the `with` statement resolves to `[1, 2, 3].values` instead, and is likely to cause bugs. - In this particular example, `values` is defined as unscopable through [`Array.prototype[@@unscopables]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@unscopables), so it still correctly resolves to the `values` parameter. If it were not defined as unscopable, one can see how this would be a difficult issue to debug. + In this particular example, `values` is defined as unscopable through [`Array.prototype[Symbol.unscopables]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@unscopables), so it still correctly resolves to the `values` parameter. If it were not defined as unscopable, one can see how this would be a difficult issue to debug. ## Examples @@ -175,4 +175,4 @@ with (namespace) { - {{jsxref("Statements/block", "block", "", 1)}} - [Strict mode](/en-US/docs/Web/JavaScript/Reference/Strict_mode) - {{jsxref("Symbol.unscopables")}} -- {{jsxref("Array/@@unscopables", "Array.prototype[@@unscopables]")}} +- {{jsxref("Array/@@unscopables", "Array.prototype[Symbol.unscopables]")}}