c-struct-js

0.2.0 • Public • Published

c-struct-js

UMD module for DataView extension inspired by C structs

NPM Version Node Version devDependencies License Standard Github File Size

Usage

Install via npm

$ npm i c-struct-js

CommonJS

const Struct = require('c-struct-js')

ES6 import (using babel)

import Struct from 'c-struct-js'

AMD requireJS

define(['c-struct-js'], (Struct) => { ... })

Or include via unpkg

<script src="https://unpkg.com/c-struct-js"></script>

UMD global

<script>
  const { Struct } = window
</script> 

Classes

StructDataView

Objects

types : object

Namespace of predefined Struct classes.

Struct ⇐ DataView

Kind: global class
Extends: DataView

new Struct(buffer, [byteOffset])

Param Type Default Description
buffer ArrayBuffer An instance of ArrayBuffer to view.
[byteOffset] number 0 Byte offset at which to view ArrayBuffer.

Struct.extend(...descriptors) ⇒ constructor

Creates a class that extends Struct with members defined by arguments.

Kind: static method of Struct
Throws:

Param Type Description
...descriptors Object Instance member definitions for extended class.
descriptors[].name string The member name.
descriptors[].type string | Struct The member type. Accepts strings 'Int8', 'Uint8', 'Int16', 'Uint16', 'Float32', 'Int32', 'Uint32', 'Float64', 'String', or any constructor that extends Struct.
[descriptors[].option] * An optional argument to append to the accessor methods of the member.
[descriptors[].byteLength] number Determined using type by default. Required when type is 'String'.
[descriptors[].byteOffset] number Determined using order of descriptors by default.

Example

const Struct = require('c-struct-js')
 
// Implementing RIFF-style chunk headers
const Word = Struct.extend(
  { name: 'word', type: 'String', byteLength: 4 }
)
 
const Chunk = Struct.extend(
  { name: 'id', type: Word },
  { name: 'size', type: Struct.types.Uint32LE }
)
 
class RIFF extends Struct.extend(
  { name: 'chunk', type: Chunk },
  // ...
) {
  constructor () {
    super(new ArrayBuffer(RIFF.byteLength))
 
    this.chunk.id.word = 'RIFF'
    this.chunk.size = this.byteLength - this.chunk.byteLength
    // ...
  }
}
 
let riff = new RIFF()
let ab = riff.chunk.id
let buf = Buffer.from(ab.buffer, ab.byteOffset, ab.byteLength)
 
console.log(buf.toString())

Struct.types : types

Namespace of predefined types.

Kind: static property of Struct

Struct.byteLength : number

Byte length of instances.

Kind: static property of Struct
Default: 0
Read only: true

Struct.from(value, [byteOffset]) ⇒ Struct

Creates an instance of Struct to view given value at byteOffset.

Kind: static method of Struct
Throws:

  • TypeError value must be a valid ArrayBuffer or view.
Param Type Default Description
value ArrayBuffer | TypedArray A valid ArrayBuffer or TypedArray.
[byteOffset] number 0 Byte offset at which to view value.

Example

// checking encoded size of WAV file
const { promisify } = require('util')
const fs = require('fs')
const read = promisify(fs.read)
const open = promisify(fs.open)
const close = promisify(fs.close)
 
// using Chunk from previous example
// ...
 
// bytes 36-44 contain SubChunk2 of WAV header
open('test.wav', 'r')
  .then(fd => {
    return read(fd, Buffer.allocUnsafe(Chunk.byteLength), 0, Chunk.byteLength, 36)
      .then((bytesRead, buffer) => close(fd).then(() => Chunk.from(buffer)))
  })
  .then(chunk => console.log('file size:', 44 + chunk.size))

Struct.isStruct(value) ⇒ boolean

Validates constructors that implement Struct.

Kind: static method of Struct

Param Type Description
value * A value to test.

Example

console.log(Struct.isStruct(Struct))   // true
console.log(Struct.isStruct(RIFF))     // true
console.log(Struct.isStruct(DataView)) // false - doesn't implement Struct
console.log(Struct.isStruct(riff))     // false - is instance, not class

Struct.union(...Classes) ⇒ constructor

Creates a union class that extends Struct with members of all Classes.

Kind: static method of Struct
Throws:

Param Type Description
...Classes constructor Classes that extend Struct.

