"array"--- Arrays eficientes de valores numéricos
*************************************************

======================================================================

Esse módulo define um tipo de objeto que pode representar
compactamente um array de valores básicos: caracteres, inteiros,
números de ponto flutuante. Arrays 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                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'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 array cujos itens são restritos pelo *type code* e
   inicializados pelo valor opcional *initializer*, que deve ser uma
   lista, um *bytes-like object*, ou outro elementos iterável 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 caractere 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()".

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

   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:

  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.
