25 Structured Data

25.1 ArrayBuffer Objects

25.1.1 Notation

The descriptions below in this section, 25.4, and 29 use the read-modify-write modification function internal data structure.

A read-modify-write modification function is a mathematical function that is notationally represented as an abstract closure that takes two Lists of byte values as arguments and returns a List of byte values. These abstract closures satisfy all of the following properties:

  • They perform all their algorithm steps atomically.
  • Their individual algorithm steps are not observable.
Note

To aid verifying that a read-modify-write modification function's algorithm steps constitute a pure, mathematical function, the following editorial conventions are recommended:

  • They do not access, directly or transitively via invoked abstract operations and abstract closures, any language or specification values except their parameters and captured values.
  • They do not return Completion Records.

25.1.2 Abstract Operations For ArrayBuffer Objects

25.1.2.1 AllocateArrayBuffer ( constructor, byteLength )

The abstract operation AllocateArrayBuffer takes arguments constructor (a constructor) and byteLength (a non-negative integer) and returns either a normal completion containing an ArrayBuffer or a throw completion. It is used to create an ArrayBuffer. It performs the following steps when called:

  1. Let obj be ? OrdinaryCreateFromConstructor(constructor, "%ArrayBuffer.prototype%", « [[ArrayBufferData]], [[ArrayBufferByteLength]], [[ArrayBufferDetachKey]] »).
  2. Let block be ? CreateByteDataBlock(byteLength).
  3. Set obj.[[ArrayBufferData]] to block.
  4. Set obj.[[ArrayBufferByteLength]] to byteLength.
  5. Return obj.

25.1.2.2 IsDetachedBuffer ( arrayBuffer )

The abstract operation IsDetachedBuffer takes argument arrayBuffer (an ArrayBuffer or a SharedArrayBuffer) and returns a Boolean. It performs the following steps when called:

  1. If arrayBuffer.[[ArrayBufferData]] is null, return true.
  2. Return false.

25.1.2.3 DetachArrayBuffer ( arrayBuffer [ , key ] )

The abstract operation DetachArrayBuffer takes argument arrayBuffer (an ArrayBuffer) and optional argument key (anything) and returns either a normal completion containing unused or a throw completion. It performs the following steps when called:

  1. Assert: IsSharedArrayBuffer(arrayBuffer) is false.
  2. If key is not present, set key to undefined.
  3. If arrayBuffer.[[ArrayBufferDetachKey]] is not key, throw a TypeError exception.
  4. Set arrayBuffer.[[ArrayBufferData]] to null.
  5. Set arrayBuffer.[[ArrayBufferByteLength]] to 0.
  6. Return unused.
 Note

Detaching an ArrayBuffer instance disassociates the Data Block used as its backing store from the instance and sets the byte length of the buffer to 0. No operations defined by this specification use the DetachArrayBuffer abstract operation. However, an ECMAScript host or implementation may define such operations.

25.1.2.4 CloneArrayBuffer ( srcBuffer, srcByteOffset, srcLength )

The abstract operation CloneArrayBuffer takes arguments srcBuffer (an ArrayBuffer or a SharedArrayBuffer), srcByteOffset (a non-negative integer), and srcLength (a non-negative integer) and returns either a normal completion containing an ArrayBuffer or a throw completion. It creates a new ArrayBuffer whose data is a copy of srcBuffer's data over the range starting at srcByteOffset and continuing for srcLength bytes. It performs the following steps when called:

  1. Assert: IsDetachedBuffer(srcBuffer) is false.
  2. Let targetBuffer be ? AllocateArrayBuffer(%ArrayBuffer%, srcLength).
  3. Let srcBlock be srcBuffer.[[ArrayBufferData]].
  4. Let targetBlock be targetBuffer.[[ArrayBufferData]].
  5. Perform CopyDataBlockBytes(targetBlock, 0, srcBlock, srcByteOffset, srcLength).
  6. Return targetBuffer.

25.1.2.5 IsUnsignedElementType ( type )

The abstract operation IsUnsignedElementType takes argument type (a TypedArray element type) and returns a Boolean. It verifies if the argument type is an unsigned TypedArray element type. It performs the following steps when called:

  1. If type is one of Uint8, Uint8C, Uint16, Uint32, or BigUint64, return true.
  2. Return false.

25.1.2.6 IsUnclampedIntegerElementType ( type )

The abstract operation IsUnclampedIntegerElementType takes argument type (a TypedArray element type) and returns a Boolean. It verifies if the argument type is an Integer TypedArray element type not including Uint8C. It performs the following steps when called:

  1. If type is one of Int8, Uint8, Int16, Uint16, Int32, or Uint32, return true.
  2. Return false.

25.1.2.7 IsBigIntElementType ( type )

The abstract operation IsBigIntElementType takes argument type (a TypedArray element type) and returns a Boolean. It verifies if the argument type is a BigInt TypedArray element type. It performs the following steps when called:

  1. If type is either BigUint64 or BigInt64, return true.
  2. Return false.

25.1.2.8 IsNoTearConfiguration ( type, order )

The abstract operation IsNoTearConfiguration takes arguments type (a TypedArray element type) and order (SeqCst, Unordered, or Init) and returns a Boolean. It performs the following steps when called:

  1. If IsUnclampedIntegerElementType(type) is true, return true.
  2. If IsBigIntElementType(type) is true and order is neither Init nor Unordered, return true.
  3. Return false.

25.1.2.9 RawBytesToNumeric ( type, rawBytes, isLittleEndian )

The abstract operation RawBytesToNumeric takes arguments type (a TypedArray element type), rawBytes (a List of byte values), and isLittleEndian (a Boolean) and returns a Number or a BigInt. It performs the following steps when called:

  1. Let elementSize be the Element Size value specified in Table 68 for Element Type type.
  2. If isLittleEndian is false, reverse the order of the elements of rawBytes.
  3. If type is Float32, then
    1. Let value be the byte elements of rawBytes concatenated and interpreted as a little-endian bit string encoding of an IEEE 754-2019 binary32 value.
    2. If value is an IEEE 754-2019 binary32 NaN value, return the NaN Number value.
    3. Return the Number value that corresponds to value.
  4. If type is Float64, then
    1. Let value be the byte elements of rawBytes concatenated and interpreted as a little-endian bit string encoding of an IEEE 754-2019 binary64 value.
    2. If value is an IEEE 754-2019 binary64 NaN value, return the NaN Number value.
    3. Return the Number value that corresponds to value.
  5. If IsUnsignedElementType(type) is true, then
    1. Let intValue be the byte elements of rawBytes concatenated and interpreted as a bit string encoding of an unsigned little-endian binary number.
  6. Else,
    1. Let intValue be the byte elements of rawBytes concatenated and interpreted as a bit string encoding of a binary little-endian two's complement number of bit length elementSize × 8.
  7. If IsBigIntElementType(type) is true, return the BigInt value that corresponds to intValue.
  8. Otherwise, return the Number value that corresponds to intValue.

25.1.2.10 GetValueFromBuffer ( arrayBuffer, byteIndex, type, isTypedArray, order [ , isLittleEndian ] )

The abstract operation GetValueFromBuffer takes arguments arrayBuffer (an ArrayBuffer or SharedArrayBuffer), byteIndex (a non-negative integer), type (a TypedArray element type), isTypedArray (a Boolean), and order (SeqCst or Unordered) and optional argument isLittleEndian (a Boolean) and returns a Number or a BigInt. It performs the following steps when called:

  1. Assert: IsDetachedBuffer(arrayBuffer) is false.
  2. Assert: There are sufficient bytes in arrayBuffer starting at byteIndex to represent a value of type.
  3. Let block be arrayBuffer.[[ArrayBufferData]].
  4. Let elementSize be the Element Size value specified in Table 68 for Element Type type.
  5. If IsSharedArrayBuffer(arrayBuffer) is true, then
    1. Let execution be the [[CandidateExecution]] field of the surrounding agent's Agent Record.
    2. Let eventsRecord be the Agent Events Record of execution.[[EventsRecords]] whose [[AgentSignifier]] is AgentSignifier().
    3. If isTypedArray is true and IsNoTearConfiguration(type, order) is true, let noTear be true; otherwise let noTear be false.
    4. Let rawValue be a List of length elementSize whose elements are nondeterministically chosen byte values.
    5. NOTE: In implementations, rawValue is the result of a non-atomic or atomic read instruction on the underlying hardware. The nondeterminism is a semantic prescription of the memory model to describe observable behaviour of hardware with weak consistency.
    6. Let readEvent be ReadSharedMemory { [[Order]]: order, [[NoTear]]: noTear, [[Block]]: block, [[ByteIndex]]: byteIndex, [[ElementSize]]: elementSize }.
    7. Append readEvent to eventsRecord.[[EventList]].
    8. Append Chosen Value Record { [[Event]]: readEvent, [[ChosenValue]]: rawValue } to execution.[[ChosenValues]].
  6. Else, let rawValue be a List whose elements are bytes from block at indices in the interval from byteIndex (inclusive) to byteIndex + elementSize (exclusive).
  7. Assert: The number of elements in rawValue is elementSize.
  8. If isLittleEndian is not present, set isLittleEndian to the value of the [[LittleEndian]] field of the surrounding agent's Agent Record.
  9. Return RawBytesToNumeric(type, rawValue, isLittleEndian).

25.1.2.11 NumericToRawBytes ( type, value, isLittleEndian )

