Movatterモバイル変換


[0]ホーム

URL:


MDN Web Docs

JavaScript typed arrays

JavaScript typed arrays are array-like objects that provide a mechanism for reading and writing raw binary data in memory buffers.

Typed arrays are not intended to replace arrays for any kind of functionality. Instead, they provide developers with a familiar interface for manipulating binary data. This is useful when interacting with platform features, such as audio and video manipulation, access to raw data usingWebSockets, and so forth. Each entry in a JavaScript typed array is a raw binary value in one of a number of supported formats, from 8-bit integers to 64-bit floating-point numbers.

Typed array objects share many of the same methods as arrays with similar semantics. However, typed arrays arenot to be confused with normal arrays, as callingArray.isArray() on a typed array returnsfalse. Moreover, not all methods available for normal arrays are supported by typed arrays (e.g., push and pop).

To achieve maximum flexibility and efficiency, JavaScript typed arrays split the implementation intobuffers andviews. A buffer is an object representing a chunk of data; it has no format to speak of, and offers no mechanism for accessing its contents. In order to access the memory contained in a buffer, you need to use aview. A view provides acontext — that is, a data type, starting offset, and number of elements.

A diagram showing how different typed arrays may be views of the same underlying buffer. Each one has a different element number and width.

Buffers

There are two types of buffers:ArrayBuffer andSharedArrayBuffer. Both are low-level representations of a memory span. They have "array" in their names, but they don't have much to do with arrays — you cannot read or write to them directly. Instead, buffers are generic objects that just contain raw data. In order to access the memory represented by a buffer, you need to use a view.

