UMD module for DataView extension inspired by C structs

$ npm i c-struct-js

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

import Struct from 'c-struct-js'

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

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

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

Struct ⇐ DataView

types : object

Namespace of predefined Struct classes.

Kind: global class
Extends: DataView

• Struct ⇐ DataView
  • new Struct(buffer, [byteOffset])
  • static
    • .extend(...descriptors) ⇒ constructor
    • .types : types
    • .byteLength : number
    • .from(value, [byteOffset]) ⇒ Struct
    • .isStruct(value) ⇒ boolean
    • .union(...Classes) ⇒ constructor
  • instance
    • .getString(byteOffset, byteLength, [encoding]) ⇒ string
    • .setString(byteOffset, byteLength, value, [encoding])
    • .get()
    • .set(typedArray, [byteOffset])
    • .next([constructor], [bytePadding])
    • .prev([constructor], [bytePadding])

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

Kind: static method of Struct
Throws:

• TypeError Unexpected type.
• TypeError byteLength is required for String type.

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())

Namespace of predefined types.

Kind: static property of Struct

Byte length of instances.

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

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.

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))

Validates constructors that implement Struct.

Kind: static method of Struct

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

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

Kind: static method of Struct
Throws:

• TypeError Union contains conflicting key.

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))

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.

Example

// using utf16 from previous example
// ...

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

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.

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))

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)

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

Kind: instance method of Struct

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
    // ...
  })

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

Kind: instance method of Struct
Throws:

• TypeError constructor must implement Struct.

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
    }
  })

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

Kind: instance method of Struct
Throws:

• TypeError constructor must implement Struct.

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)
  })

Namespace of predefined Struct classes.

Kind: global namespace

• types : object
  • .Byte ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .char : String
      • .int8 : number
      • .uint8 : number
  • .Char ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .char : String
      • .get() ⇒ String
      • .set(value)
  • .Float32BE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .float32be : number
      • .get() ⇒ number
      • .set(value)
  • .Float32LE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .float32le : number
      • .get() ⇒ number
      • .set(value)
  • .Float64BE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .float64be : number
      • .get() ⇒ number
      • .set(value)
  • .Float64LE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .float64le : number
      • .get() ⇒ number
      • .set(value)
  • .Int16BE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .int16be : number
      • .get() ⇒ number
      • .set(value)
  • .Int16LE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .int16le : number
      • .get() ⇒ number
      • .set(value)
  • .Int32BE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .int32be : number
      • .get() ⇒ number
      • .set(value)
  • .Int32LE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .int32le : number
      • .get() ⇒ number
      • .set(value)
  • .Int8 ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .int8 : number
      • .get() ⇒ number
      • .set(value)
  • .Long ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .float64be : number
      • .float64le : number
  • .Short ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .int16be : number
      • .int16le : number
      • .uint16be : number
      • .uint16le : number
  • .Uint16BE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .uint16be : number
      • .get() ⇒ number
      • .set(value)
  • .Uint16LE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .uint16le : number
      • .get() ⇒ number
      • .set(value)
  • .Uint32BE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .uint32be : number
      • .get() ⇒ number
      • .set(value)
  • .Uint32LE ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .uint32le : number
      • .get() ⇒ number
      • .set(value)
  • .Uint8 ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .uint8 : number
      • .get() ⇒ number
      • .set(value)
  • .Word ⇐ Struct
    • static
      • .byteLength : number
    • instance
      • .float32be : number
      • .float32le : number
      • .int32be : number
      • .int32le : number
      • .uint32be : number
      • .uint32le : number

A union of all 1-byte predefined types.

Kind: static mixin of types
Extends: Struct

• .Byte ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .char : String
    • .int8 : number
    • .uint8 : number

Byte length of instances.

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

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

Kind: instance property of Byte

An 8-bit signed integer.

Kind: instance property of Byte

An 8-bit unsigned integer.

Kind: instance property of Byte

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

Kind: static mixin of types
Extends: Struct

• .Char ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .char : String
    • .get() ⇒ String
    • .set(value)

Byte length of instances.

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

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

Kind: instance property of Char

Kind: instance method of Char
Returns: String - char

