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

   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 os argumentos
   "typecode", "initializer".

array.typecodes

   String com todos os códigos de tipo disponíveis.

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.

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

array.typecode

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

   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.

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.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 valor *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 opcional é "-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.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.
