buffer: implement iterable interface

This makes possible to use `for..of` loop with buffers. Also related `keys`, `values` and `entries` methods are added for feature parity with `Uint8Array`.
vkurchatkin · Dec 23, 2014 · Dec 29, 2014 · Jan 21, 2015 · Jan 20, 2015 · 47a5310ccc737366868cb84ddd499f018610e570
commit 47a5310ccc737366868cb84ddd499f018610e570
diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown
@@ -797,6 +797,19 @@ buffer.
     var b = new Buffer(50);
     b.fill("h");
 
+### buffer.values()
+
+Creates iterator for buffer values (bytes). This function is called automatically
+when `buffer` is used in a `for..of` statement.
+
+### buffer.keys()
+
+Creates iterator for buffer keys (indices).
+
+### buffer.entries()
+
+Creates iterator for `[index, byte]` arrays.
+
 ## buffer.INSPECT_MAX_BYTES
 
 * Number, Default: 50
@@ -807,6 +820,22 @@ be overridden by user modules.
 Note that this is a property on the buffer module returned by
 `require('buffer')`, not on the Buffer global, or a buffer instance.
 
+## ES6 iteration
+
+Buffers can be iterated over using `for..of` syntax:
+
+    var buf = new Buffer([1, 2, 3]);
+
+    for (var b of buf)
+      console.log(b)
+
+    // 1
+    // 2
+    // 3
+
+Additionally, `buffer.values()`, `buffer.keys()` and `buffer.entries()`
+methods can be used to create iterators.
+
 ## Class: SlowBuffer
 
 Returns an un-pooled `Buffer`.

diff --git a/lib/buffer.js b/lib/buffer.js
@@ -930,3 +930,57 @@ Buffer.prototype.writeDoubleBE = function writeDoubleBE(val, offset, noAssert) {
   internal.writeDoubleBE(this, val, offset);
   return offset + 8;
 };
+
+// ES6 iterator
+
+var ITERATOR_KIND_KEYS = 1;
+var ITERATOR_KIND_VALUES = 2;
+var ITERATOR_KIND_ENTRIES = 3;
+
+function BufferIterator(buffer, kind) {
+  this._buffer = buffer;
+  this._kind = kind;
+  this._index = 0;
+}
+
+function BufferIteratorResult(value, done) {
+  this.value = value;
+  this.done = done;
+}
+
+BufferIterator.prototype.next = function() {
+  var buffer = this._buffer;
+  var kind = this._kind;
+  var index = this._index;
+
+  if (index >= buffer.length)
+    return new BufferIteratorResult(undefined, true);
+
+  this._index++;
+
+  if (kind === ITERATOR_KIND_VALUES)
+    return new BufferIteratorResult(buffer[index], false);
+
+  if (kind === ITERATOR_KIND_ENTRIES)
+    return new BufferIteratorResult([index, buffer[index]], false);
+
+  return new BufferIteratorResult(index, false);
+};
+
+BufferIterator.prototype[Symbol.iterator] = function() {
+  return this;
+};
+
+Buffer.prototype.keys = function() {
+  return new BufferIterator(this, ITERATOR_KIND_KEYS);
+};
+
+Buffer.prototype.entries = function() {
+  return new BufferIterator(this, ITERATOR_KIND_ENTRIES);
+};
+
+Buffer.prototype.values = function() {
+  return new BufferIterator(this, ITERATOR_KIND_VALUES);
+};
+
+Buffer.prototype[Symbol.iterator] = Buffer.prototype.values;
diff --git a/test/parallel/test-buffer-iterator.js b/test/parallel/test-buffer-iterator.js
@@ -0,0 +1,82 @@
+// Copyright io.js contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+var common = require('../common');
+var assert = require('assert');
+
+var buffer = new Buffer([1, 2, 3, 4, 5]);
+var arr;
+var b;
+
+// buffers should be iterable
+
+arr = [];
+
+for (b of buffer)
+    arr.push(b);
+
+assert.deepEqual(arr, [1, 2, 3, 4, 5]);
+
+
+// buffer iterators should be iterable
+
+arr = [];
+
+for (b of buffer[Symbol.iterator]())
+  arr.push(b);
+
+assert.deepEqual(arr, [1, 2, 3, 4, 5]);
+
+
+// buffer#values() should return iterator for values
+
+arr = [];
+
+for (b of buffer.values())
+  arr.push(b);
+
+assert.deepEqual(arr, [1, 2, 3, 4, 5]);
+
+
+// buffer#keys() should return iterator for keys
+
+arr = [];
+
+for (b of buffer.keys())
+  arr.push(b);
+
+assert.deepEqual(arr, [0, 1, 2, 3, 4]);
+
+
+// buffer#entries() should return iterator for entries
+
+arr = [];
+
+for (var b of buffer.entries())
+  arr.push(b);
+
+assert.deepEqual(arr, [
+  [0, 1],
+  [1, 2],
+  [2, 3],
+  [3, 4],
+  [4, 5]
+]);