Functions

pack

Supported By

Syntax

[the] pack of ( format , value [, value [, ...]] )

pack ( format , value [, value [, ...]] )

Format yields a string describing a binary data structure. Value yields an appropriate variant for the corresponding field.

Description

The pack function packs the given values into a binary according to the binary data structure specified by format. It is inspired by the pack functions in Perl and PHP, but has a much more powerful syntax.

The format string can be specified in one of two ways. Using the short format, each field in the binary data structure is specified using the following syntax:

type [size] [elaboration] [count] [name] [description]

Only type is required. The type is a single character from the table below. Uppercase indicates big-endian values, and lowercase indicates little-endian values. The size is the number of bits. The elaboration is a type-specific string that must be enclosed in braces; for further details, see the table below. If a count is specified, the unpacked value is a list, and the count must be a number enclosed in brackets indicating the number of elements in the list; otherwise, the unpacked value is a single value. (Except for the * and @ types, where the count is the number of bytes and the offset, respectively.) The name is a string enclosed in backticks (`). The description is a string enclosed in quotes. The name and description have no effect on the packing or unpacking of the data. Whitespace in the format string is ignored except for inside quotes and as a token separator.

Using the long format, each field in the binary data structure is specified using the following syntax:

type [size] [endianness] [elaboration] [count] [name] [description] ;

Only type is required. The type is a type name from the table below. The size is the number of bits. The endianness is be for big-endian or le for little-endian; if endianness is not specified, big-endian is assumed. The elaboration is a type-specific string that must be enclosed in braces; for further details, see the table below. If a count is specified, the unpacked value is a list, and the count must be a number enclosed in brackets indicating the number of elements in the list; otherwise, the unpacked value is a single value. (Except for the binary and offset types, where the count is the number of bytes and the offset, respectively.) The name is either a sequence of alphanumeric characters, or a string enclosed in backticks (`). The description is a string enclosed in quotes, or any sequence of characters following the name and preceding the terminating semicolon. The name and description have no effect on the packing or unpacking of the data. Whitespace in the format string is ignored except for inside quotes and as a token separator.

The possible field types are:

T, t bool, boolean A boolean value (T for "truth value"). The unpacked value is false for a packed value of zero or true for a packed value of one (or any other value when unpacking).
E, e enum An enumeration. The elaboration is a list of key-value pairs, delimited by semicolons, with the key and value separated by an equals sign. Each key is an integer representing a possible packed value and each value is a string. The unpacked value is one of those strings.
J, j bitfield A bit field (J for "jumper"). The elaboration is a list of key-value pairs, delimited by semicolons, with the key and value separated by an equals sign. Each key is an integer representing a bit in the packed value (from 0 for the least-significant bit to size-1 for the most-significant bit) and each value is a string. The unpacked value is a comma-delimited list of such strings.
B, b bint An unsigned integer in binary. The unpacked value is a string of binary digits.
O, o oint An unsigned integer in octal. The unpacked value is a string of octal digits.
H, h hint An unsigned integer in hexadecimal. The unpacked value is a string of hexadecimal digits.
U, u uint An unsigned integer. The unpacked value is an integer.
I, i int, sint A signed integer. The unpacked value is an integer.
R, r ufixed An unsigned fixed-point number (R for "ratio"). The radix point is fixed in the center of the packed value (e.g., at bit 8 if the size is 16). The unpacked value is a number.
Q, q fixed, sfixed A signed fixed-point number (Q for "quotient"). The radix point is fixed in the center of the packed value (e.g., at bit 8 if the size is 16). The unpacked value is a number.
F, f float A floating-point number. The elaboration is the number of sign bits, the number of exponent bits, the number of mantissa bits, and the exponent bias, separated by periods. If the elaboration is not specified, a best guess is made at the appropriate number of bits and the appropriate bias based on the size. For sizes of 16, 32, 64, and 128 bits, this "best guess" is guaranteed to be 1.5.10.15, 1.8.23.127, 1.11.52.1023, and 1.15.112.16383, respectively, corresponding to IEEE half-, single-, double-, and quad-precision floating-point numbers. The unpacked value is a number.
K, k complex A complex number, composed of two floating-point numbers (the real part followed by the imaginary part). The size is the number of bits per part, rather than total. The elaboration is the same as for float above. The unpacked value is a complex.
C, c char, character A character constant. The size must be a multiple of 8. The elaboration is the name of a text encoding. If the elaboration is unspecified, ISO-8859-1 is assumed. The unpacked value is a string.
P, p pstring A Pascal-style string. The size is the number of bits in the count preceding the actual string data. The elaboration is the name of a text encoding. If the elaboration is unspecified, ISO-8859-1 is assumed. The unpacked value is a string.
S, s string, cstring A C-style string. The size is the number of zero bits following the actual string data and must be a multiple of 8. The elaboration is the name of a text encoding. If the elaboration is unspecified, ISO-8859-1 is assumed. The unpacked value is a string.
D, d date, time, datetime A date. The elaboration is the year, month, day, hour, minute, and second of the epoch, and the scale (0 for seconds, -3 for milliseconds, -6 for microseconds, etc.), each delimited by commas. If the elaboration is unspecified, 1970,1,1,0,0,0,0 is assumed, corresponding to the number of seconds since January 1, 1970 (the Unix epoch). To use the Macintosh epoch, use 1904,1,1,0,0,0,0. For milliseconds, replace the last number with -3. The unpacked value is a date.
X, x color, colour A color (X for Greek χρώμα, chroma, meaning "color"). The elaboration is a string determining the color model and the order and width of the color channels. The default is true color with alpha in ARGB order with size/4 bits per channel. For a size of 32 bits, this would be equivalent to an elaboration of a8r8g8b8. The unpacked value is a color.
Z, z filler A series of size filler bits (Z for "zero"). When packing, size bits are filled with zero. When unpacking, size bits are skipped and ignored. There is no unpacked value for this data type.
M, m magic The elaboration is a magic number. When packing, the resulting packed value is the magic number. When unpacking, the packed value is checked against the magic number; if they don't match, a script error is triggered. There is no unpacked value for this data type.
A, a align Alignment to a multiple of size bits. There is no unpacked value for this data type.
* blob, binary The size, endianness, and elaboration are ignored. The count is the number of bytes to pack or unpack. If the count is unspecified when unpacking, zero bytes are unpacked. If the count is unspecified when packing, however many bytes are in the unpacked value are packed. The unpacked value is a binary.
$ struct A substructure. The elaboration is a format string describing the binary data substructure. The unpacked value is a list of unpacked values from the specified substructure.
@ offset The size, endianness, and elaboration are ignored. The count is an offset from the beginning of the packed binary where future values are packed to or unpacked from. When unpacking, the offset may be anywhere in the binary. When packing, the offset must be greater than or equal to the number of bytes already packed.

