15.4 The array Module

The array module supplies a type, also called array, whose instances are mutable sequences, like lists. An array a is a one-dimensional sequence whose items can be only characters, or only numbers of one specific numeric type that is fixed when a is created.

The extension module Numeric, covered later in this chapter, also supplies a type called array that is far more powerful than array.array. For advanced array operations and multidimensional arrays, I recommend Numeric even if your array elements are not numbers.

array.array is a simple type, whose main advantage is that, compared to a list, it can save memory to hold objects all of the same (numeric or character) type. An array object a has a one-character read-only attribute a.typecode, set when a is created, that gives the type of a's items. Table 15-2 shows the possible type codes for array.

Table 15-2. Type codes for the array module

Type code	C type	Python type	Minimum size
'c'	char	str (length 1)	1 byte
'b'	char	int	1 byte
'B'	unsigned char	int	1 byte
'h'	short	int	2 bytes
'H'	unsigned short	int	2 bytes
'i'	int	int	2 bytes
'I'	unsigned	long	2 bytes
'l'	long	int	4 bytes
'L'	unsigned long	long	4 bytes
'f'	float	float	4 bytes
'd'	double	float	8 bytes

The size in bytes of each item may be larger than the minimum, depending on the machine's architecture, and is available as the read-only attribute a.itemsize. Module array supplies just one function, a factory function called array.

array(typecode,init='')

Creates and returns an array object a with the given typecode. init can be a plain string whose length is a multiple of itemsize; the string's bytes, interpreted as machine values, directly initialize a's items. Alternatively, init can be a list (of characters when typecode is 'c', otherwise of numbers): each item of the list initializes one item of a.

Array objects expose all the methods and operations of mutable sequences, as covered in Chapter 4, except method sort. Concatenation (with both + and extend) and assignment to slices require both operands to be arrays with the same type code (i.e., there is no implicit coercion between sequences). In addition to the methods of mutable sequences, an array object a also exposes the following methods.

a.byteswap(  )

Swaps the byte order of each item of a.

a.fromfile(f,n)

Reads n items, taken as machine values, from file object f, and appends the items to a. Note that f should be open for reading in binary mode, for example with mode 'rb'. When less than n items are available in f, fromfile raises EOFError after appending the items that are available.

a.fromlist(L)

Appends to a all items of list L.

a.fromstring(s)

Appends to a the bytes, interpreted as machine values, of string s. len(s) must be a multiple of a.itemsize.

a.tofile(f)

Writes all items of a, taken as machine values, to file object f. Note that f should be open for reading in binary mode, for example with mode 'rb'.

a.tolist(  )

Creates and returns a list object with the same items as a.

a.tostring(  )

Returns the string with the bytes from all items of a, taken as machine values. For any a, len(a.tostring( )) always equals len(a)*a.itemsize. f.write(a.tostring( )) is the same as a.tofile(f).