| OLD | NEW |
|---|
| 1 :mod:`struct` --- Interpret bytes as packed binary data | 1 :mod:`struct` --- Interpret bytes as packed binary data |
|
| 2 ======================================================= | 2 ======================================================= |
|
| 3 | 3 |
|
| 4 .. module:: struct | 4 .. module:: struct |
|
| 5 :synopsis: Interpret bytes as packed binary data. | 5 :synopsis: Interpret bytes as packed binary data. |
|
| 6 | 6 |
|
| 7 .. index:: | 7 .. index:: |
|
| 8 pair: C; structures | 8 pair: C; structures |
|
| 9 triple: packing; binary; data | 9 triple: packing; binary; data |
|
| 10 | 10 |
|
| (...skipping 58 matching lines...) | | Loading... |
| 69 .. function:: calcsize(fmt) | 69 .. function:: calcsize(fmt) |
|
| 70 | 70 |
|
| 71 Return the size of the struct (and hence of the bytes) corresponding to the | 71 Return the size of the struct (and hence of the bytes) corresponding to the |
|
| 72 given format. | 72 given format. |
|
| 73 | 73 |
|
| 74 .. _struct-format-strings: | 74 .. _struct-format-strings: |
|
| 75 | 75 |
|
| 76 Format Strings | 76 Format Strings |
|
| 77 -------------- | 77 -------------- |
|
| 78 | 78 |
|
| 79 .. productionlist:: |
|
| 80 format_string: (`byte_order_specifier`? `type_string`)* |
|
| 81 type_string: `primitive` |
|
| 82 : | `structure` |
|
| 83 |
|
| 79 Format strings are the mechanism used to specify the expected layout when | 84 Format strings are the mechanism used to specify the expected layout when |
|
| 80 packing and unpacking data. They are built up from format characters, which | 85 packing and unpacking data. They are built up from format characters, which |
|
| 81 specify the type of data being packed/unpacked. In addition, there are | 86 specify the type of data being packed/unpacked. There arespecial characters |
|
| 82 special characters for controlling the byte order, size, and alignment. | 87 for controlling the byte order, size, and alignment. In addition, the layout |
|
| 88 of nested structure layouts may be specified. |
|
| 83 | 89 |
|
| 84 Format Characters | 90 Structure Layout |
|
| 85 ^^^^^^^^^^^^^^^^^ | 91 ^^^^^^^^^^^^^^^^ |
|
| 92 |
|
| 93 .. productionlist:: |
|
| 94 structure: "T" "{" `format_string` "}" |
|
| 95 |
|
| 96 The structure layout format string provides a way to specify layouts which |
|
| 97 may be arbitrarily nested. Packing a structure layout requires a nested |
|
| 98 tuple with the same shape as the structure layout being packed. Similarly, |
|
| 99 unpacking produces a nested structure with the same shape as the structure |
|
| 100 layout being unpacked. |
|
| 101 |
|
| 102 |
|
| 103 Primitive Format Characters |
|
| 104 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
| 105 |
|
| 106 .. productionlist:: |
|
| 107 primitive: `count`? `code` |
|
| 108 count: `decimalinteger` |
|
| 109 code: "x" | "c" | "b" | "B" | "?" | "h" | "H" | "i" | "I" | "l" | "L" |
|
| 110 : | "q" | "Q" | "f" | "d" | "s" | "p" | "P" | "t" | "g" | "u" | "w"· |
|
| 111 | | "O" | "Z" |
|
| 86 | 112 |
|
| 87 Format characters have the following meaning; the conversion between C and | 113 Format characters have the following meaning; the conversion between C and |
|
| 88 Python values should be obvious given their types: | 114 Python values should be obvious given their types: |
|
| 89 | 115 |
|
| 90 +--------+-------------------------+--------------------+------------+ | 116 +--------+-------------------------+--------------------+------------+ |
|
| 91 | Format | C Type | Python | Notes | | 117 | Format | C Type | Python | Notes | |
|
| 92 +========+=========================+====================+============+ | 118 +========+=========================+====================+============+ |
|
| 93 | ``x`` | pad byte | no value | | | 119 | ``x`` | pad byte | no value | | |
|
| 94 +--------+-------------------------+--------------------+------------+ | 120 +--------+-------------------------+--------------------+------------+ |
|
| 95 | ``c`` | :ctype:`char` | bytes of length 1 | | | 121 | ``c`` | :ctype:`char` | bytes of length 1 | | |
|
| (...skipping 98 matching lines...) | | Loading... |
| 194 :const:`False`. When packing, the truth value of the argument object is used. | 220 :const:`False`. When packing, the truth value of the argument object is used. |
|
| 195 Either 0 or 1 in the native or standard bool representation will be packed, and | 221 Either 0 or 1 in the native or standard bool representation will be packed, and |
|
| 196 any non-zero value will be True when unpacking. | 222 any non-zero value will be True when unpacking. |
|
| 197 | 223 |
|
| 198 | 224 |
|
| 199 .. _struct-alignment: | 225 .. _struct-alignment: |
|
| 200 | 226 |
|
| 201 Byte Order, Size, and Alignment | 227 Byte Order, Size, and Alignment |
|
| 202 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | 228 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
| 203 | 229 |
|
| 230 .. productionlist:: |
|
| 231 byte_order_specifier: "!" | "@" | "=" | ">" | "<" | "^" |
|
| 232 |
|
| 204 By default, C types are represented in the machine's native format and byte | 233 By default, C types are represented in the machine's native format and byte |
|
| 205 order, and properly aligned by skipping pad bytes if necessary (according to the | 234 order, and properly aligned by skipping pad bytes if necessary (according to the |
|
| 206 rules used by the C compiler). | 235 rules used by the C compiler). |
|
| 207 | 236 |
|
| 208 Alternatively, the first character of the format string can be used to indicate | 237 Alternatively, format characters can be used to indicatethe byte order, size |
|
| 209 the byte order, size and alignment of the packed data, according to the | 238 and alignment of the packed data, according to thefollowing table: |
|
| 210 following table: |
|
| 211 | 239 |
|
| 212 +-----------+------------------------+--------------------+ | 240 +-----------+------------------------+--------------------+ |
|
| 213 | Character | Byte order | Size and alignment | | 241 | Character | Byte order | Size and alignment | |
|
| 214 +===========+========================+====================+ | 242 +===========+========================+====================+ |
|
| 215 | ``@`` | native | native | | 243 | ``@`` | native | native | |
|
| 216 +-----------+------------------------+--------------------+ | 244 +-----------+------------------------+--------------------+ |
|
| 217 | ``=`` | native | standard | | 245 | ``=`` | native | standard | |
|
| 218 +-----------+------------------------+--------------------+ | 246 +-----------+------------------------+--------------------+ |
|
| 219 | ``<`` | little-endian | standard | | 247 | ``<`` | little-endian | standard | |
|
| 220 +-----------+------------------------+--------------------+ | 248 +-----------+------------------------+--------------------+ |
|
| 221 | ``>`` | big-endian | standard | | 249 | ``>`` | big-endian | standard | |
|
| 222 +-----------+------------------------+--------------------+ | 250 +-----------+------------------------+--------------------+ |
|
| 223 | ``!`` | network (= big-endian) | standard | | 251 | ``!`` | network (= big-endian) | standard | |
|
| 224 +-----------+------------------------+--------------------+ | 252 +-----------+------------------------+--------------------+ |
|
| 225 | 253 |
|
| 226 If the first character is not one of these, ``'@'`` is assumed. | 254 These characters may occur anywhere within the format string. If no such |
|
| 255 character is mentioned, then ``'@'`` is assumed. Additionally, these |
|
| 256 characters may be mentioned multiple times within a format string. The byte |
|
| 257 order, size and alignment dictated by one of these characters is in effect |
|
| 258 until the next such character is encountered. |
|
| 227 | 259 |
|
| 228 Native byte order is big-endian or little-endian, depending on the host | 260 Native byte order is big-endian or little-endian, depending on the host |
|
| 229 system. For example, Intel x86 and AMD64 (x86-64) are little-endian; | 261 system. For example, Intel x86 and AMD64 (x86-64) are little-endian; |
|
| 230 Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature | 262 Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature |
|
| 231 switchable endianness (bi-endian). Use ``sys.byteorder`` to check the | 263 switchable endianness (bi-endian). Use ``sys.byteorder`` to check the |
|
| 232 endianness of your system. | 264 endianness of your system. |
|
| 233 | 265 |
|
| 234 Native size and alignment are determined using the C compiler's | 266 Native size and alignment are determined using the C compiler's |
|
| 235 ``sizeof`` expression. This is always combined with native byte order. | 267 ``sizeof`` expression. This is always combined with native byte order. |
|
| 236 | 268 |
|
| (...skipping 75 matching lines...) | | Loading... |
| 312 | 344 |
|
| 313 The following format ``'llh0l'`` specifies two pad bytes at the end, assuming | 345 The following format ``'llh0l'`` specifies two pad bytes at the end, assuming |
|
| 314 longs are aligned on 4-byte boundaries:: | 346 longs are aligned on 4-byte boundaries:: |
|
| 315 | 347 |
|
| 316 >>> pack('llh0l', 1, 2, 3) | 348 >>> pack('llh0l', 1, 2, 3) |
|
| 317 b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00' | 349 b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00' |
|
| 318 | 350 |
|
| 319 This only works when native size and alignment are in effect; standard size and | 351 This only works when native size and alignment are in effect; standard size and |
|
| 320 alignment does not enforce any alignment. | 352 alignment does not enforce any alignment. |
|
| 321 | 353 |
|
| 354 In addition to primitive character codes, nested structure layouts can be· |
|
| 355 packed:: |
|
| 356 |
|
| 357 >>> pack('c T { iii T { h } }', '*', (1, 2, 3, (4,))) |
|
| 358 '*\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00\x04\x00' |
|
| 359 |
|
| 360 and unpacked:: |
|
| 361 |
|
| 362 >>> unpack('T{ c T{ c } c}', 'rgb') |
|
| 363 (('r', ('g',), 'b'),) |
|
| 364 |
|
| 365 Also note that the byte order, size and alignment can be changed inline:: |
|
| 366 |
|
| 367 >>> pack('<H T { >i }', 1, (2,)) |
|
| 368 '\x01\x00\x00\x00\x00\x02' |
|
| 322 | 369 |
|
| 323 .. seealso:: | 370 .. seealso:: |
|
| 324 | 371 |
|
| 325 Module :mod:`array` | 372 Module :mod:`array` |
|
| 326 Packed binary storage of homogeneous data. | 373 Packed binary storage of homogeneous data. |
|
| 327 | 374 |
|
| 328 Module :mod:`xdrlib` | 375 Module :mod:`xdrlib` |
|
| 329 Packing and unpacking of XDR data. | 376 Packing and unpacking of XDR data. |
|
| 330 | 377 |
|
| 331 | 378 |
|
| (...skipping 40 matching lines...) | | Loading... |
| 372 | 419 |
|
| 373 .. attribute:: format | 420 .. attribute:: format |
|
| 374 | 421 |
|
| 375 The format string used to construct this Struct object. | 422 The format string used to construct this Struct object. |
|
| 376 | 423 |
|
| 377 .. attribute:: size | 424 .. attribute:: size |
|
| 378 | 425 |
|
| 379 The calculated size of the struct (and hence of the bytes) corresponding | 426 The calculated size of the struct (and hence of the bytes) corresponding |
|
| 380 to :attr:`format`. | 427 to :attr:`format`. |
|
| 381 | 428 |
|
| OLD | NEW |
|---|