"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'"       | wchar_t              | 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                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'Q'"       | "unsigned long long" | *int*               | 8                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'f'"       | *float*              | *float*             | 4                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'d'"       | double               | *float*             | 8                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+

Notes :

1. It can be 16 bits or 32 bits depending on the platform.

   Modifié dans la version 3.9: "array('u')" now uses "wchar_t" as C
   type instead of deprecated "Py_UNICODE". This change doesn't affect
   its behavior because "Py_UNICODE" is alias of "wchar_t" since
   Python 3.3.

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

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 "array.itemsize" attribute.

The module defines the following item:

array.typecodes

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

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

   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.

   Lève un événement d'audit "array.__new__" avec les arguments
   "typecode", "initializer".

   typecode

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

   itemsize

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

   append(x)

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

   buffer_info()

      Return a tuple "(address, length)" giving the current memory
      address and the length in elements of the buffer used to hold
      array's contents.  The size of the memory buffer in bytes can be
      computed as "array.buffer_info()[1] * array.itemsize".  This is
      occasionally useful when working with low-level (and inherently
      unsafe) I/O interfaces that require memory addresses, such as
      certain "ioctl()" operations.  The returned numbers are valid as
      long as the array exists and no length-changing operations are
      applied to it.

      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.

   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.

   count(x)

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

   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.

   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()" is renamed to
      "frombytes()" for clarity.

   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.

   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é.

   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.

   index(x[, start[, stop]])

      Return the smallest *i* such that *i* is the index of the first
      occurrence of *x* in the array.  The optional arguments *start*
      and *stop* can be specified to search for *x* within a
      subsection of the array.  Raise "ValueError" if *x* is not
      found.

      Modifié dans la version 3.10: Added optional *start* and *stop*
      parameters.

   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.

   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é.

   remove(x)

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

   reverse()

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

   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()" is renamed to
      "tobytes()" for clarity.

   tofile(f)

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

   tolist()

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

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

  NumPy
     The NumPy package defines another array type.
