buffer: support boxed strings and toPrimitive

Add support for `Buffer.from(new String('...'))` and
`Buffer.from({[Symbol.toPrimitive]() { return '...'; }})`

PR-URL: https://github.com/nodejs/node/pull/13725
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

1 files changed, 38 insertions, 0 deletions

diff --git a/doc/api/buffer.md b/doc/api/buffer.md
index 4488ae2ad9..3a04ad514b 100644
--- a/doc/api/buffer.md
+++ b/doc/api/buffer.md
@@ -908,6 +908,44 @@ console.log(buf2.toString());
 
 A `TypeError` will be thrown if `str` is not a string.
 
+### Class Method: Buffer.from(object[, offsetOrEncoding[, length]])
+<!-- YAML
+added: REPLACEME
+-->
+
+* `object` {Object} An object supporting `Symbol.toPrimitive` or `valueOf()`
+* `offsetOrEncoding` {number|string} A byte-offset or encoding, depending on
+  the value returned either by `object.valueOf()` or
+  `object[Symbol.toPrimitive]()`.
+* `length` {number} A length, depending on the value returned either by
+  `object.valueOf()` or `object[Symbol.toPrimitive]()`.
+
+For objects whose `valueOf()` function returns a value not strictly equal to
+`object`, returns `Buffer.from(object.valueOf(), offsetOrEncoding, length)`.
+
+For example:
+
+```js
+const buf = Buffer.from(new String('this is a test'));
+// <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>
+```
+
+For objects that support `Symbol.toPrimitive`, returns
+`Buffer.from(object[Symbol.toPrimitive](), offsetOrEncoding, length)`.
+
+For example:
+
+```js
+class Foo {
+  [Symbol.toPrimitive]() {
+    return 'this is a test';
+  }
+}
+
+const buf = Buffer.from(new Foo(), 'utf8');
+// <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>
+```
+
 ### Class Method: Buffer.isBuffer(obj)
 <!-- YAML
 added: v0.1.101