"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)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'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 4.0.

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 pelo *código de tipo* e
   inicializados pelo valor opcional *initializer*, que deve ser uma
   lista, um *objeto byte ou similar*, ou outros 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 vetor para adicionar itens iniciais ao vetor. Caso
   contrário, o inicializador iterável é passado para o método
   "extend()".

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

      Adiciona itens da string, interpretando a string como um vetor
      (como se tivesse sido lido de um arquivo usando o método
      "fromfile()").

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

   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.

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

      Novo 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'"; 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:

  Módulo "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.

  NumPy
     O pacote NumPy define outro tipo de vetor.
