jspack - library to pack primitives to octet arrays
The jspack module and documentation are essentially ports of the Python struct module and documentation, with such changes as were necessary. The port was originaly made by Fair Oaks Labs, Inc. and published at http://code.google.com/p/jspack/ If any Python people are miffed that their documentation got ripped off, let me know, and I'll gladly revise them.
npm install jspack
Before any code will be accepted it has to pass. ``` npm test npm run lint ``` Please create tests for any new functionality or bugs.
The module defines the following functions:
Unpack(fmt, a, p)
Return an array containing values unpacked from the octet array a, beginning at position p, according to the supplied format string. If there are more octets in a than required by the format string, the excess is ignored. If there are fewer octets than required, Unpack() will return undefined. If no value is supplied for the p argument, zero is assumed.
PackTo(fmt, a, p, values)
Pack and store the values array into the supplied octet array a, beginning at position p. If there are more values supplied than are specified in the format string, the excess is ignored. If there are fewer values supplied, PackTo() will return false. If there is insufficient space in a to store the packed values, PackTo() will return false. On success, PackTo() returns the a argument. If any value is of an inappropriate type, the results are undefined.
Return an octet array containing the packed values array. If there are more values supplied than are specified in the format string, the excess is ignored. If there are fewer values supplied, Pack() will return false. If any value is of an inappropriate type, the results are undefined.
Return the number of octets required to store the given format string.
(1) The "A" code simply returns a slice of the source octet array. This is primarily useful when a data structure contains bytes which are subject to multiple intepretations (e.g. unions), and the data structure is being decoded in multiple passes.
(2) The "c" and "s" codes handle strings with codepoints between 0 and 255, inclusive. The data are not bounds-checked, so strings containing characters with codepoints outside this range will encode to "octet" arrays that contain values outside the range of an octet. Furthermore, since these codes decode octet arrays by assuming the octets represent UNICODE codepoints, they may not "correctly" decode bytes in the range 128-255, since that range is subject to multiple interpretations. Caveat coder!
(3) The 8 "integer" codes clip their encoded values to the minima and maxmima of their respective types: If you invoke Struct.Pack('b', [-129]), for instance, the result will be , which is the octet encoding of -128, which is the minima of a signed char. Similarly, Struct.Pack('h', [-32769]) returns [128, 0]. Fractions are truncated.
jspack will process longs as arrays in the form:
[lowBits, hightBits]. The
decoded long array contains a third element, the unsigned flag, which is
false for signed
true for unsigned values.
This representation is similar to what Long.js, and
therefore the Google Closure Libaray, uses.
See test/int64.js for examples how to work with Long.js.
A format character may be preceded by an integral repeat count. For example, the format string "4h" means exactly the same thing as "hhhh".
Whitespace characters between formats are ignored; a count and its format must not be separated by whitespace, however.
For the "A" format character, the count is interpreted as the size of the array, not a repeat count as for the other format characters; for example, "10A" means a single 10-octet array. When packing, the Array is truncated or padded with 0 bytes as appropriate to make it conform to the specified length. When unpacking, the resulting Array always has exactly the specified number of bytes. As a special case, "0A" means a single, empty Array.
For the "s" format character, the count is interpreted as the size of the string, not a repeat count as for the other format characters; for example, "10s" means a single 10-byte string, while "10c" means 10 characters. When packing, the string is truncated or padded with 0 bytes as appropriate to make it conform to the specified length. When unpacking, the resulting string always has exactly the specified number of bytes. As a special case, "0s" means a single, empty string (while "0c" means 0 characters).
By default, C numbers are represented in network (or big-endian) byte order. Alternatively, the first character of the format string can be used to indicate byte order of the packed data, according to the following table:
Character | Byte Order ---------------------------------- < | little-endian > | big-endian ! | network (= big-endian)
If the first character is not one of these, "!" is assumed.