diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 6d06ae9ddd21c9..3877cc55699077 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -2302,6 +2302,33 @@ added: v3.0.0 On 32-bit architectures, this value is `(2^30)-1` (~1GB). On 64-bit architectures, this value is `(2^31)-1` (~2GB). +## buffer.transcode(source, fromEnc, toEnc) + + +* `source` {Buffer} A `Buffer` instance +* `fromEnc` {String} The current encoding +* `toEnc` {String} To target encoding + +Re-encodes the given `Buffer` instance from one character encoding to another. +Returns a new `Buffer` instance. + +Throws if the `fromEnc` or `toEnc` specify invalid character encodings or if +conversion from `fromEnc` to `toEnc` is not permitted. + +The transcoding process will use substitution characters if a given byte +sequence cannot be adequately represented in the target encoding. For instance: + +```js +const newBuf = buffer.transcode(Buffer.from('€'), 'utf8', 'ascii'); +console.log(newBuf.toString('ascii')); + // prints '?' +``` + +Because the Euro (`€`) sign is not representable in US-ASCII, it is replaced +with `?` in the transcoded `Buffer`. + ## Class: SlowBuffer