
:mod:`array` --- 効率のよい数値アレイ
=====================================

.. module:: array
   :synopsis: 一様な型を持つ数値からなる空間効率のよいアレイ。


.. index:: single: arrays

このモジュールでは、基本的な値 (文字、整数、浮動小数点数) のアレイ
(array、配列) をコンパクトに表現できるオブジェクト型を定義しています。
アレイはシーケンス (sequence) 型であり、中に入れるオブジェクトの型に\
制限があることを除けば、リストとまったく同じように振る舞います。
オブジェクト生成時に一文字の :dfn:`型コード` を用いて型を指定します。
次の型コードが定義されています:

+----------+----------------+------------------------+-------------------------+
| 型コード | C の型         | Python の型            | 最小サイズ (バイト単位) |
+==========+================+========================+=========================+
| ``'c'``  | char           | 文字(str型)            | 1                       |
+----------+----------------+------------------------+-------------------------+
| ``'b'``  | signed char    | int型                  | 1                       |
+----------+----------------+------------------------+-------------------------+
| ``'B'``  | unsigned char  | int型                  | 1                       |
+----------+----------------+------------------------+-------------------------+
| ``'u'``  | Py_UNICODE     | Unicode文字(unicode型) | 2                       |
+----------+----------------+------------------------+-------------------------+
| ``'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                       |
+----------+----------------+------------------------+-------------------------+

値の実際の表現はマシンアーキテクチャ (厳密に言うとCの実装) によって決まります。
値の実際のサイズは :attr:`itemsize` 属性から得られます。
Python の通常の整数型では C の unsigned (long) 整数の最大範囲を表せないため、
``'L'`` と ``'I'`` で表現されている要素に入る値は Python では長整数として表されます。

このモジュールでは次の型を定義しています:


.. function:: array(typecode[, initializer])

   要素のデータ型が *typecode* に限定される新しいアレイを返します。オプションの値 *initializer* を渡すと初期値になりますが、
   リスト、文字列または適当な型のイテレーション可能オブジェクトでなければなりません。

   .. versionchanged:: 2.4
      以前はリストか文字列しか受け付けませんでした。

   リストか文字列を渡した場合、新たに作成されたアレイの :meth:`fromlist` 、
   :meth:`fromstring` あるいは :meth:`fromunicode` メソッド (以下を参照して下さい)
   に渡され、初期値としてアレイに追加されます。それ以外の場合には、イテレーション可能オブジェクト *initializer* は新たに作成
   されたオブジェクトの :meth:`extend` メソッドに渡されます。


.. data:: ArrayType

   :func:`array` の別名です。撤廃されました。

アレイオブジェクトでは、インデクス指定、スライス、連結および反復といった、通常のシーケンスの演算をサポートしています。スライス代入を使うときは、
代入値は同じ型コードのアレイオブジェクトでなければなりません。それ以外のオブジェクトを指定すると :exc:`TypeError` を送出します。
アレイオブジェクトはバッファインタフェースを実装しており、バッファオブジェクトをサポートしている場所ならどこでも利用できます。

次のデータ要素やメソッドもサポートされています:


.. attribute:: array.typecode

   アレイを作るときに使う型コード文字です。


.. attribute:: array.itemsize

   アレイの要素 1 つの内部表現に使われるバイト長です。


.. method:: array.append(x)

   値 *x* の新たな要素をアレイの末尾に追加します。


.. method:: array.buffer_info()

   アレイの内容を記憶するために使っているバッファの、現在のメモリアドレスと要素数の入ったタプル ``(address, length)`` を返します。
   バイト単位で表したメモリバッファの大きさは ``array.buffer_info()[1] * array.itemsize`` で計算できま
   す。例えば :cfunc:`ioctl` 操作のような、メモリアドレスを必要とする低レベルな (そして、本質的に危険な) I/Oインタフェースを使って作業する
   場合に、ときどき便利です。アレイ自体が存在し、長さを変えるような演算を適用しない限り、有効な値を返します。

   .. note::

      C やC++ で書いたコードからアレイオブジェクトを使う場合
      (:meth:`buffer_info` の情報を使う意味のある唯一の方法です) は、
      アレイオブジェクトでサポートしているバッファインタフェースを使う方が\
      より理にかなっています。このメソッドは後方互換性のために保守されており、
      新しいコードでの使用は避けるべきです。バッファインタフェースの説明は
      :ref:`bufferobjects` にあります。

.. method:: array.byteswap()

   アレイのすべての要素に対して「バイトスワップ」(リトルエンディアンとビッグエンディアンの変換) を行います。このメソッドは大きさが 1、2、4 および 8
   バイトの値にのみをサポートしています。他の型の値に使うと :exc:`RuntimeError` を送出します。異なるバイトオーダをもつ計算機
   で書かれたファイルからデータを読み込むときに役に立ちます。


.. method:: array.count(x)

   シーケンス中の *x* の出現回数を返します。


