8.6. "array" — Tableaux efficaces de valeurs numériques
*******************************************************

Ce module définit un type d’objet qui permet de représenter de façon
compacte un tableau (*array*) de valeurs élémentaires : caractères,
entiers, flottants. Les tableaux sont de type séquence et se
comportent de manière très similaire aux listes, sauf que les types
d’objets qui y sont stockés sont limités. Le type est spécifié au
moment de la création de l’objet en utilisant *type code*, qui est un
caractère unique. Voir ci-dessous pour la définition des types :

+-------------+------------------+---------------------+-------------------------+
| Code d’ind  | Type C           | Type Python         | Taille minimum en       |
| ication du  |                  |                     | octets                  |
| type        |                  |                     |                         |
+=============+==================+=====================+=========================+
| "'c'"       | char             | character           | 1                       |
+-------------+------------------+---------------------+-------------------------+
| "'b'"       | "signed char"    | *int*               | 1                       |
+-------------+------------------+---------------------+-------------------------+
| "'B'"       | "unsigned char"  | *int*               | 1                       |
+-------------+------------------+---------------------+-------------------------+
| "'u'"       | Py_UNICODE       | Caractère 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                       |
+-------------+------------------+---------------------+-------------------------+

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

Le module définit le type suivant :

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.

   Modifié dans la version 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.

Les éléments de données et méthodes suivants sont également supportés
:

array.typecode

   Le code (de type Python caractère) utilisé pour spécifier le type
   des éléments du tableau.

array.itemsize

   La longueur en octets d’un élément du tableau dans la
   représentation interne.

array.append(x)

   Ajoute un nouvel élément avec la valeur *x* à la fin du tableau.

array.buffer_info()

   Renvoie un tuple "(address, length)" indiquant l’adresse mémoire
   courante et la longueur en éléments du tampon utilisé pour contenir
   le contenu du tableau. La taille du tampon mémoire en octets peut
   être calculée par "array.buffer_info()[1] * array.itemsize". Ceci
   est parfois utile lorsque vous travaillez sur des interfaces E/S de
   bas niveau (et intrinsèquement dangereuses) qui nécessitent des
   adresses mémoire, telles que certaines opérations "ioctl()". Les
   nombres renvoyés sont valides tant que le tableau existe et
   qu’aucune opération qui modifie sa taille ne lui est appliquée.

   Note: Lors de l’utilisation d’objets tableaux provenant de codes
     écrits en C ou C++ (le seul moyen d’utiliser efficacement ces
     informations), il est plus logique d’utiliser l’interface tampon
     supportée par les objets tableaux. Cette méthode est maintenue
     pour des raisons de rétrocompatibilité et devrait être évitée
     dans un nouveau code. L’interface tampon est documentée dans
     Objets de type MemoryView.

array.byteswap()

   Boutisme de tous les éléments du tableau. Ceci n’est pris en charge
   que pour les valeurs de 1, 2, 4 ou 8 octets ; pour les autres types
   de valeur, "RuntimeError" est levée. Il est utile lors de la
   lecture de données à partir d’un fichier écrit sur une machine avec
   un ordre d’octets différent.

array.count(x)

   Renvoi le nombre d’occurrences de *x* dans le tableau.

array.extend(iterable)

   Ajoute les éléments de *iterable* à la fin du tableau. Si
   *iterable* est un autre tableau, il doit le même code d’indication
   du type ; dans le cas contraire, "TypeError" sera levée. Si
   *iterable* n’est pas un tableau, il doit être itérable et ces
   éléments doivent être du bon type pour être ajoutés dans le
   tableau.

   Modifié dans la version 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)

   Ajoute les éléments de la liste. C’est l’équivalent de "for x in
   list: a.append(x)" sauf que s’il y a une erreur de type, le tableau
   est inchangé.

array.fromstring(s)

   Ajoute des éléments de la chaîne, interprétant la chaîne comme un
   tableau de valeurs machine (comme si elle avait été lue depuis le
   fichier en utilisant la méthode "from file()").

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)

   Renvoie le plus petit *i* tel que *i* est l’index de la première
   occurrence de *x* dans le tableau.

array.insert(i, x)

   Ajoute un nouvel élément avec la valeur *x* dans le tableau avant
   la position *i*. Les valeurs négatives sont traitées relativement à
   la fin du tableau.

array.pop([i])

   Supprime l’élément du tableau avec l’index *i* et le renvoie.
   L’argument optionnel par défaut est à "-1", de sorte que par défaut
   le dernier élément est supprimé et renvoyé.

array.read(f, n)

   Obsolète depuis la version 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)

   Supprime la première occurrence de *x* du tableau.

array.reverse()

   Inverse l’ordre des éléments du tableau.

array.tofile(f)

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

array.tolist()

   Convertit le tableau en une liste ordinaire avec les mêmes
   éléments.

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)

   Obsolète depuis la version 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])

Voir aussi:

  Module "struct"
     Empaquetage et dépaquetage de données binaires hétérogènes.

  Module "xdrlib"
     Empaquetage et dépaquetage des données XDR (External Data
     Representation) telles qu’elles sont utilisées dans certains
     systèmes d’appels de procédures à distance (ou RPC pour *remote
     procedure call* en anglais).

  The Numerical Python Documentation
     L’extension *Numeric Python* (NumPy) définit un autre type de
     tableau ; voir http://www.numpy.org/ pour plus d’informations sur
     *Numeric Python*.
