Add Buffer.concat method

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

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown
index 82a36eedc6..ff95304ed6 100644
--- a/doc/api/buffer.markdown
+++ b/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