buffer: add .from(), .alloc() and .allocUnsafe()

Several changes:

* Soft-Deprecate Buffer() constructors
* Add `Buffer.from()`, `Buffer.alloc()`, and `Buffer.allocUnsafe()`
* Add `--zero-fill-buffers` command line option
* Add byteOffset and length to `new Buffer(arrayBuffer)` constructor
* buffer.fill('') previously had no effect, now zero-fills
* Update the docs

PR-URL: nodejs#4682
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>

benchmark/buffers/buffer-base64-decode.js

@@ -8,7 +8,7 @@ function main(conf) {
   const s = 'abcd'.repeat(8 << 20);
   s.match(/./);  // Flatten string.
   assert.equal(s.length % 4, 0);
-  const b = Buffer(s.length / 4 * 3);
+  const b = Buffer.allocUnsafe(s.length / 4 * 3);
   b.write(s, 0, s.length, 'base64');
   bench.start();
   for (var i = 0; i < 32; i += 1) b.base64Write(s, 0, s.length);

benchmark/buffers/buffer-base64-encode.js

@@ -5,7 +5,7 @@ var bench = common.createBenchmark(main, {});
 
 function main(conf) {
   var N = 64 * 1024 * 1024;
-  var b = Buffer(N);
+  var b = Buffer.allocUnsafe(N);
   var s = '';
   var i;
   for (i = 0; i < 256; ++i) s += String.fromCharCode(i);

benchmark/buffers/buffer-bytelength.js

@@ -28,7 +28,7 @@ function main(conf) {
       strings.push(data);
     } else if (encoding === 'base64') {
       // Base64 strings will be much longer than their UTF8 counterparts
-      strings.push(new Buffer(data, 'utf8').toString('base64'));
+      strings.push(Buffer.from(data, 'utf8').toString('base64'));
     }
   }
 

benchmark/buffers/buffer-compare.js

@@ -7,10 +7,10 @@ var bench = common.createBenchmark(main, {
 });
 
 function main(conf) {
-  var iter = (conf.millions >>> 0) * 1e6;
-  var size = (conf.size >>> 0);
-  var b0 = new Buffer(size).fill('a');
-  var b1 = new Buffer(size).fill('a');
+  const iter = (conf.millions >>> 0) * 1e6;
+  const size = (conf.size >>> 0);
+  const b0 = Buffer.alloc(size, 'a');
+  const b1 = Buffer.alloc(size, 'a');
 
   b1[size - 1] = 'b'.charCodeAt(0);
 

benchmark/buffers/buffer-creation.js

@@ -1,20 +1,59 @@
 'use strict';
 const SlowBuffer = require('buffer').SlowBuffer;
 
-var common = require('../common.js');
-var bench = common.createBenchmark(main, {
-  type: ['fast', 'slow'],
-  len: [10, 1024],
+const common = require('../common.js');
+const assert = require('assert');
+const bench = common.createBenchmark(main, {
+  type: [
+    'fast-alloc',
+    'fast-alloc-fill',
+    'fast-allocUnsafe',
+    'slow',
+    'buffer()'],
+  len: [10, 1024, 2048, 4096, 8192],
   n: [1024]
 });
 
 function main(conf) {
-  var len = +conf.len;
-  var n = +conf.n;
-  var clazz = conf.type === 'fast' ? Buffer : SlowBuffer;
-  bench.start();
-  for (var i = 0; i < n * 1024; i++) {
-    new clazz(len);
+  const len = +conf.len;
+  const n = +conf.n;
+  switch (conf.type) {
+    case 'fast-alloc':
+      bench.start();
+      for (let i = 0; i < n * 1024; i++) {
+        Buffer.alloc(len);
+      }
+      bench.end(n);
+      break;
+    case 'fast-alloc-fill':
+      bench.start();
+      for (let i = 0; i < n * 1024; i++) {
+        Buffer.alloc(len, 0);
+      }
+      bench.end(n);
+      break;
+    case 'fast-allocUnsafe':
+      bench.start();
+      for (let i = 0; i < n * 1024; i++) {
+        Buffer.allocUnsafe(len);
+      }
+      bench.end(n);
+      break;
+    case 'slow':
+      bench.start();
+      for (let i = 0; i < n * 1024; i++) {
+        SlowBuffer(len);
+      }
+      bench.end(n);
+      break;
+    case 'buffer()':
+      bench.start();
+      for (let i = 0; i < n * 1024; i++) {
+        Buffer(len);
+      }
+      bench.end(n);
+      break;
+    default:
+      assert.fail(null, null, 'Should not get here');
   }
-  bench.end(n);
 }

benchmark/buffers/buffer-indexof.js

@@ -27,11 +27,11 @@ function main(conf) {
   }
 
   if (encoding === 'ucs2') {
-    aliceBuffer = new Buffer(aliceBuffer.toString(), encoding);
+    aliceBuffer = Buffer.from(aliceBuffer.toString(), encoding);
   }
 
   if (conf.type === 'buffer') {
-    search = new Buffer(new Buffer(search).toString(), encoding);
+    search = Buffer.from(Buffer.from(search).toString(), encoding);
   }
 
   bench.start();

benchmark/buffers/buffer-slice.js

@@ -7,7 +7,7 @@ var bench = common.createBenchmark(main, {
   n: [1024]
 });
 
-var buf = new Buffer(1024);
+var buf = Buffer.allocUnsafe(1024);
 var slowBuf = new SlowBuffer(1024);
 
 function main(conf) {

benchmark/buffers/buffer-tostring.js

@@ -12,7 +12,7 @@ function main(conf) {
   const arg = conf.arg === 'true';
   const len = conf.len | 0;
   const n = conf.n | 0;
-  const buf = Buffer(len).fill(42);
+  const buf = Buffer.alloc(len, 42);
 
   var i;
   bench.start();

benchmark/buffers/buffer_zero.js

@@ -6,13 +6,13 @@ const bench = common.createBenchmark(main, {
   n: [1024]
 });
 
-const zero = new Buffer(0);
+const zero = Buffer.alloc(0);
 
 function main(conf) {
   var n = +conf.n;
   bench.start();
   for (let i = 0; i < n * 1024; i++) {
-    new Buffer(zero);
+    Buffer.from(zero);
   }
   bench.end(n);
 }

benchmark/crypto/aes-gcm-throughput.js

@@ -9,10 +9,10 @@ var bench = common.createBenchmark(main, {
 });
 
 function main(conf) {
-  var message = (new Buffer(conf.len)).fill('b');
+  var message = Buffer.alloc(conf.len, 'b');
   var key = crypto.randomBytes(keylen[conf.cipher]);
   var iv = crypto.randomBytes(12);
-  var associate_data = (new Buffer(16)).fill('z');
+  var associate_data = Buffer.alloc(16, 'z');
   bench.start();
   AEAD_Bench(conf.cipher, message, associate_data, key, iv, conf.n, conf.len);
 }

benchmark/crypto/cipher-stream.js

@@ -48,8 +48,7 @@ function main(conf) {
       encoding = 'utf8';
       break;
     case 'buf':
-      message = new Buffer(conf.len);
-      message.fill('b');
+      message = Buffer.alloc(conf.len, 'b');
       break;
     default:
       throw new Error('unknown message type: ' + conf.type);

benchmark/crypto/hash-stream-creation.js

@@ -33,8 +33,7 @@ function main(conf) {
       encoding = 'utf8';
       break;
     case 'buf':
-      message = new Buffer(conf.len);
-      message.fill('b');
+      message = Buffer.alloc(conf.len, 'b');
       break;
     default:
       throw new Error('unknown message type: ' + conf.type);
@@ -58,7 +57,7 @@ function legacyWrite(algo, message, encoding, writes, len, outEnc) {
 
     // include buffer creation costs for older versions
     if (outEnc === 'buffer' && typeof res === 'string')
-      res = new Buffer(res, 'binary');
+      res = Buffer.from(res, 'binary');
   }
 
   bench.end(gbits);

benchmark/crypto/hash-stream-throughput.js

@@ -32,8 +32,7 @@ function main(conf) {
       encoding = 'utf8';
       break;
     case 'buf':
-      message = new Buffer(conf.len);
-      message.fill('b');
+      message = Buffer.alloc(conf.len, 'b');
       break;
     default:
       throw new Error('unknown message type: ' + conf.type);

benchmark/crypto/rsa-encrypt-decrypt-throughput.js

@@ -23,8 +23,7 @@ var bench = common.createBenchmark(main, {
 });
 
 function main(conf) {
-  var message = (new Buffer(conf.len)).fill('b');
-
+  var message = Buffer.alloc(conf.len, 'b');
   bench.start();
   StreamWrite(conf.algo, conf.keylen, message, conf.n, conf.len);
 }

benchmark/crypto/rsa-sign-verify-throughput.js

@@ -24,8 +24,7 @@ var bench = common.createBenchmark(main, {
 });
 
 function main(conf) {
-  var message = (new Buffer(conf.len)).fill('b');
-
+  var message = Buffer.alloc(conf.len, 'b');
   bench.start();
   StreamWrite(conf.algo, conf.keylen, message, conf.writes, conf.len);
 }

benchmark/dgram/array-vs-concat.js

@@ -31,7 +31,7 @@ function main(conf) {
 
   chunk = [];
   for (var i = 0; i < chunks; i++) {
-    chunk.push(new Buffer(Math.round(len / chunks)));
+    chunk.push(Buffer.allocUnsafe(Math.round(len / chunks)));
   }
 
   server();

benchmark/dgram/multi-buffer.js

@@ -31,7 +31,7 @@ function main(conf) {
 
   chunk = [];
   for (var i = 0; i < chunks; i++) {
-    chunk.push(new Buffer(Math.round(len / chunks)));
+    chunk.push(Buffer.allocUnsafe(Math.round(len / chunks)));
   }
 
   server();

benchmark/dgram/offset-length.js

@@ -25,7 +25,7 @@ function main(conf) {
   len = +conf.len;
   num = +conf.num;
   type = conf.type;
-  chunk = new Buffer(len);
+  chunk = Buffer.allocUnsafe(len);
   server();
 }
 

benchmark/dgram/single-buffer.js

@@ -25,7 +25,7 @@ function main(conf) {
   len = +conf.len;
   num = +conf.num;
   type = conf.type;
-  chunk = new Buffer(len);
+  chunk = Buffer.allocUnsafe(len);
   server();
 }
 

benchmark/fs-write-stream-throughput.js

@@ -45,8 +45,7 @@ function runTest(dur, size, type) {
       chunk = new Array(size + 1).join('a');
       break;
     case 'buffer':
-      chunk = new Buffer(size);
-      chunk.fill('a');
+      chunk = Buffer.alloc(size, 'a');
       break;
   }
 

benchmark/fs/read-stream-throughput.js

@@ -60,7 +60,7 @@ function runTest() {
 }
 
 function makeFile() {
-  var buf = new Buffer(filesize / 1024);
+  var buf = Buffer.allocUnsafe(filesize / 1024);
   if (encoding === 'utf8') {
     // ü
     for (var i = 0; i < buf.length; i++) {

benchmark/fs/readfile.js

@@ -17,8 +17,7 @@ var bench = common.createBenchmark(main, {
 function main(conf) {
   var len = +conf.len;
   try { fs.unlinkSync(filename); } catch (e) {}
-  var data = new Buffer(len);
-  data.fill('x');
+  var data = Buffer.alloc(len, 'x');
   fs.writeFileSync(filename, data);
   data = null;
 

benchmark/fs/write-stream-throughput.js

@@ -21,8 +21,7 @@ function main(conf) {
   var chunk;
   switch (type) {
     case 'buf':
-      chunk = new Buffer(size);
-      chunk.fill('b');
+      chunk = Buffer.alloc(size, 'b');
       break;
     case 'asc':
       chunk = new Array(size + 1).join('a');

benchmark/http/bench-parser.js

@@ -25,7 +25,7 @@ function main(conf) {
   }
   header += CRLF;
 
-  processHeader(new Buffer(header), n);
+  processHeader(Buffer.from(header), n);
 }
 
 

benchmark/http/chunked.js

@@ -18,8 +18,7 @@ var bench = common.createBenchmark(main, {
 
 function main(conf) {
   const http = require('http');
-  var chunk = new Buffer(conf.size);
-  chunk.fill('8');
+  var chunk = Buffer.alloc(conf.size, '8');
 
   var args = ['-d', '10s', '-t', 8, '-c', conf.c];
 

benchmark/http/client-request-body.js

@@ -19,8 +19,7 @@ function main(conf) {
   var chunk;
   switch (conf.type) {
     case 'buf':
-      chunk = new Buffer(len);
-      chunk.fill('x');
+      chunk = Buffer.alloc(len, 'x');
       break;
     case 'utf':
       encoding = 'utf8';

benchmark/http/end-vs-write-end.js

@@ -23,8 +23,7 @@ function main(conf) {
   var len = conf.kb * 1024;
   switch (conf.type) {
     case 'buf':
-      chunk = new Buffer(len);
-      chunk.fill('x');
+      chunk = Buffer.alloc(len, 'x');
       break;
     case 'utf':
       chunk = new Array(len / 2 + 1).join('ü');

benchmark/http_simple.js

@@ -51,7 +51,7 @@ var server = module.exports = http.createServer(function(req, res) {
     if (n <= 0)
       throw new Error('buffer called with n <= 0');
     if (storedBuffer[n] === undefined) {
-      storedBuffer[n] = new Buffer(n);
+      storedBuffer[n] = Buffer.allocUnsafe(n);
       for (i = 0; i < n; i++) {
         storedBuffer[n][i] = 'C'.charCodeAt(0);
       }

benchmark/http_simple_auto.js

@@ -47,7 +47,7 @@ var server = http.createServer(function(req, res) {
     n = parseInt(arg, 10);
     if (n <= 0) throw new Error('bytes called with n <= 0');
     if (storedBuffer[n] === undefined) {
-      storedBuffer[n] = new Buffer(n);
+      storedBuffer[n] = Buffer.allocUnsafe(n);
       for (i = 0; i < n; i++) {
         storedBuffer[n][i] = 'C'.charCodeAt(0);
       }

benchmark/net/net-c2s-cork.js

@@ -23,8 +23,7 @@ function main(conf) {
 
   switch (type) {
     case 'buf':
-      chunk = new Buffer(len);
-      chunk.fill('x');
+      chunk = Buffer.alloc(len, 'x');
       break;
     case 'utf':
       encoding = 'utf8';

benchmark/net/net-c2s.js

@@ -23,8 +23,7 @@ function main(conf) {
 
   switch (type) {
     case 'buf':
-      chunk = new Buffer(len);
-      chunk.fill('x');
+      chunk = Buffer.alloc(len, 'x');
       break;
     case 'utf':
       encoding = 'utf8';

benchmark/net/net-pipe.js

@@ -23,8 +23,7 @@ function main(conf) {
 
   switch (type) {
     case 'buf':
-      chunk = new Buffer(len);
-      chunk.fill('x');
+      chunk = Buffer.alloc(len, 'x');
       break;
     case 'utf':
       encoding = 'utf8';