"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'"       | 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                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'Q'"       | unsigned long long   | int                 | 8                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'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.

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

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

array.typecodes

   String com todos os códigos de tipo 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 *objetos byte ou similar* é permitido.

Os seguintes itens e métodos também são suportados:

array.typecode

   O caractere typecode usado para criar o vetor.

array.itemsize

   O tamanho em bytes de um item do vetor em representação interna.

array.append(x)

   Adiciona um novo item com valor *x* ao final do vetor.

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

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

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

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

array.fromfile(f, n)

   Read *n* items (as machine values) from the *file object* *f* and
   append them to the end of the array.  If less than *n* items are
   available, "EOFError" is raised, but the items that were available
   are still inserted into the array.

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

   Deprecated since version 3.2, will be removed in version 3.9.

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* do vetor.

array.reverse()

   Inverte a ordem dos itens no vetor.

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

   Devolve os itens do vetor como uma lista comum.

array.tostring()

   Deprecated alias for "tobytes()".

   Deprecated since version 3.2, will be removed in version 3.9.

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:

  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.

  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.
