This document is for an old version of Python that is no longer supported. You should upgrade and read the documentação do Python para versão estável atual.

# 8.6. `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
--- | --- | --- | ---
`'c'` | char | character | 1
`'b'` | signed char | int | 1
`'B'` | unsigned char | int | 1
`'u'` | Py_UNICODE | Caractere unicode | 2 (see note)
`'h'` | signed short | int | 2
`'H'` | unsigned short | int | 2
`'i'` | signed int | int | 2
`'I'` | unsigned int | long | 2
`'l'` | signed long | int | 4
`'L'` | unsigned long | long | 4
`'f'` | float | float | 4
`'d'` | double | float | 8

Nota

The `'u'` typecode corresponds to Python’s unicode character. On narrow Unicode builds this is 2-bytes, on wide builds this is 4-bytes.

The actual representation of values is determined by the machine architecture (strictly speaking, by the C implementation). The actual size can be accessed through the `itemsize` attribute. The values stored for `'L'` and `'I'` items will be represented as Python long integers when retrieved, because Python’s plain integer type cannot represent the full range of C’s unsigned (long) integers.

O módulo define o seguinte tipo:

class `array.``array`(typecode[, initializer])

  A new array whose items are restricted by typecode, and initialized from the optional initializer value, which must be a list, string, or iterable over elements of the appropriate type.

  Alterado na versão 2.4: Formerly, only lists or strings were accepted.

  If given a list or string, the initializer is passed to the new array’s `fromlist()`, `fromstring()`, or `fromunicode()` method (see below) to add initial items to the array. Otherwise, the iterable initializer is passed to the `extend()` method.

`array.``ArrayType`

  Obsolete alias for `array`.

Array objects support the ordinary sequence operations of indexing, slicing, concatenation, and multiplication. When using slice assignment, the assigned value must be an array object with the same type code; in all other cases, `TypeError` is raised. Array objects also implement the buffer interface, and may be used wherever buffer objects are supported.

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 Buffers and Memoryview Objects.

`array.``byteswap`()

  “Byteswap” all items of the array. This is only supported for values which are 1, 2, 4, or 8 bytes in size; for other types of values, `RuntimeError` is raised. It is useful when reading data from a file written on a machine with a different byte order.

`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,

  Alterado na versão 2.4: Formerly, the argument could only be another array.

`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. f must be a real built-in file object; something else with a `read()` method won’t do.

`array.``fromlist`(list)

  Append items from the list. This is equivalent to `for x in list: a.append(x)` except that if there is a type error, the array is unchanged.

`array.``fromstring`(s)

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

`array.``fromunicode`(s)

  Extends this array with data from the given unicode string. The array must be a type `'u'` array; otherwise a `ValueError` is raised. Use `array.fromstring(unicodestring.encode(enc))` to append Unicode data to an array of some other type.

`array.``index`(x)

  Return the smallest i such that i is the index of the first occurrence of x in the array.

`array.``insert`(i, x)

  Insert a new item with value x in the array before position i. Negative values are treated as being relative to the end of the array.

`array.``pop`([i])

  Removes the item with the index i from the array and returns it. The optional argument defaults to `-1`, so that by default the last item is removed and returned.

`array.``read`(f, n)

  Obsoleto desde a versão 1.5.1: Use the `fromfile()` method.

  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. f must be a real built-in file object; something else with a `read()` method won’t do.

`array.``remove`(x)

  Remove a primeira ocorrência de x da array.

`array.``reverse`()

  Inverte a ordem dos itens na array.

`array.``tofile`(f)

  Write all items (as machine values) to the file object f.

`array.``tolist`()

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

`array.``tostring`()

  Convert the array to an array of machine values and return the string representation (the same sequence of bytes that would be written to a file by the `tofile()` method.)

`array.``tounicode`()

  Convert the array to a unicode string. The array must be a type `'u'` array; otherwise a `ValueError` is raised. Use `array.tostring().decode(enc)` to obtain a unicode string from an array of some other type.

`array.``write`(f)

  Obsoleto desde a versão 1.5.1: Use the `tofile()` method.

  Write all items (as machine values) to the file object f.

When an array object is printed or converted to a string, it is represented as `array(typecode, initializer)`. The initializer is omitted if the array is empty, otherwise it is a string if the typecode is `'c'`, otherwise it is a list of numbers. The string 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`. Examples:

    array('l')
    array('c', 'hello world')
    array('u', u'hello \u2641')
    array('l', [1, 2, 3, 4, 5])
    array('d', [1.0, 2.0, 3.14])

Ver também

Modulo `struct`

  Packing and unpacking of heterogeneous binary data.

Módulo `xdrlib`

  Packing and unpacking of External Data Representation (XDR) data as used in some remote procedure call systems.

The Numerical Python Documentation

  The Numeric Python extension (NumPy) defines another array type; see http://www.numpy.org/ for further information about Numerical Python.