The abstract operation NumericToRawBytes takes arguments type (a TypedArray element type), value (a Number or a BigInt), and isLittleEndian (a Boolean) and returns a List of byte values. It performs the following steps when called:

  1. If type is Float32, then
    1. Let rawBytes be a List whose elements are the 4 bytes that are the result of converting value to IEEE 754-2019 binary32 format using roundTiesToEven mode. The bytes are arranged in little endian order. If value is NaN, rawBytes may be set to any implementation chosen IEEE 754-2019 binary32 format Not-a-Number encoding. An implementation must always choose the same encoding for each implementation distinguishable NaN value.
  2. Else if type is Float64, then
    1. Let rawBytes be a List whose elements are the 8 bytes that are the IEEE 754-2019 binary64 format encoding of value. The bytes are arranged in little endian order. If value is NaN, rawBytes may be set to any implementation chosen IEEE 754-2019 binary64 format Not-a-Number encoding. An implementation must always choose the same encoding for each implementation distinguishable NaN value.
  3. Else,
    1. Let n be the Element Size value specified in Table 68 for Element Type type.
    2. Let convOp be the abstract operation named in the Conversion Operation column in Table 68 for Element Type type.
    3. Let intValue be ℝ(convOp(value)).
    4. If intValue ≥ 0, then
      1. Let rawBytes be a List whose elements are the n-byte binary encoding of intValue. The bytes are ordered in little endian order.
    5. Else,
      1. Let rawBytes be a List whose elements are the n-byte binary two's complement encoding of intValue. The bytes are ordered in little endian order.
  4. If isLittleEndian is false, reverse the order of the elements of rawBytes.
  5. Return rawBytes.

25.1.2.12 SetValueInBuffer ( arrayBuffer, byteIndex, type, value, isTypedArray, order [ , isLittleEndian ] )

The abstract operation SetValueInBuffer takes arguments arrayBuffer (an ArrayBuffer or SharedArrayBuffer), byteIndex (a non-negative integer), type (a TypedArray element type), value (a Number or a BigInt), isTypedArray (a Boolean), and order (SeqCst, Unordered, or Init) and optional argument isLittleEndian (a Boolean) and returns unused. It performs the following steps when called:

  1. Assert: IsDetachedBuffer(arrayBuffer) is false.
  2. Assert: There are sufficient bytes in arrayBuffer starting at byteIndex to represent a value of type.
  3. Assert: value is a BigInt if IsBigIntElementType(type) is true; otherwise, value is a Number.
  4. Let block be arrayBuffer.[[ArrayBufferData]].
  5. Let elementSize be the Element Size value specified in Table 68 for Element Type type.
  6. If isLittleEndian is not present, set isLittleEndian to the value of the [[LittleEndian]] field of the surrounding agent's Agent Record.
  7. Let rawBytes be NumericToRawBytes(type, value, isLittleEndian).
  8. If IsSharedArrayBuffer(arrayBuffer) is true, then
    1. Let execution be the [[CandidateExecution]] field of the surrounding agent's Agent Record.
    2. Let eventsRecord be the Agent Events Record of execution.[[EventsRecords]] whose [[AgentSignifier]] is AgentSignifier().
    3. If isTypedArray is true and IsNoTearConfiguration(type, order) is true, let noTear be true; otherwise let noTear be false.
    4. Append WriteSharedMemory { [[Order]]: order, [[NoTear]]: noTear, [[Block]]: block, [[ByteIndex]]: byteIndex, [[ElementSize]]: elementSize, [[Payload]]: rawBytes } to eventsRecord.[[EventList]].
  9. Else, store the individual bytes of rawBytes into block, starting at block[byteIndex].
  10. Return unused.

25.1.2.13 GetModifySetValueInBuffer ( arrayBuffer, byteIndex, type, value, op [ , isLittleEndian ] )

The abstract operation GetModifySetValueInBuffer takes arguments arrayBuffer (an ArrayBuffer or a SharedArrayBuffer), byteIndex (a non-negative integer), type (a TypedArray element type), value (a Number or a BigInt), and op (a read-modify-write modification function) and optional argument isLittleEndian (a Boolean) and returns a Number or a BigInt. It performs the following steps when called:

  1. Assert: IsDetachedBuffer(arrayBuffer) is false.
  2. Assert: There are sufficient bytes in arrayBuffer starting at byteIndex to represent a value of type.
  3. Assert: value is a BigInt if IsBigIntElementType(type) is true; otherwise, value is a Number.
  4. Let block be arrayBuffer.[[ArrayBufferData]].
  5. Let elementSize be the Element Size value specified in Table 68 for Element Type type.
  6. If isLittleEndian is not present, set isLittleEndian to the value of the [[LittleEndian]] field of the surrounding agent's Agent Record.
  7. Let rawBytes be NumericToRawBytes(type, value, isLittleEndian).
  8. If IsSharedArrayBuffer(arrayBuffer) is true, then
    1. Let execution be the [[CandidateExecution]] field of the surrounding agent's Agent Record.
    2. Let eventsRecord be the Agent Events Record of execution.[[EventsRecords]] whose [[AgentSignifier]] is AgentSignifier().
    3. Let rawBytesRead be a List of length elementSize whose elements are nondeterministically chosen byte values.
    4. NOTE: In implementations, rawBytesRead is the result of a load-link, of a load-exclusive, or of an operand of a read-modify-write instruction on the underlying hardware. The nondeterminism is a semantic prescription of the memory model to describe observable behaviour of hardware with weak consistency.
    5. Let rmwEvent be ReadModifyWriteSharedMemory { [[Order]]: SeqCst, [[NoTear]]: true, [[Block]]: block, [[ByteIndex]]: byteIndex, [[ElementSize]]: elementSize, [[Payload]]: rawBytes, [[ModifyOp]]: op }.
    6. Append rmwEvent to eventsRecord.[[EventList]].
    7. Append Chosen Value Record { [[Event]]: rmwEvent, [[ChosenValue]]: rawBytesRead } to execution.[[ChosenValues]].
  9. Else,
    1. Let rawBytesRead be a List of length elementSize whose elements are the sequence of elementSize bytes starting with block[byteIndex].
    2. Let rawBytesModified be op(rawBytesRead, rawBytes).
    3. Store the individual bytes of rawBytesModified into block, starting at block[byteIndex].
  10. Return RawBytesToNumeric(type, rawBytesRead, isLittleEndian).

25.1.3 The ArrayBuffer Constructor

The ArrayBuffer constructor:

  • is %ArrayBuffer%.
  • is the initial value of the "ArrayBuffer" property of the global object.
  • creates and initializes a new ArrayBuffer when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified ArrayBuffer behaviour must include a super call to the ArrayBuffer constructor to create and initialize subclass instances with the internal state necessary to support the ArrayBuffer.prototype built-in methods.

25.1.3.1 ArrayBuffer ( length )

This function performs the following steps when called:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let byteLength be ? ToIndex(length).
  3. Return ? AllocateArrayBuffer(NewTarget, byteLength).

25.1.4 Properties of the ArrayBuffer Constructor

The ArrayBuffer constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has the following properties:

25.1.4.1 ArrayBuffer.isView ( arg )

This function performs the following steps when called:

  1. If arg is not an Object, return false.
  2. If arg has a [[ViewedArrayBuffer]] internal slot, return true.
  3. Return false.

25.1.4.2 ArrayBuffer.prototype

The initial value of ArrayBuffer.prototype is the ArrayBuffer prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

25.1.4.3 get ArrayBuffer [ @@species ]

ArrayBuffer[@@species] is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Return the this value.

The value of the "name" property of this function is "get [Symbol.species]".

Note

ArrayBuffer prototype methods normally use their this value's constructor to create a derived object. However, a subclass constructor may over-ride that default behaviour by redefining its @@species property.

25.1.5 Properties of the ArrayBuffer Prototype Object

The ArrayBuffer prototype object:

  • is %ArrayBuffer.prototype%.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is an ordinary object.
  • does not have an [[ArrayBufferData]] or [[ArrayBufferByteLength]] internal slot.

25.1.5.1 get ArrayBuffer.prototype.byteLength

ArrayBuffer.prototype.byteLength is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[ArrayBufferData]]).
  3. If IsSharedArrayBuffer(O) is true, throw a TypeError exception.
  4. If IsDetachedBuffer(O) is true, return +0𝔽.
  5. Let length be O.[[ArrayBufferByteLength]].
  6. Return 𝔽(length).

25.1.5.2 ArrayBuffer.prototype.constructor

The initial value of ArrayBuffer.prototype.constructor is %ArrayBuffer%.

25.1.5.3 ArrayBuffer.prototype.slice ( start, end )

This method performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[ArrayBufferData]]).
  3. If IsSharedArrayBuffer(O) is true, throw a TypeError exception.
  4. If IsDetachedBuffer(O) is true, throw a TypeError exception.
  5. Let len be O.[[ArrayBufferByteLength]].
  6. Let relativeStart be ? ToIntegerOrInfinity(start).
  7. If relativeStart = -∞, let first be 0.
  8. Else if relativeStart < 0, let first be max(len + relativeStart, 0).
  9. Else, let first be min(relativeStart, len).
  10. If end is undefined, let relativeEnd be len; else let relativeEnd be ? ToIntegerOrInfinity(end).
  11. If relativeEnd = -∞, let final be 0.
  12. Else if relativeEnd < 0, let final be max(len + relativeEnd, 0).
  13. Else, let final be min(relativeEnd, len).
  14. Let newLen be max(final - first, 0).
  15. Let ctor be ? SpeciesConstructor(O, %ArrayBuffer%).
  16. Let new be ? Construct(ctor, « 𝔽(newLen) »).
  17. Perform ? RequireInternalSlot(new, [[ArrayBufferData]]).
  18. If IsSharedArrayBuffer(new) is true, throw a TypeError exception.
  19. If IsDetachedBuffer(new) is true, throw a TypeError exception.
  20. If SameValue(new, O) is true, throw a TypeError exception.
  21. If new.[[ArrayBufferByteLength]] < newLen, throw a TypeError exception.
  22. NOTE: Side-effects of the above steps may have detached O.
  23. If IsDetachedBuffer(O) is true, throw a TypeError exception.
  24. Let fromBuf be O.[[ArrayBufferData]].
  25. Let toBuf be new.[[ArrayBufferData]].
  26. Perform CopyDataBlockBytes(toBuf, 0, fromBuf, first, newLen).
  27. Return new.

