Skip to content
ES6 Buffer Utility
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
LICENSE
README.md
bufo.js
package.json
test.js

README.md

Bufo - Buffer utility for ES6

In a world filled with Buffer related packages, this is nothing but another fish in the ocean. Bufo acts as a wrapper for the Buffer class, providing position-aware reading utility.

If you're wondering about the origin of the name, this package was named after a frog in World of Warcraft.

Installing (Node)

npm install bufo

Installing (Browser)

<script src="bufo.js"></script>

Example (Creation)

// Create a Bufo instance providing nothing more than a size...
let data = new Bufo(10);

// Using an exisitng NodeJS buffer...
let buffer = Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21]);
let data = new Bufo(buffer);

// Using a string, if you felt like it...
let data = new Bufo('\u00bd\u00bc\u00be');

// Using a native array filled with bytes...
let data = new Bufo([0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21]);

// .. And more! Check the documentation for all options.

Example (Usage)

data.readUInt8(); // -> 0x48
data.readUInt8(); // -> 0x65
data.move(-2); // Back to the start we go...
data.readString(); // -> Hello, world!

API

Bufo.ENDIAN_LITTLE

Static constant representing the little-endian byte-order. Can be provided to the constructor to set the default endianness, or to individual integer read/write calls to over-write the default endianness for that call.

Bufo.ENDIAN_BIG

Static constant representing the big-endian byte-order. Can be provided to the constructor to set the default endianness, or to individual integer read/write calls to over-write the default endianness for that call.

Bufo.bytesToString(bytes)

Convert an array of bytes into a string (without encoding).

Parameter Type Info
bytes array Array of bytes to convert.

new Bufo(buffer, defaultEncoding)

Create a new Bufo instance, wrapping the given input. How the input is handled depends on the type, check the table below.

Type Action
Buffer Buffer will be wrapped by the Bufo instance.
Bufo Wrapped buffer will be wrapped by this instance, too.
Array Treated as a byte-array, new buffer will be allocated, wrapped and filled with the bytes.
string Will be treated as a byte-array, with each char being a single byte. See Array.
number An empty instance allocated to the given size.
DataView The given DataView will be wrapped by the Bufo instance.
ArrayBuffer A DataView for this ArrayBuffer will be created and wrapped by the Bufo instance.
Parameter Type Info
buffer * Input, see table above.
defaultEncoding (optional) number Default endianness to use for all integer operations.

byteLength : number

The capacity of the internal buffer.

remainingBytes : number

The amount of bytes between the current offset and the buffer end. (byteLength - offset).

offset : number

The current offset for reading/writing operations.

lastWriteOffset : number

The offset of the buffer after the last write operation occurred. When writing data in a linear fashion, this can be used to indicate the buffer data length with byteLength as the overall capacity.

raw : Buffer

The internal buffer reference.

setEndian(endian)

Set the default endianness to use for integer operations. This can be overwritten on a per-call basis for Int16/Int32 operations.

Parameter Type Info
endian number Bufo.ENDIAN_LITTLE or Bufo.ENDIAN_BIG

seek(offset)

Set the absolute offset of this instance. If a negative value is provided, the offset will be set to that many bytes from the end of the buffer.

Parameter Type Info
offset number Absolute offset to set.

move(offset)

Set the offset relative to the current offset. Positive values will move the offset forward, negative values will move it backward. This does not wrap-around and will throw an error if you shift out of bounds.

Parameter Type Info
offset number Amount to shift the offset by.

readInt8(count)

Read one or more signed 8-bit integers from the buffer. If count is greater than one, an Array will be returned, otherwise the result will be a single number value.

Parameter Type Info
count (optional) number How many integers to read. Defaults to 1.

readUInt8(count)

Read one or more unsigned 8-bit integers from the buffer. If count is greater than one, an Array will be returned, otherwise the result will be a single number value.

Parameter Type Info
count (optional) number How many integers to read. Defaults to 1.

readInt16(count, endian)

Read one or more signed 16-bit integers from the buffer. If count is greater than one, an Array will be returned, otherwise the result will be a single number value.

Parameter Type Info
count (optional) number How many integers to read. Defaults to 1.
endian (optional) number Override the default endian for this call.

readIntU16(count, endian)

Read one or more unsigned 16-bit integers from the buffer. If count is greater than one, an Array will be returned, otherwise the result will be a single number value.

Parameter Type Info
count (optional) number How many integers to read. Defaults to 1.
endian (optional) number Override the default endian for this call.

