Skip to content

Latest commit

 

History

History
121 lines (101 loc) · 4.94 KB

README.md

File metadata and controls

121 lines (101 loc) · 4.94 KB
Raw

ByteBuffer.js - A full-featured ByteBuffer implementation in JavaScript

Provides a full-featured ByteBuffer implementation using typed arrays. It's one of the core components driving ProtoBuf.js and the PSON reference implementation.

Note: The API behind #toHex and #toString has changed with ByteBuffer 2, which is a generally revised release, in favor of making this more intuitive.

What can it do?

  • Mimics Java ByteBuffers as close as reasonable while using typed array terms
  • Signed and unsigned integers (8, 16, 32, 64 bit through Long.js) with endianness support
  • 32 and 64 bit floats
  • Varints as known from protobuf including zig-zag encoding
  • Includes an UTF8 and Base64 en-/decoder
  • C-strings, V(arint-prefixed)-strings and UTF8 L(ength-prefixed)-strings
  • Rich string toolset (to hex, base64, binary, utf8, debug, columns)
  • Relative and absolute zero-copy operations
  • Manual and automatic resizing (efficiently doubles capacity)
  • Chaining of all operations that do not return a specific value
  • Slicing, appending, prepending, reversing, flip, mark, reset, etc.

And much more...

Features

  • CommonJS compatible
  • RequireJS/AMD compatible
  • node.js compatible, also available via npm
  • Browser compatible
  • Closure Compiler ADVANCED_OPTIMIZATIONS compatible (fully annotated, ByteBuffer.min.js has been compiled this way, ByteBuffer.min.map is the source map)
  • Fully documented using jsdoc3
  • Well tested through nodeunit
  • Zero production dependencies (Long.js is optional)
  • Small footprint

Usage

Node.js / CommonJS

  • Install: npm install bytebuffer
var ByteBuffer = require("bytebuffer");
var bb = new ByteBuffer();
bb.writeLString("Hello world!").flip();
console.log(bb.readLString()+" from ByteBuffer.js");

Browser

Optionally depends on Long.js for long (int64) support. If you do not require long support, you can skip the Long.js include.

<script src="Long.min.js"></script>
<script src="ByteBuffer.min.js"></script>
var ByteBuffer = dcodeIO.ByteBuffer;
var bb = new ByteBuffer();
bb.writeLString("Hello world!").flip();
alert(bb.readLString()+" from ByteBuffer.js");

Require.js / AMD

Optionally depends on Long.js for long (int64) support. If you do not require long support, you can skip the Long.js config. Require.js example:

require.config({
    "paths": {
        "Long": "/path/to/Long.js"
        "ByteBuffer": "/path/to/ByteBuffer.js"
    }
});
require(["ByteBuffer"], function(ByteBuffer) {
    var bb = new ByteBuffer();
    bb.writeLString("Hello world!");
    bb.flip();
    alert(bb.readLString()+" from ByteBuffer.js");
});

On long (int64) support

As of the ECMAScript specification, number types have a maximum value of 2^53. Beyond that, behaviour might be unexpected. However, real long support requires the full 64 bits with the possibility to perform bitwise operations on the value for varint en-/decoding. So, to enable true long support in ByteBuffer.js, it optionally depends on Long.js, which actually utilizes two 32 bit numbers internally. If you do not require long support at all, you can skip it and save the additional bandwidth. On node, long support is available by default through the long dependency.

Downloads

Documentation

Tests (& Examples) Build Status

Support for IE<10, FF<15, Chrome<9 etc.

  • Requires working ArrayBuffer & DataView implementations (i.e. use a polyfill)

Contributors

Dretch (IE8 compatibility)

License

Apache License, Version 2.0 - http://www.apache.org/licenses/LICENSE-2.0.html