Buffers support the following actions:

  • Allocate: As soon as a new buffer is created, a new memory span is allocated and initialized to0.
  • Copy: Using theslice() method, you can efficiently copy a portion of the memory without creating views to manually copy each byte.
  • Transfer: Using thetransfer() andtransferToFixedLength() methods, you can transfer ownership of the memory span to a new buffer object. This is useful when transferring data between different execution contexts without copying. After the transfer, the original buffer is no longer usable. ASharedArrayBuffer cannot be transferred (as the buffer is already shared by all execution contexts).
  • Resize: Using theresize() method, you can resize the memory span (either claim more memory space, as long as it doesn't pass the pre-setmaxByteLength limit, or release some memory space).SharedArrayBuffer can only begrown but not shrunk.

The difference betweenArrayBuffer andSharedArrayBuffer is that the former is always owned by a single execution context at a time. If you pass anArrayBuffer to a different execution context, it istransferred and the originalArrayBuffer becomes unusable. This ensures that only one execution context can access the memory at a time. ASharedArrayBuffer is not transferred when passed to a different execution context, so it can be accessed by multiple execution contexts at the same time. This may introduce race conditions when multiple threads access the same memory span, so operations such asAtomics methods become useful.

Views

There are currently two main kinds of views: typed array views andDataView. Typed arrays provideutility methods that allow you to conveniently transform binary data.DataView is more low-level and allows granular control of how data is accessed. The ways to read and write data using the two views are very different.

Both kinds of views causeArrayBuffer.isView() to returntrue. They both have the following properties:

buffer

The underlying buffer that the view references.

byteOffset

The offset, in bytes, of the view from the start of its buffer.

byteLength

The length, in bytes, of the view.

Both constructors accept the above three as separate arguments, although typed array constructors acceptlength as the number of elements rather than the number of bytes.

Typed array views

Typed array views have self-descriptive names and provide views for all the usual numeric types likeInt8,Uint32,Float64 and so forth. There is one special typed array view,Uint8ClampedArray, which clamps the values between0 and255. This is useful forCanvas data processing, for example.

TypeValue RangeSize in bytesWeb IDL type
Int8Array-128 to 1271byte
Uint8Array0 to 2551octet
Uint8ClampedArray0 to 2551octet
Int16Array-32768 to 327672short
Uint16Array0 to 655352unsigned short
Int32Array-2147483648 to 21474836474long
Uint32Array0 to 42949672954unsigned long
Float16Array-65504 to655042N/A
Float32Array-3.4e38 to3.4e384unrestricted float
Float64Array-1.8e308 to1.8e3088unrestricted double
BigInt64Array-263 to 263 - 18bigint
BigUint64Array0 to 264 - 18bigint

All typed array views have the same methods and properties, as defined by theTypedArray class. They only differ in the underlying data type and the size in bytes. This is discussed in more detail inValue encoding and normalization.

Typed arrays are, in principle, fixed-length, so array methods that may change the length of an array are not available. This includespop,push,shift,splice, andunshift. In addition,flat is unavailable because there are no nested typed arrays, and related methods includingconcat andflatMap do not have great use cases so are unavailable. Assplice is unavailable, so too istoSpliced. All other array methods are shared betweenArray andTypedArray.

On the other hand,TypedArray has the extraset andsubarray methods that optimize working with multiple typed arrays that view the same buffer. Theset() method allows setting multiple typed array indices at once, using data from another array or typed array. If the two typed arrays share the same underlying buffer, the operation may be more efficient as it's a fast memory move. Thesubarray() method creates a new typed array view that references the same buffer as the original typed array, but with a narrower span.

There's no way to directly change the length of a typed array without changing the underlying buffer. However, when the typed array views a resizable buffer and does not have a fixedbyteLength, it islength-tracking, and will automatically resize to fit the underlying buffer as the resizable buffer is resized. SeeBehavior when viewing a resizable buffer for details.

Similar to regular arrays, you can access typed array elements usingbracket notation. The corresponding bytes in the underlying buffer are retrieved and interpreted as a number. Any property access using a number (or the string representation of a number, since numbers are always converted to strings when accessing properties) will be proxied by the typed array — they never interact with the object itself. This means, for example:

  • Out-of-bounds index access always returnsundefined, without actually accessing the property on the object.
  • Any attempt to write to such an out-of-bounds property has no effect: it does not throw an error but doesn't change the buffer or typed array either.
  • Typed array indices appear to be configurable and writable, but any attempt to change their attributes will fail.
js
const uint8 = new Uint8Array([1, 2, 3]);console.log(uint8[0]); // 1// For illustrative purposes only. Not for production code.uint8[-1] = 0;uint8[2.5] = 0;uint8[NaN] = 0;console.log(Object.keys(uint8)); // ["0", "1", "2"]console.log(uint8[NaN]); // undefined// Non-numeric access still worksuint8[true] = 0;console.log(uint8[true]); // 0Object.freeze(uint8); // TypeError: Cannot freeze array buffer views with elements

DataView

TheDataView is a low-level interface that provides a getter/setter API to read and write arbitrary data to the buffer. This is useful when dealing with different types of data, for example. Typed array views are in the native byte-order (seeEndianness) of your platform. With aDataView, the byte-order can be controlled. By default, it's big-endian—the bytes are ordered from most significant to least significant. This can be reversed, with the bytes ordered from least significant to most significant (little-endian), using getter/setter methods.

DataView does not require alignment; multi-byte read and write can be started at any specified offset. The setter methods work the same way.

The following example uses aDataView to get the binary representation of any number:

js
function toBinary(  x,  { type = "Float64", littleEndian = false, separator = " ", radix = 16 } = {},) {  const bytesNeeded = globalThis[`${type}Array`].BYTES_PER_ELEMENT;  const dv = new DataView(new ArrayBuffer(bytesNeeded));  dv[`set${type}`](0, x, littleEndian);  const bytes = Array.from({ length: bytesNeeded }, (_, i) =>    dv      .getUint8(i)      .toString(radix)      .padStart(8 / Math.log2(radix), "0"),  );  return bytes.join(separator);}console.log(toBinary(1.1)); // 3f f1 99 99 99 99 99 9aconsole.log(toBinary(1.1, { littleEndian: true })); // 9a 99 99 99 99 99 f1 3fconsole.log(toBinary(20, { type: "Int8", radix: 2 })); // 00010100

Web APIs using typed arrays

These are some examples of APIs that make use of typed arrays; there are others, and more are being added all the time.

FileReader.prototype.readAsArrayBuffer()

TheFileReader.prototype.readAsArrayBuffer() method starts reading the contents of the specifiedBlob orFile.

fetch()

Thebody option tofetch() can be a typed array orArrayBuffer, enabling you to send these objects as the payload of aPOST request.

ImageData.data

Is aUint8ClampedArray representing a one-dimensional array containing the data in the RGBA order, with integer values between0 and255 inclusive.

Examples

Using views with buffers

First of all, we will need to create a buffer, here with a fixed length of 16-bytes:

js
const buffer = new ArrayBuffer(16);

At this point, we have a chunk of memory whose bytes are all pre-initialized to 0. There's not a lot we can do with it, though. For example, we can confirm that the buffer is the right size:

js
if (buffer.byteLength === 16) {  console.log("Yes, it's 16 bytes.");} else {  console.log("Oh no, it's the wrong size!");}

Before we can really work with this buffer, we need to create a view. Let's create a view that treats the data in the buffer as an array of 32-bit signed integers:

js
const int32View = new Int32Array(buffer);

Now we can access the fields in the array just like a normal array:

js
for (let i = 0; i < int32View.length; i++) {  int32View[i] = i * 2;}

This fills out the 4 entries in the array (4 entries at 4 bytes each makes 16 total bytes) with the values0,2,4, and6.

Multiple views on the same data

Things start to get really interesting when you consider that you can create multiple views onto the same data. For example, given the code above, we can continue like this:

js
const int16View = new Int16Array(buffer);for (let i = 0; i < int16View.length; i++) {  console.log(`Entry ${i}: ${int16View[i]}`);}

Here we create a 16-bit integer view that shares the same buffer as the existing 32-bit view and we output all the values in the buffer as 16-bit integers. Now we get the output0,0,2,0,4,0,6,0 (assuming little-endian encoding):

Int16Array  |   0  |  0   |   2  |  0   |   4  |  0   |   6  |  0   |Int32Array  |      0      |      2      |      4      |      6      |ArrayBuffer | 00 00 00 00 | 02 00 00 00 | 04 00 00 00 | 06 00 00 00 |

You can go a step farther, though. Consider this:

js
int16View[0] = 32;console.log(`Entry 0 in the 32-bit array is now ${int32View[0]}`);

The output from this is"Entry 0 in the 32-bit array is now 32".

In other words, the two arrays are indeed viewed on the same data buffer, treating it as different formats.

Int16Array  |  32  |  0   |   2  |  0   |   4  |  0   |   6  |  0   |Int32Array  |     32      |      2      |      4      |      6      |ArrayBuffer | 20 00 00 00 | 02 00 00 00 | 04 00 00 00 | 06 00 00 00 |

You can do this with any view type, although if you set an integer and then read it as a floating-point number, you will probably get a strange result because the bits are interpreted differently.

js
const float32View = new Float32Array(buffer);console.log(float32View[0]); // 4.484155085839415e-44

Reading text from a buffer

Buffers don't always represent numbers. For example, reading a file can give you a text data buffer. You can read this data out of the buffer using a typed array.

The following reads UTF-8 text using theTextDecoder web API:

js
const buffer = new ArrayBuffer(8);const uint8 = new Uint8Array(buffer);// Data manually written here, but pretend it was already in the bufferuint8.set([228, 189, 160, 229, 165, 189]);const text = new TextDecoder().decode(uint8);console.log(text); // "你好"

The following reads UTF-16 text using theString.fromCharCode() method:

js
const buffer = new ArrayBuffer(8);const uint16 = new Uint16Array(buffer);// Data manually written here, but pretend it was already in the bufferuint16.set([0x4f60, 0x597d]);const text = String.fromCharCode(...uint16);console.log(text); // "你好"

Working with complex data structures

By combining a single buffer with multiple views of different types, starting at different offsets into the buffer, you can interact with data objects containing multiple data types. This lets you, for example, interact with complex data structures fromWebGL or data files.

Consider this C structure:

c
struct someStruct {    unsigned long id;    char username[16];    float amountDue;};

You can access a buffer containing data in this format like this:

js
const buffer = new ArrayBuffer(24);// … read the data into the buffer …const idView = new Uint32Array(buffer, 0, 1);const usernameView = new Uint8Array(buffer, 4, 16);const amountDueView = new Float32Array(buffer, 20, 1);

Then you can access, for example, the amount due withamountDueView[0].

Note:Thedata structure alignment in a C structure is platform-dependent. Take precautions and considerations for these padding differences.

Conversion to normal arrays

After processing a typed array, it is sometimes useful to convert it back to a normal array in order to benefit from theArray prototype. This can be done usingArray.from():

js
const typedArray = new Uint8Array([1, 2, 3, 4]);const normalArray = Array.from(typedArray);

as well as thespread syntax:

js
const typedArray = new Uint8Array([1, 2, 3, 4]);const normalArray = [...typedArray];

See also

Help improve MDN

Learn how to contribute.

This page was last modified on byMDN contributors.


[8]ページ先頭

©2009-2025 Movatter.jp