readInt32(count, endian)

Read one or more signed 32-bit integers from the buffer. If count is greater than one, an Array will be returned, otherwise the result will be a single number value.

Parameter Type Info
count (optional) number How many integers to read. Defaults to 1.
endian (optional) number Override the default endian for this call.

readIntU32(count, endian)

Read one or more unsigned 32-bit integers from the buffer. If count is greater than one, an Array will be returned, otherwise the result will be a single number value.

Parameter Type Info
count (optional) number How many integers to read. Defaults to 1.
endian (optional) number Override the default endian for this call.

readString(length)

Read a string from the buffer. If length is omitted, a single UInt32 will be read first and used as the length.

Parameter Type Info
length (optional) number Length of the string to read.

readUTF8String(length)

Read a UTF8 encoded string from the buffer. If length is omitted, a single UInt32 will be read first and used as the length.

Parameter Type Info
length (optional) number Length of the string to read.

readBuffer(length)

Reads length bytes from the buffer, writes them to a newly allocated buffer, and returns it. If length is omitted, remainingBytes will be used.

Parameter Type Info
length (optional) number How many bytes to read.

readArrayBuffer(length)

Reads length bytes from the buffer, writes them to a newly allocated ArrayBuffer, and returns it. If length is omitted, remainingBytes will be used.

Parameter Type Info
length (optional) number How many bytes to read.

readBufo(length)

Reads and returns a buffer, wrapped in a new Bufo instance. Check readBuffer documentation for details.

readUntilByte(byte, [preserveStopByte])

Reads bytes from the buffer until byte is reached. An array containing all bytes before the byte will be returned. If preserveStopByte is true, it will be included in the output. After this method, the internal offset will always be after the byte, never before it.

Parameter Type Info
byte number|string Byte character to read until.
preserveStopByte (optional) boolean Include stop byte in output if true.

writeInt8(input)

Write one or more signed 8-bit integers to the buffer.

Parameter Type Info
input number|Array Values to be written.

writeUInt8(input)

Write one or more unsigned 8-bit integers to the buffer.

Parameter Type Info
input number|Array Values to be written.

writeInt16(input, endian)

Write one or more signed 16-bit integers to the buffer.

Parameter Type Info
input number|Array Values to be written.
endian (optional) number Override the default endian for this call.

writeUInt16(input, endian)

Write one or more unsigned 16-bit integers to the buffer.

Parameter Type Info
input number|Array Values to be written.
endian (optional) number Override the default endian for this call.

writeInt32(input, endian)

Write one or more signed 32-bit integers to the buffer.

Parameter Type Info
input number|Array Values to be written.
endian (optional) number Override the default endian for this call.

writeUInt32(input, endian)

Write one or more unsigned 32-bit integers to the buffer.

Parameter Type Info
input number|Array Values to be written.
endian (optional) number Override the default endian for this call.

writeString(str, prefix)

Write a string to the buffer with each character as a seperate byte. If prefix is true, the byte-length will be written as a UInt32 first.

Parameter Type Info
str string String to write to the buffer.
prefix boolean If set, length-prefixes the string.

writeUTF8String(str, prefix)

Writes a UTF8 string to the buffer. If prefix is true, the byte-length will be written as a UInt32 first.

Parameter Type Info
str string String to write to the buffer.
prefix boolean If set, length-prefixes the string.

writeBuffer(buffer, offset, count)

Writes a buffer (or Bufo instance) to the buffer. If offset is omitted, it will default to 0 for buffers and bufo.offset for a Bufo instance. If count is omitted, it will default to buffer.length for buffers and bufo.remainingBytes for a Bufo instance.

Parameter Type Info
buffer Buffer|Bufo Buffer to read from.
offset (optional) number Offset to start reading from.
count (optional) number How many bytes to read.

writeArrayBuffer(buffer, offset, count)

Writes the contents of an ArrayBuffer to the buffer. If offset is omitted, it will default to 0. If count is omitted, it will default to the byteLength property of the provided ArrayBuffer instance.

Parameter Type Info
buffer ArrayBuffer ArrayBuffer instance to read from.
offset (optional) number Offset to start reading from.
count (optional) number How many bytes to read.

toFile(path, count, options)

Write the specified count of bytes to a file.

Parameter Type Info
path string File path.
count (optional) number Amount of bytes to write. Defaults to remainingBytes.
options (optional) object Options table. See fs.createWriteStream for usage.
You can’t perform that action at this time.