├── jspack.js ├── LICENSE └── README /jspack.js: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pgriess/node-jspack/HEAD/jspack.js -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2008, Fair Oaks Labs, Inc. 2 | All rights reserved. 3 | 4 | Redistribution and use in source and binary forms, with or without modification, are 5 | permitted provided that the following conditions are met: 6 | 7 | * Redistributions of source code must retain the above copyright notice, this list 8 | of conditions and the following disclaimer. 9 | 10 | * Redistributions in binary form must reproduce the above copyright notice, this 11 | list of conditions and the following disclaimer in the documentation and/or other 12 | materials provided with the distribution. 13 | 14 | * Neither the name of Fair Oaks Labs, Inc. nor the names of its contributors may be 15 | used to endorse or promote products derived from this software without specific 16 | prior written permission. 17 | 18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 19 | EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 20 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 21 | THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 23 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 25 | STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 26 | THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 | -------------------------------------------------------------------------------- /README: -------------------------------------------------------------------------------- 1 | Disclaimer: The jspack module and documentation are essentially ports of the 2 | Python struct module and documentation, with such changes as were necessary. 3 | If any Python people are miffed that I've ripped off their docs, let me know, 4 | and I'll gladly revise them. 5 | 6 | This module performs conversions between JavaScript values and C structs 7 | represented as octet arrays (i.e. JavaScript arrays of integral numbers 8 | between 0 and 255, inclusive). It uses format strings (explained below) as 9 | compact descriptions of the layout of the C structs and the intended conversion 10 | to/from JavaScript values. This can be used to handle binary data stored in 11 | files, or received from network connections or other sources. 12 | 13 | 14 | The module defines the following functions: 15 | 16 | Unpack(fmt, a, p) 17 | Return an array containing values unpacked from the octet array a, 18 | beginning at position p, according to the supplied format string. If there 19 | are more octets in a than required by the format string, the excess is 20 | ignored. If there are fewer octets than required, Unpack() will return 21 | undefined. If no value is supplied for the p argument, zero is assumed. 22 | 23 | PackTo(fmt, a, p, values) 24 | Pack and store the values array into the supplied octet array a, beginning 25 | at position p. If there are more values supplied than are specified in the 26 | format string, the excess is ignored. If there are fewer values supplied, 27 | PackTo() will return false. If there is insufficient space in a to store 28 | the packed values, PackTo() will return false. On success, PackTo() returns 29 | the a argument. If any value is of an inappropriate type, the results are 30 | undefined. 31 | 32 | Pack(fmt, values) 33 | Return an octet array containing the packed values array. If there are 34 | more values supplied than are specified in the format string, the excess is 35 | ignored. If there are fewer values supplied, Pack() will return false. If 36 | any value is of an inappropriate type, the results are undefined. 37 | 38 | CalcLength(fmt) 39 | Return the number of octets required to store the given format string. 40 | 41 | 42 | Format characters have the following meanings; the conversion between C and 43 | JavaScript values should be obvious given their types: 44 | 45 | Format | C Type | JavaScript Type | Size (octets) | Notes 46 | ------------------------------------------------------------------- 47 | A | char[] | Array | Length | (1) 48 | x | pad byte | N/A | 1 | 49 | c | char | string (length 1) | 1 | (2) 50 | b | signed char | number | 1 | (3) 51 | B | unsigned char | number | 1 | (3) 52 | h | signed short | number | 2 | (3) 53 | H | unsigned short | number | 2 | (3) 54 | i | signed long | number | 4 | (3) 55 | I | unsigned long | number | 4 | (3) 56 | l | signed long | number | 4 | (3) 57 | L | unsigned long | number | 4 | (3) 58 | s | char[] | string | Length | (2) 59 | f | float | number | 4 | (4) 60 | d | double | number | 8 | (5) 61 | 62 | Notes: 63 | 64 | (1) The "A" code simply returns a slice of the source octet array. This is 65 | primarily useful when a data structure contains bytes which are subject to 66 | multiple intepretations (e.g. unions), and the data structure is being 67 | decoded in multiple passes. 68 | 69 | (2) The "c" and "s" codes handle strings with codepoints between 0 and 255, 70 | inclusive. The data are not bounds-checked, so strings containing characters 71 | with codepoints outside this range will encode to "octet" arrays that contain 72 | values outside the range of an octet. Furthermore, since these codes decode 73 | octet arrays by assuming the octets represent UNICODE codepoints, they may 74 | not "correctly" decode bytes in the range 128-255, since that range is subject 75 | to multiple interpretations. Caveat coder! 76 | 77 | (3) The 8 "integer" codes clip their encoded values to the minima and maxmima 78 | of their respective types: If you invoke Struct.Pack('b', [-129]), for 79 | instance, the result will be [128], which is the octet encoding of -128, 80 | which is the minima of a signed char. Similarly, Struct.Pack('h', [-32769]) 81 | returns [128, 0]. Fractions are truncated. 82 | 83 | (4) Since JavaScript doesn't natively support 32-bit floats, whenever a float 84 | is stored, the source JavaScript number must be rounded. This module applies 85 | correct rounding during this process. Numbers with magnitude greater than or 86 | equal to 2**128-2**103 round to either positive or negative Infinity. The 87 | rounding algorithm assumes that JavsScript is using exactly 64 bits of 88 | floating point precision; 128-bit floating point will result in subtle errors. 89 | 90 | (5) This module assumes that JavaScript is using 64 bits of floating point 91 | precision, so the "d" code performs no rounding. 128-bit floating point will 92 | cause the "d" code to simply truncate significands to 52 bits. 93 | 94 | A format character may be preceded by an integral repeat count. For example, 95 | the format string "4h" means exactly the same thing as "hhhh". 96 | 97 | Whitespace characters between formats are ignored; a count and its format must 98 | not be separated by whitespace, however. 99 | 100 | For the "A" format character, the count is interpreted as the size of the 101 | array, not a repeat count as for the other format characters; for example, "10A" 102 | means a single 10-octet array. When packing, the Array is truncated or padded 103 | with 0 bytes as appropriate to make it conform to the specified length. When 104 | unpacking, the resulting Array always has exactly the specified number of bytes. 105 | As a special case, "0A" means a single, empty Array. 106 | 107 | For the "s" format character, the count is interpreted as the size of the 108 | string, not a repeat count as for the other format characters; for example, 109 | "10s" means a single 10-byte string, while "10c" means 10 characters. When 110 | packing, the string is truncated or padded with 0 bytes as appropriate to make 111 | it conform to the specified length. When unpacking, the resulting string always 112 | has exactly the specified number of bytes. As a special case, "0s" means a 113 | single, empty string (while "0c" means 0 characters). 114 | 115 | 116 | By default, C numbers are represented in network (or big-endian) byte order. 117 | Alternatively, the first character of the format string can be used to indicate 118 | byte order of the packed data, according to the following table: 119 | 120 | Character | Byte Order 121 | ---------------------------------- 122 | < | little-endian 123 | > | big-endian 124 | ! | network (= big-endian) 125 | 126 | If the first character is not one of these, "!" is assumed. 127 | --------------------------------------------------------------------------------