array— Vetores 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 código de tipo, que é um único caractere. São definidos os seguintes códigos de tipo:

Código de tipo	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 vetor cujos itens são restritos pelo código de tipo e inicializados pelo valor opcional initializer, que deve ser uma lista, um objeto byte ou similar, ou outros elementos iteráveis do tipo apropriado.

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

Levanta um evento de auditoria array.__new__ com argumentos typecode, initializer.

array.typecodes

String com todos os códigos de tipo 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 objetos byte ou similar é permitido.

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

array.typecode

O caractere typecode usado para criar o vetor.

array.itemsize

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

array.append(x)

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

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 vetor. 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 vetor existir e nenhuma operação de alteração de tamanho for aplicada a ele.

Nota

Quando se está usando vetores 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 vetores. 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 vetor.

array.extend(iterable)

Acrescenta os itens de iterable ao final do vetor. Se iterable for outro vetor, ele deve ter exatamente o mesmo código de tipo; senão, ocorrerá uma TypeError. Se iterable não for um vetor, ele deve ser iterável e seus elementos devem ser do tipo correto para ser acrescentado ao vetor.

array.frombytes(s)

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

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

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.

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 do vetor.

array.reverse()

Inverte a ordem dos itens no vetor.

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()

Devolve os itens do vetor como uma lista comum.

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

Módulo 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.