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