doc/api/buffer.markdown

   1 # Buffer
   2
   3     Stability: 3 - 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. Node 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 Node.
  37
  38 * `'hex'` - Encode each byte as two hexadecimal characters.
  39
  40 A `Buffer` object can also be used with typed arrays.  The buffer object is
  41 cloned to an `ArrayBuffer` that is used as the backing store for the typed
  42 array.  The memory of the buffer and the `ArrayBuffer` is not shared.
  43
  44 NOTE: Node.js v0.8 simply retained a reference to the buffer in `array.buffer`
  45 instead of cloning it.
  46
  47 While more efficient, it introduces subtle incompatibilities with the typed
  48 arrays specification.  `ArrayBuffer#slice()` makes a copy of the slice while
  49 `Buffer#slice()` creates a view.
  50
  51 ## Class: Buffer
  52
  53 The Buffer class is a global type for dealing with binary data directly.
  54 It can be constructed in a variety of ways.
  55
  56 ### new Buffer(size)
  57
  58 * `size` Number
  59
  60 Allocates a new buffer of `size` octets.
  61
  62 ### new Buffer(array)
  63
  64 * `array` Array
  65
  66 Allocates a new buffer using an `array` of octets.
  67
  68 ### new Buffer(str, [encoding])
  69
  70 * `str` String - string to encode.
  71 * `encoding` String - encoding to use, Optional.
  72
  73 Allocates a new buffer containing the given `str`.
  74 `encoding` defaults to `'utf8'`.
  75
  76 ### Class Method: Buffer.isEncoding(encoding)
  77
  78 * `encoding` {String} The encoding string to test
  79
  80 Returns true if the `encoding` is a valid encoding argument, or false
  81 otherwise.
  82
  83 ### Class Method: Buffer.isBuffer(obj)
  84
  85 * `obj` Object
  86 * Return: Boolean
  87
  88 Tests if `obj` is a `Buffer`.
  89
  90 ### Class Method: Buffer.byteLength(string, [encoding])
  91
  92 * `string` String
  93 * `encoding` String, Optional, Default: 'utf8'
  94 * Return: Number
  95
  96 Gives the actual byte length of a string. `encoding` defaults to `'utf8'`.
  97 This is not the same as `String.prototype.length` since that returns the
  98 number of *characters* in a string.
  99
 100 Example:
 101
 102     str = '\u00bd + \u00bc = \u00be';
 103
 104     console.log(str + ": " + str.length + " characters, " +
 105       Buffer.byteLength(str, 'utf8') + " bytes");
 106
 107     // ½ + ¼ = ¾: 9 characters, 12 bytes
 108
 109 ### Class Method: Buffer.concat(list, [totalLength])
 110
 111 * `list` {Array} List of Buffer objects to concat
 112 * `totalLength` {Number} Total length of the buffers when concatenated
 113
 114 Returns a buffer which is the result of concatenating all the buffers in
 115 the list together.
 116
 117 If the list has no items, or if the totalLength is 0, then it returns a
 118 zero-length buffer.
 119
 120 If the list has exactly one item, then the first item of the list is
 121 returned.
 122
 123 If the list has more than one item, then a new Buffer is created.
 124
 125 If totalLength is not provided, it is read from the buffers in the list.
 126 However, this adds an additional loop to the function, so it is faster
 127 to provide the length explicitly.
 128
 129 ### Class Method: Buffer.alloc(length, [receiver])
 130
 131 * `length` Number
 132 * `receiver` Object, Optional, Default: `new Object`
 133
 134
 135 **(EXPERIMENTAL)** Returns object with allocated external array data.
 136
 137 Buffers are backed by a simple allocator that only handles the assignation of
 138 external raw memory. This exposes that functionality.
 139
 140 No pooling is performed for these allocations. So there's no form of memory
 141 leak.
 142
 143 This can be used to create your own Buffer-like classes.
 144
 145     function SimpleData(n) {
 146       this.length = n;
 147       Buffer.alloc(this.length, this);
 148     }
 149
 150     SimpleData.prototype = { /* ... */ };
 151
 152 ### Class Method: Buffer.dispose(obj)
 153
 154 * `obj` Object
 155
 156
 157 **(EXPERIMENTAL)** Free memory that has been allocated to an object via
 158 `Buffer.alloc`.
 159
 160     var a = {};
 161     Buffer.alloc(3, a);
 162
 163     // { '0': 0, '1': 0, '2': 0 }
 164
 165     Buffer.dispose(a);
 166
 167     // {}
 168
 169 ### buf.length
 170
 171 * Number
 172
 173 The size of the buffer in bytes.  Note that this is not necessarily the size
 174 of the contents. `length` refers to the amount of memory allocated for the
 175 buffer object.  It does not change when the contents of the buffer are changed.
 176
 177     buf = new Buffer(1234);
 178
 179     console.log(buf.length);
 180     buf.write("some string", 0, "ascii");
 181     console.log(buf.length);
 182
 183     // 1234
 184     // 1234
 185
 186 ### buf.write(string, [offset], [length], [encoding])
 187
 188 * `string` String - data to be written to buffer
 189 * `offset` Number, Optional, Default: 0
 190 * `length` Number, Optional, Default: `buffer.length - offset`
 191 * `encoding` String, Optional, Default: 'utf8'
 192
 193 Writes `string` to the buffer at `offset` using the given encoding.
 194 `offset` defaults to `0`, `encoding` defaults to `'utf8'`. `length` is
 195 the number of bytes to write. Returns number of octets written. If `buffer` did
 196 not contain enough space to fit the entire string, it will write a partial
 197 amount of the string. `length` defaults to `buffer.length - offset`.
 198 The method will not write partial characters.
 199
 200     buf = new Buffer(256);
 201     len = buf.write('\u00bd + \u00bc = \u00be', 0);
 202     console.log(len + " bytes: " + buf.toString('utf8', 0, len));
 203
 204
 205 ### buf.toString([encoding], [start], [end])
 206
 207 * `encoding` String, Optional, Default: 'utf8'
 208 * `start` Number, Optional, Default: 0
 209 * `end` Number, Optional, Default: `buffer.length`
 210
 211 Decodes and returns a string from buffer data encoded with `encoding`
 212 (defaults to `'utf8'`) beginning at `start` (defaults to `0`) and ending at
 213 `end` (defaults to `buffer.length`).
 214
 215 See `buffer.write()` example, above.
 216
 217
 218 ### buf.toJSON()
 219
 220 Returns a JSON-representation of the Buffer instance.  `JSON.stringify`
 221 implicitly calls this function when stringifying a Buffer instance.
 222
 223 Example:
 224
 225     var buf = new Buffer('test');
 226     var json = JSON.stringify(buf);
 227
 228     console.log(json);
 229     // '{"type":"Buffer","data":[116,101,115,116]}'
 230
 231     var copy = JSON.parse(json, function(key, value) {
 232         return value && value.type === 'Buffer'
 233           ? new Buffer(value.data)
 234           : value;
 235       });
 236
 237     console.log(copy);
 238     // <Buffer 74 65 73 74>
 239
 240 ### buf[index]
 241
 242 <!--type=property-->
 243 <!--name=[index]-->
 244
 245 Get and set the octet at `index`. The values refer to individual bytes,
 246 so the legal range is between `0x00` and `0xFF` hex or `0` and `255`.
 247
 248 Example: copy an ASCII string into a buffer, one byte at a time:
 249
 250     str = "node.js";
 251     buf = new Buffer(str.length);
 252
 253     for (var i = 0; i < str.length ; i++) {
 254       buf[i] = str.charCodeAt(i);
 255     }
 256
 257     console.log(buf);
 258
 259     // node.js
 260
 261 ### buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])
 262
 263 * `targetBuffer` Buffer object - Buffer to copy into
 264 * `targetStart` Number, Optional, Default: 0
 265 * `sourceStart` Number, Optional, Default: 0
 266 * `sourceEnd` Number, Optional, Default: `buffer.length`
 267
 268 Does copy between buffers. The source and target regions can be overlapped.
 269 `targetStart` and `sourceStart` default to `0`.
 270 `sourceEnd` defaults to `buffer.length`.
 271
 272 All values passed that are `undefined`/`NaN` or are out of bounds are set equal
 273 to their respective defaults.
 274
 275 Example: build two Buffers, then copy `buf1` from byte 16 through byte 19
 276 into `buf2`, starting at the 8th byte in `buf2`.
 277
 278     buf1 = new Buffer(26);
 279     buf2 = new Buffer(26);
 280
 281     for (var i = 0 ; i < 26 ; i++) {
 282       buf1[i] = i + 97; // 97 is ASCII a
 283       buf2[i] = 33; // ASCII !
 284     }
 285
 286     buf1.copy(buf2, 8, 16, 20);
 287     console.log(buf2.toString('ascii', 0, 25));
 288
 289     // !!!!!!!!qrst!!!!!!!!!!!!!
 290
 291
 292 ### buf.slice([start], [end])
 293
 294 * `start` Number, Optional, Default: 0
 295 * `end` Number, Optional, Default: `buffer.length`
 296
 297 Returns a new buffer which references the same memory as the old, but offset
 298 and cropped by the `start` (defaults to `0`) and `end` (defaults to
 299 `buffer.length`) indexes.  Negative indexes start from the end of the buffer.
 300
 301 **Modifying the new buffer slice will modify memory in the original buffer!**
 302
 303 Example: build a Buffer with the ASCII alphabet, take a slice, then modify one
 304 byte from the original Buffer.
 305
 306     var buf1 = new Buffer(26);
 307
 308     for (var i = 0 ; i < 26 ; i++) {
 309       buf1[i] = i + 97; // 97 is ASCII a
 310     }
 311
 312     var buf2 = buf1.slice(0, 3);
 313     console.log(buf2.toString('ascii', 0, buf2.length));
 314     buf1[0] = 33;
 315     console.log(buf2.toString('ascii', 0, buf2.length));
 316
 317     // abc
 318     // !bc
 319
 320 ### buf.readUInt8(offset, [noAssert])
 321
 322 * `offset` Number
 323 * `noAssert` Boolean, Optional, Default: false
 324 * Return: Number
 325
 326 Reads an unsigned 8 bit integer from the buffer at the specified offset.
 327
 328 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 329 may be beyond the end of the buffer. Defaults to `false`.
 330
 331 Example:
 332
 333     var buf = new Buffer(4);
 334
 335     buf[0] = 0x3;
 336     buf[1] = 0x4;
 337     buf[2] = 0x23;
 338     buf[3] = 0x42;
 339
 340     for (ii = 0; ii < buf.length; ii++) {
 341       console.log(buf.readUInt8(ii));
 342     }
 343
 344     // 0x3
 345     // 0x4
 346     // 0x23
 347     // 0x42
 348
 349 ### buf.readUInt16LE(offset, [noAssert])
 350 ### buf.readUInt16BE(offset, [noAssert])
 351
 352 * `offset` Number
 353 * `noAssert` Boolean, Optional, Default: false
 354 * Return: Number
 355
 356 Reads an unsigned 16 bit integer from the buffer at the specified offset with
 357 specified endian format.
 358
 359 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 360 may be beyond the end of the buffer. Defaults to `false`.
 361
 362 Example:
 363
 364     var buf = new Buffer(4);
 365
 366     buf[0] = 0x3;
 367     buf[1] = 0x4;
 368     buf[2] = 0x23;
 369     buf[3] = 0x42;
 370
 371     console.log(buf.readUInt16BE(0));
 372     console.log(buf.readUInt16LE(0));
 373     console.log(buf.readUInt16BE(1));
 374     console.log(buf.readUInt16LE(1));
 375     console.log(buf.readUInt16BE(2));
 376     console.log(buf.readUInt16LE(2));
 377
 378     // 0x0304
 379     // 0x0403
 380     // 0x0423
 381     // 0x2304
 382     // 0x2342
 383     // 0x4223
 384
 385 ### buf.readUInt32LE(offset, [noAssert])
 386 ### buf.readUInt32BE(offset, [noAssert])
 387
 388 * `offset` Number
 389 * `noAssert` Boolean, Optional, Default: false
 390 * Return: Number
 391
 392 Reads an unsigned 32 bit integer from the buffer at the specified offset with
 393 specified endian format.
 394
 395 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 396 may be beyond the end of the buffer. Defaults to `false`.
 397
 398 Example:
 399
 400     var buf = new Buffer(4);
 401
 402     buf[0] = 0x3;
 403     buf[1] = 0x4;
 404     buf[2] = 0x23;
 405     buf[3] = 0x42;
 406
 407     console.log(buf.readUInt32BE(0));
 408     console.log(buf.readUInt32LE(0));
 409
 410     // 0x03042342
 411     // 0x42230403
 412
 413 ### buf.readInt8(offset, [noAssert])
 414
 415 * `offset` Number
 416 * `noAssert` Boolean, Optional, Default: false
 417 * Return: Number
 418
 419 Reads a signed 8 bit integer from the buffer at the specified offset.
 420
 421 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 422 may be beyond the end of the buffer. Defaults to `false`.
 423
 424 Works as `buffer.readUInt8`, except buffer contents are treated as two's
 425 complement signed values.
 426
 427 ### buf.readInt16LE(offset, [noAssert])
 428 ### buf.readInt16BE(offset, [noAssert])
 429
 430 * `offset` Number
 431 * `noAssert` Boolean, Optional, Default: false
 432 * Return: Number
 433
 434 Reads a signed 16 bit integer from the buffer at the specified offset with
 435 specified endian format.
 436
 437 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 438 may be beyond the end of the buffer. Defaults to `false`.
 439
 440 Works as `buffer.readUInt16*`, except buffer contents are treated as two's
 441 complement signed values.
 442
 443 ### buf.readInt32LE(offset, [noAssert])
 444 ### buf.readInt32BE(offset, [noAssert])
 445
 446 * `offset` Number
 447 * `noAssert` Boolean, Optional, Default: false
 448 * Return: Number
 449
 450 Reads a signed 32 bit integer from the buffer at the specified offset with
 451 specified endian format.
 452
 453 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 454 may be beyond the end of the buffer. Defaults to `false`.
 455
 456 Works as `buffer.readUInt32*`, except buffer contents are treated as two's
 457 complement signed values.
 458
 459 ### buf.readFloatLE(offset, [noAssert])
 460 ### buf.readFloatBE(offset, [noAssert])
 461
 462 * `offset` Number
 463 * `noAssert` Boolean, Optional, Default: false
 464 * Return: Number
 465
 466 Reads a 32 bit float from the buffer at the specified offset with specified
 467 endian format.
 468
 469 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 470 may be beyond the end of the buffer. Defaults to `false`.
 471
 472 Example:
 473
 474     var buf = new Buffer(4);
 475
 476     buf[0] = 0x00;
 477     buf[1] = 0x00;
 478     buf[2] = 0x80;
 479     buf[3] = 0x3f;
 480
 481     console.log(buf.readFloatLE(0));
 482
 483     // 0x01
 484
 485 ### buf.readDoubleLE(offset, [noAssert])
 486 ### buf.readDoubleBE(offset, [noAssert])
 487
 488 * `offset` Number
 489 * `noAssert` Boolean, Optional, Default: false
 490 * Return: Number
 491
 492 Reads a 64 bit double from the buffer at the specified offset with specified
 493 endian format.
 494
 495 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 496 may be beyond the end of the buffer. Defaults to `false`.
 497
 498 Example:
 499
 500     var buf = new Buffer(8);
 501
 502     buf[0] = 0x55;
 503     buf[1] = 0x55;
 504     buf[2] = 0x55;
 505     buf[3] = 0x55;
 506     buf[4] = 0x55;
 507     buf[5] = 0x55;
 508     buf[6] = 0xd5;
 509     buf[7] = 0x3f;
 510
 511     console.log(buf.readDoubleLE(0));
 512
 513     // 0.3333333333333333
 514
 515 ### buf.writeUInt8(value, offset, [noAssert])
 516
 517 * `value` Number
 518 * `offset` Number
 519 * `noAssert` Boolean, Optional, Default: false
 520
 521 Writes `value` to the buffer at the specified offset. Note, `value` must be a
 522 valid unsigned 8 bit integer.
 523
 524 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 525 that `value` may be too large for the specific function and `offset` may be
 526 beyond the end of the buffer leading to the values being silently dropped. This
 527 should not be used unless you are certain of correctness. Defaults to `false`.
 528
 529 Example:
 530
 531     var buf = new Buffer(4);
 532     buf.writeUInt8(0x3, 0);
 533     buf.writeUInt8(0x4, 1);
 534     buf.writeUInt8(0x23, 2);
 535     buf.writeUInt8(0x42, 3);
 536
 537     console.log(buf);
 538
 539     // <Buffer 03 04 23 42>
 540
 541 ### buf.writeUInt16LE(value, offset, [noAssert])
 542 ### buf.writeUInt16BE(value, offset, [noAssert])
 543
 544 * `value` Number
 545 * `offset` Number
 546 * `noAssert` Boolean, Optional, Default: false
 547
 548 Writes `value` to the buffer at the specified offset with specified endian
 549 format. Note, `value` must be a valid unsigned 16 bit integer.
 550
 551 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 552 that `value` may be too large for the specific function and `offset` may be
 553 beyond the end of the buffer leading to the values being silently dropped. This
 554 should not be used unless you are certain of correctness. Defaults to `false`.
 555
 556 Example:
 557
 558     var buf = new Buffer(4);
 559     buf.writeUInt16BE(0xdead, 0);
 560     buf.writeUInt16BE(0xbeef, 2);
 561
 562     console.log(buf);
 563
 564     buf.writeUInt16LE(0xdead, 0);
 565     buf.writeUInt16LE(0xbeef, 2);
 566
 567     console.log(buf);
 568
 569     // <Buffer de ad be ef>
 570     // <Buffer ad de ef be>
 571
 572 ### buf.writeUInt32LE(value, offset, [noAssert])
 573 ### buf.writeUInt32BE(value, offset, [noAssert])
 574
 575 * `value` Number
 576 * `offset` Number
 577 * `noAssert` Boolean, Optional, Default: false
 578
 579 Writes `value` to the buffer at the specified offset with specified endian
 580 format. Note, `value` must be a valid unsigned 32 bit integer.
 581
 582 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 583 that `value` may be too large for the specific function and `offset` may be
 584 beyond the end of the buffer leading to the values being silently dropped. This
 585 should not be used unless you are certain of correctness. Defaults to `false`.
 586
 587 Example:
 588
 589     var buf = new Buffer(4);
 590     buf.writeUInt32BE(0xfeedface, 0);
 591
 592     console.log(buf);
 593
 594     buf.writeUInt32LE(0xfeedface, 0);
 595
 596     console.log(buf);
 597
 598     // <Buffer fe ed fa ce>
 599     // <Buffer ce fa ed fe>
 600
 601 ### buf.writeInt8(value, offset, [noAssert])
 602
 603 * `value` Number
 604 * `offset` Number
 605 * `noAssert` Boolean, Optional, Default: false
 606
 607 Writes `value` to the buffer at the specified offset. Note, `value` must be a
 608 valid signed 8 bit integer.
 609
 610 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 611 that `value` may be too large for the specific function and `offset` may be
 612 beyond the end of the buffer leading to the values being silently dropped. This
 613 should not be used unless you are certain of correctness. Defaults to `false`.
 614
 615 Works as `buffer.writeUInt8`, except value is written out as a two's complement
 616 signed integer into `buffer`.
 617
 618 ### buf.writeInt16LE(value, offset, [noAssert])
 619 ### buf.writeInt16BE(value, offset, [noAssert])
 620
 621 * `value` Number
 622 * `offset` Number
 623 * `noAssert` Boolean, Optional, Default: false
 624
 625 Writes `value` to the buffer at the specified offset with specified endian
 626 format. Note, `value` must be a valid signed 16 bit integer.
 627
 628 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 629 that `value` may be too large for the specific function and `offset` may be
 630 beyond the end of the buffer leading to the values being silently dropped. This
 631 should not be used unless you are certain of correctness. Defaults to `false`.
 632
 633 Works as `buffer.writeUInt16*`, except value is written out as a two's
 634 complement signed integer into `buffer`.
 635
 636 ### buf.writeInt32LE(value, offset, [noAssert])
 637 ### buf.writeInt32BE(value, offset, [noAssert])
 638
 639 * `value` Number
 640 * `offset` Number
 641 * `noAssert` Boolean, Optional, Default: false
 642
 643 Writes `value` to the buffer at the specified offset with specified endian
 644 format. Note, `value` must be a valid signed 32 bit integer.
 645
 646 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 647 that `value` may be too large for the specific function and `offset` may be
 648 beyond the end of the buffer leading to the values being silently dropped. This
 649 should not be used unless you are certain of correctness. Defaults to `false`.
 650
 651 Works as `buffer.writeUInt32*`, except value is written out as a two's
 652 complement signed integer into `buffer`.
 653
 654 ### buf.writeFloatLE(value, offset, [noAssert])
 655 ### buf.writeFloatBE(value, offset, [noAssert])
 656
 657 * `value` Number
 658 * `offset` Number
 659 * `noAssert` Boolean, Optional, Default: false
 660
 661 Writes `value` to the buffer at the specified offset with specified endian
 662 format. Note, behavior is unspecified if `value` is not a 32 bit float.
 663
 664 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 665 that `value` may be too large for the specific function and `offset` may be
 666 beyond the end of the buffer leading to the values being silently dropped. This
 667 should not be used unless you are certain of correctness. Defaults to `false`.
 668
 669 Example:
 670
 671     var buf = new Buffer(4);
 672     buf.writeFloatBE(0xcafebabe, 0);
 673
 674     console.log(buf);
 675
 676     buf.writeFloatLE(0xcafebabe, 0);
 677
 678     console.log(buf);
 679
 680     // <Buffer 4f 4a fe bb>
 681     // <Buffer bb fe 4a 4f>
 682
 683 ### buf.writeDoubleLE(value, offset, [noAssert])
 684 ### buf.writeDoubleBE(value, offset, [noAssert])
 685
 686 * `value` Number
 687 * `offset` Number
 688 * `noAssert` Boolean, Optional, Default: false
 689
 690 Writes `value` to the buffer at the specified offset with specified endian
 691 format. Note, `value` must be a valid 64 bit double.
 692
 693 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 694 that `value` may be too large for the specific function and `offset` may be
 695 beyond the end of the buffer leading to the values being silently dropped. This
 696 should not be used unless you are certain of correctness. Defaults to `false`.
 697
 698 Example:
 699
 700     var buf = new Buffer(8);
 701     buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
 702
 703     console.log(buf);
 704
 705     buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
 706
 707     console.log(buf);
 708
 709     // <Buffer 43 eb d5 b7 dd f9 5f d7>
 710     // <Buffer d7 5f f9 dd b7 d5 eb 43>
 711
 712 ### buf.fill(value, [offset], [end])
 713
 714 * `value`
 715 * `offset` Number, Optional
 716 * `end` Number, Optional
 717
 718 Fills the buffer with the specified value. If the `offset` (defaults to `0`)
 719 and `end` (defaults to `buffer.length`) are not given it will fill the entire
 720 buffer.
 721
 722     var b = new Buffer(50);
 723     b.fill("h");
 724
 725 ## buffer.INSPECT_MAX_BYTES
 726
 727 * Number, Default: 50
 728
 729 How many bytes will be returned when `buffer.inspect()` is called. This can
 730 be overridden by user modules.
 731
 732 Note that this is a property on the buffer module returned by
 733 `require('buffer')`, not on the Buffer global, or a buffer instance.
 734
 735 ## Class: SlowBuffer
 736
 737 Returns an un-pooled `Buffer`.
 738
 739 In order to avoid the garbage collection overhead of creating many individually
 740 allocated Buffers, by default allocations under 4KB are sliced from a single
 741 larger allocated object. This approach improves both performance and memory
 742 usage since v8 does not need to track and cleanup as many `Persistent` objects.
 743
 744 In the case where a developer may need to retain a small chunk of memory from a
 745 pool for an indeterminate amount of time it may be appropriate to create an
 746 un-pooled Buffer instance using SlowBuffer and copy out the relevant bits.
 747
 748     // need to keep around a few small chunks of memory
 749     var store = [];
 750
 751     socket.on('readable', function() {
 752       var data = socket.read();
 753       // allocate for retained data
 754       var sb = new SlowBuffer(10);
 755       // copy the data into the new allocation
 756       data.copy(sb, 0, 0, 10);
 757       store.push(sb);
 758     });
 759
 760 Though this should used sparingly and only be a last resort *after* a developer
 761 has actively observed undue memory retention in their applications.