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.
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.
14 The `Buffer` class is a global, making it very rare that one would need
15 to ever `require('buffer')`.
17 Converting between Buffers and JavaScript string objects requires an explicit
18 encoding method. Here are the different string encodings.
20 * `'ascii'` - for 7 bit ASCII data only. This encoding method is very fast, and
21 will strip the high bit if set.
23 * `'utf8'` - Multibyte encoded Unicode characters. Many web pages and other
24 document formats use UTF-8.
26 * `'utf16le'` - 2 or 4 bytes, little endian encoded Unicode characters.
27 Surrogate pairs (U+10000 to U+10FFFF) are supported.
29 * `'ucs2'` - Alias of `'utf16le'`.
31 * `'base64'` - Base64 string encoding.
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.
38 * `'hex'` - Encode each byte as two hexadecimal characters.
42 The Buffer class is a global type for dealing with binary data directly.
43 It can be constructed in a variety of ways.
49 Allocates a new buffer of `size` octets.
55 Allocates a new buffer using an `array` of octets.
57 ### new Buffer(str, [encoding])
59 * `str` String - string to encode.
60 * `encoding` String - encoding to use, Optional.
62 Allocates a new buffer containing the given `str`.
63 `encoding` defaults to `'utf8'`.
65 ### Class Method: Buffer.isEncoding(encoding)
67 * `encoding` {String} The encoding string to test
69 Returns true if the `encoding` is a valid encoding argument, or false
72 ### Class Method: Buffer.isBuffer(obj)
77 Tests if `obj` is a `Buffer`.
79 ### Class Method: Buffer.byteLength(string, [encoding])
82 * `encoding` String, Optional, Default: 'utf8'
85 Gives the actual byte length of a string. `encoding` defaults to `'utf8'`.
86 This is not the same as `String.prototype.length` since that returns the
87 number of *characters* in a string.
91 str = '\u00bd + \u00bc = \u00be';
93 console.log(str + ": " + str.length + " characters, " +
94 Buffer.byteLength(str, 'utf8') + " bytes");
96 // ½ + ¼ = ¾: 9 characters, 12 bytes
98 ### Class Method: Buffer.concat(list, [totalLength])
100 * `list` {Array} List of Buffer objects to concat
101 * `totalLength` {Number} Total length of the buffers when concatenated
103 Returns a buffer which is the result of concatenating all the buffers in
106 If the list has no items, or if the totalLength is 0, then it returns a
109 If the list has exactly one item, then the first item of the list is
112 If the list has more than one item, then a new Buffer is created.
114 If totalLength is not provided, it is read from the buffers in the list.
115 However, this adds an additional loop to the function, so it is faster
116 to provide the length explicitly.
122 The size of the buffer in bytes. Note that this is not necessarily the size
123 of the contents. `length` refers to the amount of memory allocated for the
124 buffer object. It does not change when the contents of the buffer are changed.
126 buf = new Buffer(1234);
128 console.log(buf.length);
129 buf.write("some string", 0, "ascii");
130 console.log(buf.length);
135 ### buf.write(string, [offset], [length], [encoding])
137 * `string` String - data to be written to buffer
138 * `offset` Number, Optional, Default: 0
139 * `length` Number, Optional, Default: `buffer.length - offset`
140 * `encoding` String, Optional, Default: 'utf8'
142 Writes `string` to the buffer at `offset` using the given encoding.
143 `offset` defaults to `0`, `encoding` defaults to `'utf8'`. `length` is
144 the number of bytes to write. Returns number of octets written. If `buffer` did
145 not contain enough space to fit the entire string, it will write a partial
146 amount of the string. `length` defaults to `buffer.length - offset`.
147 The method will not write partial characters.
149 buf = new Buffer(256);
150 len = buf.write('\u00bd + \u00bc = \u00be', 0);
151 console.log(len + " bytes: " + buf.toString('utf8', 0, len));
154 ### buf.toString([encoding], [start], [end])
156 * `encoding` String, Optional, Default: 'utf8'
157 * `start` Number, Optional, Default: 0
158 * `end` Number, Optional, Default: `buffer.length`
160 Decodes and returns a string from buffer data encoded with `encoding`
161 (defaults to `'utf8'`) beginning at `start` (defaults to `0`) and ending at
162 `end` (defaults to `buffer.length`).
164 See `buffer.write()` example, above.
169 Returns a JSON-representation of the Buffer instance. `JSON.stringify`
170 implicitly calls this function when stringifying a Buffer instance.
174 var buf = new Buffer('test');
175 var json = JSON.stringify(buf);
178 // '{"type":"Buffer","data":[116,101,115,116]}'
180 var copy = JSON.parse(json, function(key, value) {
181 return value && value.type === 'Buffer'
182 ? new Buffer(value.data)
187 // <Buffer 74 65 73 74>
194 Get and set the octet at `index`. The values refer to individual bytes,
195 so the legal range is between `0x00` and `0xFF` hex or `0` and `255`.
197 Example: copy an ASCII string into a buffer, one byte at a time:
200 buf = new Buffer(str.length);
202 for (var i = 0; i < str.length ; i++) {
203 buf[i] = str.charCodeAt(i);
210 ### buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])
212 * `targetBuffer` Buffer object - Buffer to copy into
213 * `targetStart` Number, Optional, Default: 0
214 * `sourceStart` Number, Optional, Default: 0
215 * `sourceEnd` Number, Optional, Default: `buffer.length`
217 Does copy between buffers. The source and target regions can be overlapped.
218 `targetStart` and `sourceStart` default to `0`.
219 `sourceEnd` defaults to `buffer.length`.
221 All values passed that are `undefined`/`NaN` or are out of bounds are set equal
222 to their respective defaults.
224 Example: build two Buffers, then copy `buf1` from byte 16 through byte 19
225 into `buf2`, starting at the 8th byte in `buf2`.
227 buf1 = new Buffer(26);
228 buf2 = new Buffer(26);
230 for (var i = 0 ; i < 26 ; i++) {
231 buf1[i] = i + 97; // 97 is ASCII a
232 buf2[i] = 33; // ASCII !
235 buf1.copy(buf2, 8, 16, 20);
236 console.log(buf2.toString('ascii', 0, 25));
238 // !!!!!!!!qrst!!!!!!!!!!!!!
241 ### buf.slice([start], [end])
243 * `start` Number, Optional, Default: 0
244 * `end` Number, Optional, Default: `buffer.length`
246 Returns a new buffer which references the same memory as the old, but offset
247 and cropped by the `start` (defaults to `0`) and `end` (defaults to
248 `buffer.length`) indexes. Negative indexes start from the end of the buffer.
250 **Modifying the new buffer slice will modify memory in the original buffer!**
252 Example: build a Buffer with the ASCII alphabet, take a slice, then modify one
253 byte from the original Buffer.
255 var buf1 = new Buffer(26);
257 for (var i = 0 ; i < 26 ; i++) {
258 buf1[i] = i + 97; // 97 is ASCII a
261 var buf2 = buf1.slice(0, 3);
262 console.log(buf2.toString('ascii', 0, buf2.length));
264 console.log(buf2.toString('ascii', 0, buf2.length));
269 ### buf.readUInt8(offset, [noAssert])
272 * `noAssert` Boolean, Optional, Default: false
275 Reads an unsigned 8 bit integer from the buffer at the specified offset.
277 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
278 may be beyond the end of the buffer. Defaults to `false`.
282 var buf = new Buffer(4);
289 for (ii = 0; ii < buf.length; ii++) {
290 console.log(buf.readUInt8(ii));
298 ### buf.readUInt16LE(offset, [noAssert])
299 ### buf.readUInt16BE(offset, [noAssert])
302 * `noAssert` Boolean, Optional, Default: false
305 Reads an unsigned 16 bit integer from the buffer at the specified offset with
306 specified endian format.
308 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
309 may be beyond the end of the buffer. Defaults to `false`.
313 var buf = new Buffer(4);
320 console.log(buf.readUInt16BE(0));
321 console.log(buf.readUInt16LE(0));
322 console.log(buf.readUInt16BE(1));
323 console.log(buf.readUInt16LE(1));
324 console.log(buf.readUInt16BE(2));
325 console.log(buf.readUInt16LE(2));
334 ### buf.readUInt32LE(offset, [noAssert])
335 ### buf.readUInt32BE(offset, [noAssert])
338 * `noAssert` Boolean, Optional, Default: false
341 Reads an unsigned 32 bit integer from the buffer at the specified offset with
342 specified endian format.
344 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
345 may be beyond the end of the buffer. Defaults to `false`.
349 var buf = new Buffer(4);
356 console.log(buf.readUInt32BE(0));
357 console.log(buf.readUInt32LE(0));
362 ### buf.readInt8(offset, [noAssert])
365 * `noAssert` Boolean, Optional, Default: false
368 Reads a signed 8 bit integer from the buffer at the specified offset.
370 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
371 may be beyond the end of the buffer. Defaults to `false`.
373 Works as `buffer.readUInt8`, except buffer contents are treated as two's
374 complement signed values.
376 ### buf.readInt16LE(offset, [noAssert])
377 ### buf.readInt16BE(offset, [noAssert])
380 * `noAssert` Boolean, Optional, Default: false
383 Reads a signed 16 bit integer from the buffer at the specified offset with
384 specified endian format.
386 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
387 may be beyond the end of the buffer. Defaults to `false`.
389 Works as `buffer.readUInt16*`, except buffer contents are treated as two's
390 complement signed values.
392 ### buf.readInt32LE(offset, [noAssert])
393 ### buf.readInt32BE(offset, [noAssert])
396 * `noAssert` Boolean, Optional, Default: false
399 Reads a signed 32 bit integer from the buffer at the specified offset with
400 specified endian format.
402 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
403 may be beyond the end of the buffer. Defaults to `false`.
405 Works as `buffer.readUInt32*`, except buffer contents are treated as two's
406 complement signed values.
408 ### buf.readFloatLE(offset, [noAssert])
409 ### buf.readFloatBE(offset, [noAssert])
412 * `noAssert` Boolean, Optional, Default: false
415 Reads a 32 bit float from the buffer at the specified offset with specified
418 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
419 may be beyond the end of the buffer. Defaults to `false`.
423 var buf = new Buffer(4);
430 console.log(buf.readFloatLE(0));
434 ### buf.readDoubleLE(offset, [noAssert])
435 ### buf.readDoubleBE(offset, [noAssert])
438 * `noAssert` Boolean, Optional, Default: false
441 Reads a 64 bit double from the buffer at the specified offset with specified
444 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
445 may be beyond the end of the buffer. Defaults to `false`.
449 var buf = new Buffer(8);
460 console.log(buf.readDoubleLE(0));
462 // 0.3333333333333333
464 ### buf.writeUInt8(value, offset, [noAssert])
468 * `noAssert` Boolean, Optional, Default: false
470 Writes `value` to the buffer at the specified offset. Note, `value` must be a
471 valid unsigned 8 bit integer.
473 Set `noAssert` to true to skip validation of `value` and `offset`. This means
474 that `value` may be too large for the specific function and `offset` may be
475 beyond the end of the buffer leading to the values being silently dropped. This
476 should not be used unless you are certain of correctness. Defaults to `false`.
480 var buf = new Buffer(4);
481 buf.writeUInt8(0x3, 0);
482 buf.writeUInt8(0x4, 1);
483 buf.writeUInt8(0x23, 2);
484 buf.writeUInt8(0x42, 3);
488 // <Buffer 03 04 23 42>
490 ### buf.writeUInt16LE(value, offset, [noAssert])
491 ### buf.writeUInt16BE(value, offset, [noAssert])
495 * `noAssert` Boolean, Optional, Default: false
497 Writes `value` to the buffer at the specified offset with specified endian
498 format. Note, `value` must be a valid unsigned 16 bit integer.
500 Set `noAssert` to true to skip validation of `value` and `offset`. This means
501 that `value` may be too large for the specific function and `offset` may be
502 beyond the end of the buffer leading to the values being silently dropped. This
503 should not be used unless you are certain of correctness. Defaults to `false`.
507 var buf = new Buffer(4);
508 buf.writeUInt16BE(0xdead, 0);
509 buf.writeUInt16BE(0xbeef, 2);
513 buf.writeUInt16LE(0xdead, 0);
514 buf.writeUInt16LE(0xbeef, 2);
518 // <Buffer de ad be ef>
519 // <Buffer ad de ef be>
521 ### buf.writeUInt32LE(value, offset, [noAssert])
522 ### buf.writeUInt32BE(value, offset, [noAssert])
526 * `noAssert` Boolean, Optional, Default: false
528 Writes `value` to the buffer at the specified offset with specified endian
529 format. Note, `value` must be a valid unsigned 32 bit integer.
531 Set `noAssert` to true to skip validation of `value` and `offset`. This means
532 that `value` may be too large for the specific function and `offset` may be
533 beyond the end of the buffer leading to the values being silently dropped. This
534 should not be used unless you are certain of correctness. Defaults to `false`.
538 var buf = new Buffer(4);
539 buf.writeUInt32BE(0xfeedface, 0);
543 buf.writeUInt32LE(0xfeedface, 0);
547 // <Buffer fe ed fa ce>
548 // <Buffer ce fa ed fe>
550 ### buf.writeInt8(value, offset, [noAssert])
554 * `noAssert` Boolean, Optional, Default: false
556 Writes `value` to the buffer at the specified offset. Note, `value` must be a
557 valid signed 8 bit integer.
559 Set `noAssert` to true to skip validation of `value` and `offset`. This means
560 that `value` may be too large for the specific function and `offset` may be
561 beyond the end of the buffer leading to the values being silently dropped. This
562 should not be used unless you are certain of correctness. Defaults to `false`.
564 Works as `buffer.writeUInt8`, except value is written out as a two's complement
565 signed integer into `buffer`.
567 ### buf.writeInt16LE(value, offset, [noAssert])
568 ### buf.writeInt16BE(value, offset, [noAssert])
572 * `noAssert` Boolean, Optional, Default: false
574 Writes `value` to the buffer at the specified offset with specified endian
575 format. Note, `value` must be a valid signed 16 bit integer.
577 Set `noAssert` to true to skip validation of `value` and `offset`. This means
578 that `value` may be too large for the specific function and `offset` may be
579 beyond the end of the buffer leading to the values being silently dropped. This
580 should not be used unless you are certain of correctness. Defaults to `false`.
582 Works as `buffer.writeUInt16*`, except value is written out as a two's
583 complement signed integer into `buffer`.
585 ### buf.writeInt32LE(value, offset, [noAssert])
586 ### buf.writeInt32BE(value, offset, [noAssert])
590 * `noAssert` Boolean, Optional, Default: false
592 Writes `value` to the buffer at the specified offset with specified endian
593 format. Note, `value` must be a valid signed 32 bit integer.
595 Set `noAssert` to true to skip validation of `value` and `offset`. This means
596 that `value` may be too large for the specific function and `offset` may be
597 beyond the end of the buffer leading to the values being silently dropped. This
598 should not be used unless you are certain of correctness. Defaults to `false`.
600 Works as `buffer.writeUInt32*`, except value is written out as a two's
601 complement signed integer into `buffer`.
603 ### buf.writeFloatLE(value, offset, [noAssert])
604 ### buf.writeFloatBE(value, offset, [noAssert])
608 * `noAssert` Boolean, Optional, Default: false
610 Writes `value` to the buffer at the specified offset with specified endian
611 format. Note, behavior is unspecified if `value` is not a 32 bit float.
613 Set `noAssert` to true to skip validation of `value` and `offset`. This means
614 that `value` may be too large for the specific function and `offset` may be
615 beyond the end of the buffer leading to the values being silently dropped. This
616 should not be used unless you are certain of correctness. Defaults to `false`.
620 var buf = new Buffer(4);
621 buf.writeFloatBE(0xcafebabe, 0);
625 buf.writeFloatLE(0xcafebabe, 0);
629 // <Buffer 4f 4a fe bb>
630 // <Buffer bb fe 4a 4f>
632 ### buf.writeDoubleLE(value, offset, [noAssert])
633 ### buf.writeDoubleBE(value, offset, [noAssert])
637 * `noAssert` Boolean, Optional, Default: false
639 Writes `value` to the buffer at the specified offset with specified endian
640 format. Note, `value` must be a valid 64 bit double.
642 Set `noAssert` to true to skip validation of `value` and `offset`. This means
643 that `value` may be too large for the specific function and `offset` may be
644 beyond the end of the buffer leading to the values being silently dropped. This
645 should not be used unless you are certain of correctness. Defaults to `false`.
649 var buf = new Buffer(8);
650 buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
654 buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
658 // <Buffer 43 eb d5 b7 dd f9 5f d7>
659 // <Buffer d7 5f f9 dd b7 d5 eb 43>
661 ### buf.fill(value, [offset], [end])
664 * `offset` Number, Optional
665 * `end` Number, Optional
667 Fills the buffer with the specified value. If the `offset` (defaults to `0`)
668 and `end` (defaults to `buffer.length`) are not given it will fill the entire
671 var b = new Buffer(50);
674 ### buf.toArrayBuffer()
676 Creates a new `ArrayBuffer` with the copied memory of the buffer instance.
678 ## buffer.INSPECT_MAX_BYTES
680 * Number, Default: 50
682 How many bytes will be returned when `buffer.inspect()` is called. This can
683 be overridden by user modules.
685 Note that this is a property on the buffer module returned by
686 `require('buffer')`, not on the Buffer global, or a buffer instance.
690 Returns an un-pooled `Buffer`.
692 In order to avoid the garbage collection overhead of creating many individually
693 allocated Buffers, by default allocations under 4KB are sliced from a single
694 larger allocated object. This approach improves both performance and memory
695 usage since v8 does not need to track and cleanup as many `Persistent` objects.
697 In the case where a developer may need to retain a small chunk of memory from a
698 pool for an indeterminate amount of time it may be appropriate to create an
699 un-pooled Buffer instance using SlowBuffer and copy out the relevant bits.
701 // need to keep around a few small chunks of memory
704 socket.on('readable', function() {
705 var data = socket.read();
706 // allocate for retained data
707 var sb = new SlowBuffer(10);
708 // copy the data into the new allocation
709 data.copy(sb, 0, 0, 10);
713 Though this should used sparingly and only be a last resort *after* a developer
714 has actively observed undue memory retention in their applications.