Typed arrays

Artigo
11/03/2017

The Typed Arrays API enables web applications to use a broad range of binary file formats and directly manipulate the binary contents of files already supported by Internet Explorer 10. You can use typed arrays to handle binary data from sources such as network protocols, binary file formats, and raw graphics buffers. Typed arrays can also be used to manage in-memory binary data with well-known byte layouts.

Support for typed arrays has been added throughout Internet Explorer 10: in JavaScript, in XMLHttpRequest, in the File API, and in the Streams API.

Typed arrays provide a means to look at raw binary contents of data through a particular typed view. For example, if we want to look at our raw binary data one byte at a time, we can use a Uint8Array (Uint8 describes an 8-bit unsigned integer value, commonly known as a byte). If we want to read the raw data as an array of floating point numbers, we can use a Float32Array (Float32 describes a 32-bit IEE754 floating point value, commonly known as a floating point number). The following types are supported:

Array type	Element size and description
Int8Array	8-bit signed integer
Uint8Array	8-bit unsigned integer
Int16Array	16-bit signed integer
Uint16Array	16-bit unsigned integer
Int32Array	32-bit signed integer
Uint32Array	32-bit unsigned integer
Float32Array	32-bit IEEE754 floating point number
Float64Array	64-bit IEEE754 floating point number

The ArrayBuffer object

Each array type is a view over an ArrayBuffer. The ArrayBuffer is a reference to the raw binary data, but it doesn't provide any direct way to interact with the data. Creating a TypedArray view of the ArrayBuffer provides access to read from and write to the binary contents.

The following example creates a new ArrayBuffer from scratch and interprets its contents in a few different ways:

// Create an 8 byte buffer
var buffer = new ArrayBuffer(8);


// View as an array of Uint8s and put 0x05 in each byte
var uint8s = new Uint8Array(buffer);
for (var i = 0; i < 8; i++) {
    uint8s[i] = 5; // fill each byte with 0x05
}

 
// Inspect the resulting array
uint8s[0] === 5; // true - each byte has value 5
uint8s.byteLength === 8; // true - there are 8 Uint8s


// View the same buffer as an array of Uint32s 
var uint32s = new Uint32Array(buffer);

 
// The same raw bytes are now interpreted differently
uint32s[0] === 84215045 // true - 0x05050505 == 84215045

In this way, typed arrays can be used for tasks such as creating floating point values from their byte-level components or for building data structures that require a very specific layout of data for efficiency or data format interoperation.

The DataView object

Typed arrays enable an important new scenario, which is to read and render the contents of custom binary file formats that aren't natively supported by the browser. In addition to the various array types introduced previously in this topic, typed arrays also provide a DataView object that can be used to read and write the contents of an ArrayBuffer in an unstructured way. This is well suited to reading new file formats, which are typically made up of heterogeneous mixes of data.

The following example uses the DataView object to read a PCX image file header, which includes information like the width, height, DPI, and bits-per-pixel of color depth.

var buffer = getPCXFileContents();
var reader = new DataView(buffer);

 
// Read the header of the PCX file
var header = {}

 
// The first section is single bytes 
header.manufacturer = reader.getUint8(0);
header.version = reader.getUint8(1);
header.encoding = reader.getUint8(2);
header.bitsPerPixel = reader.getUint8(3);


// The next section is Int16 values, each in little-endian
header.xmin = reader.getInt16(4, true);
header.ymin = reader.getInt16(6, true);
header.xmax = reader.getInt16(8, true);
header.ymax = reader.getInt16(10, true);
header.hdpi = reader.getInt16(12, true);
header.vdpi = reader.getInt16(14, true);

You can use code similar to this example to add support for rendering a broad range of new data formats in the browser. This includes examples like custom image formats, additional video file formats, or domain-specific map data formats.

Getting binary data with XHR and File API

For accessing files from the server, the XMLHttpRequest API has been extended with support for various “responseType”s. The “arraybuffer” responseType provides the contents of the requested server resource to JavaScript as an ArrayBuffer object. The “blob,” “text” and “document” response types are also supported.

function getServerFileToArrayBufffer(url, successCallback) {
    // Create an XHR object
    var xhr = new XMLHttpRequest();


    xhr.onreadystatechange = function () { 
        if (xhr.readyState == xhr.DONE) {
            if (xhr.status == 200 && xhr.response) {
                // The 'response' property returns an ArrayBuffer
                successCallback(xhr.response);
            } else {
                alert("Failed to download:" + xhr.status + " " + xhr.statusText);
            }
        }
    }

 
    // Open the request for the provided url 
    xhr.open("GET", url, true);


    // Set the responseType to 'arraybuffer' for ArrayBuffer response 
    xhr.responseType = "arraybuffer";

     
    xhr.send();
}

In many cases, files are provided by the user, for example as an attachment to an email in a web mail application. The File API offers web developers tools to read the contents of files provided via an input element, drag-and-drop of files from the Desktop to a website, or any other source that provides blobs or files. The FileReader object is used to read the contents of a file into an ArrayBuffer and, like the XHR object, is asynchronous to ensure that reading from the disk doesn't prevent the user interface from responding.

function readFileToArrayBuffer(file, successCallback) {
    // Create a FileReader 
    var reader = new FileReader();


    // Register for 'load' and 'error' events
    reader.onload = function () {
        // The 'result' property returns an ArrayBuffer for readAsArrayBuffer 
        var buffer = reader.result;
        successCallback(buffer);
    }


    reader.onerror = function (evt) {
        // The error code indicates the reason for failure
        if (evt.target.error.name == "NotReadableError") {
            alert("Failed to read file: " + file.name);
        }
    }


    // Begin a read of the file contents into an ArrayBuffer
    reader.readAsArrayBuffer(file);
}