ECMAScript® 2024 Language Specification

Draft ECMA-262 / February 15, 2024

25.3 DataView Objects

25.3.1 Abstract Operations For DataView Objects

25.3.1.1 DataView With Buffer Witness Records

A DataView With Buffer Witness Record is a Record value used to encapsulate a DataView along with a cached byte length of the viewed buffer. It is used to help ensure there is a single shared memory read event of the byte length data block when the viewed buffer is a growable SharedArrayBuffers.

DataView With Buffer Witness Records have the fields listed in Table 72.

Table 72: DataView With Buffer Witness Record Fields
Field Name Value Meaning
[[Object]] a DataView The DataView object whose buffer's byte length is loaded.
[[CachedBufferByteLength]] a non-negative integer or detached The byte length of the object's [[ViewedArrayBuffer]] when the Record was created.

25.3.1.2 MakeDataViewWithBufferWitnessRecord ( obj, order )

The abstract operation MakeDataViewWithBufferWitnessRecord takes arguments obj (a DataView) and order (seq-cst or unordered) and returns a DataView With Buffer Witness Record. It performs the following steps when called:

  1. Let buffer be obj.[[ViewedArrayBuffer]].
  2. If IsDetachedBuffer(buffer) is true, then
    1. Let byteLength be detached.
  3. Else,
    1. Let byteLength be ArrayBufferByteLength(buffer, order).
  4. Return the DataView With Buffer Witness Record { [[Object]]: obj, [[CachedBufferByteLength]]: byteLength }.

25.3.1.3 GetViewByteLength ( viewRecord )

The abstract operation GetViewByteLength takes argument viewRecord (a DataView With Buffer Witness Record) and returns a non-negative integer. It performs the following steps when called:

  1. Assert: IsViewOutOfBounds(viewRecord) is false.
  2. Let view be viewRecord.[[Object]].
  3. If view.[[ByteLength]] is not auto, return view.[[ByteLength]].
  4. Assert: IsFixedLengthArrayBuffer(view.[[ViewedArrayBuffer]]) is false.
  5. Let byteOffset be view.[[ByteOffset]].
  6. Let byteLength be viewRecord.[[CachedBufferByteLength]].
  7. Assert: byteLength is not detached.
  8. Return byteLength - byteOffset.

25.3.1.4 IsViewOutOfBounds ( viewRecord )

The abstract operation IsViewOutOfBounds takes argument viewRecord (a DataView With Buffer Witness Record) and returns a Boolean. It performs the following steps when called:

  1. Let view be viewRecord.[[Object]].
  2. Let bufferByteLength be viewRecord.[[CachedBufferByteLength]].
  3. Assert: IsDetachedBuffer(view.[[ViewedArrayBuffer]]) is true if and only if bufferByteLength is detached.
  4. If bufferByteLength is detached, return true.
  5. Let byteOffsetStart be view.[[ByteOffset]].
  6. If view.[[ByteLength]] is auto, then
    1. Let byteOffsetEnd be bufferByteLength.
  7. Else,
    1. Let byteOffsetEnd be byteOffsetStart + view.[[ByteLength]].
  8. If byteOffsetStart > bufferByteLength or byteOffsetEnd > bufferByteLength, return true.
  9. NOTE: 0-length DataViews are not considered out-of-bounds.
  10. Return false.

25.3.1.5 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 viewOffset be view.[[ByteOffset]].
  6. Let viewRecord be MakeDataViewWithBufferWitnessRecord(view, unordered).
  7. NOTE: Bounds checking is not a synchronizing operation when view's backing buffer is a growable SharedArrayBuffer.
  8. If IsViewOutOfBounds(viewRecord) is true, throw a TypeError exception.
  9. Let viewSize be GetViewByteLength(viewRecord).
  10. Let elementSize be the Element Size value specified in Table 71 for Element Type type.
  11. If getIndex + elementSize > viewSize, throw a RangeError exception.
  12. Let bufferIndex be getIndex + viewOffset.
  13. Return GetValueFromBuffer(view.[[ViewedArrayBuffer]], bufferIndex, type, false, unordered, isLittleEndian).

25.3.1.6 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 viewOffset be view.[[ByteOffset]].
  8. Let viewRecord be MakeDataViewWithBufferWitnessRecord(view, unordered).
  9. NOTE: Bounds checking is not a synchronizing operation when view's backing buffer is a growable SharedArrayBuffer.
  10. If IsViewOutOfBounds(viewRecord) is true, throw a TypeError exception.
  11. Let viewSize be GetViewByteLength(viewRecord).
  12. Let elementSize be the Element Size value specified in Table 71 for Element Type type.
  13. If getIndex + elementSize > viewSize, throw a RangeError exception.
  14. Let bufferIndex be getIndex + viewOffset.
  15. Perform SetValueInBuffer(view.[[ViewedArrayBuffer]], bufferIndex, type, numberValue, false, unordered, isLittleEndian).
  16. 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 ArrayBufferByteLength(buffer, seq-cst).
  6. If offset > bufferByteLength, throw a RangeError exception.
  7. Let bufferIsFixedLength be IsFixedLengthArrayBuffer(buffer).
  8. If byteLength is undefined, then
    1. If bufferIsFixedLength is true, then
      1. Let viewByteLength be bufferByteLength - offset.
    2. Else,
      1. Let viewByteLength be auto.
  9. Else,
    1. Let viewByteLength be ? ToIndex(byteLength).
    2. If offset + viewByteLength > bufferByteLength, throw a RangeError exception.
  10. Let O be ? OrdinaryCreateFromConstructor(NewTarget, "%DataView.prototype%", « [[DataView]], [[ViewedArrayBuffer]], [[ByteLength]], [[ByteOffset]] »).
  11. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  12. Set bufferByteLength to ArrayBufferByteLength(buffer, seq-cst).
  13. If offset > bufferByteLength, throw a RangeError exception.
  14. If byteLength is not undefined, then
    1. If offset + viewByteLength > bufferByteLength, throw a RangeError exception.
  15. Set O.[[ViewedArrayBuffer]] to buffer.
  16. Set O.[[ByteLength]] to viewByteLength.
  17. Set O.[[ByteOffset]] to offset.
  18. 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 viewRecord be MakeDataViewWithBufferWitnessRecord(O, seq-cst).
  5. If IsViewOutOfBounds(viewRecord) is true, throw a TypeError exception.
  6. Let size be GetViewByteLength(viewRecord).
  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 viewRecord be MakeDataViewWithBufferWitnessRecord(O, seq-cst).
  5. If IsViewOutOfBounds(viewRecord) 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.