This project is part of the @thi.ng/umbrella monorepo.
About
C-style struct, union and bitfield read/write views of ArrayBuffers.
Features:
- Construct memory mapped JS objects based on given typedef specs
- Nested structs & unions
- Packed bitfields (signed / unsigned)
- Auto-alignment of fields to respective word boundaries (can be disabled)
- Configurable endianness (bitfields currently assume network order / big endian)
- No runtime dependencies, works in node & browser
- Small: 2.35KB minified, 1.14KB gzipped
Currently does not support array fields (incl. strings).
Status
STABLE - used in production
Search or submit any issues for this package
Installation
yarn add @thi.ng/unionstruct
// ES module
<script type="module" src="https://unpkg.com/@thi.ng/unionstruct?module" crossorigin></script>
// UMD
<script src="https://unpkg.com/@thi.ng/unionstruct/lib/index.umd.js" crossorigin></script>
Package sizes (gzipped, pre-treeshake): ESM: 1.08 KB / CJS: 1.13 KB / UMD: 1.19 KB
Dependencies
None
API
import { struct, union, sizeOf } from "@thi.ng/unionstruct";
C-style union types define alternate views of the same data. For example
this C snippet below defines such a type, of which the first 32-bits can
be accessed either via individual bitfields or as combined value. Fields
in this union type can be accessed like x.flags (combined) or
x.state.cache (only bits 9-11 of x.flags). Since all views share the
same memory, value changes of one view are reflected in all others too
(of course updating bitfields only modifies a field's allocated bit
range).
// C
typedef union {
uint32_t flags;
struct {
uint32_t type : 9;
uint32_t cache : 3;
uint32_t enabled : 1;
uint32_t visible : 1;
uint32_t selected : 1;
uint32_t locked : 1;
int32_t scheduled : 18;
uint16_t tag;
} state;
} Header;
This library provides this similarly in JS. The field spec format, bitfields and alignment are described further below.
typedef_header = [
["flags", "u32"],
["state", "struct", [
["type", "u32", 9],
["cache", "u32", 3],
["enabled", "u32", 1],
["visible", "u32", 1],
["selected", "u32", 1],
["locked", "u32", 1],
["scheduled", "i32", 18],
["tag", "u16"]]]
];
// pre-loaded binary data
buf = new Uint32Array([0x807cc0, 0x40000000, 0x3930]);
// create instance, see list of header arguments below
header = union(typedef_header, buf.buffer);
// { __buffer: ArrayBuffer { byteLength: 12 },
// __spec: [['flags', 'u32'], ['state', 'struct', [...]]],
// __size: 80,
// __offsets: { flags: 0, state: 0 },
// flags: [Getter/Setter],
// state: [Getter] }
header.state
// { __buffer: ArrayBuffer { byteLength: 12 },
// __spec: [...],
// __size: 80,
// __offsets:
// { type: 0,
// cache: 9,
// enabled: 12,
// visible: 13,
// selected: 14,
// locked: 15,
// scheduled: 16,
// tag: 64 },
// ... }
header.flags.toString(16) // "c07c8000"
header.state.type // 384
header.state.enabled // 1
header.state.visible // 1
header.state.selected // 0
header.state.locked // 0
header.state.scheduled // -131072
header.state.tag // 12345
union
union(spec: Field[], buf?: ArrayBuffer, offset = 0, align = true, littleEndian = false) => any
Takes an array of field specs (as in example above) and optional ArrayBuffer, offset etc. If no buffer is given, constructs a new one with minimum size required by this field spec. Returns an object with enumerable field accessors and the following additional keys (largely for introspection purposes):
__buffer- backing ArrayBuffer instance__offsets- bit offset in buffer for each field__spec- original field spec array provided__size- computed bit size of whole type
All top-level fields in a union share the same start address. Also see note about alignment below.
struct
struct(spec: Field[], buf?: ArrayBuffer, offset = 0, align = true, littleEndian = false) => any
Same as union, but field start addresses are arranged sequentially (and aligned individually).
sizeOf
sizeOf(spec: Field[], union = false, doAlign = true) => number
Returns bit size of given field spec, taking into account alignment.
// struct
sizeOf([["a", "u32", 14], ["b", "u32", 6], ["c","u8"]]);
// 40
// union
sizeOf([["a", "u32", 14], ["b", "u32", 6], ["c","u8"]], true);
// 14
Alignment
For unions, if align is enabled (default), the entire type's offset
will be aligned to the largest required width. E.g. If any of the
top-level fields is of type f64, alignment will be to 8-byte
boundaries. If the union contains nested types, they will be checked
recursively and aligned to largest type found (for structs only the
first field has an impact on whole struct alignment).
| Type | Alignment |
|---|---|
| f64 | 8 |
| f32 | 4 |
| u32 / i32 | 4 |
| u16 / i16 | 2 |
| u8 / i8 | 1 |
Bitfields
Bitfields can only use integer types and support both signed / unsigned flavors. Successive bitfields are densely packed (no alignment in between). The max. width of a single field is 32 bits, but an arbitrary number of successive bitfields can be defined.
If align is enabled and the last bitfield in a group does not end at a
word boundary, the field will be padded invisibly, based on its type
(has no impact on size of last field).
bitfields = struct([
// 2 packed bitfields (20 bits)
["a", "u32", 14],
["b", "u32", 6],
// 32 - 20 = 12 bit padding here
["c", "u8"] // providing no bit width forces alignment
]);
bitfields.__offsets
// { a: 0, b: 14, c: 32 }
// without padding, field `c` would incorrectly start at bit offset 24
// (since u8 aligns itself to 8-bit boundaries)
Authors
Karsten Schmidt
If this project contributes to an academic publication, please cite it as:
@misc{thing-unionstruct,
title = "@thi.ng/unionstruct",
author = "Karsten Schmidt",
note = "https://thi.ng/unionstruct",
year = 2017
}
License
© 2017 - 2021 Karsten Schmidt // Apache Software License 2.0