"array" --- 効率的な数値配列
****************************

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

This module defines an object type which can compactly represent an
array of basic values: characters, integers, floating-point numbers,
complex numbers.  Arrays are mutable *sequence* types and behave very
much like lists, except that the type of objects stored in them is
constrained.  The type is specified at object creation time by using a
*type code*, which is a single character.  The following type codes
are defined:

+-------------+----------------------+---------------------+-------------------------+---------+
| 型コード    | C の型               | Python の型         | 最小サイズ (バイト単位) | 注釈    |
|=============|======================|=====================|=========================|=========|
| "'b'"       | signed char          | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'B'"       | unsigned char        | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'u'"       | wchar_t              | Unicode 文字        | 2                       | (1)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'w'"       | Py_UCS4              | Unicode 文字        | 4                       | (2)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'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                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'e'"       | _Float16             | 浮動小数点数        | 2                       | (3)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'f'"       | 浮動小数点数         | 浮動小数点数        | 4                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'d'"       | double               | 浮動小数点数        | 8                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'Zf'"      | float complex        | 複素数              | 8                       | (4)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'Zd'"      | double complex       | 複素数              | 16                      | (4)     |
+-------------+----------------------+---------------------+-------------------------+---------+

注釈:

1. プラットフォームによって、16 ビットの場合と 32 ビットの場合がありま
   す。

   バージョン 3.9 で変更: "array('u')" の C の型は、非推奨の
   "Py_UNICODE" から "wchar_t" に変更されました。 Python 3.3 以降、
   "Py_UNICODE" は "wchar_t" の別名なので、この変更による動作の違いは
   ありません。

   バージョン 3.3 で非推奨、バージョン 3.16 で削除予定: 型コード "'w'"
   に移行してください。

2. Added in version 3.13.

3. IEEE 754 binary16「半精度」型は、IEEE 754 規格 の 2008 年の改訂で導
   入されました。 この型は C コンパイラでは広くサポートされていません
   。 コンパイラが C23 規格の附属書 H をサポートしていれば、_Float16
   型として使えます。

   Added in version 3.15.

4. 複素数型 ("Zf" と "Zd") は、C コンパイラによる複素数型 (C11 規格の
   附属書 G) のサポートの有無にかかわらず、常に利用できます。 C11 規格
   の規定に従い、各複素数型は実部と虚部を順に格納する 2 要素の C の配
   列で表されます。

   Added in version 3.15.

参考:

  ctypes モジュール、struct モジュール、numpy などのサードパーティー製
  モジュールも、似ているものの少し異なる型コードを使っています。

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

このモジュールは以下の項目を定義しています:

array.typecodes

   利用可能なすべての型コードを含むタプルです。

   バージョン 3.15 で変更: 型が "str" から "tuple" に変わりました。

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

class array.array(typecode[, initializer])

   要素の型を *typecode* で制限した新しい配列を作成します。 省略可能な
   *initializer* を指定すると、その値で初期化します。 この値は "bytes"
   オブジェクト、"bytearray" オブジェクト、Unicode 文字列、または適切
   な型の要素を返すイテラブルでなければなりません。

   "bytes" または "bytearray" オブジェクトを指定した場合、
   "initializer" は新しい配列の "frombytes()" メソッドに渡されます。
   Unicode 文字列を指定した場合は "fromunicode()" メソッドに渡されます
   。 それ以外の場合は、"initializer" のイテレーターを "extend()" メソ
   ッドに渡して、初期値となる要素を配列に追加します。

   配列オブジェクトは、インデックス参照、スライス、連結、繰り返しとい
   った、通常の ミュータブルな *シーケンス* の操作をサポートします。
   スライス代入では、代入する値は同じ型コードの配列オブジェクトでなけ
   ればならず、それ以外の場合は "TypeError" を送出します。 配列オブジ
   ェクトはバッファインターフェースも実装しており、*bytes-like オブジ
   ェクト* を受け付ける場所で使えます。

   配列は、要素の型をパラメーターとする ジェネリック型 です。

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

   typecode

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

   itemsize

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

   append(value, /)

      指定した値を持つ新しい要素を配列の末尾に追加します。

   buffer_info()

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

      注釈:

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

   byteswap()

      配列の全要素のバイト順を逆にします。 サイズが 1、2、4、8、16 バ
      イトの値だけをサポートし、それ以外の型の値では "RuntimeError" を
      送出します。 バイト順が異なるマシンで書き込まれたファイルからデ
      ータを読み込む際に便利です。 複素数型の場合、成分の順序 (実部、
      虚部の順) は変わりません。

   count(value, /)

      配列内で *value* が出現する回数を返します。

   extend(iterable, /)

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

   frombytes(buffer, /)

      *bytes-like object* の内容をマシンのデータ形式の配列として解釈し
      、要素を追加します ("fromfile()" メソッドでファイルから読み込ん
      だ場合と同じです)。

      Added in version 3.2: 明確化のため "fromstring()" の名前が
      "frombytes()" に変更されました。

   fromfile(f, n, /)

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

   fromlist(list, /)

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

   fromunicode(ustr, /)

      指定した Unicode 文字列のデータを配列に追加します。 配列の型コー
      ドは "'u'" または "'w'" でなければならず、それ以外では
      "ValueError" を送出します。 他の型の配列に Unicode データを追加
      するには、"array.frombytes(unicodestring.encode(enc))" を使って
      ください。

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

      配列内で *value* が最初に出現するインデックス *i* (つまり、該当
      する最小の *i*) を返します。 省略可能な引数 *start* と *stop* を
      指定すると、配列の一部分から *value* を探せます。 *value* が見つ
      からなければ "ValueError" を送出します。

      バージョン 3.10 で変更: 省略可能な *start* と *stop* パラメータ
      ーが追加されました。

   insert(index, value, /)

      配列の *index* が示す位置の直前に、新しい要素 *value* を挿入しま
      す。 負のインデックスは配列の末尾からの相対位置として扱われます
      。

   pop(index=-1, /)

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

   remove(value, /)

      配列内で最初に出現する *value* を削除します。

   clear()

      配列のすべての要素を削除します。

      Added in version 3.13.

   reverse()

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

   tobytes()

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

      Added in version 3.2: 名前を明確にするため、"tostring()" を
      "tobytes()" に改名しました。

   tofile(f, /)

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

   tolist()

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

   tounicode()

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

The string representation of array objects has the form
"array(typecode, initializer)". The *initializer* is omitted if the
array is empty, otherwise it is a Unicode string if the *typecode* is
"'u'" or "'w'", otherwise it is a list of numbers. The string
representation 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".
Variables "inf" and "nan" must also be defined if it contains
corresponding floating-point values. Examples:

   array('l')
   array('w', 'hello \u2641')
   array('l', [1, 2, 3, 4, 5])
   array('d', [1.0, 2.0, 3.14, -inf, nan])

参考:

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

  NumPy
     NumPy パッケージは、別の配列型を定義しています。