Kind: instance method of Char

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

Kind: static mixin of types
Extends: Struct

• .Float32BE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .float32be : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance method of Float32BE
Returns: number - float32be

Kind: instance method of Float32BE

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

Kind: static mixin of types
Extends: Struct

• .Float32LE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .float32le : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance method of Float32LE
Returns: number - float32le

Kind: instance method of Float32LE

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

Kind: static mixin of types
Extends: Struct

• .Float64BE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .float64be : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance method of Float64BE
Returns: number - float64be

Kind: instance method of Float64BE

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

Kind: static mixin of types
Extends: Struct

• .Float64LE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .float64le : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance method of Float64LE
Returns: number - float64le

Kind: instance method of Float64LE

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

Kind: static mixin of types
Extends: Struct

• .Int16BE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .int16be : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance property of Int16BE

Kind: instance method of Int16BE
Returns: number - int16be

Kind: instance method of Int16BE

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

Kind: static mixin of types
Extends: Struct

• .Int16LE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .int16le : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance property of Int16LE

Kind: instance method of Int16LE
Returns: number - int16le

Kind: instance method of Int16LE

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

Kind: static mixin of types
Extends: Struct

• .Int32BE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .int32be : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance property of Int32BE

Kind: instance method of Int32BE
Returns: number - int32be

Kind: instance method of Int32BE

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

Kind: static mixin of types
Extends: Struct

• .Int32LE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .int32le : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance property of Int32LE

Kind: instance method of Int32LE
Returns: number - int32le

Kind: instance method of Int32LE

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

Kind: static mixin of types
Extends: Struct

• .Int8 ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .int8 : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

An 8-bit signed integer.

Kind: instance property of Int8

Kind: instance method of Int8
Returns: number - int8

Kind: instance method of Int8

A union of all 8-byte predefined types.

Kind: static mixin of types
Extends: Struct

• .Long ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .float64be : number
    • .float64le : number

Byte length of instances.

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

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

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

A union of all 2-byte predefined types.

Kind: static mixin of types
Extends: Struct

• .Short ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .int16be : number
    • .int16le : number
    • .uint16be : number
    • .uint16le : number

Byte length of instances.

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

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

Kind: instance property of Short

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

Kind: instance property of Short

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

Kind: instance property of Short

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

Kind: instance property of Short

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

Kind: static mixin of types
Extends: Struct

• .Uint16BE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .uint16be : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance property of Uint16BE

Kind: instance method of Uint16BE
Returns: number - uint16be

Kind: instance method of Uint16BE

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

Kind: static mixin of types
Extends: Struct

• .Uint16LE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .uint16le : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance property of Uint16LE

Kind: instance method of Uint16LE
Returns: number - uint16le

Kind: instance method of Uint16LE

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

Kind: static mixin of types
Extends: Struct

• .Uint32BE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .uint32be : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance property of Uint32BE

Kind: instance method of Uint32BE
Returns: number - uint32be

Kind: instance method of Uint32BE

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

Kind: static mixin of types
Extends: Struct

• .Uint32LE ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .uint32le : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

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

Kind: instance property of Uint32LE

Kind: instance method of Uint32LE
Returns: number - uint32le

Kind: instance method of Uint32LE

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

Kind: static mixin of types
Extends: Struct

• .Uint8 ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .uint8 : number
    • .get() ⇒ number
    • .set(value)

Byte length of instances.

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

An 8-bit unsigned integer.

Kind: instance property of Uint8

Kind: instance method of Uint8
Returns: number - uint8

Kind: instance method of Uint8

A union of all 4-byte predefined types.

Kind: static mixin of types
Extends: Struct

• .Word ⇐ Struct
  • static
    • .byteLength : number
  • instance
    • .float32be : number
    • .float32le : number
    • .int32be : number
    • .int32le : number
    • .uint32be : number
    • .uint32le : number

Byte length of instances.

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

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

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

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

Kind: instance property of Word

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

Kind: instance property of Word

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

Kind: instance property of Word

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

Kind: instance property of Word

Available under the MIT License (c) 2017 Patrick Roberts