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 ### buf.readUInt8(offset[, noAssert])
 396
 397 * `offset` Number
 398 * `noAssert` Boolean, Optional, Default: false
 399 * Return: Number
 400
 401 Reads an unsigned 8 bit integer from the buffer at the specified offset.
 402
 403 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 404 may be beyond the end of the buffer. Defaults to `false`.
 405
 406 Example:
 407
 408     var buf = new Buffer(4);
 409
 410     buf[0] = 0x3;
 411     buf[1] = 0x4;
 412     buf[2] = 0x23;
 413     buf[3] = 0x42;
 414
 415     for (ii = 0; ii < buf.length; ii++) {
 416       console.log(buf.readUInt8(ii));
 417     }
 418
 419     // 0x3
 420     // 0x4
 421     // 0x23
 422     // 0x42
 423
 424 ### buf.readUInt16LE(offset[, noAssert])
 425 ### buf.readUInt16BE(offset[, noAssert])
 426
 427 * `offset` Number
 428 * `noAssert` Boolean, Optional, Default: false
 429 * Return: Number
 430
 431 Reads an unsigned 16 bit integer from the buffer at the specified offset with
 432 specified endian format.
 433
 434 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 435 may be beyond the end of the buffer. Defaults to `false`.
 436
 437 Example:
 438
 439     var buf = new Buffer(4);
 440
 441     buf[0] = 0x3;
 442     buf[1] = 0x4;
 443     buf[2] = 0x23;
 444     buf[3] = 0x42;
 445
 446     console.log(buf.readUInt16BE(0));
 447     console.log(buf.readUInt16LE(0));
 448     console.log(buf.readUInt16BE(1));
 449     console.log(buf.readUInt16LE(1));
 450     console.log(buf.readUInt16BE(2));
 451     console.log(buf.readUInt16LE(2));
 452
 453     // 0x0304
 454     // 0x0403
 455     // 0x0423
 456     // 0x2304
 457     // 0x2342
 458     // 0x4223
 459
 460 ### buf.readUInt32LE(offset[, noAssert])
 461 ### buf.readUInt32BE(offset[, noAssert])
 462
 463 * `offset` Number
 464 * `noAssert` Boolean, Optional, Default: false
 465 * Return: Number
 466
 467 Reads an unsigned 32 bit integer from the buffer at the specified offset with
 468 specified endian format.
 469
 470 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 471 may be beyond the end of the buffer. Defaults to `false`.
 472
 473 Example:
 474
 475     var buf = new Buffer(4);
 476
 477     buf[0] = 0x3;
 478     buf[1] = 0x4;
 479     buf[2] = 0x23;
 480     buf[3] = 0x42;
 481
 482     console.log(buf.readUInt32BE(0));
 483     console.log(buf.readUInt32LE(0));
 484
 485     // 0x03042342
 486     // 0x42230403
 487
 488 ### buf.readInt8(offset[, noAssert])
 489
 490 * `offset` Number
 491 * `noAssert` Boolean, Optional, Default: false
 492 * Return: Number
 493
 494 Reads a signed 8 bit integer from the buffer at the specified offset.
 495
 496 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 497 may be beyond the end of the buffer. Defaults to `false`.
 498
 499 Works as `buffer.readUInt8`, except buffer contents are treated as two's
 500 complement signed values.
 501
 502 ### buf.readInt16LE(offset[, noAssert])
 503 ### buf.readInt16BE(offset[, noAssert])
 504
 505 * `offset` Number
 506 * `noAssert` Boolean, Optional, Default: false
 507 * Return: Number
 508
 509 Reads a signed 16 bit integer from the buffer at the specified offset with
 510 specified endian format.
 511
 512 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 513 may be beyond the end of the buffer. Defaults to `false`.
 514
 515 Works as `buffer.readUInt16*`, except buffer contents are treated as two's
 516 complement signed values.
 517
 518 ### buf.readInt32LE(offset[, noAssert])
 519 ### buf.readInt32BE(offset[, noAssert])
 520
 521 * `offset` Number
 522 * `noAssert` Boolean, Optional, Default: false
 523 * Return: Number
 524
 525 Reads a signed 32 bit integer from the buffer at the specified offset with
 526 specified endian format.
 527
 528 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 529 may be beyond the end of the buffer. Defaults to `false`.
 530
 531 Works as `buffer.readUInt32*`, except buffer contents are treated as two's
 532 complement signed values.
 533
 534 ### buf.readFloatLE(offset[, noAssert])
 535 ### buf.readFloatBE(offset[, noAssert])
 536
 537 * `offset` Number
 538 * `noAssert` Boolean, Optional, Default: false
 539 * Return: Number
 540
 541 Reads a 32 bit float from the buffer at the specified offset with specified
 542 endian format.
 543
 544 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 545 may be beyond the end of the buffer. Defaults to `false`.
 546
 547 Example:
 548
 549     var buf = new Buffer(4);
 550
 551     buf[0] = 0x00;
 552     buf[1] = 0x00;
 553     buf[2] = 0x80;
 554     buf[3] = 0x3f;
 555
 556     console.log(buf.readFloatLE(0));
 557
 558     // 0x01
 559
 560 ### buf.readDoubleLE(offset[, noAssert])
 561 ### buf.readDoubleBE(offset[, noAssert])
 562
 563 * `offset` Number
 564 * `noAssert` Boolean, Optional, Default: false
 565 * Return: Number
 566
 567 Reads a 64 bit double from the buffer at the specified offset with specified
 568 endian format.
 569
 570 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 571 may be beyond the end of the buffer. Defaults to `false`.
 572
 573 Example:
 574
 575     var buf = new Buffer(8);
 576
 577     buf[0] = 0x55;
 578     buf[1] = 0x55;
 579     buf[2] = 0x55;
 580     buf[3] = 0x55;
 581     buf[4] = 0x55;
 582     buf[5] = 0x55;
 583     buf[6] = 0xd5;
 584     buf[7] = 0x3f;
 585
 586     console.log(buf.readDoubleLE(0));
 587
 588     // 0.3333333333333333
 589
 590 ### buf.writeUInt8(value, offset[, noAssert])
 591
 592 * `value` Number
 593 * `offset` Number
 594 * `noAssert` Boolean, Optional, Default: false
 595
 596 Writes `value` to the buffer at the specified offset. Note, `value` must be a
 597 valid unsigned 8 bit integer.
 598
 599 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 600 that `value` may be too large for the specific function and `offset` may be
 601 beyond the end of the buffer leading to the values being silently dropped. This
 602 should not be used unless you are certain of correctness. Defaults to `false`.
 603
 604 Example:
 605
 606     var buf = new Buffer(4);
 607     buf.writeUInt8(0x3, 0);
 608     buf.writeUInt8(0x4, 1);
 609     buf.writeUInt8(0x23, 2);
 610     buf.writeUInt8(0x42, 3);
 611
 612     console.log(buf);
 613
 614     // <Buffer 03 04 23 42>
 615
 616 ### buf.writeUInt16LE(value, offset[, noAssert])
 617 ### buf.writeUInt16BE(value, offset[, noAssert])
 618
 619 * `value` Number
 620 * `offset` Number
 621 * `noAssert` Boolean, Optional, Default: false
 622
 623 Writes `value` to the buffer at the specified offset with specified endian
 624 format. Note, `value` must be a valid unsigned 16 bit integer.
 625
 626 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 627 that `value` may be too large for the specific function and `offset` may be
 628 beyond the end of the buffer leading to the values being silently dropped. This
 629 should not be used unless you are certain of correctness. Defaults to `false`.
 630
 631 Example:
 632
 633     var buf = new Buffer(4);
 634     buf.writeUInt16BE(0xdead, 0);
 635     buf.writeUInt16BE(0xbeef, 2);
 636
 637     console.log(buf);
 638
 639     buf.writeUInt16LE(0xdead, 0);
 640     buf.writeUInt16LE(0xbeef, 2);
 641
 642     console.log(buf);
 643
 644     // <Buffer de ad be ef>
 645     // <Buffer ad de ef be>
 646
 647 ### buf.writeUInt32LE(value, offset[, noAssert])
 648 ### buf.writeUInt32BE(value, offset[, noAssert])
 649
 650 * `value` Number
 651 * `offset` Number
 652 * `noAssert` Boolean, Optional, Default: false
 653
 654 Writes `value` to the buffer at the specified offset with specified endian
 655 format. Note, `value` must be a valid unsigned 32 bit integer.
 656
 657 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 658 that `value` may be too large for the specific function and `offset` may be
 659 beyond the end of the buffer leading to the values being silently dropped. This
 660 should not be used unless you are certain of correctness. Defaults to `false`.
 661
 662 Example:
 663
 664     var buf = new Buffer(4);
 665     buf.writeUInt32BE(0xfeedface, 0);
 666
 667     console.log(buf);
 668
 669     buf.writeUInt32LE(0xfeedface, 0);
 670
 671     console.log(buf);
 672
 673     // <Buffer fe ed fa ce>
 674     // <Buffer ce fa ed fe>
 675
 676 ### buf.writeInt8(value, offset[, noAssert])
 677
 678 * `value` Number
 679 * `offset` Number
 680 * `noAssert` Boolean, Optional, Default: false
 681
 682 Writes `value` to the buffer at the specified offset. Note, `value` must be a
 683 valid signed 8 bit integer.
 684
 685 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 686 that `value` may be too large for the specific function and `offset` may be
 687 beyond the end of the buffer leading to the values being silently dropped. This
 688 should not be used unless you are certain of correctness. Defaults to `false`.
 689
 690 Works as `buffer.writeUInt8`, except value is written out as a two's complement
 691 signed integer into `buffer`.
 692
 693 ### buf.writeInt16LE(value, offset[, noAssert])
 694 ### buf.writeInt16BE(value, offset[, noAssert])
 695
 696 * `value` Number
 697 * `offset` Number
 698 * `noAssert` Boolean, Optional, Default: false
 699
 700 Writes `value` to the buffer at the specified offset with specified endian
 701 format. Note, `value` must be a valid signed 16 bit integer.
 702
 703 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 704 that `value` may be too large for the specific function and `offset` may be
 705 beyond the end of the buffer leading to the values being silently dropped. This
 706 should not be used unless you are certain of correctness. Defaults to `false`.
 707
 708 Works as `buffer.writeUInt16*`, except value is written out as a two's
 709 complement signed integer into `buffer`.
 710
 711 ### buf.writeInt32LE(value, offset[, noAssert])
 712 ### buf.writeInt32BE(value, offset[, noAssert])
 713
 714 * `value` Number
 715 * `offset` Number
 716 * `noAssert` Boolean, Optional, Default: false
 717
 718 Writes `value` to the buffer at the specified offset with specified endian
 719 format. Note, `value` must be a valid signed 32 bit integer.
 720
 721 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 722 that `value` may be too large for the specific function and `offset` may be
 723 beyond the end of the buffer leading to the values being silently dropped. This
 724 should not be used unless you are certain of correctness. Defaults to `false`.
 725
 726 Works as `buffer.writeUInt32*`, except value is written out as a two's
 727 complement signed integer into `buffer`.
 728
 729 ### buf.writeFloatLE(value, offset[, noAssert])
 730 ### buf.writeFloatBE(value, offset[, noAssert])
 731
 732 * `value` Number
 733 * `offset` Number
 734 * `noAssert` Boolean, Optional, Default: false
 735
 736 Writes `value` to the buffer at the specified offset with specified endian
 737 format. Note, behavior is unspecified if `value` is not a 32 bit float.
 738
 739 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 740 that `value` may be too large for the specific function and `offset` may be
 741 beyond the end of the buffer leading to the values being silently dropped. This
 742 should not be used unless you are certain of correctness. Defaults to `false`.
 743
 744 Example:
 745
 746     var buf = new Buffer(4);
 747     buf.writeFloatBE(0xcafebabe, 0);
 748
 749     console.log(buf);
 750
 751     buf.writeFloatLE(0xcafebabe, 0);
 752
 753     console.log(buf);
 754
 755     // <Buffer 4f 4a fe bb>
 756     // <Buffer bb fe 4a 4f>
 757
 758 ### buf.writeDoubleLE(value, offset[, noAssert])
 759 ### buf.writeDoubleBE(value, offset[, noAssert])
 760
 761 * `value` Number
 762 * `offset` Number
 763 * `noAssert` Boolean, Optional, Default: false
 764
 765 Writes `value` to the buffer at the specified offset with specified endian
 766 format. Note, `value` must be a valid 64 bit double.
 767
 768 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 769 that `value` may be too large for the specific function and `offset` may be
 770 beyond the end of the buffer leading to the values being silently dropped. This
 771 should not be used unless you are certain of correctness. Defaults to `false`.
 772
 773 Example:
 774
 775     var buf = new Buffer(8);
 776     buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
 777
 778     console.log(buf);
 779
 780     buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
 781
 782     console.log(buf);
 783
 784     // <Buffer 43 eb d5 b7 dd f9 5f d7>
 785     // <Buffer d7 5f f9 dd b7 d5 eb 43>
 786
 787 ### buf.fill(value[, offset][, end])
 788
 789 * `value`
 790 * `offset` Number, Optional
 791 * `end` Number, Optional
 792
 793 Fills the buffer with the specified value. If the `offset` (defaults to `0`)
 794 and `end` (defaults to `buffer.length`) are not given it will fill the entire
 795 buffer.
 796
 797     var b = new Buffer(50);
 798     b.fill("h");
 799
 800 ### buffer.values()
 801
 802 Creates iterator for buffer values (bytes). This function is called automatically
 803 when `buffer` is used in a `for..of` statement.
 804
 805 ### buffer.keys()
 806
 807 Creates iterator for buffer keys (indices).
 808
 809 ### buffer.entries()
 810
 811 Creates iterator for `[index, byte]` arrays.
 812
 813 ## buffer.INSPECT_MAX_BYTES
 814
 815 * Number, Default: 50
 816
 817 How many bytes will be returned when `buffer.inspect()` is called. This can
 818 be overridden by user modules.
 819
 820 Note that this is a property on the buffer module returned by
 821 `require('buffer')`, not on the Buffer global, or a buffer instance.
 822
 823 ## ES6 iteration
 824
 825 Buffers can be iterated over using `for..of` syntax:
 826
 827     var buf = new Buffer([1, 2, 3]);
 828
 829     for (var b of buf)
 830       console.log(b)
 831
 832     // 1
 833     // 2
 834     // 3
 835
 836 Additionally, `buffer.values()`, `buffer.keys()` and `buffer.entries()`
 837 methods can be used to create iterators.
 838
 839 ## Class: SlowBuffer
 840
 841 Returns an un-pooled `Buffer`.
 842
 843 In order to avoid the garbage collection overhead of creating many individually
 844 allocated Buffers, by default allocations under 4KB are sliced from a single
 845 larger allocated object. This approach improves both performance and memory
 846 usage since v8 does not need to track and cleanup as many `Persistent` objects.
 847
 848 In the case where a developer may need to retain a small chunk of memory from a
 849 pool for an indeterminate amount of time it may be appropriate to create an
 850 un-pooled Buffer instance using SlowBuffer and copy out the relevant bits.
 851
 852     // need to keep around a few small chunks of memory
 853     var store = [];
 854
 855     socket.on('readable', function() {
 856       var data = socket.read();
 857       // allocate for retained data
 858       var sb = new SlowBuffer(10);
 859       // copy the data into the new allocation
 860       data.copy(sb, 0, 0, 10);
 861       store.push(sb);
 862     });
 863
 864 Though this should used sparingly and only be a last resort *after* a developer
 865 has actively observed undue memory retention in their applications.