Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(692)

Unified Diff: Doc/library/struct.rst

Issue 1258041: PEP 3318 - New struct string syntax Base URL: http://svn.python.org/view/*checkout*/python/branches/py3k/
Patch Set: Created 13 years, 10 months ago
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « no previous file | Lib/test/test_struct.py » ('j') | Modules/_struct.c » ('J')
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
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`
« no previous file with comments | « no previous file | Lib/test/test_struct.py » ('j') | Modules/_struct.c » ('J')

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b