doc: add documentation for buffer.byteOffset

Also document a common issue when casting a Buffer object to a TypedArray object. Fixes: #19301 PR-URL: #21718 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
nodejs · Jul 9, 2018 · 53b587a5afa3811e1e8c3b052a04380858dd3f30 · 53b587a
1 parent 8c97ffb
commit 53b587a5afa3811e1e8c3b052a04380858dd3f30
Unified Split

Showing with 25 additions and 0 deletions.

+25 −0 doc/api/buffer.md
diff --git 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]]]])
 <!-- YAML
 added: v0.11.13