doc/api/buffer.markdown

   1 # Buffer
   2
   3     Stability: 2 - Stable
   4
   5 Pure JavaScript is Unicode friendly but not nice to binary data.  When
   6 dealing with TCP streams or the file system, it's necessary to handle octet
   7 streams. io.js has several strategies for manipulating, creating, and
   8 consuming octet streams.
   9
  10 Raw data is stored in instances of the `Buffer` class. A `Buffer` is similar
  11 to an array of integers but corresponds to a raw memory allocation outside
  12 the V8 heap. A `Buffer` cannot be resized.
  13
  14 The `Buffer` class is a global, making it very rare that one would need
  15 to ever `require('buffer')`.
  16
  17 Converting between Buffers and JavaScript string objects requires an explicit
  18 encoding method.  Here are the different string encodings.
  19
  20 * `'ascii'` - for 7 bit ASCII data only.  This encoding method is very fast, and
  21   will strip the high bit if set.
  22
  23 * `'utf8'` - Multibyte encoded Unicode characters. Many web pages and other
  24   document formats use UTF-8.
  25
  26 * `'utf16le'` - 2 or 4 bytes, little endian encoded Unicode characters.
  27   Surrogate pairs (U+10000 to U+10FFFF) are supported.
  28
  29 * `'ucs2'` - Alias of `'utf16le'`.
  30
  31 * `'base64'` - Base64 string encoding.
  32
  33 * `'binary'` - A way of encoding raw binary data into strings by using only
  34   the first 8 bits of each character. This encoding method is deprecated and
  35   should be avoided in favor of `Buffer` objects where possible. This encoding
  36   will be removed in future versions of io.js.
  37
  38 * `'hex'` - Encode each byte as two hexadecimal characters.
  39
  40 Creating a typed array from a `Buffer` works with the following caveats:
  41
  42 1. The buffer's memory is copied, not shared.
  43
  44 2. The buffer's memory is interpreted as an array, not a byte array.  That is,
  45    `new Uint32Array(new Buffer([1,2,3,4]))` creates a 4-element `Uint32Array`
  46    with elements `[1,2,3,4]`, not an `Uint32Array` with a single element
  47    `[0x1020304]` or `[0x4030201]`.
  48
  49 NOTE: Node.js v0.8 simply retained a reference to the buffer in `array.buffer`
  50 instead of cloning it.
  51
  52 While more efficient, it introduces subtle incompatibilities with the typed
  53 arrays specification.  `ArrayBuffer#slice()` makes a copy of the slice while
  54 `Buffer#slice()` creates a view.
  55
  56 ## Class: Buffer
  57
  58 The Buffer class is a global type for dealing with binary data directly.
  59 It can be constructed in a variety of ways.
  60
  61 ### new Buffer(size)
  62
  63 * `size` Number
  64
  65 Allocates a new buffer of `size` octets. Note, `size` must be no more than
  66 [kMaxLength](smalloc.html#smalloc_smalloc_kmaxlength). Otherwise, a `RangeError`
  67 will be thrown here.
  68
  69 ### new Buffer(array)
  70
  71 * `array` Array
  72
  73 Allocates a new buffer using an `array` of octets.
  74
  75 ### new Buffer(buffer)
  76
  77 * `buffer` {Buffer}
  78
  79 Copies the passed `buffer` data onto a new `Buffer` instance.
  80
  81 ### new Buffer(str[, encoding])
  82
  83 * `str` String - string to encode.
  84 * `encoding` String - encoding to use, Optional.
  85
  86 Allocates a new buffer containing the given `str`.
  87 `encoding` defaults to `'utf8'`.
  88
  89 ### Class Method: Buffer.isEncoding(encoding)
  90
  91 * `encoding` {String} The encoding string to test
  92
  93 Returns true if the `encoding` is a valid encoding argument, or false
  94 otherwise.
  95
  96 ### Class Method: Buffer.isBuffer(obj)
  97
  98 * `obj` Object
  99 * Return: Boolean
 100
 101 Tests if `obj` is a `Buffer`.
 102
 103 ### Class Method: Buffer.byteLength(string[, encoding])
 104
 105 * `string` String
 106 * `encoding` String, Optional, Default: 'utf8'
 107 * Return: Number
 108
 109 Gives the actual byte length of a string. `encoding` defaults to `'utf8'`.
 110 This is not the same as `String.prototype.length` since that returns the
 111 number of *characters* in a string.
 112
 113 Example:
 114
 115     str = '\u00bd + \u00bc = \u00be';
 116
 117     console.log(str + ": " + str.length + " characters, " +
 118       Buffer.byteLength(str, 'utf8') + " bytes");
 119
 120     // ½ + ¼ = ¾: 9 characters, 12 bytes
 121
 122 ### Class Method: Buffer.concat(list[, totalLength])
 123
 124 * `list` {Array} List of Buffer objects to concat
 125 * `totalLength` {Number} Total length of the buffers when concatenated
 126
 127 Returns a buffer which is the result of concatenating all the buffers in
 128 the list together.
 129
 130 If the list has no items, or if the totalLength is 0, then it returns a
 131 zero-length buffer.
 132
 133 If the list has exactly one item, then the first item of the list is
 134 returned.
 135
 136 If the list has more than one item, then a new Buffer is created.
 137
 138 If totalLength is not provided, it is read from the buffers in the list.
 139 However, this adds an additional loop to the function, so it is faster
 140 to provide the length explicitly.
 141
 142 ### Class Method: Buffer.compare(buf1, buf2)
 143
 144 * `buf1` {Buffer}
 145 * `buf2` {Buffer}
 146
 147 The same as [`buf1.compare(buf2)`](#buffer_buf_compare_otherbuffer). Useful
 148 for sorting an Array of Buffers:
 149
 150     var arr = [Buffer('1234'), Buffer('0123')];
 151     arr.sort(Buffer.compare);
 152
 153
 154 ### buf.length
 155
 156 * Number
 157
 158 The size of the buffer in bytes.  Note that this is not necessarily the size
 159 of the contents. `length` refers to the amount of memory allocated for the
 160 buffer object.  It does not change when the contents of the buffer are changed.
 161
 162     buf = new Buffer(1234);
 163
 164     console.log(buf.length);
 165     buf.write("some string", 0, "ascii");
 166     console.log(buf.length);
 167
 168     // 1234
 169     // 1234
 170
 171 While the `length` property is not immutable, changing the value of `length`
 172 can result in undefined and inconsistent behavior. Applications that wish to
 173 modify the length of a buffer should therefore treat `length` as read-only and
 174 use `buf.slice` to create a new buffer.
 175
 176     buf = new Buffer(10);
 177     buf.write("abcdefghj", 0, "ascii");
 178     console.log(buf.length); // 10
 179     buf = buf.slice(0,5);
 180     console.log(buf.length); // 5
 181
 182 ### buf.write(string[, offset][, length][, encoding])
 183
 184 * `string` String - data to be written to buffer
 185 * `offset` Number, Optional, Default: 0
 186 * `length` Number, Optional, Default: `buffer.length - offset`
 187 * `encoding` String, Optional, Default: 'utf8'
 188
 189 Writes `string` to the buffer at `offset` using the given encoding.
 190 `offset` defaults to `0`, `encoding` defaults to `'utf8'`. `length` is
 191 the number of bytes to write. Returns number of octets written. If `buffer` did
 192 not contain enough space to fit the entire string, it will write a partial
 193 amount of the string. `length` defaults to `buffer.length - offset`.
 194 The method will not write partial characters.
 195
 196     buf = new Buffer(256);
 197     len = buf.write('\u00bd + \u00bc = \u00be', 0);
 198     console.log(len + " bytes: " + buf.toString('utf8', 0, len));
 199
 200 ### buf.writeUIntLE(value, offset, byteLength[, noAssert])
 201 ### buf.writeUIntBE(value, offset, byteLength[, noAssert])
 202 ### buf.writeIntLE(value, offset, byteLength[, noAssert])
 203 ### buf.writeIntBE(value, offset, byteLength[, noAssert])
 204
 205 * `value` {Number} Bytes to be written to buffer
 206 * `offset` {Number} `0 <= offset <= buf.length`
 207 * `byteLength` {Number} `0 < byteLength <= 6`
 208 * `noAssert` {Boolean} Default: false
 209 * Return: {Number}
 210
 211 Writes `value` to the buffer at the specified `offset` and `byteLength`.
 212 Supports up to 48 bits of accuracy. For example:
 213
 214     var b = new Buffer(6);
 215     b.writeUIntBE(0x1234567890ab, 0, 6);
 216     // <Buffer 12 34 56 78 90 ab>
 217
 218 Set `noAssert` to `true` to skip validation of `value` and `offset`. Defaults
 219 to `false`.
 220
 221 ### buf.readUIntLE(offset, byteLength[, noAssert])
 222 ### buf.readUIntBE(offset, byteLength[, noAssert])
 223 ### buf.readIntLE(offset, byteLength[, noAssert])
 224 ### buf.readIntBE(offset, byteLength[, noAssert])
 225
 226 * `offset` {Number} `0 <= offset <= buf.length`
 227 * `byteLength` {Number} `0 < byteLength <= 6`
 228 * `noAssert` {Boolean} Default: false
 229 * Return: {Number}
 230
 231 A generalized version of all numeric read methods. Supports up to 48 bits of
 232 accuracy. For example:
 233
 234     var b = new Buffer(6);
 235     b.writeUint16LE(0x90ab, 0);
 236     b.writeUInt32LE(0x12345678, 2);
 237     b.readUIntLE(0, 6).toString(16);  // Specify 6 bytes (48 bits)
 238     // output: '1234567890ab'
 239
 240 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 241 may be beyond the end of the buffer. Defaults to `false`.
 242
 243 ### buf.toString([encoding][, start][, end])
 244
 245 * `encoding` String, Optional, Default: 'utf8'
 246 * `start` Number, Optional, Default: 0
 247 * `end` Number, Optional, Default: `buffer.length`
 248
 249 Decodes and returns a string from buffer data encoded using the specified
 250 character set encoding. If `encoding` is `undefined` or `null`, then `encoding`
 251 defaults to `'utf8'. The `start` and `end` parameters default to `0` and
 252 `buffer.length` when `undefined`.
 253
 254     buf = new Buffer(26);
 255     for (var i = 0 ; i < 26 ; i++) {
 256       buf[i] = i + 97; // 97 is ASCII a
 257     }
 258     buf.toString('ascii'); // outputs: abcdefghijklmnopqrstuvwxyz
 259     buf.toString('ascii',0,5); // outputs: abcde
 260     buf.toString('utf8',0,5); // outputs: abcde
 261     buf.toString(undefined,0,5); // encoding defaults to 'utf8', outputs abcde
 262
 263 See `buffer.write()` example, above.
 264
 265
 266 ### buf.toJSON()
 267
 268 Returns a JSON-representation of the Buffer instance.  `JSON.stringify`
 269 implicitly calls this function when stringifying a Buffer instance.
 270
 271 Example:
 272
 273     var buf = new Buffer('test');
 274     var json = JSON.stringify(buf);
 275
 276     console.log(json);
 277     // '{"type":"Buffer","data":[116,101,115,116]}'
 278
 279     var copy = JSON.parse(json, function(key, value) {
 280         return value && value.type === 'Buffer'
 281           ? new Buffer(value.data)
 282           : value;
 283       });
 284
 285     console.log(copy);
 286     // <Buffer 74 65 73 74>
 287
 288 ### buf[index]
 289
 290 <!--type=property-->
 291 <!--name=[index]-->
 292
 293 Get and set the octet at `index`. The values refer to individual bytes,
 294 so the legal range is between `0x00` and `0xFF` hex or `0` and `255`.
 295
 296 Example: copy an ASCII string into a buffer, one byte at a time:
 297
 298     str = "io.js";
 299     buf = new Buffer(str.length);
 300
 301     for (var i = 0; i < str.length ; i++) {
 302       buf[i] = str.charCodeAt(i);
 303     }
 304
 305     console.log(buf);
 306
 307     // io.js
 308
 309 ### buf.equals(otherBuffer)
 310
 311 * `otherBuffer` {Buffer}
 312
 313 Returns a boolean of whether `this` and `otherBuffer` have the same
 314 bytes.
 315
 316 ### buf.compare(otherBuffer)
 317
 318 * `otherBuffer` {Buffer}
 319
 320 Returns a number indicating whether `this` comes before or after or is
 321 the same as the `otherBuffer` in sort order.
 322
 323
 324 ### buf.copy(targetBuffer[, targetStart][, sourceStart][, sourceEnd])
 325
 326 * `targetBuffer` Buffer object - Buffer to copy into
 327 * `targetStart` Number, Optional, Default: 0
 328 * `sourceStart` Number, Optional, Default: 0
 329 * `sourceEnd` Number, Optional, Default: `buffer.length`
 330
 331 Copies data from a region of this buffer to a region in the target buffer even
 332 if the target memory region overlaps with the source. If `undefined` the
 333 `targetStart` and `sourceStart` parameters default to `0` while `sourceEnd`
 334 defaults to `buffer.length`.
 335
 336 Example: build two Buffers, then copy `buf1` from byte 16 through byte 19
 337 into `buf2`, starting at the 8th byte in `buf2`.
 338
 339     buf1 = new Buffer(26);
 340     buf2 = new Buffer(26);
 341
 342     for (var i = 0 ; i < 26 ; i++) {
 343       buf1[i] = i + 97; // 97 is ASCII a
 344       buf2[i] = 33; // ASCII !
 345     }
 346
 347     buf1.copy(buf2, 8, 16, 20);
 348     console.log(buf2.toString('ascii', 0, 25));
 349
 350     // !!!!!!!!qrst!!!!!!!!!!!!!
 351
 352 Example: Build a single buffer, then copy data from one region to an overlapping
 353 region in the same buffer
 354
 355     buf = new Buffer(26);
 356
 357     for (var i = 0 ; i < 26 ; i++) {
 358       buf[i] = i + 97; // 97 is ASCII a
 359     }
 360
 361     buf.copy(buf, 0, 4, 10);
 362     console.log(buf.toString());
 363
 364     // efghijghijklmnopqrstuvwxyz
 365
 366
 367 ### buf.slice([start][, end])
 368
 369 * `start` Number, Optional, Default: 0
 370 * `end` Number, Optional, Default: `buffer.length`
 371
 372 Returns a new buffer which references the same memory as the old, but offset
 373 and cropped by the `start` (defaults to `0`) and `end` (defaults to
 374 `buffer.length`) indexes.  Negative indexes start from the end of the buffer.
 375
 376 **Modifying the new buffer slice will modify memory in the original buffer!**
 377
 378 Example: build a Buffer with the ASCII alphabet, take a slice, then modify one
 379 byte from the original Buffer.
 380
 381     var buf1 = new Buffer(26);
 382
 383     for (var i = 0 ; i < 26 ; i++) {
 384       buf1[i] = i + 97; // 97 is ASCII a
 385     }
 386
 387     var buf2 = buf1.slice(0, 3);
 388     console.log(buf2.toString('ascii', 0, buf2.length));
 389     buf1[0] = 33;
 390     console.log(buf2.toString('ascii', 0, buf2.length));
 391
 392     // abc
 393     // !bc
 394
 395
 396 ### buf.indexOf(value[, byteOffset])
 397
 398 * `value` String, Buffer or Number
 399 * `byteOffset` Number, Optional, Default: 0
 400 * Return: Number
 401
 402 Operates similar to
 403 [Array#indexOf()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf).
 404 Accepts a String, Buffer or Number. Strings are interpreted as UTF8. Buffers
 405 will use the entire buffer. So in order to compare a partial Buffer use
 406 `Buffer#slice()`. Numbers can range from 0 to 255.
 407
 408 ### buf.readUInt8(offset[, noAssert])
 409
 410 * `offset` Number
 411 * `noAssert` Boolean, Optional, Default: false
 412 * Return: Number
 413
 414 Reads an unsigned 8 bit integer from the buffer at the specified offset.
 415
 416 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 417 may be beyond the end of the buffer. Defaults to `false`.
 418
 419 Example:
 420
 421     var buf = new Buffer(4);
 422
 423     buf[0] = 0x3;
 424     buf[1] = 0x4;
 425     buf[2] = 0x23;
 426     buf[3] = 0x42;
 427
 428     for (ii = 0; ii < buf.length; ii++) {
 429       console.log(buf.readUInt8(ii));
 430     }
 431
 432     // 0x3
 433     // 0x4
 434     // 0x23
 435     // 0x42
 436
 437 ### buf.readUInt16LE(offset[, noAssert])
 438 ### buf.readUInt16BE(offset[, noAssert])
 439
 440 * `offset` Number
 441 * `noAssert` Boolean, Optional, Default: false
 442 * Return: Number
 443
 444 Reads an unsigned 16 bit integer from the buffer at the specified offset with
 445 specified endian format.
 446
 447 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 448 may be beyond the end of the buffer. Defaults to `false`.
 449
 450 Example:
 451
 452     var buf = new Buffer(4);
 453
 454     buf[0] = 0x3;
 455     buf[1] = 0x4;
 456     buf[2] = 0x23;
 457     buf[3] = 0x42;
 458
 459     console.log(buf.readUInt16BE(0));
 460     console.log(buf.readUInt16LE(0));
 461     console.log(buf.readUInt16BE(1));
 462     console.log(buf.readUInt16LE(1));
 463     console.log(buf.readUInt16BE(2));
 464     console.log(buf.readUInt16LE(2));
 465
 466     // 0x0304
 467     // 0x0403
 468     // 0x0423
 469     // 0x2304
 470     // 0x2342
 471     // 0x4223
 472
 473 ### buf.readUInt32LE(offset[, noAssert])
 474 ### buf.readUInt32BE(offset[, noAssert])
 475
 476 * `offset` Number
 477 * `noAssert` Boolean, Optional, Default: false
 478 * Return: Number
 479
 480 Reads an unsigned 32 bit integer from the buffer at the specified offset with
 481 specified endian format.
 482
 483 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 484 may be beyond the end of the buffer. Defaults to `false`.
 485
 486 Example:
 487
 488     var buf = new Buffer(4);
 489
 490     buf[0] = 0x3;
 491     buf[1] = 0x4;
 492     buf[2] = 0x23;
 493     buf[3] = 0x42;
 494
 495     console.log(buf.readUInt32BE(0));
 496     console.log(buf.readUInt32LE(0));
 497
 498     // 0x03042342
 499     // 0x42230403
 500
 501 ### buf.readInt8(offset[, noAssert])
 502
 503 * `offset` Number
 504 * `noAssert` Boolean, Optional, Default: false
 505 * Return: Number
 506
 507 Reads a signed 8 bit integer from the buffer at the specified offset.
 508
 509 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 510 may be beyond the end of the buffer. Defaults to `false`.
 511
 512 Works as `buffer.readUInt8`, except buffer contents are treated as two's
 513 complement signed values.
 514
 515 ### buf.readInt16LE(offset[, noAssert])
 516 ### buf.readInt16BE(offset[, noAssert])
 517
 518 * `offset` Number
 519 * `noAssert` Boolean, Optional, Default: false
 520 * Return: Number
 521
 522 Reads a signed 16 bit integer from the buffer at the specified offset with
 523 specified endian format.
 524
 525 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 526 may be beyond the end of the buffer. Defaults to `false`.
 527
 528 Works as `buffer.readUInt16*`, except buffer contents are treated as two's
 529 complement signed values.
 530
 531 ### buf.readInt32LE(offset[, noAssert])
 532 ### buf.readInt32BE(offset[, noAssert])
 533
 534 * `offset` Number
 535 * `noAssert` Boolean, Optional, Default: false
 536 * Return: Number
 537
 538 Reads a signed 32 bit integer from the buffer at the specified offset with
 539 specified endian format.
 540
 541 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 542 may be beyond the end of the buffer. Defaults to `false`.
 543
 544 Works as `buffer.readUInt32*`, except buffer contents are treated as two's
 545 complement signed values.
 546
 547 ### buf.readFloatLE(offset[, noAssert])
 548 ### buf.readFloatBE(offset[, noAssert])
 549
 550 * `offset` Number
 551 * `noAssert` Boolean, Optional, Default: false
 552 * Return: Number
 553
 554 Reads a 32 bit float from the buffer at the specified offset with specified
 555 endian format.
 556
 557 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 558 may be beyond the end of the buffer. Defaults to `false`.
 559
 560 Example:
 561
 562     var buf = new Buffer(4);
 563
 564     buf[0] = 0x00;
 565     buf[1] = 0x00;
 566     buf[2] = 0x80;
 567     buf[3] = 0x3f;
 568
 569     console.log(buf.readFloatLE(0));
 570
 571     // 0x01
 572
 573 ### buf.readDoubleLE(offset[, noAssert])
 574 ### buf.readDoubleBE(offset[, noAssert])
 575
 576 * `offset` Number
 577 * `noAssert` Boolean, Optional, Default: false
 578 * Return: Number
 579
 580 Reads a 64 bit double from the buffer at the specified offset with specified
 581 endian format.
 582
 583 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 584 may be beyond the end of the buffer. Defaults to `false`.
 585
 586 Example:
 587
 588     var buf = new Buffer(8);
 589
 590     buf[0] = 0x55;
 591     buf[1] = 0x55;
 592     buf[2] = 0x55;
 593     buf[3] = 0x55;
 594     buf[4] = 0x55;
 595     buf[5] = 0x55;
 596     buf[6] = 0xd5;
 597     buf[7] = 0x3f;
 598
 599     console.log(buf.readDoubleLE(0));
 600
 601     // 0.3333333333333333
 602
 603 ### buf.writeUInt8(value, offset[, noAssert])
 604
 605 * `value` Number
 606 * `offset` Number
 607 * `noAssert` Boolean, Optional, Default: false
 608
 609 Writes `value` to the buffer at the specified offset. Note, `value` must be a
 610 valid unsigned 8 bit integer.
 611
 612 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 613 that `value` may be too large for the specific function and `offset` may be
 614 beyond the end of the buffer leading to the values being silently dropped. This
 615 should not be used unless you are certain of correctness. Defaults to `false`.
 616
 617 Example:
 618
 619     var buf = new Buffer(4);
 620     buf.writeUInt8(0x3, 0);
 621     buf.writeUInt8(0x4, 1);
 622     buf.writeUInt8(0x23, 2);
 623     buf.writeUInt8(0x42, 3);
 624
 625     console.log(buf);
 626
 627     // <Buffer 03 04 23 42>
 628
 629 ### buf.writeUInt16LE(value, offset[, noAssert])
 630 ### buf.writeUInt16BE(value, offset[, noAssert])
 631
 632 * `value` Number
 633 * `offset` Number
 634 * `noAssert` Boolean, Optional, Default: false
 635
 636 Writes `value` to the buffer at the specified offset with specified endian
 637 format. Note, `value` must be a valid unsigned 16 bit integer.
 638
 639 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 640 that `value` may be too large for the specific function and `offset` may be
 641 beyond the end of the buffer leading to the values being silently dropped. This
 642 should not be used unless you are certain of correctness. Defaults to `false`.
 643
 644 Example:
 645
 646     var buf = new Buffer(4);
 647     buf.writeUInt16BE(0xdead, 0);
 648     buf.writeUInt16BE(0xbeef, 2);
 649
 650     console.log(buf);
 651
 652     buf.writeUInt16LE(0xdead, 0);
 653     buf.writeUInt16LE(0xbeef, 2);
 654
 655     console.log(buf);
 656
 657     // <Buffer de ad be ef>
 658     // <Buffer ad de ef be>
 659
 660 ### buf.writeUInt32LE(value, offset[, noAssert])
 661 ### buf.writeUInt32BE(value, offset[, noAssert])
 662
 663 * `value` Number
 664 * `offset` Number
 665 * `noAssert` Boolean, Optional, Default: false
 666
 667 Writes `value` to the buffer at the specified offset with specified endian
 668 format. Note, `value` must be a valid unsigned 32 bit integer.
 669
 670 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 671 that `value` may be too large for the specific function and `offset` may be
 672 beyond the end of the buffer leading to the values being silently dropped. This
 673 should not be used unless you are certain of correctness. Defaults to `false`.
 674
 675 Example:
 676
 677     var buf = new Buffer(4);
 678     buf.writeUInt32BE(0xfeedface, 0);
 679
 680     console.log(buf);
 681
 682     buf.writeUInt32LE(0xfeedface, 0);
 683
 684     console.log(buf);
 685
 686     // <Buffer fe ed fa ce>
 687     // <Buffer ce fa ed fe>
 688
 689 ### buf.writeInt8(value, offset[, noAssert])
 690
 691 * `value` Number
 692 * `offset` Number
 693 * `noAssert` Boolean, Optional, Default: false
 694
 695 Writes `value` to the buffer at the specified offset. Note, `value` must be a
 696 valid signed 8 bit integer.
 697
 698 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 699 that `value` may be too large for the specific function and `offset` may be
 700 beyond the end of the buffer leading to the values being silently dropped. This
 701 should not be used unless you are certain of correctness. Defaults to `false`.
 702
 703 Works as `buffer.writeUInt8`, except value is written out as a two's complement
 704 signed integer into `buffer`.
 705
 706 ### buf.writeInt16LE(value, offset[, noAssert])
 707 ### buf.writeInt16BE(value, offset[, noAssert])
 708
 709 * `value` Number
 710 * `offset` Number
 711 * `noAssert` Boolean, Optional, Default: false
 712
 713 Writes `value` to the buffer at the specified offset with specified endian
 714 format. Note, `value` must be a valid signed 16 bit integer.
 715
 716 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 717 that `value` may be too large for the specific function and `offset` may be
 718 beyond the end of the buffer leading to the values being silently dropped. This
 719 should not be used unless you are certain of correctness. Defaults to `false`.
 720
 721 Works as `buffer.writeUInt16*`, except value is written out as a two's
 722 complement signed integer into `buffer`.
 723
 724 ### buf.writeInt32LE(value, offset[, noAssert])
 725 ### buf.writeInt32BE(value, offset[, noAssert])
 726
 727 * `value` Number
 728 * `offset` Number
 729 * `noAssert` Boolean, Optional, Default: false
 730
 731 Writes `value` to the buffer at the specified offset with specified endian
 732 format. Note, `value` must be a valid signed 32 bit integer.
 733
 734 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 735 that `value` may be too large for the specific function and `offset` may be
 736 beyond the end of the buffer leading to the values being silently dropped. This
 737 should not be used unless you are certain of correctness. Defaults to `false`.
 738
 739 Works as `buffer.writeUInt32*`, except value is written out as a two's
 740 complement signed integer into `buffer`.
 741
 742 ### buf.writeFloatLE(value, offset[, noAssert])
 743 ### buf.writeFloatBE(value, offset[, noAssert])
 744
 745 * `value` Number
 746 * `offset` Number
 747 * `noAssert` Boolean, Optional, Default: false
 748
 749 Writes `value` to the buffer at the specified offset with specified endian
 750 format. Note, behavior is unspecified if `value` is not a 32 bit float.
 751
 752 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 753 that `value` may be too large for the specific function and `offset` may be
 754 beyond the end of the buffer leading to the values being silently dropped. This
 755 should not be used unless you are certain of correctness. Defaults to `false`.
 756
 757 Example:
 758
 759     var buf = new Buffer(4);
 760     buf.writeFloatBE(0xcafebabe, 0);
 761
 762     console.log(buf);
 763
 764     buf.writeFloatLE(0xcafebabe, 0);
 765
 766     console.log(buf);
 767
 768     // <Buffer 4f 4a fe bb>
 769     // <Buffer bb fe 4a 4f>
 770
 771 ### buf.writeDoubleLE(value, offset[, noAssert])
 772 ### buf.writeDoubleBE(value, offset[, noAssert])
 773
 774 * `value` Number
 775 * `offset` Number
 776 * `noAssert` Boolean, Optional, Default: false
 777
 778 Writes `value` to the buffer at the specified offset with specified endian
 779 format. Note, `value` must be a valid 64 bit double.
 780
 781 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 782 that `value` may be too large for the specific function and `offset` may be
 783 beyond the end of the buffer leading to the values being silently dropped. This
 784 should not be used unless you are certain of correctness. Defaults to `false`.
 785
 786 Example:
 787
 788     var buf = new Buffer(8);
 789     buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
 790
 791     console.log(buf);
 792
 793     buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
 794
 795     console.log(buf);
 796
 797     // <Buffer 43 eb d5 b7 dd f9 5f d7>
 798     // <Buffer d7 5f f9 dd b7 d5 eb 43>
 799
 800 ### buf.fill(value[, offset][, end])
 801
 802 * `value`
 803 * `offset` Number, Optional
 804 * `end` Number, Optional
 805
 806 Fills the buffer with the specified value. If the `offset` (defaults to `0`)
 807 and `end` (defaults to `buffer.length`) are not given it will fill the entire
 808 buffer.
 809
 810     var b = new Buffer(50);
 811     b.fill("h");
 812
 813 ### buffer.values()
 814
 815 Creates iterator for buffer values (bytes). This function is called automatically
 816 when `buffer` is used in a `for..of` statement.
 817
 818 ### buffer.keys()
 819
 820 Creates iterator for buffer keys (indices).
 821
 822 ### buffer.entries()
 823
 824 Creates iterator for `[index, byte]` arrays.
 825
 826 ## buffer.INSPECT_MAX_BYTES
 827
 828 * Number, Default: 50
 829
 830 How many bytes will be returned when `buffer.inspect()` is called. This can
 831 be overridden by user modules.
 832
 833 Note that this is a property on the buffer module returned by
 834 `require('buffer')`, not on the Buffer global, or a buffer instance.
 835
 836 ## ES6 iteration
 837
 838 Buffers can be iterated over using `for..of` syntax:
 839
 840     var buf = new Buffer([1, 2, 3]);
 841
 842     for (var b of buf)
 843       console.log(b)
 844
 845     // 1
 846     // 2
 847     // 3
 848
 849 Additionally, `buffer.values()`, `buffer.keys()` and `buffer.entries()`
 850 methods can be used to create iterators.
 851
 852 ## Class: SlowBuffer
 853
 854 Returns an un-pooled `Buffer`.
 855
 856 In order to avoid the garbage collection overhead of creating many individually
 857 allocated Buffers, by default allocations under 4KB are sliced from a single
 858 larger allocated object. This approach improves both performance and memory
 859 usage since v8 does not need to track and cleanup as many `Persistent` objects.
 860
 861 In the case where a developer may need to retain a small chunk of memory from a
 862 pool for an indeterminate amount of time it may be appropriate to create an
 863 un-pooled Buffer instance using SlowBuffer and copy out the relevant bits.
 864
 865     // need to keep around a few small chunks of memory
 866     var store = [];
 867
 868     socket.on('readable', function() {
 869       var data = socket.read();
 870       // allocate for retained data
 871       var sb = new SlowBuffer(10);
 872       // copy the data into the new allocation
 873       data.copy(sb, 0, 0, 10);
 874       store.push(sb);
 875     });
 876
 877 Though this should used sparingly and only be a last resort *after* a developer
 878 has actively observed undue memory retention in their applications.