Example

// Getting surrogate pairs of utf16le encoding
const UTF16LE = Struct.extend(
  { name: 'code', type: 'String', byteLength: 2, option: 'utf16le' }
)
 
const UTF16Pair = Struct.extend(
  { name: 'lo', type: 'Uint8' },
  { name: 'hi', type: 'Uint8' }
)
 
const UTF16 = Struct.union(Utf16le, Utf16Pair)
 
let utf16 = new Utf16(new ArrayBuffer(UTF16.byteLength))
 
utf16.code = ''
 
// € ac 20
console.log(utf16.code, utf16.lo.toString(16), utf16.hi.toString(16))

struct.getString(byteOffset, byteLength, [encoding]) ⇒ string

Gets string with byteLength and encoding from viewed ArrayBuffer at byteOffset. Depending on data and encoding, returned string may have different length than byteLength.

Kind: instance method of Struct
Throws:

  • TypeError encoding must be a valid string encoding.
Param Type Default Description
byteOffset number Byte offset within ArrayBuffer of string to read.
byteLength number Byte length within ArrayBuffer of string to read.
[encoding] string "utf8" Encoding within ArrayBuffer of string to read.

Example

// using utf16 from previous example
// ...
 
console.log(utf16.code === utf16.getString(0, 2, 'utf16le')) // true

struct.setString(byteOffset, byteLength, value, [encoding])

Sets string with byteLength and encoding to viewed ArrayBuffer at byteOffset. Depending on byteLength and encoding, set string may be truncated or padded.

Kind: instance method of Struct
Throws:

  • TypeError encoding must be a valid string encoding.
Param Type Default Description
byteOffset number Byte offset within ArrayBuffer of string to write.
byteLength number Byte length within ArrayBuffer of string to write.
value string String value to write to ArrayBuffer.
[encoding] string "utf8" Encoding within ArrayBuffer of string to write.

Example

// using utf16 from previous example
// ...
 
utf16.setString(0, 2, '$', 'utf16le')
 
// $ 24 0
console.log(utf16.code, utf16.lo.toString(16), utf16.hi.toString(16))

struct.get()

Default member getter when accessed as a member of a parent Struct.

Kind: instance method of Struct
Example

// Better implementation for RIFF-style chunk headers
class Word extends Struct.extend(
  { name: 'word', type: 'String', byteLength: 4 }
) {
  get () { return this.word }
  set (string) { this.word = string }
}
 
const Chunk = Struct.extend(
  { name: 'id', type: Word },
  { name: 'size', type: Struct.types.Uint32LE }
)
 
// Other structs...
 
class RIFF extends Struct.extend(
  { name: 'chunk', type: Chunk },
  // Other fields...
) {
  constructor (arrayBuffer = new ArrayBuffer(RIFF.byteLength), byteOffset = 0) {
    super(arrayBuffer, byteOffset)
 
    this.chunk.id = 'RIFF'
    this.chunk.size = this.byteLength - this.chunk.byteLength
    // ...
  }
}
 
let riff = new RIFF()
let id = riff.chunk.id
 
// 'RIFF' instead of instance of Word
console.log(id)

struct.set(typedArray, [byteOffset])

Sets memory in ArrayBuffer starting at byteOffset with data from typedArray.

Kind: instance method of Struct

Param Type Default Description
typedArray TypedArray View of data to copy.
[byteOffset] number 0 Byte offset within ArrayBuffer at which to write.

Example

// reading header of WAV file into instance of RIFF
 
// using RIFF from previous example
// ...
let riff = new RIFF()
 
open('test.wav', 'r')
  .then(fd => {
    return read(fd, Buffer.allocUnsafe(RIFF.byteLength), 0, RIFF.byteLength, 0)
      .then((bytesRead, buffer) => close(fd).then(() => buffer))
  })
  .then(buffer => {
    riff.set(buffer)
    // populated with header bytes from test.wav
    // ...
  })

struct.next([constructor], [bytePadding])

Initializes the next chunk of the buffer as another instance of Struct.

Kind: instance method of Struct
Throws:

  • TypeError constructor must implement Struct.
Param Type Default Description
[constructor] constructor this.constructor The Struct class with which to initialize.
[bytePadding] number 0 Amount of bytes after the end of this to begin ArrayBuffer view.

