Index: Doc/library/struct.rst |
=================================================================== |
--- Doc/library/struct.rst (revision 81143) |
+++ Doc/library/struct.rst (working copy) |
@@ -76,14 +76,40 @@ |
Format Strings |
-------------- |
+.. productionlist:: |
+ format_string: (`byte_order_specifier`? `type_string`)* |
+ type_string: `primitive` |
+ : | `structure` |
+ |
Format strings are the mechanism used to specify the expected layout when |
packing and unpacking data. They are built up from format characters, which |
-specify the type of data being packed/unpacked. In addition, there are |
-special characters for controlling the byte order, size, and alignment. |
+specify the type of data being packed/unpacked. There are special characters |
+for controlling the byte order, size, and alignment. In addition, the layout |
+of nested structure layouts may be specified. |
-Format Characters |
-^^^^^^^^^^^^^^^^^ |
+Structure Layout |
+^^^^^^^^^^^^^^^^ |
+.. productionlist:: |
+ structure: "T" "{" `format_string` "}" |
+ |
+The structure layout format string provides a way to specify layouts which |
+may be arbitrarily nested. Packing a structure layout requires a nested |
+tuple with the same shape as the structure layout being packed. Similarly, |
+unpacking produces a nested structure with the same shape as the structure |
+layout being unpacked. |
+ |
+ |
+Primitive Format Characters |
+^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
+ |
+.. productionlist:: |
+ primitive: `count`? `code` |
+ count: `decimalinteger` |
+ code: "x" | "c" | "b" | "B" | "?" | "h" | "H" | "i" | "I" | "l" | "L" |
+ : | "q" | "Q" | "f" | "d" | "s" | "p" | "P" | "t" | "g" | "u" | "w" |
+ | | "O" | "Z" |
+ |
Format characters have the following meaning; the conversion between C and |
Python values should be obvious given their types: |
@@ -201,13 +227,15 @@ |
Byte Order, Size, and Alignment |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
+.. productionlist:: |
+ byte_order_specifier: "!" | "@" | "=" | ">" | "<" | "^" |
+ |
By default, C types 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). |
-Alternatively, the first character of the format string can be used to indicate |
-the byte order, size and alignment of the packed data, according to the |
-following table: |
+Alternatively, format characters can be used to indicate the byte order, size |
+and alignment of the packed data, according to the following table: |
+-----------+------------------------+--------------------+ |
| Character | Byte order | Size and alignment | |
@@ -223,7 +251,11 @@ |
| ``!`` | network (= big-endian) | standard | |
+-----------+------------------------+--------------------+ |
-If the first character is not one of these, ``'@'`` is assumed. |
+These characters may occur anywhere within the format string. If no such |
+character is mentioned, then ``'@'`` is assumed. Additionally, these |
+characters may be mentioned multiple times within a format string. The byte |
+order, size and alignment dictated by one of these characters is in effect |
+until the next such character is encountered. |
Native byte order is big-endian or little-endian, depending on the host |
system. For example, Intel x86 and AMD64 (x86-64) are little-endian; |
@@ -319,7 +351,22 @@ |
This only works when native size and alignment are in effect; standard size and |
alignment does not enforce any alignment. |
+In addition to primitive character codes, nested structure layouts can be |
+packed:: |
+ >>> pack('c T { iii T { h } }', '*', (1, 2, 3, (4,))) |
+ '*\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00\x04\x00' |
+ |
+and unpacked:: |
+ |
+ >>> unpack('T{ c T{ c } c}', 'rgb') |
+ (('r', ('g',), 'b'),) |
+ |
+Also note that the byte order, size and alignment can be changed inline:: |
+ |
+ >>> pack('<H T { >i }', 1, (2,)) |
+ '\x01\x00\x00\x00\x00\x02' |
+ |
.. seealso:: |
Module :mod:`array` |