cpython-lru_cache-weakref: Doc/lib/libstruct.tex annotate

annotate Doc/lib/libstruct.tex @ 19283:b865cd5c1925 legacy-trunk

Added comments before recently added/assigned slots in the type object, so the backward compatibility issues will be easier to understand. I only added comments indicating additions and assignments back to Python 2.0.

author	Fred Drake <fdrake@acm.org>
date	Wed, 15 Aug 2001 18:32:33 +0000
parents	33b4357aebb8
children	2894458877c8

rev	line source
8918 acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8725 diff changeset	1 \section{\module{struct} ---
11224 905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	2 Interpret strings as packed binary data}
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8018 diff changeset	3 \declaremodule{builtin}{struct}
760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8018 diff changeset	4
760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8018 diff changeset	5 \modulesynopsis{Interpret strings as packed binary data.}
760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8018 diff changeset	6
11224 905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	7 \indexii{C}{structures}
905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	8 \indexiii{packing}{binary}{data}
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	9
11224 905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	10 This module performs conversions between Python values and C
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	11 structs represented as Python strings. It uses \dfn{format strings}
11224 905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	12 (explained below) as compact descriptions of the lay-out of the C
905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	13 structs and the intended conversion to/from Python values. This can
905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	14 be used in handling binary data stored in files or from network
905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	15 connections, among other sources.
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	16
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	17 The module defines the following exception and functions:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	18
7612 46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	19
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	20 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	21 Exception raised on various occasions; argument is a string
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	22 describing what is wrong.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	23 \end{excdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	24
9560 06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	25 \begin{funcdesc}{pack}{fmt, v1, v2, \textrm{\ldots}}
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	26 Return a string containing the values
9560 06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	27 \code{\var{v1}, \var{v2}, \textrm{\ldots}} packed according to the given
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	28 format. The arguments must match the values required by the format
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	29 exactly.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	30 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	31
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7694 diff changeset	32 \begin{funcdesc}{unpack}{fmt, string}
9560 06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	33 Unpack the string (presumably packed by \code{pack(\var{fmt},
06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	34 \textrm{\ldots})}) according to the given format. The result is a
06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	35 tuple even if it contains exactly one item. The string must contain
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	36 exactly the amount of data required by the format
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	37 (\code{len(\var{string})} must equal \code{calcsize(\var{fmt})}).
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	38 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	39
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	40 \begin{funcdesc}{calcsize}{fmt}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	41 Return the size of the struct (and hence of the string)
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	42 corresponding to the given format.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	43 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	44
9560 06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	45 Format characters have the following meaning; the conversion between
11224 905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	46 C and Python values should be obvious given their types:
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	47
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	48 \begin{tableiv}{c\|l\|l\|c}{samp}{Format}{C Type}{Python}{Notes}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	49 \lineiv{x}{pad byte}{no value}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	50 \lineiv{c}{\ctype{char}}{string of length 1}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	51 \lineiv{b}{\ctype{signed char}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	52 \lineiv{B}{\ctype{unsigned char}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	53 \lineiv{h}{\ctype{short}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	54 \lineiv{H}{\ctype{unsigned short}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	55 \lineiv{i}{\ctype{int}}{integer}{}
18069 8e187740aa96 Initial support for 'q' and 'Q' struct format codes: for now, only in Tim Peters <tim.peters@gmail.com> parents: 16226 diff changeset	56 \lineiv{I}{\ctype{unsigned int}}{long}{}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	57 \lineiv{l}{\ctype{long}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	58 \lineiv{L}{\ctype{unsigned long}}{long}{}
18069 8e187740aa96 Initial support for 'q' and 'Q' struct format codes: for now, only in Tim Peters <tim.peters@gmail.com> parents: 16226 diff changeset	59 \lineiv{q}{\ctype{long long}}{long}{(1)}
8e187740aa96 Initial support for 'q' and 'Q' struct format codes: for now, only in Tim Peters <tim.peters@gmail.com> parents: 16226 diff changeset	60 \lineiv{Q}{\ctype{unsigned long long}}{long}{(1)}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	61 \lineiv{f}{\ctype{float}}{float}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	62 \lineiv{d}{\ctype{double}}{float}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	63 \lineiv{s}{\ctype{char[]}}{string}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	64 \lineiv{p}{\ctype{char[]}}{string}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	65 \lineiv{P}{\ctype{void *}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	66 \end{tableiv}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	67
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	68 \noindent
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	69 Notes:
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	70
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	71 \begin{description}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	72 \item[(1)]
18069 8e187740aa96 Initial support for 'q' and 'Q' struct format codes: for now, only in Tim Peters <tim.peters@gmail.com> parents: 16226 diff changeset	73 The \character{q} and \character{Q} conversion codes are available in
8e187740aa96 Initial support for 'q' and 'Q' struct format codes: for now, only in Tim Peters <tim.peters@gmail.com> parents: 16226 diff changeset	74 native mode only if the platform C compiler supports C \ctype{long long},
18125 27dd9ec3162c Add a version annotation for the Q and q format codes. Fred Drake <fdrake@acm.org> parents: 18084 diff changeset	75 or, on Windows, \ctype{__int64}. They are always available in standard
18084 bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module. Tim Peters <tim.peters@gmail.com> parents: 18069 diff changeset	76 modes.
18125 27dd9ec3162c Add a version annotation for the Q and q format codes. Fred Drake <fdrake@acm.org> parents: 18084 diff changeset	77 \versionadded{2.2}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	78 \end{description}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11224 diff changeset	79
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	80
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	81 A format character may be preceded by an integral repeat count. For
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	82 example, the format string \code{'4h'} means exactly the same as
9560 06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	83 \code{'hhhh'}.
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	84
6167 9e432468f756 Ignore whitespace between formats (not internal to a count+format). Guido van Rossum <guido@python.org> parents: 5818 diff changeset	85 Whitespace characters between formats are ignored; a count and its
9e432468f756 Ignore whitespace between formats (not internal to a count+format). Guido van Rossum <guido@python.org> parents: 5818 diff changeset	86 format must not contain whitespace though.
9e432468f756 Ignore whitespace between formats (not internal to a count+format). Guido van Rossum <guido@python.org> parents: 5818 diff changeset	87
8725 f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	88 For the \character{s} format character, the count is interpreted as the
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	89 size of the string, not a repeat count like for the other format
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	90 characters; for example, \code{'10s'} means a single 10-byte string, while
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	91 \code{'10c'} means 10 characters. For packing, the string is
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	92 truncated or padded with null bytes as appropriate to make it fit.
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	93 For unpacking, the resulting string always has exactly the specified
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	94 number of bytes. As a special case, \code{'0s'} means a single, empty
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	95 string (while \code{'0c'} means 0 characters).
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	96
8725 f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	97 The \character{p} format character can be used to encode a Pascal
f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	98 string. The first byte is the length of the stored string, with the
f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	99 bytes of the string following. If count is given, it is used as the
f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	100 total number of bytes used, including the length byte. If the string
f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	101 passed in to \function{pack()} is too long, the stored representation
f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	102 is truncated. If the string is too short, padding is used to ensure
f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	103 that exactly enough bytes are used to satisfy the count.
f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	104
18084 bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module. Tim Peters <tim.peters@gmail.com> parents: 18069 diff changeset	105 For the \character{I}, \character{L}, \character{q} and \character{Q}
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module. Tim Peters <tim.peters@gmail.com> parents: 18069 diff changeset	106 format characters, the return value is a Python long integer.
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	107
9125 6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	108 For the \character{P} format character, the return value is a Python
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	109 integer or long integer, depending on the size needed to hold a
9560 06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	110 pointer when it has been cast to an integer type. A \NULL{} pointer will
06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	111 always be returned as the Python integer \code{0}. When packing pointer-sized
9125 6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	112 values, Python integer or long integer objects may be used. For
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	113 example, the Alpha and Merced processors use 64-bit pointer values,
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	114 meaning a Python long integer will be used to hold the pointer; other
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	115 platforms use 32-bit pointers and will use a Python integer.
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	116
11224 905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	117 By default, C numbers are represented in the machine's native format
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	118 and byte order, and properly aligned by skipping pad bytes if
11224 905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	119 necessary (according to the rules used by the C compiler).
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	120
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	121 Alternatively, the first character of the format string can be used to
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	122 indicate the byte order, size and alignment of the packed data,
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	123 according to the following table:
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	124
8018 011ae71fea96 Lighten up tables. Fred Drake <fdrake@acm.org> parents: 7877 diff changeset	125 \begin{tableiii}{c\|l\|l}{samp}{Character}{Byte order}{Size and alignment}
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	126 \lineiii{@}{native}{native}
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	127 \lineiii{=}{native}{standard}
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	128 \lineiii{<}{little-endian}{standard}
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	129 \lineiii{>}{big-endian}{standard}
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	130 \lineiii{!}{network (= big-endian)}{standard}
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	131 \end{tableiii}
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	132
8725 f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	133 If the first character is not one of these, \character{@} is assumed.
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	134
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	135 Native byte order is big-endian or little-endian, depending on the
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	136 host system. For example, Motorola and Sun processors are big-endian;
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	137 Intel and DEC processors are little-endian.
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	138
11224 905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	139 Native size and alignment are determined using the C compiler's
9560 06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	140 \keyword{sizeof} expression. This is always combined with native byte
06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	141 order.
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	142
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	143 Standard size and alignment are as follows: no alignment is required
18084 bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module. Tim Peters <tim.peters@gmail.com> parents: 18069 diff changeset	144 for any type (so you have to use pad bytes);
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module. Tim Peters <tim.peters@gmail.com> parents: 18069 diff changeset	145 \ctype{short} is 2 bytes;
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module. Tim Peters <tim.peters@gmail.com> parents: 18069 diff changeset	146 \ctype{int} and \ctype{long} are 4 bytes;
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module. Tim Peters <tim.peters@gmail.com> parents: 18069 diff changeset	147 \ctype{long long} (\ctype{__int64} on Windows) is 8 bytes;
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module. Tim Peters <tim.peters@gmail.com> parents: 18069 diff changeset	148 \ctype{float} and \ctype{double} are 32-bit and 64-bit
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module. Tim Peters <tim.peters@gmail.com> parents: 18069 diff changeset	149 IEEE floating point numbers, respectively.
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	150
9560 06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	151 Note the difference between \character{@} and \character{=}: both use
06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	152 native byte order, but the size and alignment of the latter is
06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	153 standardized.
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	154
8725 f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	155 The form \character{!} is available for those poor souls who claim they
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	156 can't remember whether network byte order is big-endian or
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	157 little-endian.
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	158
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	159 There is no way to indicate non-native byte order (force
8725 f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	160 byte-swapping); use the appropriate choice of \character{<} or
f7976e02b873 Document the 'p' format character. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	161 \character{>}.
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	162
9125 6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	163 The \character{P} format character is only available for the native
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	164 byte ordering (selected as the default or with the \character{@} byte
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	165 order character). The byte order character \character{=} chooses to
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	166 use little- or big-endian ordering based on the host system. The
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	167 struct module does not interpret this as native ordering, so the
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	168 \character{P} format is not available.
6cd93322b810 Patch by Greg Stein to document the 'P' flag. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	169
4843 38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	170 Examples (all using native byte order, size and alignment, on a
38ae2a0fc4f3 Document the new extensions. Guido van Rossum <guido@python.org> parents: 2609 diff changeset	171 big-endian machine):
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	172
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6875 diff changeset	173 \begin{verbatim}
4866 3960340a3252 Describe standard float/double support. Guido van Rossum <guido@python.org> parents: 4843 diff changeset	174 >>> from struct import *
3960340a3252 Describe standard float/double support. Guido van Rossum <guido@python.org> parents: 4843 diff changeset	175 >>> pack('hhl', 1, 2, 3)
16226 c7c404b35f33 Show '\011', '\012', and '\015' as '\t', '\n', '\r' in strings. Ka-Ping Yee <ping@zesty.ca> parents: 12223 diff changeset	176 '\x00\x01\x00\x02\x00\x00\x00\x03'
c7c404b35f33 Show '\011', '\012', and '\015' as '\t', '\n', '\r' in strings. Ka-Ping Yee <ping@zesty.ca> parents: 12223 diff changeset	177 >>> unpack('hhl', '\x00\x01\x00\x02\x00\x00\x00\x03')
4866 3960340a3252 Describe standard float/double support. Guido van Rossum <guido@python.org> parents: 4843 diff changeset	178 (1, 2, 3)
3960340a3252 Describe standard float/double support. Guido van Rossum <guido@python.org> parents: 4843 diff changeset	179 >>> calcsize('hhl')
3960340a3252 Describe standard float/double support. Guido van Rossum <guido@python.org> parents: 4843 diff changeset	180 8
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6875 diff changeset	181 \end{verbatim}
9560 06717e52068f Fix minor nit with respect to conversion. Fred Drake <fdrake@acm.org> parents: 9125 diff changeset	182
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	183 Hint: to align the end of a structure to the alignment requirement of
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	184 a particular type, end the format with the code for that type with a
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	185 repeat count of zero. For example, the format \code{'llh0l'}
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	186 specifies two pad bytes at the end, assuming longs are aligned on
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	187 4-byte boundaries. This only works when native size and alignment are
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18125 diff changeset	188 in effect; standard size and alignment does not enforce any alignment.
7612 46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	189
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	190 \begin{seealso}
11224 905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	191 \seemodule{array}{Packed binary storage of homogeneous data.}
905226471b4c Added additional index entries. Fred Drake <fdrake@acm.org> parents: 10642 diff changeset	192 \seemodule{xdrlib}{Packing and unpacking of XDR data.}
7612 46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	193 \end{seealso}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstruct.tex @ 19283:b865cd5c1925 legacy-trunk