"array" --- Efficient arrays of numeric values
**********************************************

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

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

+-------------+----------------------+---------------------+-------------------------+---------+
| 型コード    | C の型               | Python の型         | 最小サイズ (バイト単位) | 注釈    |
|=============|======================|=====================|=========================|=========|
| "'b'"       | signed char          | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'B'"       | unsigned char        | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'u'"       | wchar_t              | 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. It can be 16 bits or 32 bits depending on the platform.

   バージョン 3.9 で変更: "array('u')" now uses "wchar_t" as C type
   instead of deprecated "Py_UNICODE". This change doesn't affect its
   behavior because "Py_UNICODE" is alias of "wchar_t" since Python
   3.3.

   バージョン 3.3 で非推奨、バージョン 4.0 で削除予定.

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

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

array.typecodes

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

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

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
   "bytes" or "bytearray" object, a Unicode string, or iterable over
   elements of the appropriate type.

   If given a "bytes" or "bytearray" object, the initializer is passed
   to the new array's "frombytes()" method; if given a Unicode string,
   the initializer is passed to the "fromunicode()" method; otherwise,
   the initializer's iterator is passed to the "extend()" method to
   add initial items to the array.

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

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

   typecode

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

   itemsize

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

   append(x)

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

   buffer_info()

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

      注釈:

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

   byteswap()

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

   count(x)

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

   extend(iterable)

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

   frombytes(buffer)

      Appends items from the *bytes-like object*, interpreting its
      content as an array of machine values (as if it had been read
      from a file using the "fromfile()" method).

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

   fromfile(f, n)

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

   fromlist(list)

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

   fromunicode(s)

      Extends this array with data from the given Unicode string. The
      array must have type code "'u'"; otherwise a "ValueError" is
      raised. Use "array.frombytes(unicodestring.encode(enc))" to
      append Unicode data to an array of some other type.

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

      Return the smallest *i* such that *i* is the index of the first
      occurrence of *x* in the array.  The optional arguments *start*
      and *stop* can be specified to search for *x* within a
      subsection of the array.  Raise "ValueError" if *x* is not
      found.

      バージョン 3.10 で変更: Added optional *start* and *stop*
      parameters.

   insert(i, x)

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

   pop([i])

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

   remove(x)

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

   reverse()

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

   tobytes()

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

      Added in version 3.2: "tostring()" is renamed to "tobytes()" for
      clarity.

   tofile(f)

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

   tolist()

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

   tounicode()

      Convert the array to a Unicode string.  The array must have a
      type "'u'"; otherwise a "ValueError" is raised. Use
      "array.tobytes().decode(enc)" to obtain a Unicode string from an
      array of some other type.

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'", 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('u', 'hello \u2641')
   array('l', [1, 2, 3, 4, 5])
   array('d', [1.0, 2.0, 3.14, -inf, nan])

参考:

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

  Module "xdrlib"
     Packing and unpacking of External Data Representation (XDR) data
     as used in some remote procedure call systems.

  NumPy
     The NumPy package defines another array type.
