Node.js stores raw data in instances of a Buffer class which is similar to an array of integers but stores raw memory allocations outside the heap. A Buffer is a region of a physical memory storage used to temporarily store data while it is being manipulated. A Buffer class is global in scope, thus not needing a require to use it, and cannot be resized.
Converting Between String Objects and Buffers
To convert between a Buffer and a String Object requires you to supply an explicit encoding method. The following is a list of the different string encodings available:
| ascii | To be used for 7-bit ASCII data only and limited to the ASCII character set. This is a very fast encoding method but will strip the high-bit off if set. |
|---|---|
| utf8 | Multi-byte encoded Unicode characters typically used in many document formats including web based content. |
| utf16le,ucs2 | 2 or 4 bytes, little endian encoded Unicode characters. It can encode only Basic Multilingual Plane U+0000 - U+FFFF (BMP). |
| base64 | Base64 encoded strings |
| binary | A deprecated encoding from raw binary data into strings by only using the first 8 bits of each character. This should not be used as it will be removed from Node.js in the future. |
| hex | Encode each byte as two hexidecimal characters. |
Creating Buffers in Node.js
The Buffer object has the following constructors for creation:
// Allocate a new Buffer of “size” octets new Buffer( size // number; size of the buffer ); > var buf = new Buffer(5); // Create a buffer of size 5. > console.log(buf); <Buffer 00 00 00 00 00> // Allocates a new Buffer using the supplied Array of octets new Buffer( array // array; user supplied array of data ); > var buf = new Buffer([1,2,3,4,5]); // Create a buffer of size 5 with the numbers 1-5. > console.log(buf); <Buffer 00 01 02 03 04 05> /// Allocates a new buffer containing the string “str”. The encoding defaults to “utf8”. new Buffer( str, // string; A input string to store in the Buffer encoding // string (optional); Character encoding defaulting to utf8. ); >var buf = new Buffer(“Hello World!”, “utf8”); // Create a Buffer containing the string “Hello World!” >console.log(buf); <Buffer 48 65 6c 6c 6f 20 57 6f 72 6c 64 21> Static Methods
The Buffer object contains the following static methods for use when interacting with Buffer objects.
// Test if encoding string is valid Buffer.isEncoding( encoding // string; Encoding string to verify ); // Test if object is a Buffer Buffer.isBuffer( obj // object; object to test ); // Calculate the byte length of a string Buffer.byteLength( string, // string; input string to get length of encoding // string (optional); encoding string defaults to utf8. ); // Concatenate a list of Buffer objects into a single Buffer Buffer.concat( list, // array; Array of Buffer objects totalLength // number (optional); total length of buffers when concatenated ); Writing To Buffers
Buffers aren’t of much use unless you can actually manipulate the data in them. The constructors can be used to create new Buffers with content and the write method allows you to write a string to an existing buffer. You can also use the [] accessor to set individual octets in the Buffer.
// Write a string to a Buffer buf.write( str, // string; A supplied string offset, // number (optional); The index of the buffer to start writing to (default is 0) length, // number (optional); The number of bytes to write (defaults to buf.length – offset. encoding // string (encoding); The encoding to use (defaults to utf8). ); > var buf = new Buffer(“Hi There); > buf.toString(); ”Hi There” > buf.write(“HI”); > buf.toString(); ”HI There” >buf.write(“H”, 4); >buf.toString(); ”HI THere” >buf[7] = “E” >buf.toString(); ”HI THerE” Reading From Buffers
Reading from Buffers can be done with the index [] accessor and the toString() method to convert the Buffer to a string
// decode and return a string from a Buffer buf.toString( encoding, // string (optional); The encoding to use when converting to a string (defaults to “utf8”). start, // number (optional); The index in Buffer to start at (defaults to 0). end // number (optional); The index in Buffer to end at (defaults to buf.length). ); >var buf = new Buffer(“Hi There”); >buf.toString(); ”Hi There” >buf[3]; ”T” >buf.toString(“utf8”, 3); ”There” Since JSON is at the heart of JavaScript, there is the following method to convert a buffer to it’s JSON array format
// Return a JSON-representation of the Buffer instance. buf.toJSON(); >var buf = new Buffer(“Hi There”); >buf.toJSON(); [ 72, 105, 32, 84, 104, 101, 104, 101 ] Further Exploration
To explore the full list of features of the Buffer object, check out the Buffer documentation on nodejs.org.