Prev: marshal Up: Built-in Modules Top: Top

3.9. Built-in module `struct`

This module performs conversions between Python values and C structs represented as Python strings. It uses format strings (explained below) as compact descriptions of the lay-out of the C structs and the intended conversion to/from Python values.

The module defines the following exception and functions:

error -- exception of module struct: Exception raised on various occasions; argument is a string describing what is wrong.

pack (fmt, v1, v2, @varr@vardots) -- function of module struct: Return a string containing the values v1, v2, ... packed according to the given format. The arguments must match the values required by the format exactly.

unpack (fmt, string) -- function of module struct: Unpack the string (presumably packed by pack(fmt, ...)) according to the given format. The result is a tuple even if it contains exactly one item. The string must contain exactly the amount of data required by the format (i.e. len(string) must equal calcsize(fmt)).

calcsize (fmt) -- function of module struct: Return the size of the struct (and hence of the string) corresponding to the given format.

Format characters have the following meaning; the conversion between C and Python values should be obvious given their types:

Format: C --- Python
`x': pad byte --- no value
`c': char --- string of length 1
`b': signed char --- integer
`h': short --- integer
`i': int --- integer
`l': long --- integer
`f': float --- float
`d': double --- float

A format character may be preceded by an integral repeat count; e.g. the format string '4h' means exactly the same as 'hhhh'.

C numbers are represented in the machine's native format and byte order, and properly aligned by skipping pad bytes if necessary (according to the rules used by the C compiler).

Examples (all on a big-endian machine):

pack('hhl', 1, 2, 3) == '\000\001\000\002\000\000\000\003'
unpack('hhl', '\000\001\000\002\000\000\000\003') == (1, 2, 3)

calcsize('hhl') == 8

Hint: to align the end of a structure to the alignment requirement of a particular type, end the format with the code for that type with a repeat count of zero, e.g. the format 'llh0l' specifies two pad bytes at the end, assuming longs are aligned on 4-byte boundaries.

(More format characters are planned, e.g. 's' for character arrays, upper case for unsigned variants, and a way to specify the byte order, which is useful for [de]constructing network packets and reading/writing portable binary file formats like TIFF and AIFF.)

3.9. Built-in module struct

3.9. Built-in module `struct`