array— Arrays eficientes de valores numéricos

---

Esse módulo define um tipo de objeto que pode representar compactamente um array de valores básicos: caracteres, inteiros, números de ponto flutuante. Arrays 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	Notas
'b'	signed char	int	1
'B'	unsigned char	int	1
'u'	Py_UNICODE	Caractere unicode	2	(1)
'h'	signed short	int	2
'H'	unsigned short	int	2
'i'	signed int	int	2
'I'	unsigned int	int	2
'l'	signed long	int	4
'L'	unsigned long	int	4
'q'	signed long long	int	8
'Q'	unsigned long long	int	8
'f'	float	float	4
'd'	double	float	8

Notas:

1. O 'u' corresponde ao obsoleto caractere unicode (Py_UNICODE que é wchar_t). Dependendo da plataforma, pode ser de 16 bits ou 32 bits.

   O 'u' será removido junto com o resto da Py_UNICODE API.

   Deprecated since version 3.3, will be removed in version 4.0.

A representação dos valores é definida pela arquitetura da máquina, mais especificamente da implementação do C. O tamanho real pode ser acessado pelo atributo itemsize

O módulo define o seguinte tipo:

class array.array(typecode[, initializer])

Um novo array cujos itens são restritos pelo type code e inicializados pelo valor opcional initializer, que deve ser uma lista, um bytes-like object, ou outro elementos iterável do tipo apropriado.

Se passado uma lista ou string, o inicializador é passado para os métodos fromlist(), frombytes(), ou fromunicode() (ver abaixo) do novo array para adicionar itens iniciais ao array. Caso contrário, o inicializador iterável é passado para o método extend().

array.typecodes

String com todos os types codes disponíveis.

Objetos array tem suporte para as operações de sequência comuns: indexação, fatiamento, concatenação, e multiplicação. Quando usando a atribuição de fatias, o valor associado deve ser um objeto array com o mesmo código de tipo; caso contrário , TypeError é levantada. Objetos array também implementam a interface buffer, e também podem ser usados em qualquer lugar onde bytes-like objects é permitido.

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

array.typecode

O caractere 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 Protocolo de Buffer.

array.byteswap()

“Byteswap” todos os itens do vetor. Isso é somente suportado para valores de 1, 2, 4 ou 8 bytes de tamanho; para outros tipos de valores é levantada RuntimeError . Isso é útil quando estamos lendo dados de um arquivo para serem escritos em um arquivo de outra máquina de ordem de bytes diferente.

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,

array.frombytes(s)

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

Novo na versão 3.2: fromstring() for renomeado para frombytes() para maior clareza.

array.fromfile(f, n)

Lê n itens (como valores de máquinas) do objeto arquivo f e adiciona-os ao fim do vetor. Se estão disponíveis menos de n itens, EOFError é levantada, mas os itens disponíveis ainda são inseridos ao final do vetor. f deve realmente ser um objeto arquivo; qualquer outra coisa com um método read() não vai funcionar.

array.fromlist(list)

Adiciona itens de list. Isso é equivalente a for x in list: a.append(x) exceto que se ocorrer um errro de tipo, o vetor não é alterado.

array.fromstring()

Alias deprecado para frombytes().

Deprecated since version 3.2, will be removed in version 3.9.

array.fromunicode(s)

Estende este vetor com os dados da strind unicode fornecida. O vetor deve ser do tipo 'u'; aso contrário uma ValueError será levantada. Use array.frombytes(unicodestring.encode(enc)) para adicionar dados Unicode para um vetor de outros tipos de dados.

array.index(x)

Retorna o menor i em que i é o índice da primeira ocorrência de x no vetor.

array.insert(i, x)

Insere um novo item com o x no vetor antes da posição i. Valores negativos são tratados como sendo em relação ao fim do vetor.

array.pop([i])

Remove o item com o índice i do vetor e retorna este item. O valor padrão do argumento é -1, assim por padrão o último item é removido e retornado.

array.remove(x)

Remove a primeira ocorrência de x da array.

array.reverse()

Inverte a ordem dos itens na array.

array.tobytes()

Devolve os itens do vetor como um vetor de valores de máquina com a representação em bytes (a mesma sequência de bytes que seria escrita pelo método tofile().)

Novo na versão 3.2: tostring() foi nomeada para tobytes() para maior clareza.

array.tofile(f)

Escreve todos os itens (como valores de máquinas) para o objeto arquivo f.

array.tolist()

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

array.tostring()

Deprecated alias for tobytes().

Deprecated since version 3.2, will be removed in version 3.9.

array.tounicode()

Devolve os itens do vetor como uma string unicode. O vetor deve ser do tipo 'u'; caso contrário ValueError é levantada. Use array.tobytes().decode(enc) para obter uma string unicode de um vetor de outros tipos.

Quando um vetor é exibido ou convertido para uma string, é representado como array(typecode, initializer). O initializer é omitido se o vetor estiver vazio, caso contrário será uma string se typecode for 'u', se não será uma lista de números. É garantido que será possível uma conversão da string de volta para um vetor com o mesmo tipo e valor usando eval(), contanto que a classe array tenha sido importada usando from array import array. Exemplos:

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

Ver também

Modulo struct

Empacotamento e desempacotamento de dados binários heterogêneos.

Módulo xdrlib

Empacotamento e desempacotamento de dados External Data Representation (XDR) usados em alguns sistemas para chamada remota de procedimentos.

The Numerical Python Documentation

A extensão Numeric Python (NumPy) define outro tipo array; veja http://www.numpy.org/ para mais informações sobre Numerical Python.