Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{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 | |
| 13 | \begin{tableiii}{|c|c|c|}{code}{Typecode}{Type}{Minimal size in bytes} |
| 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 |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +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 |
| 32 | type can't 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 | See also built-in module \code{struct}. |
Fred Drake | 4f496cc | 1997-12-16 04:08:24 +0000 | [diff] [blame] | 35 | \refbimodindex{struct} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 36 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 37 | The module defines the following function: |
| 38 | |
| 39 | \renewcommand{\indexsubitem}{(in module array)} |
| 40 | |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 41 | \begin{funcdesc}{array}{typecode\optional{\, initializer}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 42 | Return a new array whose items are restricted by \var{typecode}, and |
| 43 | initialized from the optional \var{initializer} value, which must be a |
| 44 | list or a string. The list or string is passed to the new array's |
| 45 | \code{fromlist()} or \code{fromstring()} method (see below) to add |
| 46 | initial items to the array. |
| 47 | \end{funcdesc} |
| 48 | |
| 49 | Array objects support the following data items and methods: |
| 50 | |
| 51 | \begin{datadesc}{typecode} |
| 52 | The typecode character used to create the array. |
| 53 | \end{datadesc} |
| 54 | |
| 55 | \begin{datadesc}{itemsize} |
| 56 | The length in bytes of one array item in the internal representation. |
| 57 | \end{datadesc} |
| 58 | |
| 59 | \begin{funcdesc}{append}{x} |
| 60 | Append a new item with value \var{x} to the end of the array. |
| 61 | \end{funcdesc} |
| 62 | |
Guido van Rossum | 8f06247 | 1997-08-14 19:50:37 +0000 | [diff] [blame] | 63 | \begin{funcdesc}{buffer_info}{} |
Fred Drake | bef9b0b | 1997-12-29 19:33:45 +0000 | [diff] [blame] | 64 | Return a tuple \code{(\var{address}, \var{length})} giving the current |
Guido van Rossum | 8f06247 | 1997-08-14 19:50:37 +0000 | [diff] [blame] | 65 | memory address and the length in bytes of the buffer used to hold |
| 66 | array's contents. This is occasionally useful when working with |
| 67 | low-level (and inherently unsafe) I/O interfaces that require memory |
| 68 | addresses, such as certain \code{ioctl} operations. The returned |
| 69 | numbers are valid as long as the array exists and no length-changing |
| 70 | operations are applied to it. |
| 71 | \end{funcdesc} |
| 72 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 73 | \begin{funcdesc}{byteswap}{x} |
| 74 | ``Byteswap'' all items of the array. This is only supported for |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 75 | 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] | 76 | on a machine with a different byte order. |
| 77 | \end{funcdesc} |
| 78 | |
| 79 | \begin{funcdesc}{fromfile}{f\, n} |
| 80 | Read \var{n} items (as machine values) from the file object \var{f} |
| 81 | and append them to the end of the array. If less than \var{n} items |
| 82 | are available, \code{EOFError} is raised, but the items that were |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 83 | available are still inserted into the array. \var{f} must be a real |
| 84 | built-in file object; something else with a \code{read()} method won't |
| 85 | do. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 86 | \end{funcdesc} |
| 87 | |
| 88 | \begin{funcdesc}{fromlist}{list} |
Guido van Rossum | 6c4f003 | 1995-03-07 10:14:09 +0000 | [diff] [blame] | 89 | Append items from the list. This is equivalent to |
| 90 | \code{for x in \var{list}:\ a.append(x)} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 91 | except that if there is a type error, the array is unchanged. |
| 92 | \end{funcdesc} |
| 93 | |
| 94 | \begin{funcdesc}{fromstring}{s} |
| 95 | Appends items from the string, interpreting the string as an |
| 96 | array of machine values (i.e. as if it had been read from a |
| 97 | file using the \code{fromfile()} method). |
| 98 | \end{funcdesc} |
| 99 | |
| 100 | \begin{funcdesc}{insert}{i\, x} |
| 101 | Insert a new item with value \var{x} in the array before position |
| 102 | \var{i}. |
| 103 | \end{funcdesc} |
| 104 | |
| 105 | \begin{funcdesc}{tofile}{f} |
| 106 | Write all items (as machine values) to the file object \var{f}. |
| 107 | \end{funcdesc} |
| 108 | |
| 109 | \begin{funcdesc}{tolist}{} |
| 110 | Convert the array to an ordinary list with the same items. |
| 111 | \end{funcdesc} |
| 112 | |
| 113 | \begin{funcdesc}{tostring}{} |
| 114 | Convert the array to an array of machine values and return the |
| 115 | string representation (the same sequence of bytes that would |
| 116 | be written to a file by the \code{tofile()} method.) |
| 117 | \end{funcdesc} |
| 118 | |
| 119 | When an array object is printed or converted to a string, it is |
| 120 | represented as \code{array(\var{typecode}, \var{initializer})}. The |
| 121 | \var{initializer} is omitted if the array is empty, otherwise it is a |
| 122 | string if the \var{typecode} is \code{'c'}, otherwise it is a list of |
| 123 | numbers. The string is guaranteed to be able to be converted back to |
| 124 | an array with the same type and value using reverse quotes |
| 125 | (\code{``}). Examples: |
| 126 | |
| 127 | \bcode\begin{verbatim} |
| 128 | array('l') |
| 129 | array('c', 'hello world') |
| 130 | array('l', [1, 2, 3, 4, 5]) |
| 131 | array('d', [1.0, 2.0, 3.14]) |
| 132 | \end{verbatim}\ecode |