From b70367e8cf0f4eae8a4f0c92b1a8a1fa59fec288 Mon Sep 17 00:00:00 2001 From: Andreas Madsen Date: Mon, 9 Jul 2018 15:31:18 +0200 Subject: doc: add documentation for buffer.byteOffset Also document a common issue when casting a Buffer object to a TypedArray object. Fixes: https://github.com/nodejs/node/issues/19301 PR-URL: https://github.com/nodejs/node/pull/21718 Reviewed-By: Vse Mozhet Byt Reviewed-By: Luigi Pinca Reviewed-By: James M Snell Reviewed-By: Colin Ihrig Reviewed-By: Trivikram Kamat --- doc/api/buffer.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index c219f00e4a..8e1d1c325b 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -992,6 +992,31 @@ console.log(buffer.buffer === arrayBuffer); // Prints: true ``` +### buf.byteOffset + +* {integer} The `byteOffset` on the underlying `ArrayBuffer` object based on + which this `Buffer` object is created. + +When setting `byteOffset` in `Buffer.from(ArrayBuffer, byteOffset, length)` +or sometimes when allocating a buffer smaller than `Buffer.poolSize` the +buffer doesn't start from a zero offset on the underlying `ArrayBuffer`. + +This can cause problems when accessing the underlying `ArrayBuffer` directly +using `buf.buffer`, as the first bytes in this `ArrayBuffer` may be unrelated +to the `buf` object itself. + +A common issue is when casting a `Buffer` object to a `TypedArray` object, +in this case one needs to specify the `byteOffset` correctly: + +```js +// Create a buffer smaller than `Buffer.poolSize`. +const nodeBuffer = new Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); + +// When casting the Node.js Buffer to an Int8 TypedArray remember to use the +// byteOffset. +new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length); +``` + ### buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])