25.1.5.4 ArrayBuffer.prototype [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "ArrayBuffer".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

25.1.6 Properties of ArrayBuffer Instances

ArrayBuffer instances inherit properties from the ArrayBuffer prototype object. ArrayBuffer instances each have an [[ArrayBufferData]] internal slot, an [[ArrayBufferByteLength]] internal slot, and an [[ArrayBufferDetachKey]] internal slot.

ArrayBuffer instances whose [[ArrayBufferData]] is null are considered to be detached and all operators to access or modify data contained in the ArrayBuffer instance will fail.

ArrayBuffer instances whose [[ArrayBufferDetachKey]] is set to a value other than undefined need to have all DetachArrayBuffer calls passing that same "detach key" as an argument, otherwise a TypeError will result. This internal slot is only ever set by certain embedding environments, not by algorithms in this specification.

25.2 SharedArrayBuffer Objects

25.2.1 Abstract Operations for SharedArrayBuffer Objects

25.2.1.1 AllocateSharedArrayBuffer ( constructor, byteLength )

The abstract operation AllocateSharedArrayBuffer takes arguments constructor (a constructor) and byteLength (a non-negative integer) and returns either a normal completion containing a SharedArrayBuffer or a throw completion. It is used to create a SharedArrayBuffer. It performs the following steps when called:

  1. Let obj be ? OrdinaryCreateFromConstructor(constructor, "%SharedArrayBuffer.prototype%", « [[ArrayBufferData]], [[ArrayBufferByteLength]] »).
  2. Let block be ? CreateSharedByteDataBlock(byteLength).
  3. Set obj.[[ArrayBufferData]] to block.
  4. Set obj.[[ArrayBufferByteLength]] to byteLength.
  5. Return obj.

25.2.1.2 IsSharedArrayBuffer ( obj )

The abstract operation IsSharedArrayBuffer takes argument obj (an ArrayBuffer or a SharedArrayBuffer) and returns a Boolean. It tests whether an object is an ArrayBuffer, a SharedArrayBuffer, or a subtype of either. It performs the following steps when called:

  1. Let bufferData be obj.[[ArrayBufferData]].
  2. If bufferData is null, return false.
  3. If bufferData is a Data Block, return false.
  4. Assert: bufferData is a Shared Data Block.
  5. Return true.

25.2.2 The SharedArrayBuffer Constructor

The SharedArrayBuffer constructor:

  • is %SharedArrayBuffer%.
  • is the initial value of the "SharedArrayBuffer" property of the global object, if that property is present (see below).
  • creates and initializes a new SharedArrayBuffer when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified SharedArrayBuffer behaviour must include a super call to the SharedArrayBuffer constructor to create and initialize subclass instances with the internal state necessary to support the SharedArrayBuffer.prototype built-in methods.

Whenever a host does not provide concurrent access to SharedArrayBuffers it may omit the "SharedArrayBuffer" property of the global object.

Note

Unlike an ArrayBuffer, a SharedArrayBuffer cannot become detached, and its internal [[ArrayBufferData]] slot is never null.

25.2.2.1 SharedArrayBuffer ( length )

This function performs the following steps when called:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let byteLength be ? ToIndex(length).
  3. Return ? AllocateSharedArrayBuffer(NewTarget, byteLength).

25.2.3 Properties of the SharedArrayBuffer Constructor

The SharedArrayBuffer constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has the following properties:

25.2.3.1 SharedArrayBuffer.prototype

The initial value of SharedArrayBuffer.prototype is the SharedArrayBuffer prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

25.2.3.2 get SharedArrayBuffer [ @@species ]

SharedArrayBuffer[@@species] is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Return the this value.

The value of the "name" property of this function is "get [Symbol.species]".

25.2.4 Properties of the SharedArrayBuffer Prototype Object

The SharedArrayBuffer prototype object:

  • is %SharedArrayBuffer.prototype%.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is an ordinary object.
  • does not have an [[ArrayBufferData]] or [[ArrayBufferByteLength]] internal slot.

25.2.4.1 get SharedArrayBuffer.prototype.byteLength

SharedArrayBuffer.prototype.byteLength is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[ArrayBufferData]]).
  3. If IsSharedArrayBuffer(O) is false, throw a TypeError exception.
  4. Let length be O.[[ArrayBufferByteLength]].
  5. Return 𝔽(length).

25.2.4.2 SharedArrayBuffer.prototype.constructor

The initial value of SharedArrayBuffer.prototype.constructor is %SharedArrayBuffer%.

25.2.4.3 SharedArrayBuffer.prototype.slice ( start, end )

This method performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[ArrayBufferData]]).
  3. If IsSharedArrayBuffer(O) is false, throw a TypeError exception.
  4. Let len be O.[[ArrayBufferByteLength]].
  5. Let relativeStart be ? ToIntegerOrInfinity(start).
  6. If relativeStart = -∞, let first be 0.
  7. Else if relativeStart < 0, let first be max(len + relativeStart, 0).
  8. Else, let first be min(relativeStart, len).
  9. If end is undefined, let relativeEnd be len; else let relativeEnd be ? ToIntegerOrInfinity(end).
  10. If relativeEnd = -∞, let final be 0.
  11. Else if relativeEnd < 0, let final be max(len + relativeEnd, 0).
  12. Else, let final be min(relativeEnd, len).
  13. Let newLen be max(final - first, 0).
  14. Let ctor be ? SpeciesConstructor(O, %SharedArrayBuffer%).
  15. Let new be ? Construct(ctor, « 𝔽(newLen) »).
  16. Perform ? RequireInternalSlot(new, [[ArrayBufferData]]).
  17. If IsSharedArrayBuffer(new) is false, throw a TypeError exception.
  18. If new.[[ArrayBufferData]] is O.[[ArrayBufferData]], throw a TypeError exception.
  19. If new.[[ArrayBufferByteLength]] < newLen, throw a TypeError exception.
  20. Let fromBuf be O.[[ArrayBufferData]].
  21. Let toBuf be new.[[ArrayBufferData]].
  22. Perform CopyDataBlockBytes(toBuf, 0, fromBuf, first, newLen).
  23. Return new.

25.2.4.4 SharedArrayBuffer.prototype [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "SharedArrayBuffer".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

25.2.5 Properties of SharedArrayBuffer Instances

SharedArrayBuffer instances inherit properties from the SharedArrayBuffer prototype object. SharedArrayBuffer instances each have an [[ArrayBufferData]] internal slot and an [[ArrayBufferByteLength]] internal slot.

Note

SharedArrayBuffer instances, unlike ArrayBuffer instances, are never detached.

25.3 DataView Objects

25.3.1 Abstract Operations For DataView Objects

25.3.1.1 GetViewValue ( view, requestIndex, isLittleEndian, type )

The abstract operation GetViewValue takes arguments view (an ECMAScript language value), requestIndex (an ECMAScript language value), isLittleEndian (an ECMAScript language value), and type (a TypedArray element type) and returns either a normal completion containing either a Number or a BigInt, or a throw completion. It is used by functions on DataView instances to retrieve values from the view's buffer. It performs the following steps when called:

  1. Perform ? RequireInternalSlot(view, [[DataView]]).
  2. Assert: view has a [[ViewedArrayBuffer]] internal slot.
  3. Let getIndex be ? ToIndex(requestIndex).
  4. Set isLittleEndian to ToBoolean(isLittleEndian).
  5. Let buffer be view.[[ViewedArrayBuffer]].
  6. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  7. Let viewOffset be view.[[ByteOffset]].
  8. Let viewSize be view.[[ByteLength]].
  9. Let elementSize be the Element Size value specified in Table 68 for Element Type type.
  10. If getIndex + elementSize > viewSize, throw a RangeError exception.
  11. Let bufferIndex be getIndex + viewOffset.
  12. Return GetValueFromBuffer(buffer, bufferIndex, type, false, Unordered, isLittleEndian).

25.3.1.2 SetViewValue ( view, requestIndex, isLittleEndian, type, value )

The abstract operation SetViewValue takes arguments view (an ECMAScript language value), requestIndex (an ECMAScript language value), isLittleEndian (an ECMAScript language value), type (a TypedArray element type), and value (an ECMAScript language value) and returns either a normal completion containing undefined or a throw completion. It is used by functions on DataView instances to store values into the view's buffer. It performs the following steps when called:

  1. Perform ? RequireInternalSlot(view, [[DataView]]).
  2. Assert: view has a [[ViewedArrayBuffer]] internal slot.
  3. Let getIndex be ? ToIndex(requestIndex).
  4. If IsBigIntElementType(type) is true, let numberValue be ? ToBigInt(value).
  5. Otherwise, let numberValue be ? ToNumber(value).
  6. Set isLittleEndian to ToBoolean(isLittleEndian).
  7. Let buffer be view.[[ViewedArrayBuffer]].
  8. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  9. Let viewOffset be view.[[ByteOffset]].
  10. Let viewSize be view.[[ByteLength]].
  11. Let elementSize be the Element Size value specified in Table 68 for Element Type type.
  12. If getIndex + elementSize > viewSize, throw a RangeError exception.
  13. Let bufferIndex be getIndex + viewOffset.
  14. Perform SetValueInBuffer(buffer, bufferIndex, type, numberValue, false, Unordered, isLittleEndian).
  15. Return undefined.

25.3.2 The DataView Constructor

The DataView constructor:

  • is %DataView%.
  • is the initial value of the "DataView" property of the global object.
  • creates and initializes a new DataView when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified DataView behaviour must include a super call to the DataView constructor to create and initialize subclass instances with the internal state necessary to support the DataView.prototype built-in methods.

25.3.2.1 DataView ( buffer [ , byteOffset [ , byteLength ] ] )

This function performs the following steps when called:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Perform ? RequireInternalSlot(buffer, [[ArrayBufferData]]).
  3. Let offset be ? ToIndex(byteOffset).
  4. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  5. Let bufferByteLength be buffer.[[ArrayBufferByteLength]].
  6. If offset > bufferByteLength, throw a RangeError exception.
  7. If byteLength is undefined, then
    1. Let viewByteLength be bufferByteLength - offset.
  8. Else,
    1. Let viewByteLength be ? ToIndex(byteLength).
    2. If offset + viewByteLength > bufferByteLength, throw a RangeError exception.
  9. Let O be ? OrdinaryCreateFromConstructor(NewTarget, "%DataView.prototype%", « [[DataView]], [[ViewedArrayBuffer]], [[ByteLength]], [[ByteOffset]] »).
  10. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  11. Set O.[[ViewedArrayBuffer]] to buffer.
  12. Set O.[[ByteLength]] to viewByteLength.
  13. Set O.[[ByteOffset]] to offset.
  14. Return O.

25.3.3 Properties of the DataView Constructor

The DataView constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has the following properties:

25.3.3.1 DataView.prototype

The initial value of DataView.prototype is the DataView prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

25.3.4 Properties of the DataView Prototype Object

The DataView prototype object:

  • is %DataView.prototype%.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is an ordinary object.
  • does not have a [[DataView]], [[ViewedArrayBuffer]], [[ByteLength]], or [[ByteOffset]] internal slot.

25.3.4.1 get DataView.prototype.buffer

DataView.prototype.buffer is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[DataView]]).
  3. Assert: O has a [[ViewedArrayBuffer]] internal slot.
  4. Let buffer be O.[[ViewedArrayBuffer]].
  5. Return buffer.

