ArrayBuffer[Symbol.species]

Baseline Widely available

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

The ArrayBuffer[Symbol.species] static accessor property returns the constructor used to construct return values from array buffer methods.

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. Avoid relying on it if possible.

Syntax

js
ArrayBuffer[Symbol.species]

Return value

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 [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
class ArrayBuffer {
  static get [Symbol.species]() {
    return this;
  }
}

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()), 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 [Symbol.species] property returns the default constructor function, which is the ArrayBuffer constructor for ArrayBuffer.

js
ArrayBuffer[Symbol.species]; // function ArrayBuffer()

Species in derived objects

In an instance of a custom ArrayBuffer subclass, such as MyArrayBuffer, the MyArrayBuffer species is the MyArrayBuffer constructor. However, you might want to overwrite this, in order to return parent ArrayBuffer objects in your derived class methods:

js
class MyArrayBuffer extends ArrayBuffer {
  // Overwrite MyArrayBuffer species to the parent ArrayBuffer constructor
  static get [Symbol.species]() {
    return ArrayBuffer;
  }
}

Specifications

Specification
ECMAScript Language Specification
# sec-get-arraybuffer-%symbol.species%

Browser compatibility

BCD tables only load in the browser

See also