Fred Drake | 3a0351c | 1998-04-04 07:23:21 +0000 | [diff] [blame] | 1 | \section{Built-in Module \module{array}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-array} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 3 | \bimodindex{array} |
| 4 | \index{arrays} |
| 5 | |
| 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}, |
| 11 | which is a single character. The following type codes are defined: |
| 12 | |
Fred Drake | ee60191 | 1998-04-11 20:53:03 +0000 | [diff] [blame^] | 13 | \begin{tableiii}{c|l|c}{code}{Type code}{C Type}{Minimum size in bytes} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 14 | \lineiii{'c'}{character}{1} |
| 15 | \lineiii{'b'}{signed integer}{1} |
Guido van Rossum | b0b8181 | 1997-01-03 19:20:52 +0000 | [diff] [blame] | 16 | \lineiii{'B'}{unsigned integer}{1} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 17 | \lineiii{'h'}{signed integer}{2} |
Guido van Rossum | b0b8181 | 1997-01-03 19:20:52 +0000 | [diff] [blame] | 18 | \lineiii{'H'}{unsigned integer}{2} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 19 | \lineiii{'i'}{signed integer}{2} |
Guido van Rossum | b0b8181 | 1997-01-03 19:20:52 +0000 | [diff] [blame] | 20 | \lineiii{'I'}{unsigned integer}{2} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 21 | \lineiii{'l'}{signed integer}{4} |
Guido van Rossum | b0b8181 | 1997-01-03 19:20:52 +0000 | [diff] [blame] | 22 | \lineiii{'L'}{unsigned integer}{4} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 23 | \lineiii{'f'}{floating point}{4} |
| 24 | \lineiii{'d'}{floating point}{8} |
| 25 | \end{tableiii} |
| 26 | |
| 27 | The actual representation of values is determined by the machine |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 28 | architecture (strictly speaking, by the \C{} implementation). The actual |
Guido van Rossum | b0b8181 | 1997-01-03 19:20:52 +0000 | [diff] [blame] | 29 | size can be accessed through the \var{itemsize} attribute. The values |
| 30 | stored for \code{'L'} and \code{'I'} items will be represented as |
| 31 | Python long integers when retrieved, because Python's plain integer |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 32 | type cannot represent the full range of \C{}'s unsigned (long) integers. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 33 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 34 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 35 | The module defines the following function and type object: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 36 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 37 | \begin{funcdesc}{array}{typecode\optional{, initializer}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 38 | Return a new array whose items are restricted by \var{typecode}, and |
| 39 | initialized from the optional \var{initializer} value, which must be a |
| 40 | list or a string. The list or string is passed to the new array's |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 41 | \method{fromlist()} or \method{fromstring()} method (see below) to add |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 42 | initial items to the array. |
| 43 | \end{funcdesc} |
| 44 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 45 | \begin{datadesc}{ArrayType} |
| 46 | Type object corresponding to the objects returned by |
| 47 | \function{array()}. |
| 48 | \end{datadesc} |
| 49 | |
| 50 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 51 | Array objects support the following data items and methods: |
| 52 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 53 | \begin{memberdesc}[array]{typecode} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 54 | The typecode character used to create the array. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 55 | \end{memberdesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 56 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 57 | \begin{memberdesc}[array]{itemsize} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 58 | The length in bytes of one array item in the internal representation. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 59 | \end{memberdesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 60 | |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 61 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 62 | \begin{methoddesc}[array]{append}{x} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 63 | Append a new item with value \var{x} to the end of the array. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 64 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 65 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 66 | \begin{methoddesc}[array]{buffer_info}{} |
Fred Drake | bef9b0b | 1997-12-29 19:33:45 +0000 | [diff] [blame] | 67 | Return a tuple \code{(\var{address}, \var{length})} giving the current |
Guido van Rossum | 8f06247 | 1997-08-14 19:50:37 +0000 | [diff] [blame] | 68 | memory address and the length in bytes of the buffer used to hold |
| 69 | array's contents. This is occasionally useful when working with |
| 70 | low-level (and inherently unsafe) I/O interfaces that require memory |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 71 | addresses, such as certain \cfunction{ioctl()} operations. The returned |
Guido van Rossum | 8f06247 | 1997-08-14 19:50:37 +0000 | [diff] [blame] | 72 | numbers are valid as long as the array exists and no length-changing |
| 73 | operations are applied to it. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 74 | \end{methoddesc} |
Guido van Rossum | 8f06247 | 1997-08-14 19:50:37 +0000 | [diff] [blame] | 75 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 76 | \begin{methoddesc}[array]{byteswap}{x} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 77 | ``Byteswap'' all items of the array. This is only supported for |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 78 | integer values. It is useful when reading data from a file written |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 79 | on a machine with a different byte order. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 80 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 81 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 82 | \begin{methoddesc}[array]{fromfile}{f, n} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 83 | Read \var{n} items (as machine values) from the file object \var{f} |
| 84 | and append them to the end of the array. If less than \var{n} items |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 85 | are available, \exception{EOFError} is raised, but the items that were |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 86 | available are still inserted into the array. \var{f} must be a real |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 87 | built-in file object; something else with a \method{read()} method won't |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 88 | do. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 89 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 90 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 91 | \begin{methoddesc}[array]{fromlist}{list} |
Guido van Rossum | 6c4f003 | 1995-03-07 10:14:09 +0000 | [diff] [blame] | 92 | Append items from the list. This is equivalent to |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 93 | \samp{for x in \var{list}:\ a.append(x)} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 94 | except that if there is a type error, the array is unchanged. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 95 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 96 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 97 | \begin{methoddesc}[array]{fromstring}{s} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 98 | Appends items from the string, interpreting the string as an |
| 99 | array of machine values (i.e. as if it had been read from a |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 100 | file using the \method{fromfile()} method). |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 101 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 102 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 103 | \begin{methoddesc}[array]{insert}{i, x} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 104 | Insert a new item with value \var{x} in the array before position |
| 105 | \var{i}. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 106 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 107 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 108 | \begin{methoddesc}[array]{read}{f, n} |
Fred Drake | 92e3194 | 1998-02-27 16:21:31 +0000 | [diff] [blame] | 109 | \deprecated {1.5.1} |
| 110 | {Use the \method{fromfile()} method.} |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 111 | Read \var{n} items (as machine values) from the file object \var{f} |
| 112 | and append them to the end of the array. If less than \var{n} items |
| 113 | are available, \exception{EOFError} is raised, but the items that were |
| 114 | available are still inserted into the array. \var{f} must be a real |
| 115 | built-in file object; something else with a \method{read()} method won't |
| 116 | do. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 117 | \end{methoddesc} |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 118 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 119 | \begin{methoddesc}[array]{reverse}{} |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 120 | Reverse the order of the items in the array. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 121 | \end{methoddesc} |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 122 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 123 | \begin{methoddesc}[array]{tofile}{f} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 124 | Write all items (as machine values) to the file object \var{f}. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 125 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 126 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 127 | \begin{methoddesc}[array]{tolist}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 128 | Convert the array to an ordinary list with the same items. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 129 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 130 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 131 | \begin{methoddesc}[array]{tostring}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 132 | Convert the array to an array of machine values and return the |
| 133 | string representation (the same sequence of bytes that would |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 134 | be written to a file by the \method{tofile()} method.) |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 135 | \end{methoddesc} |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 136 | |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 137 | \begin{methoddesc}[array]{write}{f} |
Fred Drake | 92e3194 | 1998-02-27 16:21:31 +0000 | [diff] [blame] | 138 | \deprecated {1.5.1} |
| 139 | {Use the \method{tofile()} method.} |
Fred Drake | 8a13525 | 1998-02-27 15:19:42 +0000 | [diff] [blame] | 140 | Write all items (as machine values) to the file object \var{f}. |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 141 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 142 | |
| 143 | When an array object is printed or converted to a string, it is |
| 144 | represented as \code{array(\var{typecode}, \var{initializer})}. The |
| 145 | \var{initializer} is omitted if the array is empty, otherwise it is a |
| 146 | string if the \var{typecode} is \code{'c'}, otherwise it is a list of |
| 147 | numbers. The string is guaranteed to be able to be converted back to |
| 148 | an array with the same type and value using reverse quotes |
| 149 | (\code{``}). Examples: |
| 150 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 151 | \begin{verbatim} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 152 | array('l') |
| 153 | array('c', 'hello world') |
| 154 | array('l', [1, 2, 3, 4, 5]) |
| 155 | array('d', [1.0, 2.0, 3.14]) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 156 | \end{verbatim} |
Fred Drake | dd1f52b | 1998-04-03 03:35:24 +0000 | [diff] [blame] | 157 | |
| 158 | |
| 159 | \begin{seealso} |
| 160 | \seemodule{struct}{Packing and unpacking of heterogeneous binary data.} |
| 161 | \end{seealso} |