Example

// iterating through a large dataset
const readFile = promisify(fs.readFile)
 
readFile('test.wav')
  .then(buffer => {
    for (let struct = new Struct.types.Uint8(buffer.buffer, 44); struct !== null; struct = struct.next()) {
      // iterates through each byte of sound data
      console.log(struct.uint8) // 0-255
    }
  })

struct.prev([constructor], [bytePadding])

Initializes the previous chunk of the buffer as another instance of Struct.

Kind: instance method of Struct
Throws:

  • TypeError constructor must implement Struct.
Param Type Default Description
[constructor] constructor this.constructor The Struct class with which to initialize.
[bytePadding] number 0 Amount of bytes before the end of this to end ArrayBuffer view.

Example

// accessing header of first data
 
readFile('test.wav')
  .then(buffer => {
    let data = new Struct.types.Uint8(buffer.buffer, 44)
    // to properly initialize RIFF header at byteOffset of 0
    let riff = data.prev(RIFF, data.byteOffset - Chunk.byteLength)
 
    // 'RIFF'
    console.log(riff.chunk.id)
  })

types : object

Namespace of predefined Struct classes.

Kind: global namespace

types.Byte ⇐ Struct

A union of all 1-byte predefined types.

Kind: static mixin of types
Extends: Struct

Byte.byteLength : number

Byte length of instances.

Kind: static property of Byte
Default: 1
Read only: true

byte.char : String

A single byte binary string character. Accepts any characters from the latin-1 block.

Kind: instance property of Byte

byte.int8 : number

An 8-bit signed integer.

Kind: instance property of Byte

byte.uint8 : number

An 8-bit unsigned integer.

Kind: instance property of Byte

types.Char ⇐ Struct

A predefined type for storing a binary-encoded string character.

Kind: static mixin of types
Extends: Struct

Char.byteLength : number

Byte length of instances.

Kind: static property of Char
Default: 1
Read only: true

char.char : String

A single byte binary string character. Accepts any characters from the latin-1 block.

Kind: instance property of Char

char.get() ⇒ String

Kind: instance method of Char
Returns: String - char

char.set(value)

Kind: instance method of Char

Param Type
value String

types.Float32BE ⇐ Struct

A predefined type for storing a 32-bit floating point number in big-endian byte order.

Kind: static mixin of types
Extends: Struct

Float32BE.byteLength : number

Byte length of instances.

Kind: static property of Float32BE
Default: 4
Read only: true

float32BE.float32be : number

A 32-bit floating point number accessed in big-endian byte order.

Kind: instance property of Float32BE
See: IEEE 754 Single-precision floating-point format

float32BE.get() ⇒ number

Kind: instance method of Float32BE
Returns: number - float32be

float32BE.set(value)

Kind: instance method of Float32BE

Param Type
value number

types.Float32LE ⇐ Struct

A predefined type for storing a 32-bit floating point number in little-endian byte order.

Kind: static mixin of types
Extends: Struct

Float32LE.byteLength : number

Byte length of instances.

Kind: static property of Float32LE
Default: 4
Read only: true

float32LE.float32le : number

A 32-bit floating point number accessed in big-endian byte order.

Kind: instance property of Float32LE
See: IEEE 754 Single-precision floating-point format

float32LE.get() ⇒ number

Kind: instance method of Float32LE
Returns: number - float32le

float32LE.set(value)

Kind: instance method of Float32LE

Param Type
value number

types.Float64BE ⇐ Struct

A predefined type for storing a 64-bit floating point number in big-endian byte order.

Kind: static mixin of types
Extends: Struct

Float64BE.byteLength : number

Byte length of instances.

Kind: static property of Float64BE
Default: 8
Read only: true

float64BE.float64be : number

A 64-bit floating point number accessed in big-endian byte order.

Kind: instance property of Float64BE
See: IEEE 754 Double-precision floating-point format

float64BE.get() ⇒ number

Kind: instance method of Float64BE
Returns: number - float64be

float64BE.set(value)

Kind: instance method of Float64BE

Param Type
value number

types.Float64LE ⇐ Struct

A predefined type for storing a 64-bit floating point number in little-endian byte order.

Kind: static mixin of types
Extends: Struct

Float64LE.byteLength : number

Byte length of instances.

