# `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 | (2)
`'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')` agora usa `wchar_t` como tipo C no lugar do descontinuado `Py_UNICODE`. Essa mudança não afeta o comportamento pois `Py_UNICODE` é um apelido para `wchar_t` desde Python 3.3.

   Deprecated since version 3.3, will be removed in version 3.16: Por favor, migre para o código de tipo `'w'`.

2. Adicionado na versão 3.13.

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

O módulo define o seguinte 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])

  Um novo vetor cujos itens são restritos por typecode e inicializados a partir do valor opcional initializer, que deve ser um objeto `bytes` ou `bytearray`, uma string Unicode ou iterável sobre elementos do tipo apropriado.

  Se for fornecido um objeto `bytes` ou `bytearray`, o inicializador é passado para o método `frombytes()` do novo vetor; se for fornecida uma string Unicode, o inicializador é passado para o método `fromunicode()`; caso contrário, o iterador do inicializador é passado para o método `extend()` para adicionar itens iniciais ao vetor.

  Objetos vetor 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 vetor com o mesmo código de tipo; caso contrário, `TypeError` é levantada. Objetos vetor também implementam a interface buffer, e também podem ser usados em qualquer lugar onde objetos bytes ou similares é permitido.

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

  typecode

    O caractere de código de tipo 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()

    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.

  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)

    Adiciona itens do objeto bytes ou similar, interpretando seu conteúdo como um vetor de valores de máquina (como se tivesse sido lido de um arquivo usando o método `fromfile()`).

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

  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 erro de tipo, o vetor não é alterado.

  fromunicode(s)

    Estende este vetor com dados da string Unicode fornecida. O vetor deve ter o código de tipo `'u'` ou `'w'`; caso contrário, uma `ValueError` é levantada. Use `array.frombytes(unicodestring.encode(enc))` para anexar dados Unicode a um vetor de algum outro tipo.

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

    Retorna o menor i tal que i seja o índice da primeira ocorrência de x no vetor. Os argumentos opcionais start e stop podem ser especificados para procurar por x dentro de uma subseção do vetor. Levanta `ValueError` se x não for encontrado.

    Alterado na versão 3.10: Adicionados os parâmetros opcionais start e *stop.

  insert(i, x)

    Insere um novo item com o valor 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 opcional é `-1`, assim por padrão o último item é removido e retornado.

  remove(x)

    Remove a primeira ocorrência de x do vetor.

  clear()

    Remove todos os elementos do vetor.

    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()` foi nomeado para `tobytes()` para maior clareza.

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

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

A representação em string de objetos vetor tem o formato `array(typecode, initializer)`. O initializer é omitido se o vetor estiver vazio; caso contrário, é uma string Unicode se o typecode for `'u'` ou `'w'`; caso contrário, é uma lista de números. A representação em string pode ser convertida novamente para um array com o mesmo tipo e valor usando `eval()`, desde que a classe `array` tenha sido importada usando `from array import array`. As variáveis `inf` e `nan` também devem ser definidas se contiverem valores de ponto flutuante correspondentes. Exemplos:

    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

  O pacote NumPy define outro tipo de vetor.