8.6. array— Arrays eficientes de valores numéricos

Esse módulo define um tipo de objeto que pode representar compactamente um vetor de valores básicos: caracteres, inteiros, números de ponto flutuante. Vetores são tipos de sequência e funcionam bem parecidamente com listas, porém o tipo dos objetos armazenados é restringido. O tipo é especificado na criação do objeto usando um type code, que é um único caractere. Os seguintes type codes são definidos:

Type code	Tipo em C	Tipo em Python	Tamanho mínimo em bytes
'c'	char	character	1
'b'	signed char	int	1
'B'	unsigned char	int	1
'u'	Py_UNICODE	Caractere unicode	2 (see note)
'h'	signed short	int	2
'H'	unsigned short	int	2
'i'	signed int	int	2
'I'	unsigned int	extenso, comprido	2
'l'	signed long	int	4
'L'	unsigned long	extenso, comprido	4
'f'	float	float	4
'd'	double	float	8

Nota

The 'u' typecode corresponds to Python’s unicode character. On narrow Unicode builds this is 2-bytes, on wide builds this is 4-bytes.

The actual representation of values is determined by the machine architecture (strictly speaking, by the C implementation). The actual size can be accessed through the itemsize attribute. The values stored for 'L' and 'I' items will be represented as Python long integers when retrieved, because Python’s plain integer type cannot represent the full range of C’s unsigned (long) integers.

O módulo define o seguinte tipo:

class array.array(typecode[, initializer])

A new array whose items are restricted by typecode, and initialized from the optional initializer value, which must be a list, string, or iterable over elements of the appropriate type.

Alterado na versão 2.4: Formerly, only lists or strings were accepted.

If given a list or string, the initializer is passed to the new array’s fromlist(), fromstring(), or fromunicode() method (see below) to add initial items to the array. Otherwise, the iterable initializer is passed to the extend() method.

array.ArrayType

Obsolete alias for array.

Array objects support the ordinary sequence operations of indexing, slicing, concatenation, and multiplication. When using slice assignment, the assigned value must be an array object with the same type code; in all other cases, TypeError is raised. Array objects also implement the buffer interface, and may be used wherever buffer objects are supported.

Os seguintes itens e métodos também são suportados:

array.typecode

O caracter typecode usado para criar o array

array.itemsize

O tamanho em bytes de um item do array em representação interna

array.append(x)

Adiciona um novo item com valor x ao final do array.

array.buffer_info()

Retorna uma tupla (address, length) com o endereço corrente da memória e o tamanho em elementos do buffer usado para armazenar conteúdos do array. O tamanho do buffer da memória em bytes pode ser computado como array.buffer_info()[1] * array.itemsize. Isso é ocasionalmente útil quando se está trabalhando com interfaces I/O de baixo nível (inerentemente inseguras) que precisam de endereços de memória, como algumas operações ioctl(). Os números retornados são válidos enquanto o array existir e nenhuma operação de alteração de tamanho for aplicada a ele.

Nota

Quando se está usando arrays de código escrito em C ou C++ (o único jeito efetivo de usar essa informação), faz mais sentido usar a interface do buffer suportada pelos arrays. Esse método é mantido para retrocompatibilidade e deve ser evitado em código novo. A interface de buffers está documentada em Buffers and Memoryview Objects.

array.byteswap()

“Byteswap” all items of the array. This is only supported for values which are 1, 2, 4, or 8 bytes in size; for other types of values, RuntimeError is raised. It is useful when reading data from a file written on a machine with a different byte order.

array.count(x)

Retorna a quantidade de ocorrências de x no array.

array.extend(iterable)

Acrescenta os itens em iterable ao final do array. Se iterable for outro array, ele deve ter exatamente o mesmo type code; senão, ocorrerá um TypeError. Se iterable não for um array, ele deve ser iterável e seus elementos devem ser do tipo correto para ser acrescentado ao array,

Alterado na versão 2.4: Formerly, the argument could only be another array.

array.fromfile(f, n)

Read n items (as machine values) from the file object f and append them to the end of the array. If less than n items are available, EOFError is raised, but the items that were available are still inserted into the array. f must be a real built-in file object; something else with a read() method won’t do.

array.fromlist(list)

Append items from the list. This is equivalent to for x in list: a.append(x) except that if there is a type error, the array is unchanged.

array.fromstring(s)

Adiciona itens da string, interpretando a string como um array (como se tivesse sido lido de um arquivo usando o método fromfile()).

array.fromunicode(s)

Extends this array with data from the given unicode string. The array must be a type 'u' array; otherwise a ValueError is raised. Use array.fromstring(unicodestring.encode(enc)) to append Unicode data to an array of some other type.

array.index(x)

Return the smallest i such that i is the index of the first occurrence of x in the array.

array.insert(i, x)

Insert a new item with value x in the array before position i. Negative values are treated as being relative to the end of the array.

array.pop([i])

Removes the item with the index i from the array and returns it. The optional argument defaults to -1, so that by default the last item is removed and returned.

array.read(f, n)

Obsoleto desde a versão 1.5.1: Use the fromfile() method.

Read n items (as machine values) from the file object f and append them to the end of the array. If less than n items are available, EOFError is raised, but the items that were available are still inserted into the array. f must be a real built-in file object; something else with a read() method won’t do.

array.remove(x)

Remove a primeira ocorrência de x da array.

array.reverse()

Inverte a ordem dos itens na array.

array.tofile(f)

Write all items (as machine values) to the file object f.

array.tolist()

Converte a array para uma lista comum com os mesmos itens.

array.tostring()

Convert the array to an array of machine values and return the string representation (the same sequence of bytes that would be written to a file by the tofile() method.)

array.tounicode()

Convert the array to a unicode string. The array must be a type 'u' array; otherwise a ValueError is raised. Use array.tostring().decode(enc) to obtain a unicode string from an array of some other type.

array.write(f)

Obsoleto desde a versão 1.5.1: Use the tofile() method.

Write all items (as machine values) to the file object f.

When an array object is printed or converted to a string, it is represented as array(typecode, initializer). The initializer is omitted if the array is empty, otherwise it is a string if the typecode is 'c', otherwise it is a list of numbers. The string is guaranteed to be able to be converted back to an array with the same type and value using eval(), so long as the array class has been imported using from array import array. Examples:

array('l')
array('c', 'hello world')
array('u', u'hello \u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])

Ver também

Modulo struct

Packing and unpacking of heterogeneous binary data.

Módulo xdrlib

Packing and unpacking of External Data Representation (XDR) data as used in some remote procedure call systems.

The Numerical Python Documentation

The Numeric Python extension (NumPy) defines another array type; see http://www.numpy.org/ for further information about Numerical Python.