doc: warn against filling buffer with invalid data

PR-URL: #17428 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Anatoli Papirovski <[email protected]> Reviewed-By: Ali Ijaz Sheikh <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Michaël Zasso <[email protected]>
nodejs · Dec 7, 2017 · 99fc75e · 99fc75e
1 parent 930f7a6
commit 99fc75e
Showing 1 changed file with 13 additions and 0 deletions.
diff --git a/doc/api/buffer.md b/doc/api/buffer.md
@@ -1253,6 +1253,19 @@ Example: Fill a `Buffer` with a two-byte character
 console.log(Buffer.allocUnsafe(3).fill('\u0222'));
 ```
 
+If `value` is contains invalid characters, it is truncated; if no valid
+fill data remains, no filling is performed:
+
+```js
+const buf = Buffer.allocUnsafe(5);
+// Prints: <Buffer 61 61 61 61 61>
+console.log(buf.fill('a'));
+// Prints: <Buffer aa aa aa aa aa>
+console.log(buf.fill('aazz', 'hex'));
+// Prints: <Buffer aa aa aa aa aa>
+console.log(buf.fill('zz', 'hex'));
+```
+
 ### buf.includes(value[, byteOffset][, encoding])
 <!-- YAML
 added: v5.3.0