In addition to the type names listed above, the following special type names are allowed in a long-format format string. These special type names specify a size and, for some, an endianness and an elaboration in addition to a data type.

bbyte alias for bint8
obyte alias for oint8
hbyte alias for hint8
ubyte alias for uint8
sbyte alias for sint8
byte alias for int8
bshort alias for bint16
oshort alias for oint16
hshort alias for hint16
ushort alias for uint16
sshort alias for sint16
short alias for int16
blong alias for bint64
olong alias for oint64
hlong alias for hint64
ulong alias for uint64
slong alias for sint64
long alias for int64
half alias for float16
single alias for float32
real alias for float32
double alias for float64
quad alias for float128
onecc alias for char8
occ alias for char8
twocc alias for char16
tcc alias for char16
fourcc alias for char32
fcc alias for char32
eightcc alias for char64
ecc alias for char64
wstring alias for pstring16
lstring alias for pstring32
wchar alias for char16be{UTF-16}
wcharbe alias for char16be{UTF-16}
wcharle alias for char16le{UTF-16}
ostype alias for char32be{MacRoman}
symbol alias for char64be{ISO-8859-1}
point alias for struct{sint16be y; sint16be x;}
rect alias for struct{sint16be top; sint16be left; sint16be bottom; sint16be right;}
rectangle alias for struct{sint16be top; sint16be left; sint16be bottom; sint16be right;}
rgbcolor alias for struct{uint16be red; uint16be green; uint16be blue;}
rgbcolour alias for struct{uint16be red; uint16be green; uint16be blue;}

Notes

If the format string is not properly formed, a script error is triggered.

If any value is not of an appropriate type for its corresponding field, a script error is triggered.

If there are fewer values passed to the function than are specified by the format, the missing values are assumed to be empty. If the corresponding fields are, e.g., char or string, this will have no ill effect, but if the corresponding fields are, e.g., boolean or date, this will trigger a script error.

If there are more values passed to the function than are specified by the format, the extra values are ignored.

The values to be packed must be passed directly as parameters to the pack function. If you already have the values you need in a list, either put the format string before the list then pass the list to the pack function, or pass the list as the value for a struct whose elaboration is the original format string.

See Also

unpack