Commit 50b804dc authored by Fred Drake's avatar Fred Drake

Fix minor nit with respect to conversion.

Update some logical markup.
parent caa3379c
...@@ -6,9 +6,9 @@ ...@@ -6,9 +6,9 @@
\indexii{C@\C{}}{structures} \indexii{C@\C{}}{structures}
This module performs conversions between Python values and C This module performs conversions between Python values and \C{}
structs represented as Python strings. It uses \dfn{format strings} structs represented as Python strings. It uses \dfn{format strings}
(explained below) as compact descriptions of the lay-out of the C (explained below) as compact descriptions of the lay-out of the \C{}
structs and the intended conversion to/from Python values. structs and the intended conversion to/from Python values.
The module defines the following exception and functions: The module defines the following exception and functions:
...@@ -19,19 +19,19 @@ The module defines the following exception and functions: ...@@ -19,19 +19,19 @@ The module defines the following exception and functions:
describing what is wrong. describing what is wrong.
\end{excdesc} \end{excdesc}
\begin{funcdesc}{pack}{fmt, v1, v2, {\rm \ldots}} \begin{funcdesc}{pack}{fmt, v1, v2, \textrm{\ldots}}
Return a string containing the values Return a string containing the values
\code{\var{v1}, \var{v2}, {\rm \ldots}} packed according to the given \code{\var{v1}, \var{v2}, \textrm{\ldots}} packed according to the given
format. The arguments must match the values required by the format format. The arguments must match the values required by the format
exactly. exactly.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{unpack}{fmt, string} \begin{funcdesc}{unpack}{fmt, string}
Unpack the string (presumably packed by \code{pack(\var{fmt}, {\rm \ldots})}) Unpack the string (presumably packed by \code{pack(\var{fmt},
according to the given format. The result is a tuple even if it \textrm{\ldots})}) according to the given format. The result is a
contains exactly one item. The string must contain exactly the tuple even if it contains exactly one item. The string must contain
amount of data required by the format (i.e. \code{len(\var{string})} must exactly the amount of data required by the format (i.e.
equal \code{calcsize(\var{fmt})}). \code{len(\var{string})} must equal \code{calcsize(\var{fmt})}).
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{calcsize}{fmt} \begin{funcdesc}{calcsize}{fmt}
...@@ -39,29 +39,30 @@ The module defines the following exception and functions: ...@@ -39,29 +39,30 @@ The module defines the following exception and functions:
corresponding to the given format. corresponding to the given format.
\end{funcdesc} \end{funcdesc}
Format characters have the following meaning; the conversion between C Format characters have the following meaning; the conversion between
and Python values should be obvious given their types: \C{} and Python values should be obvious given their types:
\begin{tableiii}{c|l|l}{samp}{Format}{C Type}{Python} \begin{tableiii}{c|l|l}{samp}{Format}{C Type}{Python}
\lineiii{x}{pad byte}{no value} \lineiii{x}{pad byte}{no value}
\lineiii{c}{char}{string of length 1} \lineiii{c}{\ctype{char}}{string of length 1}
\lineiii{b}{signed char}{integer} \lineiii{b}{\ctype{signed char}}{integer}
\lineiii{B}{unsigned char}{integer} \lineiii{B}{\ctype{unsigned char}}{integer}
\lineiii{h}{short}{integer} \lineiii{h}{\ctype{short}}{integer}
\lineiii{H}{unsigned short}{integer} \lineiii{H}{\ctype{unsigned short}}{integer}
\lineiii{i}{int}{integer} \lineiii{i}{\ctype{int}}{integer}
\lineiii{I}{unsigned int}{integer} \lineiii{I}{\ctype{unsigned int}}{integer}
\lineiii{l}{long}{integer} \lineiii{l}{\ctype{long}}{integer}
\lineiii{L}{unsigned long}{integer} \lineiii{L}{\ctype{unsigned long}}{integer}
\lineiii{f}{float}{float} \lineiii{f}{\ctype{float}}{float}
\lineiii{d}{double}{float} \lineiii{d}{\ctype{double}}{float}
\lineiii{s}{char[]}{string} \lineiii{s}{\ctype{char[]}}{string}
\lineiii{p}{char[]}{string} \lineiii{p}{\ctype{char[]}}{string}
\lineiii{P}{void *}{integer} \lineiii{P}{\ctype{void *}}{integer}
\end{tableiii} \end{tableiii}
A format character may be preceded by an integral repeat count; e.g.\ A format character may be preceded by an integral repeat count;
the format string \code{'4h'} means exactly the same as \code{'hhhh'}. e.g.\ the format string \code{'4h'} means exactly the same as
\code{'hhhh'}.
Whitespace characters between formats are ignored; a count and its Whitespace characters between formats are ignored; a count and its
format must not contain whitespace though. format must not contain whitespace though.
...@@ -88,16 +89,16 @@ value is a Python long integer. ...@@ -88,16 +89,16 @@ value is a Python long integer.
For the \character{P} format character, the return value is a Python For the \character{P} format character, the return value is a Python
integer or long integer, depending on the size needed to hold a integer or long integer, depending on the size needed to hold a
pointer when it has been cast to an integer type. A NULL pointer will pointer when it has been cast to an integer type. A \NULL{} pointer will
always be returned as the Python integer 0. When packing pointer-sized always be returned as the Python integer \code{0}. When packing pointer-sized
values, Python integer or long integer objects may be used. For values, Python integer or long integer objects may be used. For
example, the Alpha and Merced processors use 64-bit pointer values, example, the Alpha and Merced processors use 64-bit pointer values,
meaning a Python long integer will be used to hold the pointer; other meaning a Python long integer will be used to hold the pointer; other
platforms use 32-bit pointers and will use a Python integer. platforms use 32-bit pointers and will use a Python integer.
By default, C numbers are represented in the machine's native format By default, \C{} numbers are represented in the machine's native format
and byte order, and properly aligned by skipping pad bytes if and byte order, and properly aligned by skipping pad bytes if
necessary (according to the rules used by the C compiler). necessary (according to the rules used by the \C{} compiler).
Alternatively, the first character of the format string can be used to Alternatively, the first character of the format string can be used to
indicate the byte order, size and alignment of the packed data, indicate the byte order, size and alignment of the packed data,
...@@ -117,16 +118,19 @@ Native byte order is big-endian or little-endian, depending on the ...@@ -117,16 +118,19 @@ Native byte order is big-endian or little-endian, depending on the
host system (e.g. Motorola and Sun are big-endian; Intel and DEC are host system (e.g. Motorola and Sun are big-endian; Intel and DEC are
little-endian). little-endian).
Native size and alignment are determined using the C compiler's sizeof Native size and alignment are determined using the \C{} compiler's
expression. This is always combined with native byte order. \keyword{sizeof} expression. This is always combined with native byte
order.
Standard size and alignment are as follows: no alignment is required Standard size and alignment are as follows: no alignment is required
for any type (so you have to use pad bytes); short is 2 bytes; int and for any type (so you have to use pad bytes); \ctype{short} is 2 bytes;
long are 4 bytes. Float and double are 32-bit and 64-bit IEEE floating \ctype{int} and \ctype{long} are 4 bytes. \ctype{float} and
point numbers, respectively. \ctype{double} are 32-bit and 64-bit IEEE floating point numbers,
respectively.
Note the difference between \character{@} and \character{=}: both use native Note the difference between \character{@} and \character{=}: both use
byte order, but the size and alignment of the latter is standardized. native byte order, but the size and alignment of the latter is
standardized.
The form \character{!} is available for those poor souls who claim they The form \character{!} is available for those poor souls who claim they
can't remember whether network byte order is big-endian or can't remember whether network byte order is big-endian or
...@@ -156,7 +160,7 @@ big-endian machine): ...@@ -156,7 +160,7 @@ big-endian machine):
8 8
>>> >>>
\end{verbatim} \end{verbatim}
%
Hint: to align the end of a structure to the alignment requirement of Hint: to align the end of a structure to the alignment requirement of
a particular type, end the format with the code for that type with a a particular type, end the format with the code for that type with a
repeat count of zero, e.g.\ the format \code{'llh0l'} specifies two repeat count of zero, e.g.\ the format \code{'llh0l'} specifies two
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment