Add Buffer.concat method

We write out this loop a lot of places throughout node.
It clearly needs to be an API method.

doc/api/buffer.markdown

@@ -148,6 +148,26 @@ Example:
 
     // ½ + ¼ = ¾: 9 characters, 12 bytes
 
+### Class Method: Buffer.concat(list, [totalLength])
+
+* `list` {Array} List of Buffer objects to concat
+* `totalLength` {Number} Total length of the buffers when concatenated
+
+Returns a buffer which is the result of concatenating all the buffers in
+the list together.
+
+If the list has no items, or if the totalLength is 0, then it returns a
+zero-length buffer.
+
+If the list has exactly one item, then the first item of the list is
+returned.
+
+If the list has more than one item, then a new Buffer is created.
+
+If totalLength is not provided, it is read from the buffers in the list.
+However, this adds an additional loop to the function, so it is faster
+to provide the length explicitly.
+
 ### buf.length
 
 * Number

lib/buffer.js

@@ -469,6 +469,38 @@ Buffer.prototype.fill = function fill(value, start, end) {
 };
 
 
+Buffer.concat = function(list, length) {
+  if (!Array.isArray(list)) {
+    throw new Error('Usage: Buffer.concat(list, [length])');
+  }
+
+  if (list.length === 0) {
+    return new Buffer(0);
+  } else if (list.length === 1) {
+    return list[0];
+  }
+
+  if (typeof length !== 'number') {
+    length = 0;
+    for (var i = 0; i < list.length; i++) {
+      var buf = list[i];
+      length += buf.length;
+    }
+  }
+
+  var buffer = new Buffer(length);
+  var pos = 0;
+  for (var i = 0; i < list.length; i++) {
+    var buf = list[i];
+    buf.copy(buffer, pos);
+    pos += buf.length;
+  }
+  return buffer;
+};
+
+
+
+
 // copy(targetBuffer, targetStart=0, sourceStart=0, sourceEnd=buffer.length)
 Buffer.prototype.copy = function(target, target_start, start, end) {
   var source = this;

test/simple/test-buffer-concat.js

@@ -0,0 +1,41 @@
+// Copyright Joyent, Inc. and other Node 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 zero = [];
+var one  = [ new Buffer('asdf') ];
+var long = [];
+for (var i = 0; i < 10; i++) long.push(new Buffer('asdf'));
+
+var flatZero = Buffer.concat(zero);
+var flatOne = Buffer.concat(one);
+var flatLong = Buffer.concat(long);
+var flatLongLen = Buffer.concat(long, 40);
+
+assert(flatZero.length === 0);
+assert(flatOne.toString() === 'asdf');
+assert(flatOne === one[0]);
+assert(flatLong.toString() === (new Array(10+1).join('asdf')));
+assert(flatLongLen.toString() === (new Array(10+1).join('asdf')));
+
+console.log("ok");