Kind: static property of Float64LE
Default: 8
Read only: true

float64LE.float64le : number

A 64-bit floating point number accessed in little-endian byte order.

Kind: instance property of Float64LE
See: IEEE 754 Double-precision floating-point format

float64LE.get() ⇒ number

Kind: instance method of Float64LE
Returns: number - float64le

float64LE.set(value)

Kind: instance method of Float64LE

Param Type
value number

types.Int16BE ⇐ Struct

A predefined type for storing a 16-bit signed integer in big-endian byte order.

Kind: static mixin of types
Extends: Struct

Int16BE.byteLength : number

Byte length of instances.

Kind: static property of Int16BE
Default: 2
Read only: true

int16BE.int16be : number

A 16-bit signed integer accessed in big-endian byte order.

Kind: instance property of Int16BE

int16BE.get() ⇒ number

Kind: instance method of Int16BE
Returns: number - int16be

int16BE.set(value)

Kind: instance method of Int16BE

Param Type
value number

types.Int16LE ⇐ Struct

A predefined type for storing a 16-bit signed integer in little-endian byte order.

Kind: static mixin of types
Extends: Struct

Int16LE.byteLength : number

Byte length of instances.

Kind: static property of Int16LE
Default: 2
Read only: true

int16LE.int16le : number

A 16-bit signed integer accessed in little-endian byte order.

Kind: instance property of Int16LE

int16LE.get() ⇒ number

Kind: instance method of Int16LE
Returns: number - int16le

int16LE.set(value)

Kind: instance method of Int16LE

Param Type
value number

types.Int32BE ⇐ Struct

A predefined type for storing a 32-bit signed integer in big-endian byte order.

Kind: static mixin of types
Extends: Struct

Int32BE.byteLength : number

Byte length of instances.

Kind: static property of Int32BE
Default: 4
Read only: true

int32BE.int32be : number

A 32-bit signed integer accessed in big-endian byte order.

Kind: instance property of Int32BE

int32BE.get() ⇒ number

Kind: instance method of Int32BE
Returns: number - int32be

int32BE.set(value)

Kind: instance method of Int32BE

Param Type
value number

types.Int32LE ⇐ Struct

A predefined type for storing a 32-bit signed integer in little-endian byte order.

Kind: static mixin of types
Extends: Struct

Int32LE.byteLength : number

Byte length of instances.

Kind: static property of Int32LE
Default: 4
Read only: true

int32LE.int32le : number

A 32-bit signed integer accessed in big-endian byte order.

Kind: instance property of Int32LE

int32LE.get() ⇒ number

Kind: instance method of Int32LE
Returns: number - int32le

int32LE.set(value)

Kind: instance method of Int32LE

Param Type
value number

types.Int8 ⇐ Struct

A predefined type for storing an 8-bit signed integer.

Kind: static mixin of types
Extends: Struct

Int8.byteLength : number

Byte length of instances.

Kind: static property of Int8
Default: 1
Read only: true

int8.int8 : number

An 8-bit signed integer.

Kind: instance property of Int8

int8.get() ⇒ number

Kind: instance method of Int8
Returns: number - int8

int8.set(value)

Kind: instance method of Int8

Param Type
value number

types.Long ⇐ Struct

A union of all 8-byte predefined types.

Kind: static mixin of types
Extends: Struct

Long.byteLength : number

Byte length of instances.

Kind: static property of Long
Default: 8
Read only: true

long.float64be : number

A 64-bit floating point number accessed in big-endian byte order.

Kind: instance property of Long
See: IEEE 754 Double-precision floating-point format

long.float64le : number

A 64-bit floating point number accessed in little-endian byte order.

Kind: instance property of Long
See: IEEE 754 Double-precision floating-point format

types.Short ⇐ Struct

A union of all 2-byte predefined types.

Kind: static mixin of types
Extends: Struct

Short.byteLength : number

Byte length of instances.

Kind: static property of Short
Default: 2
Read only: true

short.int16be : number

A 16-bit signed integer accessed in big-endian byte order.

Kind: instance property of Short

short.int16le : number

A 16-bit signed integer accessed in little-endian byte order.

Kind: instance property of Short

short.uint16be : number

A 16-bit unsigned integer accessed in big-endian byte order.

Kind: instance property of Short

short.uint16le : number