25.3.4.2 get DataView.prototype.byteLength

DataView.prototype.byteLength is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[DataView]]).
  3. Assert: O has a [[ViewedArrayBuffer]] internal slot.
  4. Let buffer be O.[[ViewedArrayBuffer]].
  5. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  6. Let size be O.[[ByteLength]].
  7. Return 𝔽(size).

25.3.4.3 get DataView.prototype.byteOffset

DataView.prototype.byteOffset is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[DataView]]).
  3. Assert: O has a [[ViewedArrayBuffer]] internal slot.
  4. Let buffer be O.[[ViewedArrayBuffer]].
  5. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  6. Let offset be O.[[ByteOffset]].
  7. Return 𝔽(offset).

25.3.4.4 DataView.prototype.constructor

The initial value of DataView.prototype.constructor is %DataView%.

25.3.4.5 DataView.prototype.getBigInt64 ( byteOffset [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. Return ? GetViewValue(v, byteOffset, littleEndian, BigInt64).

25.3.4.6 DataView.prototype.getBigUint64 ( byteOffset [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. Return ? GetViewValue(v, byteOffset, littleEndian, BigUint64).

25.3.4.7 DataView.prototype.getFloat32 ( byteOffset [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? GetViewValue(v, byteOffset, littleEndian, Float32).

25.3.4.8 DataView.prototype.getFloat64 ( byteOffset [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? GetViewValue(v, byteOffset, littleEndian, Float64).

25.3.4.9 DataView.prototype.getInt8 ( byteOffset )

This method performs the following steps when called:

  1. Let v be the this value.
  2. Return ? GetViewValue(v, byteOffset, true, Int8).

25.3.4.10 DataView.prototype.getInt16 ( byteOffset [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? GetViewValue(v, byteOffset, littleEndian, Int16).

25.3.4.11 DataView.prototype.getInt32 ( byteOffset [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? GetViewValue(v, byteOffset, littleEndian, Int32).

25.3.4.12 DataView.prototype.getUint8 ( byteOffset )

This method performs the following steps when called:

  1. Let v be the this value.
  2. Return ? GetViewValue(v, byteOffset, true, Uint8).

25.3.4.13 DataView.prototype.getUint16 ( byteOffset [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? GetViewValue(v, byteOffset, littleEndian, Uint16).

25.3.4.14 DataView.prototype.getUint32 ( byteOffset [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? GetViewValue(v, byteOffset, littleEndian, Uint32).

25.3.4.15 DataView.prototype.setBigInt64 ( byteOffset, value [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. Return ? SetViewValue(v, byteOffset, littleEndian, BigInt64, value).

25.3.4.16 DataView.prototype.setBigUint64 ( byteOffset, value [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. Return ? SetViewValue(v, byteOffset, littleEndian, BigUint64, value).

25.3.4.17 DataView.prototype.setFloat32 ( byteOffset, value [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? SetViewValue(v, byteOffset, littleEndian, Float32, value).

25.3.4.18 DataView.prototype.setFloat64 ( byteOffset, value [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? SetViewValue(v, byteOffset, littleEndian, Float64, value).

25.3.4.19 DataView.prototype.setInt8 ( byteOffset, value )

This method performs the following steps when called:

  1. Let v be the this value.
  2. Return ? SetViewValue(v, byteOffset, true, Int8, value).

25.3.4.20 DataView.prototype.setInt16 ( byteOffset, value [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? SetViewValue(v, byteOffset, littleEndian, Int16, value).

25.3.4.21 DataView.prototype.setInt32 ( byteOffset, value [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? SetViewValue(v, byteOffset, littleEndian, Int32, value).

25.3.4.22 DataView.prototype.setUint8 ( byteOffset, value )

This method performs the following steps when called:

  1. Let v be the this value.
  2. Return ? SetViewValue(v, byteOffset, true, Uint8, value).

25.3.4.23 DataView.prototype.setUint16 ( byteOffset, value [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? SetViewValue(v, byteOffset, littleEndian, Uint16, value).

25.3.4.24 DataView.prototype.setUint32 ( byteOffset, value [ , littleEndian ] )

This method performs the following steps when called:

  1. Let v be the this value.
  2. If littleEndian is not present, set littleEndian to false.
  3. Return ? SetViewValue(v, byteOffset, littleEndian, Uint32, value).

25.3.4.25 DataView.prototype [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "DataView".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

25.3.5 Properties of DataView Instances

DataView instances are ordinary objects that inherit properties from the DataView prototype object. DataView instances each have [[DataView]], [[ViewedArrayBuffer]], [[ByteLength]], and [[ByteOffset]] internal slots.

Note

The value of the [[DataView]] internal slot is not used within this specification. The simple presence of that internal slot is used within the specification to identify objects created using the DataView constructor.

25.4 The Atomics Object

The Atomics object:

  • is %Atomics%.
  • is the initial value of the "Atomics" property of the global object.
  • is an ordinary object.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • does not have a [[Construct]] internal method; it cannot be used as a constructor with the new operator.
  • does not have a [[Call]] internal method; it cannot be invoked as a function.

The Atomics object provides functions that operate indivisibly (atomically) on shared memory array cells as well as functions that let agents wait for and dispatch primitive events. When used with discipline, the Atomics functions allow multi-agent programs that communicate through shared memory to execute in a well-understood order even on parallel CPUs. The rules that govern shared-memory communication are provided by the memory model, defined below.

Note

For informative guidelines for programming and implementing shared memory in ECMAScript, please see the notes at the end of the memory model section.

25.4.1 WaiterList Objects

A WaiterList is a semantic object that contains an ordered list of agent signifiers for those agents that are waiting on a location (block, i) in shared memory; block is a Shared Data Block and i a byte offset into the memory of block. A WaiterList object also optionally contains a Synchronize event denoting the previous leaving of its critical section.

Initially a WaiterList object has an empty list and no Synchronize event.

The agent cluster has a store of WaiterList objects; the store is indexed by (block, i). WaiterLists are agent-independent: a lookup in the store of WaiterLists by (block, i) will result in the same WaiterList object in any agent in the agent cluster.

Each WaiterList has a critical section that controls exclusive access to that WaiterList during evaluation. Only a single agent may enter a WaiterList's critical section at one time. Entering and leaving a WaiterList's critical section is controlled by the abstract operations EnterCriticalSection and LeaveCriticalSection. Operations on a WaiterList—adding and removing waiting agents, traversing the list of agents, suspending and notifying agents on the list, setting and retrieving the Synchronize event—may only be performed by agents that have entered the WaiterList's critical section.

25.4.2 Abstract Operations for Atomics

25.4.2.1 ValidateIntegerTypedArray ( typedArray [ , waitable ] )

The abstract operation ValidateIntegerTypedArray takes argument typedArray (an ECMAScript language value) and optional argument waitable (a Boolean) and returns either a normal completion containing either an ArrayBuffer or a SharedArrayBuffer, or a throw completion. It performs the following steps when called:

  1. If waitable is not present, set waitable to false.
  2. Perform ? ValidateTypedArray(typedArray).
  3. Let buffer be typedArray.[[ViewedArrayBuffer]].
  4. If waitable is true, then
    1. If typedArray.[[TypedArrayName]] is neither "Int32Array" nor "BigInt64Array", throw a TypeError exception.
  5. Else,
    1. Let type be TypedArrayElementType(typedArray).
    2. If IsUnclampedIntegerElementType(type) is false and IsBigIntElementType(type) is false, throw a TypeError exception.
  6. Return buffer.

25.4.2.2 ValidateAtomicAccess ( typedArray, requestIndex )

The abstract operation ValidateAtomicAccess takes arguments typedArray (a TypedArray) and requestIndex (an ECMAScript language value) and returns either a normal completion containing an integer or a throw completion. It performs the following steps when called:

  1. Let length be typedArray.[[ArrayLength]].
  2. Let accessIndex be ? ToIndex(requestIndex).
  3. Assert: accessIndex ≥ 0.
  4. If accessIndex ≥ length, throw a RangeError exception.
  5. Let elementSize be TypedArrayElementSize(typedArray).
  6. Let offset be typedArray.[[ByteOffset]].
  7. Return (accessIndex × elementSize) + offset.

25.4.2.3 GetWaiterList ( block, i )

The abstract operation GetWaiterList takes arguments block (a Shared Data Block) and i (a non-negative integer that is evenly divisible by 4) and returns a WaiterList. It performs the following steps when called:

  1. Assert: i and i + 3 are valid byte offsets within the memory of block.
  2. Return the WaiterList that is referenced by the pair (block, i).

25.4.2.4 EnterCriticalSection ( WL )

The abstract operation EnterCriticalSection takes argument WL (a WaiterList) and returns unused. It performs the following steps when called:

  1. Assert: The surrounding agent is not in the critical section for any WaiterList.
  2. Wait until no agent is in the critical section for WL, then enter the critical section for WL (without allowing any other agent to enter).
  3. If WL has a Synchronize event, then
    1. NOTE: A WL whose critical section has been entered at least once has a Synchronize event set by LeaveCriticalSection.
    2. Let execution be the [[CandidateExecution]] field of the surrounding agent's Agent Record.
    3. Let eventsRecord be the Agent Events Record of execution.[[EventsRecords]] whose [[AgentSignifier]] is AgentSignifier().
    4. Let enterEvent be a new Synchronize event.
    5. Append enterEvent to eventsRecord.[[EventList]].
    6. Let leaveEvent be the Synchronize event in WL.
    7. Append (leaveEvent, enterEvent) to eventsRecord.[[AgentSynchronizesWith]].
  4. Return unused.

EnterCriticalSection has contention when an agent attempting to enter the critical section must wait for another agent to leave it. When there is no contention, FIFO order of EnterCriticalSection calls is observable. When there is contention, an implementation may choose an arbitrary order but may not cause an agent to wait indefinitely.

25.4.2.5 LeaveCriticalSection ( WL )

The abstract operation LeaveCriticalSection takes argument WL (a WaiterList) and returns unused. It performs the following steps when called:

  1. Assert: The surrounding agent is in the critical section for WL.
  2. Let execution be the [[CandidateExecution]] field of the surrounding agent's Agent Record.
  3. Let eventsRecord be the Agent Events Record of execution.[[EventsRecords]] whose [[AgentSignifier]] is AgentSignifier().
  4. Let leaveEvent be a new Synchronize event.
  5. Append leaveEvent to eventsRecord.[[EventList]].
  6. Set the Synchronize event in WL to leaveEvent.
  7. Leave the critical section for WL.
  8. Return unused.

25.4.2.6 AddWaiter ( WL, W )

The abstract operation AddWaiter takes arguments WL (a WaiterList) and W (an agent signifier) and returns unused. It performs the following steps when called:

  1. Assert: The surrounding agent is in the critical section for WL.
  2. Assert: W is not on the list of waiters in any WaiterList.
  3. Append W to WL.
  4. Return unused.

25.4.2.7 RemoveWaiter ( WL, W )

The abstract operation RemoveWaiter takes arguments WL (a WaiterList) and W (an agent signifier) and returns unused. It performs the following steps when called:

  1. Assert: The surrounding agent is in the critical section for WL.
  2. Assert: W is on the list of waiters in WL.
  3. Remove W from the list of waiters in WL.
  4. Return unused.

25.4.2.8 RemoveWaiters ( WL, c )

The abstract operation RemoveWaiters takes arguments WL (a WaiterList) and c (a non-negative integer or +∞) and returns a List of agent signifiers. It performs the following steps when called:

  1. Assert: The surrounding agent is in the critical section for WL.
  2. Let S be a reference to the list of waiters in WL.
  3. Let len be the number of elements in S.
  4. Let n be min(c, len).
  5. Let L be a List whose elements are the first n elements of S.
  6. Remove the first n elements of S.
  7. Return L.

25.4.2.9 SuspendAgent ( WL, W, minimumTimeout )

The abstract operation SuspendAgent takes arguments WL (a WaiterList), W (an agent signifier), and minimumTimeout (a non-negative extended mathematical value) and returns a Boolean. It performs the following steps when called:

  1. Assert: The surrounding agent is in the critical section for WL.
  2. Assert: W is AgentSignifier().
  3. Assert: W is on the list of waiters in WL.
  4. Assert: AgentCanSuspend() is true.
  5. Let additionalTimeout be an implementation-defined non-negative mathematical value.
  6. Let timeout be minimumTimeout + additionalTimeout.
  7. NOTE: When minimumTimeout is +∞, timeout is also +∞ and the following step can terminate only by another agent calling NotifyWaiter.
  8. Perform LeaveCriticalSection(WL) and suspend W for up to timeout milliseconds, performing the combined operation in such a way that a notification that arrives after the critical section is exited but before the suspension takes effect is not lost. W can wake from suspension either because the timeout expired or because it was notified explicitly by another agent calling NotifyWaiter with arguments WL and W, and not for any other reasons at all.
  9. Perform EnterCriticalSection(WL).
  10. If W was notified explicitly by another agent calling NotifyWaiter with arguments WL and W, return true.
  11. Return false.
 Note

additionalTimeout allows implementations to pad timeouts as necessary, such as for reducing power consumption or coarsening timer resolution to mitigate timing attacks. This value may differ from call to call of SuspendAgent.

25.4.2.10 NotifyWaiter ( WL, W )

The abstract operation NotifyWaiter takes arguments WL (a WaiterList) and W (an agent signifier) and returns unused. It performs the following steps when called:

  1. Assert: The surrounding agent is in the critical section for WL.
  2. Notify the agent W.
  3. Return unused.
 Note

The embedding may delay notifying W, e.g. for resource management reasons, but W must eventually be notified in order to guarantee forward progress.

25.4.2.11 AtomicReadModifyWrite ( typedArray, index, value, op )

The abstract operation AtomicReadModifyWrite takes arguments typedArray (an ECMAScript language value), index (an ECMAScript language value), value (an ECMAScript language value), and op (a read-modify-write modification function) and returns either a normal completion containing either a Number or a BigInt, or a throw completion. op takes two List of byte values arguments and returns a List of byte values. This operation atomically loads a value, combines it with another value, and stores the result of the combination. It returns the loaded value. It performs the following steps when called:

  1. Let buffer be ? ValidateIntegerTypedArray(typedArray).
  2. Let indexedPosition be ? ValidateAtomicAccess(typedArray, index).
  3. If typedArray.[[ContentType]] is BigInt, let v be ? ToBigInt(value).
  4. Otherwise, let v be 𝔽(? ToIntegerOrInfinity(value)).
  5. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  6. NOTE: The above check is not redundant with the check in ValidateIntegerTypedArray because the call to ToBigInt or ToIntegerOrInfinity on the preceding lines can have arbitrary side effects, which could cause the buffer to become detached.
  7. Let elementType be TypedArrayElementType(typedArray).
  8. Return GetModifySetValueInBuffer(buffer, indexedPosition, elementType, v, op).

25.4.2.12 ByteListBitwiseOp ( op, xBytes, yBytes )

The abstract operation ByteListBitwiseOp takes arguments op (&, ^, or |), xBytes (a List of byte values), and yBytes (a List of byte values) and returns a List of byte values. The operation atomically performs a bitwise operation on all byte values of the arguments and returns a List of byte values. It performs the following steps when called:

  1. Assert: xBytes and yBytes have the same number of elements.
  2. Let result be a new empty List.
  3. Let i be 0.
  4. For each element xByte of xBytes, do
    1. Let yByte be yBytes[i].
    2. If op is &, let resultByte be the result of applying the bitwise AND operation to xByte and yByte.
    3. Else if op is ^, let resultByte be the result of applying the bitwise exclusive OR (XOR) operation to xByte and yByte.
    4. Else, op is |. Let resultByte be the result of applying the bitwise inclusive OR operation to xByte and yByte.
    5. Set i to i + 1.
    6. Append resultByte to result.
  5. Return result.

25.4.2.13 ByteListEqual ( xBytes, yBytes )

The abstract operation ByteListEqual takes arguments xBytes (a List of byte values) and yBytes (a List of byte values) and returns a Boolean. It performs the following steps when called:

  1. If xBytes and yBytes do not have the same number of elements, return false.
  2. Let i be 0.
  3. For each element xByte of xBytes, do
    1. Let yByte be yBytes[i].
    2. If xByte ≠ yByte, return false.
    3. Set i to i + 1.
  4. Return true.

25.4.3 Atomics.add ( typedArray, index, value )

This function performs the following steps when called:

  1. Let type be TypedArrayElementType(typedArray).
  2. Let isLittleEndian be the value of the [[LittleEndian]] field of the surrounding agent's Agent Record.
  3. Let add be a new read-modify-write modification function with parameters (xBytes, yBytes) that captures type and isLittleEndian and performs the following steps atomically when called:
    1. Let x be RawBytesToNumeric(type, xBytes, isLittleEndian).
    2. Let y be RawBytesToNumeric(type, yBytes, isLittleEndian).
    3. If x is a Number, then
      1. Let sum be Number::add(x, y).
    4. Else,
      1. Assert: x is a BigInt.
      2. Let sum be BigInt::add(x, y).
    5. Let sumBytes be NumericToRawBytes(type, sum, isLittleEndian).
    6. Assert: sumBytes, xBytes, and yBytes have the same number of elements.
    7. Return sumBytes.
  4. Return ? AtomicReadModifyWrite(typedArray, index, value, add).

25.4.4 Atomics.and ( typedArray, index, value )

This function performs the following steps when called:

  1. Let and be a new read-modify-write modification function with parameters (xBytes, yBytes) that captures nothing and performs the following steps atomically when called:
    1. Return ByteListBitwiseOp(&, xBytes, yBytes).
  2. Return ? AtomicReadModifyWrite(typedArray, index, value, and).

25.4.5 Atomics.compareExchange ( typedArray, index, expectedValue, replacementValue )

This function performs the following steps when called:

  1. Let buffer be ? ValidateIntegerTypedArray(typedArray).
  2. Let block be buffer.[[ArrayBufferData]].
  3. Let indexedPosition be ? ValidateAtomicAccess(typedArray, index).
  4. If typedArray.[[ContentType]] is BigInt, then
    1. Let expected be ? ToBigInt(expectedValue).
    2. Let replacement be ? ToBigInt(replacementValue).
  5. Else,
    1. Let expected be 𝔽(? ToIntegerOrInfinity(expectedValue)).
    2. Let replacement be 𝔽(? ToIntegerOrInfinity(replacementValue)).
  6. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  7. NOTE: The above check is not redundant with the check in ValidateIntegerTypedArray because the call to ToBigInt or ToIntegerOrInfinity on the preceding lines can have arbitrary side effects, which could cause the buffer to become detached.
  8. Let elementType be TypedArrayElementType(typedArray).
  9. Let elementSize be TypedArrayElementSize(typedArray).
  10. Let isLittleEndian be the value of the [[LittleEndian]] field of the surrounding agent's Agent Record.
  11. Let expectedBytes be NumericToRawBytes(elementType, expected, isLittleEndian).
  12. Let replacementBytes be NumericToRawBytes(elementType, replacement, isLittleEndian).
  13. If IsSharedArrayBuffer(buffer) is true, then
    1. Let execution be the [[CandidateExecution]] field of the surrounding agent's Agent Record.
    2. Let eventsRecord be the Agent Events Record of execution.[[EventsRecords]] whose [[AgentSignifier]] is AgentSignifier().
    3. Let rawBytesRead be a List of length elementSize whose elements are nondeterministically chosen byte values.
    4. NOTE: In implementations, rawBytesRead is the result of a load-link, of a load-exclusive, or of an operand of a read-modify-write instruction on the underlying hardware. The nondeterminism is a semantic prescription of the memory model to describe observable behaviour of hardware with weak consistency.
    5. NOTE: The comparison of the expected value and the read value is performed outside of the read-modify-write modification function to avoid needlessly strong synchronization when the expected value is not equal to the read value.
    6. If ByteListEqual(rawBytesRead, expectedBytes) is true, then
      1. Let second be a new read-modify-write modification function with parameters (oldBytes, newBytes) that captures nothing and performs the following steps atomically when called:
        1. Return newBytes.
      2. Let event be ReadModifyWriteSharedMemory { [[Order]]: SeqCst, [[NoTear]]: true, [[Block]]: block, [[ByteIndex]]: indexedPosition, [[ElementSize]]: elementSize, [[Payload]]: replacementBytes, [[ModifyOp]]: second }.
    7. Else,
      1. Let event be ReadSharedMemory { [[Order]]: SeqCst, [[NoTear]]: true, [[Block]]: block, [[ByteIndex]]: indexedPosition, [[ElementSize]]: elementSize }.
    8. Append event to eventsRecord.[[EventList]].
    9. Append Chosen Value Record { [[Event]]: event, [[ChosenValue]]: rawBytesRead } to execution.[[ChosenValues]].
  14. Else,
    1. Let rawBytesRead be a List of length elementSize whose elements are the sequence of elementSize bytes starting with block[indexedPosition].
    2. If ByteListEqual(rawBytesRead, expectedBytes) is true, then
      1. Store the individual bytes of replacementBytes into block, starting at block[indexedPosition].
  15. Return RawBytesToNumeric(elementType, rawBytesRead, isLittleEndian).

25.4.6 Atomics.exchange ( typedArray, index, value )

This function performs the following steps when called:

  1. Let second be a new read-modify-write modification function with parameters (oldBytes, newBytes) that captures nothing and performs the following steps atomically when called:
    1. Return newBytes.
  2. Return ? AtomicReadModifyWrite(typedArray, index, value, second).

25.4.7 Atomics.isLockFree ( size )

This function performs the following steps when called:

  1. Let n be ? ToIntegerOrInfinity(size).
  2. Let AR be the Agent Record of the surrounding agent.
  3. If n = 1, return AR.[[IsLockFree1]].
  4. If n = 2, return AR.[[IsLockFree2]].
  5. If n = 4, return true.
  6. If n = 8, return AR.[[IsLockFree8]].
  7. Return false.
 Note

This function is an optimization primitive. The intuition is that if the atomic step of an atomic primitive (compareExchange, load, store, add, sub, and, or, xor, or exchange) on a datum of size n bytes will be performed without the surrounding agent acquiring a lock outside the n bytes comprising the datum, then Atomics.isLockFree(n) will return true. High-performance algorithms will use this function to determine whether to use locks or atomic operations in critical sections. If an atomic primitive is not lock-free then it is often more efficient for an algorithm to provide its own locking.

Atomics.isLockFree(4) always returns true as that can be supported on all known relevant hardware. Being able to assume this will generally simplify programs.

Regardless of the value returned by this function, all atomic operations are guaranteed to be atomic. For example, they will never have a visible operation take place in the middle of the operation (e.g., "tearing").

25.4.8 Atomics.load ( typedArray, index )

This function performs the following steps when called:

  1. Let buffer be ? ValidateIntegerTypedArray(typedArray).
  2. Let indexedPosition be ? ValidateAtomicAccess(typedArray, index).
  3. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  4. NOTE: The above check is not redundant with the check in ValidateIntegerTypedArray because the call to ValidateAtomicAccess on the preceding line can have arbitrary side effects, which could cause the buffer to become detached.
  5. Let elementType be TypedArrayElementType(typedArray).
  6. Return GetValueFromBuffer(buffer, indexedPosition, elementType, true, SeqCst).

25.4.9 Atomics.or ( typedArray, index, value )

This function performs the following steps when called:

  1. Let or be a new read-modify-write modification function with parameters (xBytes, yBytes) that captures nothing and performs the following steps atomically when called:
    1. Return ByteListBitwiseOp(|, xBytes, yBytes).
  2. Return ? AtomicReadModifyWrite(typedArray, index, value, or).

25.4.10 Atomics.store ( typedArray, index, value )

This function performs the following steps when called:

  1. Let buffer be ? ValidateIntegerTypedArray(typedArray).
  2. Let indexedPosition be ? ValidateAtomicAccess(typedArray, index).
  3. If typedArray.[[ContentType]] is BigInt, let v be ? ToBigInt(value).
  4. Otherwise, let v be 𝔽(? ToIntegerOrInfinity(value)).
  5. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  6. NOTE: The above check is not redundant with the check in ValidateIntegerTypedArray because the call to ToBigInt or ToIntegerOrInfinity on the preceding lines can have arbitrary side effects, which could cause the buffer to become detached.
  7. Let elementType be TypedArrayElementType(typedArray).
  8. Perform SetValueInBuffer(buffer, indexedPosition, elementType, v, true, SeqCst).
  9. Return v.

25.4.11 Atomics.sub ( typedArray, index, value )

This function performs the following steps when called:

  1. Let type be TypedArrayElementType(typedArray).
  2. Let isLittleEndian be the value of the [[LittleEndian]] field of the surrounding agent's Agent Record.
  3. Let subtract be a new read-modify-write modification function with parameters (xBytes, yBytes) that captures type and isLittleEndian and performs the following steps atomically when called:
    1. Let x be RawBytesToNumeric(type, xBytes, isLittleEndian).
    2. Let y be RawBytesToNumeric(type, yBytes, isLittleEndian).
    3. If x is a Number, then
      1. Let difference be Number::subtract(x, y).
    4. Else,
      1. Assert: x is a BigInt.
      2. Let difference be BigInt::subtract(x, y).
    5. Let differenceBytes be NumericToRawBytes(type, difference, isLittleEndian).
    6. Assert: differenceBytes, xBytes, and yBytes have the same number of elements.
    7. Return differenceBytes.
  4. Return ? AtomicReadModifyWrite(typedArray, index, value, subtract).

25.4.12 Atomics.wait ( typedArray, index, value, timeout )

This function puts the surrounding agent in a wait queue and suspends it until notified or until the wait times out, returning a String differentiating those cases.

It performs the following steps when called:

  1. Let buffer be ? ValidateIntegerTypedArray(typedArray, true).
  2. If IsSharedArrayBuffer(buffer) is false, throw a TypeError exception.
  3. Let indexedPosition be ? ValidateAtomicAccess(typedArray, index).
  4. If typedArray.[[TypedArrayName]] is "BigInt64Array", let v be ? ToBigInt64(value).
  5. Otherwise, let v be ? ToInt32(value).
  6. Let q be ? ToNumber(timeout).
  7. If q is either NaN or +∞𝔽, let t be +∞; else if q is -∞𝔽, let t be 0; else let t be max(ℝ(q), 0).
  8. Let B be AgentCanSuspend().
  9. If B is false, throw a TypeError exception.
  10. Let block be buffer.[[ArrayBufferData]].
  11. Let WL be GetWaiterList(block, indexedPosition).
  12. Perform EnterCriticalSection(WL).
  13. Let elementType be TypedArrayElementType(typedArray).
  14. Let w be GetValueFromBuffer(buffer, indexedPosition, elementType, true, SeqCst).
  15. If v ≠ w, then
    1. Perform LeaveCriticalSection(WL).
    2. Return "not-equal".
  16. Let W be AgentSignifier().
  17. Perform AddWaiter(WL, W).
  18. Let notified be SuspendAgent(WL, W, t).
  19. If notified is true, then
    1. Assert: W is not on the list of waiters in WL.
  20. Else,
    1. Perform RemoveWaiter(WL, W).
  21. Perform LeaveCriticalSection(WL).
  22. If notified is true, return "ok".
  23. Return "timed-out".

25.4.13 Atomics.notify ( typedArray, index, count )

This function notifies some agents that are sleeping in the wait queue.

It performs the following steps when called:

  1. Let buffer be ? ValidateIntegerTypedArray(typedArray, true).
  2. Let indexedPosition be ? ValidateAtomicAccess(typedArray, index).
  3. If count is undefined, let c be +∞.
  4. Else,
    1. Let intCount be ? ToIntegerOrInfinity(count).
    2. Let c be max(intCount, 0).
  5. Let block be buffer.[[ArrayBufferData]].
  6. If IsSharedArrayBuffer(buffer) is false, return +0𝔽.
  7. Let WL be GetWaiterList(block, indexedPosition).
  8. Perform EnterCriticalSection(WL).
  9. Let S be RemoveWaiters(WL, c).
  10. For each element W of S, do
    1. Perform NotifyWaiter(WL, W).
  11. Perform LeaveCriticalSection(WL).
  12. Let n be the number of elements in S.
  13. Return 𝔽(n).

25.4.14 Atomics.xor ( typedArray, index, value )

This function performs the following steps when called:

  1. Let xor be a new read-modify-write modification function with parameters (xBytes, yBytes) that captures nothing and performs the following steps atomically when called:
    1. Return ByteListBitwiseOp(^, xBytes, yBytes).
  2. Return ? AtomicReadModifyWrite(typedArray, index, value, xor).

25.4.15 Atomics [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "Atomics".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

25.5 The JSON Object

The JSON object:

  • is %JSON%.
  • is the initial value of the "JSON" property of the global object.
  • is an ordinary object.
  • contains two functions, parse and stringify, that are used to parse and construct JSON texts.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • does not have a [[Construct]] internal method; it cannot be used as a constructor with the new operator.
  • does not have a [[Call]] internal method; it cannot be invoked as a function.

The JSON Data Interchange Format is defined in ECMA-404. The JSON interchange format used in this specification is exactly that described by ECMA-404. Conforming implementations of JSON.parse and JSON.stringify must support the exact interchange format described in the ECMA-404 specification without any deletions or extensions to the format.

25.5.1 JSON.parse ( text [ , reviver ] )

This function parses a JSON text (a JSON-formatted String) and produces an ECMAScript language value. The JSON format represents literals, arrays, and objects with a syntax similar to the syntax for ECMAScript literals, Array Initializers, and Object Initializers. After parsing, JSON objects are realized as ECMAScript objects. JSON arrays are realized as ECMAScript Array instances. JSON strings, numbers, booleans, and null are realized as ECMAScript Strings, Numbers, Booleans, and null.

The optional reviver parameter is a function that takes two parameters, key and value. It can filter and transform the results. It is called with each of the key/value pairs produced by the parse, and its return value is used instead of the original value. If it returns what it received, the structure is not modified. If it returns undefined then the property is deleted from the result.

  1. Let jsonString be ? ToString(text).
  2. Parse StringToCodePoints(jsonString) as a JSON text as specified in ECMA-404. Throw a SyntaxError exception if it is not a valid JSON text as defined in that specification.
  3. Let scriptString be the string-concatenation of "(", jsonString, and ");".
  4. Let script be ParseText(StringToCodePoints(scriptString), Script).
  5. NOTE: The early error rules defined in 13.2.5.1 have special handling for the above invocation of ParseText.
  6. Assert: script is a Parse Node.
  7. Let completion be Completion(Evaluation of script).
  8. NOTE: The PropertyDefinitionEvaluation semantics defined in 13.2.5.5 have special handling for the above evaluation.
  9. Let unfiltered be completion.[[Value]].
  10. Assert: unfiltered is either a String, a Number, a Boolean, an Object that is defined by either an ArrayLiteral or an ObjectLiteral, or null.
  11. If IsCallable(reviver) is true, then
    1. Let root be OrdinaryObjectCreate(%Object.prototype%).
    2. Let rootName be the empty String.
    3. Perform ! CreateDataPropertyOrThrow(root, rootName, unfiltered).
    4. Return ? InternalizeJSONProperty(root, rootName, reviver).
  12. Else,
    1. Return unfiltered.

The "length" property of this function is 2𝔽.

Note

Valid JSON text is a subset of the ECMAScript PrimaryExpression syntax. Step 2 verifies that jsonString conforms to that subset, and step 10 asserts that that parsing and evaluation returns a value of an appropriate type.

However, because 13.2.5.5 behaves differently during JSON.parse, the same source text can produce different results when evaluated as a PrimaryExpression rather than as JSON. Furthermore, the Early Error for duplicate "__proto__" properties in object literals, which likewise does not apply during JSON.parse, means that not all texts accepted by JSON.parse are valid as a PrimaryExpression, despite matching the grammar.

25.5.1.1 InternalizeJSONProperty ( holder, name, reviver )

The abstract operation InternalizeJSONProperty takes arguments holder (an Object), name (a String), and reviver (a function object) and returns either a normal completion containing an ECMAScript language value or a throw completion.

Note 1

This algorithm intentionally does not throw an exception if either [[Delete]] or CreateDataProperty return false.

It performs the following steps when called:

  1. Let val be ? Get(holder, name).
  2. If val is an Object, then
    1. Let isArray be ? IsArray(val).
    2. If isArray is true, then
      1. Let len be ? LengthOfArrayLike(val).
      2. Let I be 0.
      3. Repeat, while I < len,
        1. Let prop be ! ToString(𝔽(I)).
        2. Let newElement be ? InternalizeJSONProperty(val, prop, reviver).
        3. If newElement is undefined, then
          1. Perform ? val.[[Delete]](prop).
        4. Else,
          1. Perform ? CreateDataProperty(val, prop, newElement).
        5. Set I to I + 1.
    3. Else,
      1. Let keys be ? EnumerableOwnProperties(val, key).
      2. For each String P of keys, do
        1. Let newElement be ? InternalizeJSONProperty(val, P, reviver).
        2. If newElement is undefined, then
          1. Perform ? val.[[Delete]](P).
        3. Else,
          1. Perform ? CreateDataProperty(val, P, newElement).
  3. Return ? Call(reviver, holder, « name, val »).

It is not permitted for a conforming implementation of JSON.parse to extend the JSON grammars. If an implementation wishes to support a modified or extended JSON interchange format it must do so by defining a different parse function.

Note 2

In the case where there are duplicate name Strings within an object, lexically preceding values for the same key shall be overwritten.

25.5.2 JSON.stringify ( value [ , replacer [ , space ] ] )

This function returns a String in UTF-16 encoded JSON format representing an ECMAScript language value, or undefined. It can take three parameters. The value parameter is an ECMAScript language value, which is usually an object or array, although it can also be a String, Boolean, Number or null. The optional replacer parameter is either a function that alters the way objects and arrays are stringified, or an array of Strings and Numbers that acts as an inclusion list for selecting the object properties that will be stringified. The optional space parameter is a String or Number that allows the result to have white space injected into it to improve human readability.

It performs the following steps when called:

  1. Let stack be a new empty List.
  2. Let indent be the empty String.
  3. Let PropertyList be undefined.
  4. Let ReplacerFunction be undefined.
  5. If replacer is an Object, then
    1. If IsCallable(replacer) is true, then
      1. Set ReplacerFunction to replacer.
    2. Else,
      1. Let isArray be ? IsArray(replacer).
      2. If isArray is true, then
        1. Set PropertyList to a new empty List.
        2. Let len be ? LengthOfArrayLike(replacer).
        3. Let k be 0.
        4. Repeat, while k < len,
          1. Let prop be ! ToString(𝔽(k)).
          2. Let v be ? Get(replacer, prop).
          3. Let item be undefined.
          4. If v is a String, set item to v.
          5. Else if v is a Number, set item to ! ToString(v).
          6. Else if v is an Object, then
            1. If v has a [[StringData]] or [[NumberData]] internal slot, set item to ? ToString(v).
          7. If item is not undefined and PropertyList does not contain item, then
            1. Append item to PropertyList.
          8. Set k to k + 1.
  6. If space is an Object, then
    1. If space has a [[NumberData]] internal slot, then
      1. Set space to ? ToNumber(space).
    2. Else if space has a [[StringData]] internal slot, then
      1. Set space to ? ToString(space).
  7. If space is a Number, then
    1. Let spaceMV be ! ToIntegerOrInfinity(space).
    2. Set spaceMV to min(10, spaceMV).
    3. If spaceMV < 1, let gap be the empty String; otherwise let gap be the String value containing spaceMV occurrences of the code unit 0x0020 (SPACE).
  8. Else if space is a String, then
    1. If the length of space ≤ 10, let gap be space; otherwise let gap be the substring of space from 0 to 10.
  9. Else,
    1. Let gap be the empty String.
  10. Let wrapper be OrdinaryObjectCreate(%Object.prototype%).
  11. Perform ! CreateDataPropertyOrThrow(wrapper, the empty String, value).
  12. Let state be the JSON Serialization Record { [[ReplacerFunction]]: ReplacerFunction, [[Stack]]: stack, [[Indent]]: indent, [[Gap]]: gap, [[PropertyList]]: PropertyList }.
  13. Return ? SerializeJSONProperty(state, the empty String, wrapper).

The "length" property of this function is 3𝔽.

Note 1

JSON structures are allowed to be nested to any depth, but they must be acyclic. If value is or contains a cyclic structure, then this function must throw a TypeError exception. This is an example of a value that cannot be stringified:

a = [];
a[0] = a;
my_text = JSON.stringify(a); // This must throw a TypeError.
 Note 2

Symbolic primitive values are rendered as follows:

  • The null value is rendered in JSON text as the String value "null".
  • The undefined value is not rendered.
  • The true value is rendered in JSON text as the String value "true".
  • The false value is rendered in JSON text as the String value "false".
Note 3

String values are wrapped in QUOTATION MARK (") code units. The code units " and \ are escaped with \ prefixes. Control characters code units are replaced with escape sequences \uHHHH, or with the shorter forms, \b (BACKSPACE), \f (FORM FEED), \n (LINE FEED), \r (CARRIAGE RETURN), \t (CHARACTER TABULATION).

 Note 4

Finite numbers are stringified as if by calling ToString(number). NaN and Infinity regardless of sign are represented as the String value "null".

 Note 5

Values that do not have a JSON representation (such as undefined and functions) do not produce a String. Instead they produce the undefined value. In arrays these values are represented as the String value "null". In objects an unrepresentable value causes the property to be excluded from stringification.

 Note 6

An object is rendered as U+007B (LEFT CURLY BRACKET) followed by zero or more properties, separated with a U+002C (COMMA), closed with a U+007D (RIGHT CURLY BRACKET). A property is a quoted String representing the property name, a U+003A (COLON), and then the stringified property value. An array is rendered as an opening U+005B (LEFT SQUARE BRACKET) followed by zero or more values, separated with a U+002C (COMMA), closed with a U+005D (RIGHT SQUARE BRACKET).

25.5.2.1 JSON Serialization Record

A JSON Serialization Record is a Record value used to enable serialization to the JSON format.

JSON Serialization Records have the fields listed in Table 69.

Table 69: JSON Serialization Record Fields
Field Name Value Meaning
[[ReplacerFunction]] a function object or undefined A function that can supply replacement values for object properties (from JSON.stringify's replacer parameter).
[[PropertyList]] either a List of Strings or undefined The names of properties to include when serializing a non-array object (from JSON.stringify's replacer parameter).
[[Gap]] a String The unit of indentation (from JSON.stringify's space parameter).
[[Stack]] a List of Objects The set of nested objects that are in the process of being serialized. Used to detect cyclic structures.
[[Indent]] a String The current indentation.

25.5.2.2 SerializeJSONProperty ( state, key, holder )

The abstract operation SerializeJSONProperty takes arguments state (a JSON Serialization Record), key (a String), and holder (an Object) and returns either a normal completion containing either a String or undefined, or a throw completion. It performs the following steps when called:

  1. Let value be ? Get(holder, key).
  2. If value is an Object or value is a BigInt, then
    1. Let toJSON be ? GetV(value, "toJSON").
    2. If IsCallable(toJSON) is true, then
      1. Set value to ? Call(toJSON, value, « key »).
  3. If state.[[ReplacerFunction]] is not undefined, then
    1. Set value to ? Call(state.[[ReplacerFunction]], holder, « key, value »).
  4. If value is an Object, then
    1. If value has a [[NumberData]] internal slot, then
      1. Set value to ? ToNumber(value).
    2. Else if value has a [[StringData]] internal slot, then
      1. Set value to ? ToString(value).
    3. Else if value has a [[BooleanData]] internal slot, then
      1. Set value to value.[[BooleanData]].
    4. Else if value has a [[BigIntData]] internal slot, then
      1. Set value to value.[[BigIntData]].
  5. If value is null, return "null".
  6. If value is true, return "true".
  7. If value is false, return "false".
  8. If value is a String, return QuoteJSONString(value).
  9. If value is a Number, then
    1. If value is finite, return ! ToString(value).
    2. Return "null".
  10. If value is a BigInt, throw a TypeError exception.
  11. If value is an Object and IsCallable(value) is false, then
    1. Let isArray be ? IsArray(value).
    2. If isArray is true, return ? SerializeJSONArray(state, value).
    3. Return ? SerializeJSONObject(state, value).
  12. Return undefined.

25.5.2.3 QuoteJSONString ( value )

The abstract operation QuoteJSONString takes argument value (a String) and returns a String. It wraps value in 0x0022 (QUOTATION MARK) code units and escapes certain other code units within it. This operation interprets value as a sequence of UTF-16 encoded code points, as described in 6.1.4. It performs the following steps when called:

  1. Let product be the String value consisting solely of the code unit 0x0022 (QUOTATION MARK).
  2. For each code point C of StringToCodePoints(value), do
    1. If C is listed in the “Code Point” column of Table 70, then
      1. Set product to the string-concatenation of product and the escape sequence for C as specified in the “Escape Sequence” column of the corresponding row.
    2. Else if C has a numeric value less than 0x0020 (SPACE) or C has the same numeric value as a leading surrogate or trailing surrogate, then
      1. Let unit be the code unit whose numeric value is the numeric value of C.
      2. Set product to the string-concatenation of product and UnicodeEscape(unit).
    3. Else,
      1. Set product to the string-concatenation of product and UTF16EncodeCodePoint(C).
  3. Set product to the string-concatenation of product and the code unit 0x0022 (QUOTATION MARK).
  4. Return product.
Table 70: JSON Single Character Escape Sequences
Code Point Unicode Character Name Escape Sequence
U+0008 BACKSPACE \b
U+0009 CHARACTER TABULATION \t
U+000A LINE FEED (LF) \n
U+000C FORM FEED (FF) \f
U+000D CARRIAGE RETURN (CR) \r
U+0022 QUOTATION MARK \"
U+005C REVERSE SOLIDUS \\

25.5.2.4 UnicodeEscape ( C )

The abstract operation UnicodeEscape takes argument C (a code unit) and returns a String. It represents C as a Unicode escape sequence. It performs the following steps when called:

  1. Let n be the numeric value of C.
  2. Assert: n ≤ 0xFFFF.
  3. Let hex be the String representation of n, formatted as a lowercase hexadecimal number.
  4. Return the string-concatenation of the code unit 0x005C (REVERSE SOLIDUS), "u", and ! StringPad(hex, 4𝔽, "0", start).

25.5.2.5 SerializeJSONObject ( state, value )

The abstract operation SerializeJSONObject takes arguments state (a JSON Serialization Record) and value (an Object) and returns either a normal completion containing a String or a throw completion. It serializes an object. It performs the following steps when called:

  1. If state.[[Stack]] contains value, throw a TypeError exception because the structure is cyclical.
  2. Append value to state.[[Stack]].
  3. Let stepback be state.[[Indent]].
  4. Set state.[[Indent]] to the string-concatenation of state.[[Indent]] and state.[[Gap]].
  5. If state.[[PropertyList]] is not undefined, then
    1. Let K be state.[[PropertyList]].
  6. Else,
    1. Let K be ? EnumerableOwnProperties(value, key).
  7. Let partial be a new empty List.
  8. For each element P of K, do
    1. Let strP be ? SerializeJSONProperty(state, P, value).
    2. If strP is not undefined, then
      1. Let member be QuoteJSONString(P).
      2. Set member to the string-concatenation of member and ":".
      3. If state.[[Gap]] is not the empty String, then
        1. Set member to the string-concatenation of member and the code unit 0x0020 (SPACE).
      4. Set member to the string-concatenation of member and strP.
      5. Append member to partial.
  9. If partial is empty, then
    1. Let final be "{}".
  10. Else,
    1. If state.[[Gap]] is the empty String, then
      1. Let properties be the String value formed by concatenating all the element Strings of partial with each adjacent pair of Strings separated with the code unit 0x002C (COMMA). A comma is not inserted either before the first String or after the last String.
      2. Let final be the string-concatenation of "{", properties, and "}".
    2. Else,
      1. Let separator be the string-concatenation of the code unit 0x002C (COMMA), the code unit 0x000A (LINE FEED), and state.[[Indent]].
      2. Let properties be the String value formed by concatenating all the element Strings of partial with each adjacent pair of Strings separated with separator. The separator String is not inserted either before the first String or after the last String.
      3. Let final be the string-concatenation of "{", the code unit 0x000A (LINE FEED), state.[[Indent]], properties, the code unit 0x000A (LINE FEED), stepback, and "}".
  11. Remove the last element of state.[[Stack]].
  12. Set state.[[Indent]] to stepback.
  13. Return final.

25.5.2.6 SerializeJSONArray ( state, value )

The abstract operation SerializeJSONArray takes arguments state (a JSON Serialization Record) and value (an ECMAScript language value) and returns either a normal completion containing a String or a throw completion. It serializes an array. It performs the following steps when called:

  1. If state.[[Stack]] contains value, throw a TypeError exception because the structure is cyclical.
  2. Append value to state.[[Stack]].
  3. Let stepback be state.[[Indent]].
  4. Set state.[[Indent]] to the string-concatenation of state.[[Indent]] and state.[[Gap]].
  5. Let partial be a new empty List.
  6. Let len be ? LengthOfArrayLike(value).
  7. Let index be 0.
  8. Repeat, while index < len,
    1. Let strP be ? SerializeJSONProperty(state, ! ToString(𝔽(index)), value).
    2. If strP is undefined, then
      1. Append "null" to partial.
    3. Else,
      1. Append strP to partial.
    4. Set index to index + 1.
  9. If partial is empty, then
    1. Let final be "[]".
  10. Else,
    1. If state.[[Gap]] is the empty String, then
      1. Let properties be the String value formed by concatenating all the element Strings of partial with each adjacent pair of Strings separated with the code unit 0x002C (COMMA). A comma is not inserted either before the first String or after the last String.
      2. Let final be the string-concatenation of "[", properties, and "]".
    2. Else,
      1. Let separator be the string-concatenation of the code unit 0x002C (COMMA), the code unit 0x000A (LINE FEED), and state.[[Indent]].
      2. Let properties be the String value formed by concatenating all the element Strings of partial with each adjacent pair of Strings separated with separator. The separator String is not inserted either before the first String or after the last String.
      3. Let final be the string-concatenation of "[", the code unit 0x000A (LINE FEED), state.[[Indent]], properties, the code unit 0x000A (LINE FEED), stepback, and "]".
  11. Remove the last element of state.[[Stack]].
  12. Set state.[[Indent]] to stepback.
  13. Return final.
 Note

The representation of arrays includes only the elements in the interval from +0𝔽 (inclusive) to array.length (exclusive). Properties whose keys are not array indices are excluded from the stringification. An array is stringified as an opening LEFT SQUARE BRACKET, elements separated by COMMA, and a closing RIGHT SQUARE BRACKET.

25.5.3 JSON [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "JSON".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.