.. method:: array.extend(iterable)

   *iterable* から要素を取り出し、アレイの末尾に要素を追加します。 *iterable* が別のアレイ型である場合、二つのアレイは *全く* 同
   じ型コードをでなければなりません。それ以外の場合には :exc:`TypeError` を送出します。 *iterable*
   がアレイでない場合、アレイに値を追加できるような正しい型の要素からなるイテレーション可能オブジェクトでなければなりません。

   .. versionchanged:: 2.4
      以前は他のアレイ型しか引数に指定できませんでした。


.. method:: array.fromfile(f, n)

   ファイルオブジェクト *f* から (マシン依存のデータ形式そのままで)
   *n* 個の要素を読み出し、アレイの末尾に要素を追加します。
   *n* 個の要素を読めなかったときは :exc:`EOFError` を送出しますが、
   それまでに読み出せた値はアレイに追加されています。
   *f* は本当の組み込みファイルオブジェクトでなければなりません。
   :meth:`read` メソッドをもつ他の型では動作しません。


.. method:: array.fromlist(list)

   リストから要素を追加します。
   型に関するエラーが発生した場合にアレイが変更されないことを除き、
   ``for x in list: a.append(x)`` と同じです。


.. method:: array.fromstring(s)

   文字列から要素を追加します。文字列は、 (ファイルから :meth:`fromfile` メソッドを使って値を読み込んだときのように)
   マシン依存のデータ形式で表された値の配列として解釈されます。


.. method:: array.fromunicode(s)

   指定した Unicode 文字列のデータを使ってアレイを拡張します。アレイの型コードは ``'u'`` でなければなりません。それ以外の場合には、
   :exc:`ValueError` を送出します。他の型のアレイに Unicode 型のデータ
   を追加するには、 ``array.fromstring(unicodestring.decode(enc))`` を使ってください。


.. method:: array.index(x)

   アレイ中で *x* が出現するインデクスのうち最小の値 *i* を返します。


.. method:: array.insert(i, x)

   アレイ中の位置 *i* の前に値 *x* をもつ新しい要素を挿入します。 *i* の値が負の場合、アレイの末尾からの相対位置として扱います。


.. method:: array.pop([i])

   アレイからインデクスが *i* の要素を取り除いて返します。オプションの引数はデフォルトで ``-1`` になっていて、最後の要素を取り
   除いて返すようになっています。


.. method:: array.read(f, n)

   .. deprecated:: 1.5.1
      :meth:`fromfile` メソッドを使ってください。

   ファイルオブジェクト *f* から (マシン依存のデータ形式そのままで) *n* 個の要素を読み出し、アレイの末尾に要素を追加します。 *n*
   個の要素を読めなかったときは :exc:`EOFError` を送出しますが、それまでに読み出せた値はアレイに追加されています。 *f*
   は本当の組み込みファイルオブジェクトでなければなりません。 :meth:`read` メソッドをもつ他の型では動作しません。


.. method:: array.remove(x)

   アレイ中の *x* のうち、最初に現れたものを取り除きます。


.. method:: array.reverse()

   アレイの要素の順番を逆にします。


.. method:: array.tofile(f)

   アレイのすべての要素をファイルオブジェクト *f* に (マシン依存のデータ形式そのままで)書き込みます。


.. method:: array.tolist()

   アレイを同じ要素を持つ普通のリストに変換します。


.. method:: array.tostring()

   アレイをマシン依存のデータアレイに変換し、文字列表現 (:meth:`tofile` メソッドによってファイルに書き込まれるものと同じバイト列) を返します。


.. method:: array.tounicode()

   アレイを Unicode 文字列に変換します。アレイの型コードは ``'u'`` でなければなりません。それ以外の場合には :exc:`ValueError`
   を送出します。他の型のアレイから Unicode 文字列を得るには、 ``array.tostring().decode(enc)`` を使ってください。


.. method:: array.write(f)

   .. deprecated:: 1.5.1
      :meth:`tofile` メソッドを使ってください。

   ファイルオブジェクト *f* に、全ての要素を(マシン依存のデータ形式そのままで)書き込みます。

アレイオブジェクトを表示したり文字列に変換したりすると、 ``array(typecode, initializer)`` という形式で表現されま
す。アレイが空の場合、 *initializer* の表示を省略します。アレイが空でなければ、 *typecode* が ``'c'`` の場合には文字列に、
それ以外の場合には数値のリストになります。関数 :func:`array` を ``from array import array`` で import して
いる限り、変換後の文字列に :func:`eval` を用いると元のアレイオブジェクトと同じデータ型と値を持つアレイに逆変換できること
が保証されています。文字列表現の例を以下に示します::

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


.. seealso::

   Module :mod:`struct`
      異なる種類のバイナリデータのパックおよびアンパック。

   Module :mod:`xdrlib`
      遠隔手続き呼び出しシステムで使われる外部データ表現仕様 (External Data Representation, XDR)
      のデータのパックおよびアンパック。

   `The Numerical Python Manual <http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm>`_
      Numeric Python 拡張モジュール (NumPy) では、別の方法でシーケンス型を定義しています。Numerical Python
      に関する詳しい情報は http://numpy.sourceforge.net/ を参照してください。
      (NumPy マニュアルの PDF バージョンは
      http://numpy.sourceforge.net/numdoc/numdoc.pdf で手に入ります。)

