mirror of https://github.com/svaarala/duktape.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
73 lines
3.0 KiB
73 lines
3.0 KiB
name: duk_get_buffer_data
|
|
|
|
proto: |
|
|
void *duk_get_buffer_data(duk_context *ctx, duk_idx_t idx, duk_size_t *out_size);
|
|
|
|
stack: |
|
|
[ ... val! ... ]
|
|
|
|
summary: |
|
|
<p>Get the data pointer for a plain buffer or a buffer object (ArrayBuffer,
|
|
Node.js Buffer, DataView, or TypedArray view) value at <code>idx</code> without
|
|
modifying or coercing the value. Return a non-<code>NULL</code> pointer if the
|
|
value is a valid buffer with a non-zero size. For a zero-size buffer, may return
|
|
a <code>NULL</code> or a non-<code>NULL</code> pointer. Returns <code>NULL</code>
|
|
if the value is not a buffer, the value is a buffer object whose "backing buffer"
|
|
doesn't fully cover the buffer object's apparent size, or the index is invalid.
|
|
If <code>out_size</code> is non-<code>NULL</code>, the size of the buffer is
|
|
written to <code>*out_size</code>; 0 is written if the return value is
|
|
<code>NULL</code>.</p>
|
|
|
|
<p>The data area indicated by the return pointer and length is the full
|
|
buffer for a plain buffer value, and the active "slice" for a buffer object.
|
|
The length returned is expressed in bytes (instead of elements), so that you
|
|
can always access <code>ptr[0]</code> to <code>ptr[len - 1]</code>.
|
|
For example:</p>
|
|
|
|
<ul>
|
|
<li>For <code>new Uint8Array(16)</code> the return pointer would point to
|
|
start of the array and length would be 16.</li>
|
|
<li>For <code>new Uint32Array(16)</code> the return pointer would point to
|
|
start of the array and length would be 64.</li>
|
|
<li>For <code>new Uint32Array(16).subarray(2, 6)</code> the return pointer
|
|
would point to the start of the subarray (2 x 4 = 8 bytes from the start
|
|
of the Uint32Array) and length would be 16 ((6-2) x 4).</li>
|
|
</ul>
|
|
|
|
<p>If the target value or the underlying buffer value of a buffer object is a
|
|
fixed buffer, the returned pointer is stable and won't change during the
|
|
lifetime of the buffer. For dynamic and external buffers the pointer may
|
|
change as the buffer is resized or reconfigured; the caller is responsible for
|
|
ensuring pointer values returned from this API call are not used after the
|
|
buffer is resized/reconfigured. Buffers created from Ecmascript code directly
|
|
e.g. as <code>new Buffer(8)</code> are backed by an automatic fixed buffer, so
|
|
their pointers are always stable.</p>
|
|
|
|
<p>In special cases it's possible that a buffer object is backed by a plain
|
|
buffer which is smaller than the buffer object's apparent size. In these
|
|
cases a <code>NULL</code> is returned; this ensures that the pointer and size
|
|
returned can always be used safely. (This behavior may change even in minor
|
|
versions.)</p>
|
|
|
|
<div include="buffer-null-pointer-ambiguity.html" />
|
|
|
|
example: |
|
|
void *ptr;
|
|
duk_size_t sz;
|
|
|
|
duk_eval_string(ctx, "new Uint16Array(16)");
|
|
ptr = duk_get_buffer_data(ctx, -1, &sz);
|
|
|
|
/* Here 'ptr' would be non-NULL and sz would be 32 (bytes). */
|
|
|
|
tags:
|
|
- stack
|
|
- buffer
|
|
- bufferobject
|
|
|
|
seealso:
|
|
- duk_require_buffer_data
|
|
- duk_get_buffer
|
|
- duk_require_buffer
|
|
|
|
introduced: 1.3.0
|
|
|