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'

wchar_t

Caractere unicode

2

(1)

'w'

Py_UCS4

Caractere unicode

4

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

ponto flutuante

ponto flutuante

4

'd'

double

ponto flutuante

8

Notas:

  1. Pode ser de 16 ou 32 bits dependendo da plataforma.

    Alterado na versão 3.9: array('u') now uses wchar_t as C type instead of deprecated Py_UNICODE. This change doesn’t affect its behavior because Py_UNICODE is alias of wchar_t since Python 3.3.

    Deprecated since version 3.3, will be removed in version 3.16: Please migrate to 'w' typecode.

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 array.itemsize attribute.

The module defines the following item:

array.typecodes

String com todos os códigos de tipo disponíveis.

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 bytes or bytearray object, a Unicode string, or iterable over elements of the appropriate type.

If given a bytes or bytearray object, the initializer is passed to the new array’s frombytes() method; if given a Unicode string, the initializer is passed to the fromunicode() method; otherwise, the initializer’s iterator is passed to the extend() method to add initial items to the array.

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.

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

typecode

O caractere typecode usado para criar o vetor.

itemsize

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

append(x)

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

buffer_info()

Return a tuple (address, length) giving the current memory address and the length in elements of the buffer used to hold array’s contents. The size of the memory buffer in bytes can be computed as array.buffer_info()[1] * array.itemsize. This is occasionally useful when working with low-level (and inherently unsafe) I/O interfaces that require memory addresses, such as certain ioctl() operations. The returned numbers are valid as long as the array exists and no length-changing operations are applied to it.

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.

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.

count(x)

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

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.

frombytes(buffer)

Appends items from the bytes-like object, interpreting its content as an array of machine values (as if it had been read from a file using the fromfile() method).

Adicionado na versão 3.2: fromstring() is renamed to frombytes() for clarity.

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.

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.

fromunicode(s)

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

index(x[, start[, stop]])

Return the smallest i such that i is the index of the first occurrence of x in the array. The optional arguments start and stop can be specified to search for x within a subsection of the array. Raise ValueError if x is not found.

Alterado na versão 3.10: Added optional start and stop parameters.

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.

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.

remove(x)

Remove a primeira ocorrência de x do vetor.

clear()

Remove all elements from the array.

Adicionado na versão 3.13.

reverse()

Inverte a ordem dos itens no vetor.

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

Adicionado na versão 3.2: tostring() is renamed to tobytes() for clarity.

tofile(f)

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

tolist()

Devolve os itens do vetor como uma lista comum.

tounicode()

Convert the array to a Unicode string. The array must have a type 'u' or 'w'; otherwise a ValueError is raised. Use array.tobytes().decode(enc) to obtain a Unicode string from an array of some other type.

The string representation of array objects has the form array(typecode, initializer). The initializer is omitted if the array is empty, otherwise it is a Unicode string if the typecode is 'u' or 'w', otherwise it is a list of numbers. The string representation 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. Variables inf and nan must also be defined if it contains corresponding floating-point values. Examples:

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

Ver também

Módulo struct

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

NumPy

The NumPy package defines another array type.