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: #4682
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>

Author: jasnell

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);
 }