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

   Descontinuado desde a versão 3.3, será removido na versão 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 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()").

      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 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'"; 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]])

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

      Convert the array to a Unicode string.  The array must have a
      type "'u'"; 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'", 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('u', '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.

  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.
