diff options
author | James M Snell <jasnell@gmail.com> | 2014-12-19 09:46:44 -0800 |
---|---|---|
committer | Timothy J Fontaine <tjfontaine@gmail.com> | 2014-12-22 12:24:28 -0800 |
commit | 102a861ec2e79ee78d8b8526fa410aac5db18753 (patch) | |
tree | 78d81b8aee1a100b0105160d6ba60c3eecebfeca /doc/api | |
parent | 48536394c954b2e3e41dcaee3778373ea79e2c25 (diff) | |
download | node-102a861ec2e79ee78d8b8526fa410aac5db18753.tar.gz |
doc: clarify buffer api documentation
Better wording for start and end parameters, also document .length
should be considered readonly.
RE: #8857, #8859, #8913
PR: #8910
PR-URL: https://github.com/joyent/node/pull/8910
Signed-off-by: Timothy J Fontaine <tjfontaine@gmail.com>
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/buffer.markdown | 51 |
1 files changed, 42 insertions, 9 deletions
diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index b042300d3..ccc2e62ea 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -118,9 +118,19 @@ next time `buf.write()` is called. * `start` Number, Optional, Default: 0 * `end` Number, Optional, Default: `buffer.length` -Decodes and returns a string from buffer data encoded with `encoding` -(defaults to `'utf8'`) beginning at `start` (defaults to `0`) and ending at -`end` (defaults to `buffer.length`). +Decodes and returns a string from buffer data encoded using the specified +character set encoding. If `encoding` is `undefined` or `null`, then `encoding` +defaults to `'utf8'. The `start` and `end` parameters default to `0` and +`buffer.length` when `undefined`. + + buf = new Buffer(26); + for (var i = 0 ; i < 26 ; i++) { + buf[i] = i + 97; // 97 is ASCII a + } + buf.toString('ascii'); // outputs: abcdefghijklmnopqrstuvwxyz + buf.toString('ascii',0,5); // outputs: abcde + buf.toString('utf8',0,5); // outputs: abcde + buf.toString(undefined,0,5); // encoding defaults to 'utf8', outputs abcde See `buffer.write()` example, above. @@ -228,6 +238,17 @@ buffer object. It does not change when the contents of the buffer are changed. // 1234 // 1234 +While the `length` property is not immutable, changing the value of `length` +can result in undefined and inconsistent behavior. Applications that wish to +modify the length of a buffer should therefore treat `length` as read-only and +use `buf.slice` to create a new buffer. + + buf = new Buffer(10); + buf.write("abcdefghj", 0, "ascii"); + console.log(buf.length); // 10 + buf = buf.slice(0,5); + console.log(buf.length); // 5 + ### buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd]) * `targetBuffer` Buffer object - Buffer to copy into @@ -235,12 +256,10 @@ buffer object. It does not change when the contents of the buffer are changed. * `sourceStart` Number, Optional, Default: 0 * `sourceEnd` Number, Optional, Default: `buffer.length` -Does copy between buffers. The source and target regions can be overlapped. -`targetStart` and `sourceStart` default to `0`. -`sourceEnd` defaults to `buffer.length`. - -All values passed that are `undefined`/`NaN` or are out of bounds are set equal -to their respective defaults. +Copies data from a region of this buffer to a region in the target buffer even +if the target memory region overlaps with the source. If `undefined` the +`targetStart` and `sourceStart` parameters default to `0` while `sourceEnd` +defaults to `buffer.length`. Example: build two Buffers, then copy `buf1` from byte 16 through byte 19 into `buf2`, starting at the 8th byte in `buf2`. @@ -258,6 +277,20 @@ into `buf2`, starting at the 8th byte in `buf2`. // !!!!!!!!qrst!!!!!!!!!!!!! +Example: Build a single buffer, then copy data from one region to an overlapping +region in the same buffer + + buf = new Buffer(26); + + for (var i = 0 ; i < 26 ; i++) { + buf[i] = i + 97; // 97 is ASCII a + } + + buf.copy(buf, 0, 4, 10); + console.log(buf.toString()); + + // efghijghijklmnopqrstuvwxyz + ### buf.slice([start], [end]) |