home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / a / array < prev   
Text File  |  1996-11-14  |  5KB  |  100 lines
  1. <TITLE>array -- Python library reference</TITLE>
  2. Prev: <A HREF="../w/whrandom" TYPE="Prev">whrandom</A>  
  3. Up: <A HREF="../m/miscellaneous_services" TYPE="Up">Miscellaneous Services</A>  
  4. Top: <A HREF="../t/top" TYPE="Top">Top</A>  
  5. <H1>5.4. Built-in Module <CODE>array</CODE></H1>
  6. This module defines a new object type which can efficiently represent
  7. an array of basic values: characters, integers, floating point
  8. numbers.  Arrays are sequence types and behave very much like lists,
  9. except that the type of objects stored in them is constrained.  The
  10. type is specified at object creation time by using a <DFN>type code</DFN>,
  11. which is a single character.  The following type codes are defined:
  12. <P>
  13. <DL>
  14. <DT><I>Typecode</I><DD><I>Type</I>  ---  <I>Minimal size in bytes</I>
  15. <P>
  16. <DT><CODE>'c'</CODE><DD>character  ---  1
  17. <DT><CODE>'b'</CODE><DD>signed integer  ---  1
  18. <DT><CODE>'h'</CODE><DD>signed integer  ---  2
  19. <DT><CODE>'i'</CODE><DD>signed integer  ---  2
  20. <DT><CODE>'l'</CODE><DD>signed integer  ---  4
  21. <DT><CODE>'f'</CODE><DD>floating point  ---  4
  22. <DT><CODE>'d'</CODE><DD>floating point  ---  8
  23. </DL>
  24. The actual representation of values is determined by the machine
  25. architecture (strictly speaking, by the C implementation).  The actual
  26. size can be accessed through the <VAR>itemsize</VAR> attribute.
  27. <P>
  28. See also built-in module <CODE>struct</CODE>.
  29. The module defines the following function:
  30. <P>
  31. <DL><DT><B>array</B> (<VAR>typecode</VAR>[, <VAR>initializer</VAR>]) -- function of module array<DD>
  32. Return a new array whose items are restricted by <VAR>typecode</VAR>, and
  33. initialized from the optional <VAR>initializer</VAR> value, which must be a
  34. list or a string.  The list or string is passed to the new array's
  35. <CODE>fromlist()</CODE> or <CODE>fromstring()</CODE> method (see below) to add
  36. initial items to the array.
  37. </DL>
  38. Array objects support the following data items and methods:
  39. <P>
  40. <DL><DT><B>typecode</B> -- data of module array<DD>
  41. The typecode character used to create the array.
  42. </DL>
  43. <DL><DT><B>itemsize</B> -- data of module array<DD>
  44. The length in bytes of one array item in the internal representation.
  45. </DL>
  46. <DL><DT><B>append</B> (<VAR>x</VAR>) -- function of module array<DD>
  47. Append a new item with value <VAR>x</VAR> to the end of the array.
  48. </DL>
  49. <DL><DT><B>byteswap</B> (<VAR>x</VAR>) -- function of module array<DD>
  50. ``Byteswap'' all items of the array.  This is only supported for
  51. integer values.  It is useful when reading data from a file written
  52. on a machine with a different byte order.
  53. </DL>
  54. <DL><DT><B>fromfile</B> (<VAR>f</VAR>, <VAR>n</VAR>) -- function of module array<DD>
  55. Read <VAR>n</VAR> items (as machine values) from the file object <VAR>f</VAR>
  56. and append them to the end of the array.  If less than <VAR>n</VAR> items
  57. are available, <CODE>EOFError</CODE> is raised, but the items that were
  58. available are still inserted into the array.  <VAR>f</VAR> must be a real
  59. built-in file object; something else with a <CODE>read()</CODE> method won't
  60. do.
  61. </DL>
  62. <DL><DT><B>fromlist</B> (<VAR>list</VAR>) -- function of module array<DD>
  63. Append items from the list.  This is equivalent to
  64. <CODE>for x in <VAR>list</VAR>: a.append(x)</CODE>
  65. except that if there is a type error, the array is unchanged.
  66. </DL>
  67. <DL><DT><B>fromstring</B> (<VAR>s</VAR>) -- function of module array<DD>
  68. Appends items from the string, interpreting the string as an
  69. array of machine values (i.e. as if it had been read from a
  70. file using the <CODE>fromfile()</CODE> method).
  71. </DL>
  72. <DL><DT><B>insert</B> (<VAR>i</VAR>, <VAR>x</VAR>) -- function of module array<DD>
  73. Insert a new item with value <VAR>x</VAR> in the array before position
  74. <VAR>i</VAR>.
  75. </DL>
  76. <DL><DT><B>tofile</B> (<VAR>f</VAR>) -- function of module array<DD>
  77. Write all items (as machine values) to the file object <VAR>f</VAR>.
  78. </DL>
  79. <DL><DT><B>tolist</B> () -- function of module array<DD>
  80. Convert the array to an ordinary list with the same items.
  81. </DL>
  82. <DL><DT><B>tostring</B> () -- function of module array<DD>
  83. Convert the array to an array of machine values and return the
  84. string representation (the same sequence of bytes that would
  85. be written to a file by the <CODE>tofile()</CODE> method.)
  86. </DL>
  87. When an array object is printed or converted to a string, it is
  88. represented as <CODE>array(<VAR>typecode</VAR>, <VAR>initializer</VAR>)</CODE>.  The
  89. <VAR>initializer</VAR> is omitted if the array is empty, otherwise it is a
  90. string if the <VAR>typecode</VAR> is <CODE>'c'</CODE>, otherwise it is a list of
  91. numbers.  The string is guaranteed to be able to be converted back to
  92. an array with the same type and value using reverse quotes
  93. (<CODE>``</CODE>).  Examples:
  94. <P>
  95. <UL COMPACT><CODE>array('l')<P>
  96. array('c', 'hello world')<P>
  97. array('l', [1, 2, 3, 4, 5])<P>
  98. array('d', [1.0, 2.0, 3.14])<P>
  99. </CODE></UL>
  100.