项目作者: raidiun

项目描述 :
Vanilla JS ESM port of Python's struct
高级语言: JavaScript
项目地址: git://github.com/raidiun/jpstruct.git
创建时间: 2021-06-03T16:25:41Z
项目社区:https://github.com/raidiun/jpstruct

开源协议:

下载


jpstruct (Js-Python Struct)

Vanilla JavaScript port of Python’s struct.
Implemented as an ESM module for simple usage into the browser.

Requires support for BigInt
and BigUint64Array
from ES2020 for Q and q format characters.

Input and Output

Uint8Arrays are used for byte-level representations.

Unpacking operations return an Array containing the the unpacked data in the same order as the
format string.

Differences from Python’s struct

In Python, the empty array [] is truthy, while in JavaScript it is falsy. This means that
struct.pack('?',[]) in Python has a different result to jpstruct.pack('?',[]); in JavaScript.

Values that return true from Number.isInteger() will be coerced into integers for integer format
characters. This breaks with Python behaviour where attempting to pack a float would raise an error.

The native size format characters n and N are interpreted the as i and I, i.e. the
platform is assumed to use 32-bit ssize_t and size_t types. Similarly, the pointer format
character P is also assumed to be 32-bit and is interpreted as I.

The half-precision floating point format character e is not supported. It will be treated as
an unsigned short (H format character).

The perl-string format character p is not supported.

Format String

The format string format is the same as Python’s implementation with a few caveats detailed below.

Byteorder Marker

The leading character of a format string can be used to indicate the byte order of the underlying
data. In Python’s implementation, this can also determine additional size and alignment variations.
In this implementation, no alignment padding is added to any of the variants. Additionally,
standard sizes apply for all cases.

Character Endianness
@ (Platform determined)
= (Platform determined)
< Little-endian
> Big-endian
! Big-endian (network byte order)

As in Python, if the leading character is not one of the options in the table, the functions will
behave as if the leading character was @.

Format Characters

The remainder of the format string is made up of format characters and an optional count preceding
each format character. The count is a base-10 integer that effectively repeats the following format
character. For strings (s), the count is used to specify the length of the string.

Format Character C Type Javascript Type
x - Used to add padding byte to format
c char string (length 1)
b int8_t number
B uint8_t number
? bool (encoded as 1 byte) boolean
h int16_t number
H uint16_t number
i int32_t number
I uint32_t number
l int32_t number
L uint32_t number
q int64_t bigint
Q uint64_t bigint
n int32_t number
N uint32_t number
e binary16 number
f float number
d double number
s char[] Uint8Array
P void* number

To convert the Uint8Array returned from a s format string:

  1. let unpacked = jpstruct.unpack('4s',Uint8Array.from([0x20,0x20,0x20,0x20]));
  2. let result = String.fromCharCode(...unpacked[0]);

Examples

Pack a string

  1. import * as jpstruct from '../jpstruct.js';
  2. let packed = jpstruct.pack('10s','helloworld');

Pack into a supplied buffer

  1. const orderedfields = [253,13,0,0,40,11,10,33280,0];
  2. const formatter = new jpstruct.Struct('<BBBBBBBHB');
  3. let writable_buf = new Uint8Array(100);
  4. formatter.pack_into(writable_buf,0,...orderedfields);

Pack a BigInt

  1. const packed = jpstruct.pack('<Q',72340172838076673n);

Tests

The testsuite attempts to replicate all of the tests present in the
Python testsuite. There are
still a few missing at this point but coverage is 100% when big-endian platform detection is
excluded.

There are also some additional tests that are a hangover from MAVLink porting efforts.

  1. npm test