8.7. 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

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

(2)

'Q'

unsigned long long

int

8

(2)

'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.

  2. Os type codes 'q' e 'Q' estão disponíveis apenas se o compilador C usado para construir o Python suportar o tipo long long do C, ou __int64 no Windows.

    Novo na versão 3.3.

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 itinializer, que deve ser uma lista, um bytes-like object, ou 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 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 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 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().

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

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.