"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 em C            | Tipo em Python      | Tamanho mínimo em bytes | Notas   |
| tipo        |                      |                     |                         |         |
|=============|======================|=====================|=========================|=========|
| "'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.
