"array" — 効率のよい数値アレイ
******************************

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

+-------------+------------------+---------------------+-------------------------+
| 型コード    | C の型           | Python の型         | 最小サイズ (バイト単位) |
+=============+==================+=====================+=========================+
| "'c'"       | char             | character           | 1                       |
+-------------+------------------+---------------------+-------------------------+
| "'b'"       | signed char      | int                 | 1                       |
+-------------+------------------+---------------------+-------------------------+
| "'B'"       | unsigned char    | int                 | 1                       |
+-------------+------------------+---------------------+-------------------------+
| "'u'"       | Py_UNICODE       | Unicode文字(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'"       | 浮動小数点数     | 浮動小数点数        | 4                       |
+-------------+------------------+---------------------+-------------------------+
| "'d'"       | double           | 浮動小数点数        | 8                       |
+-------------+------------------+---------------------+-------------------------+

注釈: 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.

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

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.

   バージョン 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.

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

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()" の情報を使う意味のある唯一の方法です) は、アレイ
     オブジェクトでサポートしているバッファインタフェースを使う方がよ
     り理にかなっています。このメソッドは後方互換性のために保守されて
     おり、新しいコードでの使用は避けるべきです。バッファインタフェー
     スの説明は Buffers and Memoryview Objects にあります。

array.byteswap()

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

array.count(x)

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

array.extend(iterable)

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

   バージョン 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)

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

array.fromstring(s)

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

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)

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

array.insert(i, x)

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

array.pop([i])

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

array.read(f, n)

   バージョン 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)

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

array.reverse()

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

array.tofile(f)

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

array.tolist()

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

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)

   バージョン 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])

参考:

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

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

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