From f5620ba9f530012a66b6e67bd52ecc641f96c6aa Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 16 Dec 2014 09:04:11 -0800 Subject: [PATCH 1/5] Documentation improvement on buffer.copy.. per https://github.com/joyent/node/issues/8857 --- doc/api/buffer.markdown | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index b384b05f43d..308ab36f7e4 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -259,12 +259,10 @@ the same as the `otherBuffer` in sort order. * `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 not specified or passed +as `undefined`/`NaN`, the `targetStart` and `sourceStart` parameters default +to `0` and `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`. @@ -282,6 +280,19 @@ 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('ascii')); + + // efghijghijklmnopqrstuvwxyz ### buf.slice([start], [end]) From 83602574e84b26d83c3ce500faa34a0a94645108 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 16 Dec 2014 09:18:37 -0800 Subject: [PATCH 2/5] Alternative fix for https://github.com/joyent/node/issues/8859 (there's an alternate proposed fix here: https://github.com/zetxx/node/commit/c691bf340effde7974e25e3be2aa409bf14 c2012) --- doc/api/buffer.markdown | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index 308ab36f7e4..b37b8167011 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -187,12 +187,19 @@ The method will not write partial characters. * `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`). - -See `buffer.write()` example, above. +Decodes and returns a string from buffer data encoded using the specified +character set encoding. If `encoding` is not specified or is `undefined` or +`null`, `encoding` defaults to `'utf8'. The `start` and `end` parameters +default to `0` and `buffer.length` when not specified or passed as `undefined`/`NaN`. + 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 ### buf.toJSON() From 863e7189ed0e5781077022f1e5cbc4b604aaf153 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 16 Dec 2014 12:13:15 -0800 Subject: [PATCH 3/5] Revert "Alternative fix for https://github.com/joyent/node/issues/8859" This reverts commit 83602574e84b26d83c3ce500faa34a0a94645108. --- doc/api/buffer.markdown | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index b37b8167011..308ab36f7e4 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -187,19 +187,12 @@ The method will not write partial characters. * `start` Number, Optional, Default: 0 * `end` Number, Optional, Default: `buffer.length` -Decodes and returns a string from buffer data encoded using the specified -character set encoding. If `encoding` is not specified or is `undefined` or -`null`, `encoding` defaults to `'utf8'. The `start` and `end` parameters -default to `0` and `buffer.length` when not specified or passed as `undefined`/`NaN`. +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`). + +See `buffer.write()` example, above. - 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 ### buf.toJSON() From ef513cbcaf01a77a384442f5cccdb4cb8fdc4f13 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 16 Dec 2014 12:13:22 -0800 Subject: [PATCH 4/5] Revert "Documentation improvement on buffer.copy.. per" This reverts commit f5620ba9f530012a66b6e67bd52ecc641f96c6aa. --- doc/api/buffer.markdown | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index 308ab36f7e4..b384b05f43d 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -259,10 +259,12 @@ the same as the `otherBuffer` in sort order. * `sourceStart` Number, Optional, Default: 0 * `sourceEnd` Number, Optional, Default: `buffer.length` -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 not specified or passed -as `undefined`/`NaN`, the `targetStart` and `sourceStart` parameters default -to `0` and `sourceEnd` defaults to `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. Example: build two Buffers, then copy `buf1` from byte 16 through byte 19 into `buf2`, starting at the 8th byte in `buf2`. @@ -280,19 +282,6 @@ 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('ascii')); - - // efghijghijklmnopqrstuvwxyz ### buf.slice([start], [end]) From 60724d1c337d91df2f36d909c675691c06ea8581 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 16 Dec 2014 13:02:30 -0800 Subject: [PATCH 5/5] Documentation improvement for https://github.com/joyent/node/issues/8853 ... specifically, acknowledge in the docs that EE.addListener(...) does not check to see if the given listener has already been added, and that newListener will be called regardless of whether an already existing listener is added twice. --- doc/api/events.markdown | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/doc/api/events.markdown b/doc/api/events.markdown index 1625f748a17..511bda974de 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -33,7 +33,10 @@ added and `'removeListener'` when a listener is removed. ### emitter.addListener(event, listener) ### emitter.on(event, listener) -Adds a listener to the end of the listeners array for the specified event. +Adds a listener to the end of the listeners array for the specified `event`. +No checks are made to see if the `listener` has already been added. Multiple +calls passing the same combination of `event` and `listener` will result +in the `listener` being added multiple times. server.on('connection', function (stream) { console.log('someone connected!'); @@ -65,6 +68,11 @@ Remove a listener from the listener array for the specified event. // ... server.removeListener('connection', callback); +`removeListener` will remove, at most, one instance of a listener from the +listener array. If any single listener has been added multiple times to the +listener array for the specified `event`, then `removeListener` must be called +multiple times to remove each instance. + Returns emitter, so calls can be chained. ### emitter.removeAllListeners([event]) @@ -121,8 +129,9 @@ Return the number of listeners for a given event. * `event` {String} The event name * `listener` {Function} The event handler function -This event is emitted any time someone adds a new listener. It is unspecified -if `listener` is in the list returned by `emitter.listeners(event)`. +This event is emitted any time someone adds a listener, even if the added +listener was previously already added to the listeners array for the given +`event`. ### Event: 'removeListener'