A 16-bit unsigned integer accessed in little-endian byte order.

Kind: instance property of Short

types.Uint16BE ⇐ Struct

A predefined type for storing a 16-bit unsigned integer in big-endian byte order.

Kind: static mixin of types
Extends: Struct

Uint16BE.byteLength : number

Byte length of instances.

Kind: static property of Uint16BE
Default: 2
Read only: true

uint16BE.uint16be : number

A 16-bit unsigned integer accessed in big-endian byte order.

Kind: instance property of Uint16BE

uint16BE.get() ⇒ number

Kind: instance method of Uint16BE
Returns: number - uint16be

uint16BE.set(value)

Kind: instance method of Uint16BE

Param Type
value number

types.Uint16LE ⇐ Struct

A predefined type for storing a 16-bit unsigned integer in little-endian byte order.

Kind: static mixin of types
Extends: Struct

Uint16LE.byteLength : number

Byte length of instances.

Kind: static property of Uint16LE
Default: 2
Read only: true

uint16LE.uint16le : number

A 16-bit unsigned integer accessed in little-endian byte order.

Kind: instance property of Uint16LE

uint16LE.get() ⇒ number

Kind: instance method of Uint16LE
Returns: number - uint16le

uint16LE.set(value)

Kind: instance method of Uint16LE

Param Type
value number

types.Uint32BE ⇐ Struct

A predefined type for storing a 32-bit unsigned integer in big-endian byte order.

Kind: static mixin of types
Extends: Struct

Uint32BE.byteLength : number

Byte length of instances.

Kind: static property of Uint32BE
Default: 4
Read only: true

uint32BE.uint32be : number

A 32-bit unsigned integer accessed in big-endian byte order.

Kind: instance property of Uint32BE

uint32BE.get() ⇒ number

Kind: instance method of Uint32BE
Returns: number - uint32be

uint32BE.set(value)

Kind: instance method of Uint32BE

Param Type
value number

types.Uint32LE ⇐ Struct

A predefined type for storing a 32-bit unsigned integer in little-endian byte order.

Kind: static mixin of types
Extends: Struct

Uint32LE.byteLength : number

Byte length of instances.

Kind: static property of Uint32LE
Default: 4
Read only: true

uint32LE.uint32le : number

A 32-bit unsigned integer accessed in little-endian byte order.

Kind: instance property of Uint32LE

uint32LE.get() ⇒ number

Kind: instance method of Uint32LE
Returns: number - uint32le

uint32LE.set(value)

Kind: instance method of Uint32LE

Param Type
value number

types.Uint8 ⇐ Struct

A predefined type for storing an 8-bit unsigned integer.

Kind: static mixin of types
Extends: Struct

Uint8.byteLength : number

Byte length of instances.

Kind: static property of Uint8
Default: 1
Read only: true

uint8.uint8 : number

An 8-bit unsigned integer.

Kind: instance property of Uint8

uint8.get() ⇒ number

Kind: instance method of Uint8
Returns: number - uint8

uint8.set(value)

Kind: instance method of Uint8

Param Type
value number

types.Word ⇐ Struct

A union of all 4-byte predefined types.

Kind: static mixin of types
Extends: Struct

Word.byteLength : number

Byte length of instances.

Kind: static property of Word
Default: 4
Read only: true

word.float32be : number

A 32-bit floating point number accessed in big-endian byte order.

Kind: instance property of Word
See: IEEE 754 Single-precision floating-point format

word.float32le : number

A 32-bit floating point number accessed in big-endian byte order.

Kind: instance property of Word
See: IEEE 754 Single-precision floating-point format

word.int32be : number

A 32-bit signed integer accessed in big-endian byte order.

Kind: instance property of Word

word.int32le : number

A 32-bit signed integer accessed in big-endian byte order.

Kind: instance property of Word

word.uint32be : number

A 32-bit unsigned integer accessed in big-endian byte order.

Kind: instance property of Word

word.uint32le : number

A 32-bit unsigned integer accessed in little-endian byte order.

Kind: instance property of Word

License

Available under the MIT License (c) 2017 Patrick Roberts

Readme

Keywords

none

Package Sidebar

Install

npm i c-struct-js

Weekly Downloads

7

Version

0.2.0

License

MIT

Last publish

Collaborators

  • patrickroberts