8.7. "array"--- Arrays 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 type
code, que é um único caractere. Os seguintes type codes são definidos:

+-------------+----------------------+---------------------+-------------------------+---------+
| Type code   | Tipo em C            | Tipo em Python      | Tamanho mínimo em bytes | Notas   |
|=============|======================|=====================|=========================|=========|
| "'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                       | (2)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'Q'"       | unsigned long long   | int                 | 8                       | (2)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'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.

2. Os type codes "'q'" e "'Q'" estão disponíveis apenas se o
   compilador C usado para construir o Python suportar o tipo "long
   long" do C, ou "__int64" no Windows.

   Novo na versão 3.3.

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 array cujos itens são restritos pelo *type code* e
   inicializados pelo valor opcional *itinializer*, que deve ser uma
   lista, um *bytes-like object*, ou 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 array para adicionar itens iniciais ao array. Caso
   contrário, o inicializador iterável é passado para o método
   "extend()".

array.typecodes

   String com todos os types codes 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 *bytes-like objects* é permitido.

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

array.typecode

   O caracter typecode usado para criar o array

array.itemsize

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

array.append(x)

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

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 array.  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 array existir e nenhuma operação de
   alteração de tamanho for aplicada a ele.

   Nota:

     Quando se está usando arrays 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 arrays. 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 array.

array.extend(iterable)

   Acrescenta os itens em *iterable* ao final do array. Se *iterable*
   for outro array, ele deve ter *exatamente* o mesmo type code;
   senão, ocorrerá um "TypeError". Se *iterable* não for um array, ele
   deve ser iterável e seus elementos devem ser do tipo correto para
   ser acrescentado ao array,

array.frombytes(s)

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

   Novo na versão 3.2: "fromstring()" for 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. *f* deve realmente ser um objeto
   arquivo; qualquer outra coisa com um método "read()" não vai
   funcionar.

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

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

array.reverse()

   Inverte a ordem dos itens na array.

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

   Converte a array para uma lista comum com os mesmos itens.

array.tostring()

   Deprecated alias for "tobytes()".

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:

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