home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / s / struct < prev    next >
Encoding:
Text File  |  1996-11-14  |  3.3 KB  |  72 lines
  1. <TITLE>struct -- Python library reference</TITLE>
  2. Prev: <A HREF="../r/regsub" TYPE="Prev">regsub</A>  
  3. Up: <A HREF="../s/string_services" TYPE="Up">String Services</A>  
  4. Top: <A HREF="../t/top" TYPE="Top">Top</A>  
  5. <H1>4.4. Built-in Module <CODE>struct</CODE></H1>
  6. This module performs conversions between Python values and C
  7. structs represented as Python strings.  It uses <DFN>format strings</DFN>
  8. (explained below) as compact descriptions of the lay-out of the C
  9. structs and the intended conversion to/from Python values.
  10. <P>
  11. See also built-in module <CODE>array</CODE>.
  12. The module defines the following exception and functions:
  13. <P>
  14. <DL><DT><B>error</B> -- exception of module struct<DD>
  15. Exception raised on various occasions; argument is a string
  16. describing what is wrong.
  17. </DL>
  18. <DL><DT><B>pack</B> (<VAR>fmt</VAR>, <VAR>v1</VAR>, <VAR>v2</VAR>, @varr@vardots) -- function of module struct<DD>
  19. Return a string containing the values
  20. <CODE><VAR>v1</VAR>, <VAR>v2</VAR>, <R>...</R></CODE> packed according to the given
  21. format.  The arguments must match the values required by the format
  22. exactly.
  23. </DL>
  24. <DL><DT><B>unpack</B> (<VAR>fmt</VAR>, <VAR>string</VAR>) -- function of module struct<DD>
  25. Unpack the string (presumably packed by <CODE>pack(<VAR>fmt</VAR>, <R>...</R>)</CODE>)
  26. according to the given format.  The result is a tuple even if it
  27. contains exactly one item.  The string must contain exactly the
  28. amount of data required by the format (i.e.  <CODE>len(<VAR>string</VAR>)</CODE> must
  29. equal <CODE>calcsize(<VAR>fmt</VAR>)</CODE>).
  30. </DL>
  31. <DL><DT><B>calcsize</B> (<VAR>fmt</VAR>) -- function of module struct<DD>
  32. Return the size of the struct (and hence of the string)
  33. corresponding to the given format.
  34. </DL>
  35. Format characters have the following meaning; the conversion between C
  36. and Python values should be obvious given their types:
  37. <P>
  38. <DL>
  39. <DT><I>Format</I><DD><I>C</I>  ---  <I>Python</I>
  40. <P>
  41. <DT>`<SAMP>x</SAMP>'<DD>pad byte  ---  no value
  42. <DT>`<SAMP>c</SAMP>'<DD>char  ---  string of length 1
  43. <DT>`<SAMP>b</SAMP>'<DD>signed char  ---  integer
  44. <DT>`<SAMP>h</SAMP>'<DD>short  ---  integer
  45. <DT>`<SAMP>i</SAMP>'<DD>int  ---  integer
  46. <DT>`<SAMP>l</SAMP>'<DD>long  ---  integer
  47. <DT>`<SAMP>f</SAMP>'<DD>float  ---  float
  48. <DT>`<SAMP>d</SAMP>'<DD>double  ---  float
  49. </DL>
  50. A format character may be preceded by an integral repeat count; e.g.
  51. the format string <CODE>'4h'</CODE> means exactly the same as <CODE>'hhhh'</CODE>.
  52. <P>
  53. C numbers are represented in the machine's native format and byte
  54. order, and properly aligned by skipping pad bytes if necessary
  55. (according to the rules used by the C compiler).
  56. <P>
  57. Examples (all on a big-endian machine):
  58. <P>
  59. <UL COMPACT><CODE>pack('hhl', 1, 2, 3) == '\000\001\000\002\000\000\000\003'<P>
  60. unpack('hhl', '\000\001\000\002\000\000\000\003') == (1, 2, 3)<P>
  61. calcsize('hhl') == 8<P>
  62. </CODE></UL>
  63. Hint: to align the end of a structure to the alignment requirement of
  64. a particular type, end the format with the code for that type with a
  65. repeat count of zero, e.g. the format <CODE>'llh0l'</CODE> specifies two
  66. pad bytes at the end, assuming longs are aligned on 4-byte boundaries.
  67. <P>
  68. (More format characters are planned, e.g. <CODE>'s'</CODE> for character
  69. arrays, upper case for unsigned variants, and a way to specify the
  70. byte order, which is useful for [de]constructing network packets and
  71. reading/writing portable binary file formats like TIFF and AIFF.)
  72.