<h1 id="bufferobjects">Buffer objects</h1>

<h2>Overview of buffer types</h2>

<p>Duktape provides the following buffer and buffer-related types:</p>

<th>Type</th>

<th>Standard</th>

<th>Duktape version</th>

<th>Description</th>

<td>Plain buffer</td>

<td>No<br />Duktape&nbsp;specific</td>

<td>1.0</td>

<td>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 <code>Uint8Array</code>.</td>

<td>ArrayBuffer object</td>

<td>Yes<br />ES2015</td>

<td>1.3</td>

<td>Standard object type for representing a byte array. References an underlying plain buffer.</td>

<td>DataView, typed array objects</td>

<td>Yes<br />ES2015</td>

<td>1.3</td>

<td>View objects to access an underlying ArrayBuffer. References an underlying plain buffer.</td>

<td>Node.js Buffer object</td>

<td>No<br />Node.js-like</td>

<td>1.3</td>

<td>Object with <a href="https://nodejs.org/api/buffer.html">Node.js Buffer API</a>,

inherits from Uint8Array.prototype. References an underlying plain buffer.</td>

<p>See <a href="https://github.com/svaarala/duktape/blob/master/doc/buffers.rst">buffers.rst</a>

for a detailed discussion, including a

<a href="https://github.com/svaarala/duktape/blob/master/doc/buffers.rst#summary-of-buffer-related-values">detailed table of buffer types and their properties</a>.</p>

<h2>Plain buffers</h2>

<p>Plain buffers are a non-standard memory efficient way of representing

buffer data. Plain buffers mimic Uint8Array objects so that they inherit

from <code>Uint8Array.prototype</code>, 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):</p>

<th>Property name</th>

<th>Example value</th>

<th>Description</th>

<td>[index]</td>

<td>0-255</td>

<td>Index properties in the range [0, length-1]. Reads and writes behave

like for <code>Uint8Array</code>.</td>

<td class="propname">length</td>

<td>24</td>

<td>Length of buffer in bytes. Length is not writable, so you can't resize

a buffer by assigning its length.</td>

<td class="propname">byteOffset</td>

<td>0</td>

<td>Always 0, present to match typed arrays.</td>

<td class="propname">byteLength</td>

<td>24</td>

<td>Same as <code>.length</code>.</td>

<td class="propname">BYTES_PER_ELEMENT</td>

<td>1</td>

<td>Always 1, present to match typed arrays.</td>

<td class="propname">buffer</td>

<td>&nbsp;</td>

<td>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.</td>

<p>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.</p>

<p>For more details, see:</p>

<li><a href="http://wiki.duktape.org/HowtoBuffers.html">How to work with buffers</a></li>

<li><a href="#typealgorithms">Type algorithms</a></li>

<li><a href="https://github.com/svaarala/duktape/blob/master/doc/buffers.rst">buffers.rst</a></li>

<h2>Working with buffers</h2>

<p>Buffer values work in both C and ECMAScript code:</p>

<li>For ECMAScript code most of the behavior is defined in the relevant API

standards, with exceptions for Duktape-specific features like mixing

different buffer types.</li>

<li>For C code there are API calls to work with

<a href="api.html#taglist-buffer">plain buffers</a> and

<a href="api.html#taglist-bufferobject">buffer objects</a>.</li>

<p>See

<a href="http://wiki.duktape.org/HowtoBuffers.html">How to work with buffers</a>

for examples.</p>

<div class="note">

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. <b>The behavior for unbacked buffers is

not part of versioning guarantees and may change between minor versions.</b>

<h2>Current limitations</h2>

<li>See <a href="#typedarray-custombehavior">TypedArray binding</a> custom

behavior.</li>

<li>See <a href="#nodejsbuffer-custombehavior">Node.js Buffer binding</a> custom

behavior.</li>