ByteBuffer is available via npm:
npm install byte-buffer
Or for usage in the browser:
As an ECMAScript module:
;const b = ;
In CommonJS environments:
const ByteBuffer = ;const b = ;
Available in the global scope when included in browser environments:
const b = ;
ByteBuffer's API borrows heavily from Adobe's IDataInput and IDataOutput as well as David Flanagan's BufferView.
Use the following constants to indicate endianness:
1 // Buffer of one byte with big-endian byte order1 ByteBufferLITTLE_ENDIAN // Little-endian byte order instead
ByteBuffers may also be constructed from other byte-aware sources:
Or from generic sequences:
0 1 2 3
After construction a ByteBuffer's read/write index is always at the front of the
b is assumed to be an instance of ByteBuffer.
bbuffer // Reference to internal ArrayBufferbbuffer = 3 // Sets new buffer
braw // Reference to raw buffer (read-only)
bview // Reference to internal DataView (read-only)
blength // Number of bytes in the buffer (read-only)bbyteLength // Alias
border // Buffer's current default byte orderborder = ByteBufferBIG_ENDIAN // Sets byte order
bavailable // Number of available bytes (read-only)
ByteBuffer maintains a read/write index to simplify usage.
bindex // Current read/write indexbindex = 4 // Sets index
If the index is out of bounds, a RangeError will be thrown.
b // Sets index to front of the buffer
b // Sets index to end of the buffer
b // Forwards ten bytesb // Backs two bytes
These methods may be chained:
All read methods default to the ByteBuffer's byte order if not given.
b // Buffer's default byte orderb // Explicit byte order
b // Reads 6 bytesb // Reads all remaining bytes
b // Reads 5 bytes as a stringb // Reads all remaining bytes as a stringb // Alias
b // Reads string up to NULL-byte or end of buffer
All write methods default to the ByteBuffer's byte order if not given.
bb // Explicit byte order
Additionally, all the above write methods may be chained:
The following string related methods do not return the buffer itself, but rather provide the number of bytes that were written to it. More on this under implicit growth strategy a bit further down.
b // Writes given string and returns number of bytesb // Alias
b // Writes given string and returns number of bytes (including NULL-byte)
The buffer may be grown at the front or at the end. When prepending, the buffer's index is adjusted accordingly.
b // Prepends given number of bytes
b // Appends given number of bytes
This feature allows a ByteBuffer to grow implicitly when writing arbitrary data. Since every implicit growth requires the buffer to be rebuilt from scratch, care must be taken when using this feature. Writing low byte-length pieces of data in rapid succession is not recommended.
To protect the unaware from harm, this feature needs to be explicitly enabled:
b = 2 ByteBufferBIG_ENDIAN true // Last argument indicates implicit growth strategyb // Implicitly makes room for 4 bytes - by growing with 2 - prior to writing
The implicit growth strategy can also be enabled and disabled after construction:
bimplicitGrowth = true/false
Implicit growth is a must when dealing with UTF-8 encoded strings, as dealing with arbitrary user data - e.g. names or addresses - may include various characters that require to be encoded in multiple bytes, which would be relatively verbose to calculate beforehand.
The buffer may be truncated at the front, end or both. Both arguments are
optional and may be negative in which case the offsets are calculated from the
respective boundaries of the buffer. The
begin-argument defaults to the current
index, allowing efficient clipping in various scenarios, e.g. when used in
combination with network sockets to shift off read data. The
defaults to the end of the buffer.
bclip2 -2bclip-2 4
b // Independent clone of given slice of the buffer
b // Independent clone of the entire buffer
b // Reverses buffer in place
b // Changes to this array are not backed
b // Hexadecimal representation of this buffer, e.g: 42 79 74 65 42 75 66 66 65 72
b // ASCII representation of this buffer, e.g: B y t e B u f f e r
Development & Contribution
ByteBuffer is written in ES2015+, modularized using ECMAScript Modules, compiled by Babel, bundled with rollup and tested through Jest.
Getting this toolchain up and running, is easy and straight-forward:
Get the code:git clone git://github.com/timkurvers/byte-buffer.git
Download and install Node.js – including
npm– for your platform.
Install dependencies:npm install
npm test:watchwhich will run tests when source files change.
When contributing, please:
- Fork the repository
- Accompany each logical unit of operation with at least one test
- Open a pull request
- Do not include any distribution files (such as
- Maintains read-index and supports seeking
- Various string/char utilities (may support UTF-8)
- Does not support writing values
- Does not support NULL-terminated C-strings
- Does not support growing, clipping, cloning and reversing
- Supports a wide range of browsers/setups
- Supports reading/writing values
- Maintains index and supports seeking
- Supports UTF-8 characters
- Does not support NULL-terminated C-strings
- Does not support growing, clipping, cloning and reversing as view and buffer are immutable