From 30b0bc4fa93ae553cd61484a0da34aa697708e63 Mon Sep 17 00:00:00 2001 From: Ben Noordhuis Date: Sun, 10 Feb 2013 21:41:06 +0100 Subject: [PATCH] doc: update buffer/typed array documentation Clarify that typed array constructors accept buffers as their first argument but that the memory is not shared and why this was changed in v0.9. --- doc/api/buffer.markdown | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index 9d924490203..d187225a4f5 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -40,22 +40,16 @@ encoding method. Here are the different string encodings. * `'hex'` - Encode each byte as two hexadecimal characters. -`Buffer` can also be used with Typed Array Views and DataViews. +A `Buffer` object can also be used with typed arrays. The buffer object is +cloned to an `ArrayBuffer` that is used as the backing store for the typed +array. The memory of the buffer and the `ArrayBuffer` is not shared. - var buff = new Buffer(4); - var ui16 = new Uint16Array(buff); - var view = new DataView(buff); +NOTE: Node.js v0.8 simply retained a reference to the buffer in `array.buffer` +instead of cloning it. - ui16[0] = 1; - ui16[1] = 2; - console.log(buff); - - view.setInt16(0, 1); // set big-endian int16 at byte offset 0 - view.setInt16(2, 2, true); // set little-endian int16 at byte offset 2 - console.log(buff); - - // - // +While more efficient, it introduces subtle incompatibilities with the typed +arrays specification. `ArrayBuffer#slice()` and `Buffer#slice()` behave +differently when passed negative indices, for example. ## Class: Buffer