Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

TypedArray: buffer, byte offset, byte length, and element count

Distinguish the whole buffer from a typed array’s byte range and element count, and see what its getters report after resizing or detachment.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

view.buffer
view.byteOffset
view.byteLength
view.length

new Uint16Array(buffer)
new Uint16Array(buffer, byteOffset)
new Uint16Array(buffer, byteOffset, length)

TypedArray.buffer/byteOffset/byteLength/length names four inherited getter-only properties on views such as Uint16Array. TypedArray names the family; there is no global TypedArray constructor to call directly. Calling one of these getters on a receiver that is not a typed array throws TypeError. view.length is not Uint16Array.length, which is the constructor’s declared parameter count.

view.buffer returns the same backing ArrayBuffer or SharedArrayBuffer, not a copy. view.byteOffset is where the view starts relative to the buffer’s beginning, and view.byteLength is the view’s size, both in bytes. view.length counts elements. When both reads observe the same view size, view.byteLength === view.length * view.BYTES_PER_ELEMENT. The getters are read separately: if another agent grows the backing SharedArrayBuffer between reads, the getters on a length-tracking view can observe different sizes, and the comparison can be false. view.buffer.byteLength measures the whole buffer, not just the view.

In new Uint16Array(buffer, byteOffset, length), the second argument is in bytes and the third is in elements. A misaligned offset or a range beyond the buffer throws RangeError. Writes are visible through overlapping views of the same buffer. Passing a view does not hide the remaining bytes: to disclose only a valid range, copy its bytes into a separate buffer.

On a fixed-size buffer, omitting length covers the remainder, which must fit a whole number of elements. On a resizable ArrayBuffer or growable SharedArrayBuffer, omitting length or passing undefined creates a length-tracking view: it counts the whole elements that fit from its offset. An explicit element count makes the view fixed-length.

Shrinking a buffer can put a view out of bounds, and regrowing it can bring the view back in bounds. While out of bounds, or after its ArrayBuffer is detached (for example, by transfer), all three numeric getters return 0, but buffer still returns the same object. A valid empty view can have a nonzero offset. Resizing and growing are specified in ECMAScript 2024; check support in the target runtime before relying on them.

Examples

{
  const buffer = new ArrayBuffer(16);
  const view = new Uint16Array(buffer, 4, 3);

  console.log([
    view.buffer === buffer,
    view.byteOffset,
    view.byteLength,
    view.length,
    view.buffer.byteLength,
  ].join(" "));

  view[0] = 513;
  console.log(String(new Uint16Array(buffer)[2]));
}

Result

true 4 6 3 16
513

The view starts at byte 4 and covers three two-byte elements, or 6 of the 16 bytes. Writing at index 0 is visible at index 2 in the full-buffer view.

Related lessons

  • JavaScript · Lesson 2 · Advanced · Version: 4

Sources