8.6. "array" --- 効率のよい数値アレイ
*************************************

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

+-------------+------------------+---------------------+-------------------------+
| 型コード    | 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                       |
+-------------+------------------+---------------------+-------------------------+

注釈: "'u'" 型コードは Python の Unicode 文字列に対応します。一文字
  幅の文 字は 2 バイトで二文字幅の文字は 4 バイトです。

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

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

class array.array(typecode[, initializer])

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

   バージョン 2.4 で変更: 以前はリストか文字列しか受け付けませんでした
   。

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

array.ArrayType

   "array" の別名です。撤廃されました。

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

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

array.typecode

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

array.itemsize

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

array.append(x)

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

array.buffer_info()

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

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

array.byteswap()

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

array.count(x)

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

array.extend(iterable)

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

   バージョン 2.4 で変更: 以前は他のアレイ型しか引数に指定できませんで
   した。

array.fromfile(f, n)

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

array.fromlist(list)

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

array.fromstring(s)

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

array.fromunicode(s)

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

array.index(x)

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

array.insert(i, x)

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

array.pop([i])

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

array.read(f, n)

   バージョン 1.5.1 で非推奨: "fromfile()" メソッドを使ってください。

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

array.remove(x)

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

array.reverse()

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

array.tofile(f)

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

array.tolist()

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

array.tostring()

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

array.tounicode()

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

array.write(f)

   バージョン 1.5.1 で非推奨: "tofile()" メソッドを使ってください。

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

アレイオブジェクトを表示したり文字列に変換したりすると、
"array(typecode, initializer)" という形式で表現されます。 アレイが空の
場合は *initializer* の表示を省略します。 アレイが空でなければ、
*typecode* が "'c'" の場合には文字列に、それ以外の場合には数値のリスト
になります。 "array" クラスが "from array import array" というふうにイ
ンポートされている限り、変換後の文字列に "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])

参考:

  "struct" モジュール
     異なる種類のバイナリデータのパックおよびアンパック。

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

  Numerical Python ドキュメント
     Numeric Python 拡張モジュール (NumPy) では、別の方法でシーケンス
     型を定義しています。 Numerical Python に関する詳しい情報は
     http://www.numpy.org/ を参照してください。
