Index: Doc/library/struct.rst =================================================================== --- Doc/library/struct.rst (revision 87813) +++ Doc/library/struct.rst (working copy) @@ -76,10 +76,17 @@ Format Strings -------------- +.. productionlist:: + format_string: `byte_order_specifier`? `format_string_body` + format_string_body: (`count`? `type_string`)* + type_string: `character_code` | `structure` + count: `decimalinteger` + Format strings are the mechanism used to specify the expected layout when packing and unpacking data. They are built up from :ref:`format-characters`, -which specify the type of data being packed/unpacked. In addition, there are -special characters for controlling the :ref:`struct-alignment`. +which specify the type of data being packed/unpacked. There are special +characters for controlling the :ref:`struct-alignment`. In addition, +the layout of nested :ref:`structure-layout` may be specified. .. _struct-alignment: @@ -87,6 +94,9 @@ 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). @@ -145,11 +155,34 @@ count of zero. See :ref:`struct-examples`. +.. _structure-layout: + +Structure Layout +^^^^^^^^^^^^^^^^ + +.. productionlist:: + structure: "T" "{" `format_string_body` "}" + +The structure layout format string provides a way to specify layouts which +may be arbitrarily nested (with limits, see note). 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. + +.. note:: + The allowable nesting depth of structures is limited. It is guaranteed + that at least 63 nesting levels are allowed. + .. _format-characters: Format Characters ^^^^^^^^^^^^^^^^^ +.. productionlist:: + character_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. The 'Standard size' column refers to the size of the packed value in bytes when using standard size; that @@ -323,7 +356,30 @@ 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'),) + +Empty structures are allowed, but note that they must be packed with empty +tuples:: + +>>> pack('T{}', ()) + b'' +>>> pack('T{T{}}', ((),)) + b'' +>>> pack('T{}') + Traceback (most recent call last): + File "", line 1, in + struct.error: pack requires exactly 1 arguments + + .. seealso:: Module :mod:`array`

AltStyle によって変換されたページ (->オリジナル) /