8.7. "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       | Notes   |
| ication du  |                      |                     | octets                  |         |
| type        |                      |                     |                         |         |
|=============|======================|=====================|=========================|=========|
| "'b'"       | "signed char"        | *int*               | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'B'"       | "unsigned char"      | *int*               | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'u'"       | Py_UNICODE           | Caractère 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                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+

Notes :

1. Le code de type "'u'" correspond au type obsolète de Python
   caractère Unicode ("Py_UNICODE" de type "wchar_t"). Selon la
   plateforme, il peut être 16 bits ou 32 bits.

   "'u'" sera supprimé avec le reste de l'API "Py_UNICODE".

   Deprecated since version 3.3, will be removed in version 4.0.

2. Les codes de type "'q'" et "'Q'" ne sont disponibles que si le
   compilateur C de la plateforme utilisé pour construire Python gère
   le type C "long long", ou, sur Windows, "__int64".

   Nouveau dans la version 3.3.

La représentation réelle des valeurs est déterminée par l'architecture
de la machine (à proprement parler, par l'implémentation C). La taille
réelle est accessible via l'attribut "itemsize".

Le module définit le type suivant :

class array.array(typecode[, initializer])

   Un nouveau tableau dont les éléments sont limités par *typecode*,
   et initialisés par la valeur optionnelle *initializer*, qui peut
   être une liste, un *bytes-like object*, ou un itérable sur des
   éléments du type approprié.

   Si le paramètre *initializer* est une liste ou une chaîne de
   caractères, il est passé à la méthode "fromlist()", "frombytes()"
   ou "fromunicode()" du tableau (voir ci-dessous) pour ajouter les
   éléments initiaux du tableau. Si c'est un itérable, il est passé à
   la méthode "extend()".

array.typecodes

   Une chaîne avec tous les codes de types disponibles.

Les objets de tableau supportent les opérations classiques de séquence
: indiçage, découpage, concaténation et multiplication. Lors de
l'utilisation de tranche, la valeur assignée doit être un tableau du
même type ; dans tous les autres cas, l'exception "TypeError" est
levée. Les objets de tableau implémentent également l'interface
tampon, et peuvent être utilisés partout où *bytes-like objects* sont
supportés.

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
     Protocole tampon.

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.

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

   Nouveau dans la version 3.2: "fromstring()" est renommée en
   "frombytes()" pour plus de lisibilité.

array.fromfile(f, n)

   Lit *n* éléments (en tant que valeurs machine) du *file object* *f*
   et les ajouter à la fin du tableau. Si moins de *n* éléments sont
   disponibles, "EOFError" est levée, mais les éléments qui étaient
   disponibles sont tout de même insérés dans le tableau. *f* doit
   être un objet fichier natif ; quelque chose d'autre avec une
   méthode "read()" ne suffit pas.

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

   Alias obsolète de "frombytes()".

array.fromunicode(s)

   Étend ce tableau avec les données de la chaîne Unicode donnée. Le
   tableau doit être de type "'u'" ; sinon "ValueError" est levée.
   Utiliser "array.frombytes(unicodestring.encode(enc))" pour ajouter
   des données Unicode à un tableau d'un autre 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.remove(x)

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

array.reverse()

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

array.tobytes()

   Convertit le tableau en un tableau de valeurs machine et renvoie la
   représentation en octets (la même séquence d'octets qui serait
   écrite par la méthode "tofile()").

   Nouveau dans la version 3.2: "tostring()" est renommé en
   "tobytes()" pour plus de lisibilité.

array.tofile(f)

   Écrit tous les éléments (en tant que valeurs machine) du *file
   object* *f*.

array.tolist()

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

array.tostring()

   Alias obsolète de "tobytes()".

array.tounicode()

   Convertit le tableau en une chaîne Unicode. Le tableau doit être un
   tableau de type "'u'" ; sinon "ValueError" est levée. Utilisez
   "array.tobytes().decode(enc)" pour obtenir une chaîne Unicode
   depuis un tableau de tout autre type.

Quand un objet tableau est affiché ou converti en chaîne, il est
représenté en tant que "array(typecode, initializer)". *initializer*
est omis si le tableau est vide, sinon c'est une chaine si le
*typecode* est "'u'", sinon c'est une liste de nombres. Il est garanti
que la chaîne puisse être convertie en un tableau avec le même type et
la même valeur en utilisant "eval()", tant que la classe "array" a été
importée en utilisant "from array import array". Exemples :

   array('l')
   array('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).

  *La documentation de *Numerical Python*
  <https://docs.scipy.org/doc/>*
     L'extension *Numeric Python* (NumPy) définit un autre type de
     tableau ; voir http://www.numpy.org/ pour plus d'informations sur
     *Numeric Python*.
