JavaScript Typed Arrays: Beginners Guide

are array-like objects that provide a mechanism for reading and writing raw binary data in memory buffers. As you may already know, objects grow and shrink dynamically and can have any JavaScript value. JavaScript engines perform optimizations so that these arrays are fast. JavaScript typed arrays Array However, as web applications become more and more powerful, adding features such as audio and video manipulation, access to raw data using WebSockets, and so forth, it has become clear that there are times when it would be helpful for JavaScript code to be able to quickly and easily manipulate raw binary data. This is where typed arrays come in. 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. However, typed arrays are to be confused with normal arrays, as calling on a typed array returns . Moreover, not all methods available for normal arrays are supported by typed arrays (e.g. push and pop). not Array.isArray() false Buffers and views: typed array architecture To achieve maximum flexibility and efficiency, JavaScript typed arrays split the implementation into and . A buffer (implemented by the object) 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 a view. A view provides a context — that is, a data type, starting offset, and the number of elements — that turns the data into a typed array. buffers views ArrayBuffer The is a data type that is used to represent a generic, fixed-length binary data buffer. You can't directly manipulate the contents of an ; instead, you create a typed array view or a which represents the buffer in a specific format, and use that to read and write the contents of the buffer. ArrayBuffer ArrayBuffer ArrayBuffer DataView Typed array views have self-descriptive names and provide views for all the usual numeric types like , , and so forth. There is one special typed array view, the . It clamps the values between 0 and 255. This is useful for , for example. Typed array views Int8 Uint32 Float64 Uint8ClampedArray Canvas data processing Int8Array Description: 8-bit two's complement signed integer Value Range: to -128 127 Size in bytes: 1 Web IDL type: byte Equivalent C type: int8_t Uint8Array Description: 8-bit unsigned integer Value Range: to 0 255 Size in bytes: 1 Web IDL type: octet Equivalent C type: uint8_t Uint8ClampedArray Description: 8-bit unsigned integer (clamped) Value Range: to 0 255 Size in bytes: 1 Web IDL type: octet Equivalent C type: uint8_t Int16Array Description: 16-bit two's complement signed integer Value Range: to -32768 32767 Size in bytes: 2 Web IDL type: short Equivalent C type: int16_t Uint16Array Description: 16-bit unsigned integer Value Range: to 0 65535 Size in bytes: 2 Web IDL type: unsigned short Equivalent C type: uint16_t Int32Array Description: 32-bit two's complement signed integer Value Range: to -2147483648 2147483647 Size in bytes: 4 Web IDL type: long Equivalent C type: int32_t Uint32Array Description: 32-bit unsigned integer Value Range: to 0 4294967295 Size in bytes: 4 Web IDL type: unsigned long Equivalent C type: uint32_t Float32Array Description: 32-bit IEEE floating point number (7 significant digits e.g., ) 1.123456 Value Range: to 1.2×10^-38 3.4×10^38 Size in bytes: 4 Web IDL type: unrestricted float Equivalent C type: float Float64Array Description: 64-bit IEEE floating point number (16 significant digits e.g., ) 1.123...15 Value Range: to 5.0×10^-324 1.8×10^308 Size in bytes: 8 Web IDL type: unrestricted double Equivalent C type: double BigInt64Array Description: 64-bit two's complement signed integer Value Range: to -2^63 2^63-1 Size in bytes: 8 Web IDL type: bigint Equivalent C type: int64_t (signed long long) BigUint64Array Description: 64-bit unsigned integer Value Range: to 0 2^64-1 Size in bytes: 8 Web IDL type: bigint Equivalent C type: uint64_t (unsigned long long) DataView The 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 (see ) of your platform. With a you are able to control the byte-order. It is big-endian by default and can be set to little-endian in the getter/setter methods. DataView Endianness DataView 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() The method starts reading the contents of the specified or . FileReader.prototype.readAsArrayBuffer() Blob File XMLHttpRequest.prototype.send() instances' method now supports typed arrays and objects as argument. XMLHttpRequest send() ArrayBuffer ImageData.data Is a representing a one-dimensional array containing the data in the RGBA order, with integer values between and inclusive. Uint8ClampedArray 0 255 Examples Using views with buffers First of all, we will need to create a buffer, here with a fixed length of 16-bytes: buffer = ( ); let 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. We can confirm that it is indeed 16 bytes long, and that's about it: (buffer.byteLength === ) { .log( ); } { .log( ); } if 16 console "Yes, it's 16 bytes." else console "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: int32View = (buffer); let new Int32Array Now we can access the fields in the array just like a normal array: ( i = ; i < int32View.length; i++) { int32View[i] = i * ; } for let 0 2 This fills out the 4 entries in the array (4 entries at 4 bytes each makes 16 total bytes) with the values , , , and . 0 2 4 6 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: Multiple views on the same data int16View = (buffer); ( i = ; i < int16View.length; i++) { .log( + i + + int16View[i]); } let new Int16Array for let 0 console 'Entry ' ': ' 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 output , , , , , , , . 0 0 2 0 4 0 6 0 You can go a step farther, though. Consider this: int16View[ ] = ; .log( + int32View[ ]); 0 32 console 'Entry 0 in the 32-bit array is now ' 0 The output from this is . "Entry 0 in the 32-bit array is now 32" In other words, the two arrays are indeed simply viewed on the same data buffer, treating it as different formats. You can do this with any . view types 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 from , data files, or C structures you need to use while using . Working with complex data structures WebGL js-ctypes Consider this C structure: struct someStruct { unsigned long id; char username[ ]; float amountDue; }; 16 You can access a buffer containing data in this format like this: buffer = ( ); idView = (buffer, , ); usernameView = (buffer, , ); amountDueView = (buffer, , ); let new ArrayBuffer 24 // ... read the data into the buffer ... let new Uint32Array 0 1 let new Uint8Array 4 16 let new Float32Array 20 1 Then you can access, for example, the amount due with . amountDueView[0] The in a C structure is platform-dependent. Take precautions and considerations for these padding differences. Note: data structure alignment After processing a typed array, it is sometimes useful to convert it back to a normal array in order to benefit from the prototype. This can be done using , or using the following code where is unsupported. Conversion to normal arrays Array Array.from() Array.from() typedArray = ([ , , , ]), normalArray = .prototype.slice.call(typedArray); normalArray.length === ; normalArray.constructor === ; let new Uint8Array 1 2 3 4 Array 4 Array Specifications ECMAScript (ECMA-262) The definition of 'TypedArray Objects' in that specification. Browser compatibility See also Getting ArrayBuffers or typed arrays from -encoded strings Base64 StringView – a C-like representation of strings based on typed arrays Faster Canvas Pixel Manipulation with Typed Arrays Typed Arrays: Binary Data in the Browser Endianness Credits Source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays Published under license Open CC Attribution ShareAlike 3.0