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

======================================================================

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

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

注釈:

1. タイプコード "'u'" は Python の古い Unicode 文字 ("Py_UNICODE" ある
   いは "wchar_t") を表します。プラットフォームに依存して、これは
   16bit か 32bit になります。

   "'u'" は将来的に他の "Py_UNICODE" API と一緒に削除されるでしょう。

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

値の実際の表現はマシンアーキテクチャ (厳密に言うとCの実装) によって決
まります。値の実際のサイズは "itemsize" 属性から得られます。

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

class array.array(typecode[, initializer])

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

   リストか文字列を渡した場合、initializer は新たに作成されたアレイの
   "fromlist()" 、 "frombytes()" あるいは "fromunicode()" メソッド (以
   下を参照) に渡され、アレイに初期項目を追加します。それ以外の場合に
   は、イテラブルの *initializer* は "extend()" メソッドに渡されます。

   引数 "typecode", "initializer" 付きで 監査イベント "array.__new__"
   を送出します。

array.typecodes

   すべての利用可能なタイプコードを含む文字列

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

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

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 Protocol) にあります。

array.byteswap()

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

array.count(x)

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

array.extend(iterable)

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

array.frombytes(s)

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

   バージョン 3.2 で追加: 明確化のため "fromstring()" の名前が
   "frombytes()" に変更されました。

array.fromfile(f, n)

   *ファイルオブジェクト* *f* から (マシンのデータ形式そのままで) *n*
   個の要素を読み出し、アレイの末尾に要素を追加します。 *n* 個未満の要
   素しか読めなかった場合は "EOFError" を送出しますが、それまでに読み
   出せた値はアレイに追加されます。

array.fromlist(list)

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

array.fromstring()

   "frombytes()" に対する廃止予定のエイリアス

   Deprecated since version 3.2, will be removed in version 3.9.

array.fromunicode(s)

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

array.index(x)

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

array.insert(i, x)

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

array.pop([i])

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

array.remove(x)

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

array.reverse()

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

array.tobytes()

   array をマシンの値の array に変換して、 bytes の形で返します
   ("tofile()" メソッドを使ってファイルに書かれるバイト列と同じです)。

   バージョン 3.2 で追加: 明確化のため "tostring()" の名前が
   "tobytes()" に変更されました。

array.tofile(f)

   すべての要素を (マシンの値の形式で) *file object* *f* に書き込みま
   す。

array.tolist()

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

array.tostring()

   "tobytes()" に対する廃止予定のエイリアス

   Deprecated since version 3.2, will be removed in version 3.9.

array.tounicode()

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

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

   array('l')
   array('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/ を参照してください。
