Buffer objects

Overview of buffer types

Duktape provides the following buffer and buffer-related types:

Type Standard Duktape version Description
Plain buffer No
Duktape specific
1.0 Plain, primitive buffer value (not an object), similar to how a plain string relates to a String object. Behaves like an Uint8Array instance where possible, object coerces to an actual Uint8Array.
ArrayBuffer object Yes
ES2015
1.3 Standard object type for representing a byte array. References an underlying plain buffer.
DataView, typed array objects Yes
ES2015
1.3 View objects to access an underlying ArrayBuffer. References an underlying plain buffer.
Node.js Buffer object No
Node.js-like
1.3 Object with Node.js Buffer API, inherits from Uint8Array.prototype. References an underlying plain buffer.

See buffers.rst for a detailed discussion, including a detailed table of buffer types and their properties.

Plain buffers

Plain buffers are a non-standard memory efficient way of representing buffer data. Plain buffers mimic Uint8Array objects so that they inherit from Uint8Array.prototype, are accepted as typed array constructor arguments, and so on. While plain buffers don't have a property table and can't hold properties of their own, they have the following virtual or inherited properties (example values are for a 24-byte buffer):

Property name Example value Description
[index] 0-255 Index properties in the range [0, length-1]. Reads and writes behave like for Uint8Array.
length 24 Length of buffer in bytes. Length is not writable, so you can't resize a buffer by assigning its length.
byteOffset 0 Always 0, present to match typed arrays.
byteLength 24 Same as .length.
BYTES_PER_ELEMENT 1 Always 1, present to match typed arrays.
buffer   Getter property which returns a new ArrayBuffer instance backing to the plain buffer without making a copy. Because plain buffers don't have a property table, a new ArrayBuffer is created on every property read. Absent if buffer object support is disabled in Duktape configuration.

Buffer objects like ArrayBuffer and Node.js Buffer are implemented on top of plain buffer values and provide additional functionality like view/slice support, typed accessors, and methods to manipulate data in different endianness. However, they have more overhead than plain buffers.

For more details, see:

Working with buffers

Buffer values work in both C and ECMAScript code:

See How to work with buffers for examples.

In special cases the plain buffer backing a buffer object may not be large enough to cover the apparent size of the buffer object; the buffer object is then "uncovered" or "unbacked". Duktape guarantees memory safe behavior for such buffers, but other than that behavior varies between calls. For example, a call may ignore the situation silently returning undefined, NaN, or zero, or it may throw a TypeError. The behavior for unbacked buffers is not part of versioning guarantees and may change between minor versions.

Current limitations