Utility to assist in parsing c-style structs from an ArrayBuffer
Branch: master
Clone or download
toji Merge pull request #1 from divergentdave/master
Small bug fix towards Firefox compatibility
Latest commit fad5fbe Oct 15, 2011
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
README.md Correcting gramatical mistake in README Aug 27, 2011
js-struct.js Spelling change, writeable=>writable Oct 14, 2011
test.html Expanded callback method to include offset, added basic documentation… Aug 24, 2011

README.md

jsStruct

Typed Arrays have made parsing binary files much more reasonable in Javascript, but we still lack the simplicity of c-style struct reading, where you can simply point a struct at a memory offset and read it. This utility attempts to provide the same convenience in Javascript, in a reasonably efficient manner.

Better documentation should be forthcoming. Library currently supports reading only, will probably add write in the future.

Sample

// buffer may also come from an XHR request with responseType = "arraybuffer"
var buffer = new ArrayBuffer(128); // Assume the buffer is populated with sensible binary data

// Define the struct layout
var SimpleStruct = Struct.create(
    Struct.int8("myChar"),
    Struct.int16("myShort"),
    Struct.int32("myInt"),
    Struct.float32("myFloat")
);

var ComplexStruct = Struct.create(
    Struct.struct("myStruct", SimpleStruct), // Structs can be nested
    Struct.string("myString", 4),
    Struct.array("myArray", Struct.int8(), 4), // Primitives or other structs can be read as fixed-length arrays
    Struct.array("myStructArray", SimpleStruct, 2),
    { 
        // The last argument passed to Struct.create can be additional properties for the object
        // These properties will be available on every instance of this struct that is created
        myFunction: {
            value: function() {
                console.log("myFunction has been called");
            }
        }
    }
);

// readStructs accepts the following arguments:
//  arrayBuffer - the ArrayBuffer to read from
//  offset - the byte offset into the buffer where reading should start
//  count - the number of structs to read. Structs are assumed to be tightly packed
// returns an array of structs
var a = SimpleStruct.readStructs(buffer, 0, 2); // Returns an array of 2 simpleStructs
var b = ComplexStruct.readStructs(buffer, 32, 1); // Returns an array of 1 complexStruct

// myFunction will be available on every instance of a ComplexStruct
b[0].myFunction();

// readStructs can also accept a callback, which will be called with the parsed structure and offset of that 
// structure within the stream as they are parsed.
SimpleStruct.readStructs(buffer, 0, 2, function(newStruct, offset) {
    console.log("Parsed " + newStruct + " at offset " + offset);
});