"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*.  The following type codes are defined:

+-------------+----------------------+---------------------+-------------------------+---------+
| 型コード    | C の型               | Python の型         | 最小サイズ (バイト単位) | 注釈    |
|=============|======================|=====================|=========================|=========|
| "'b'"       | signed char          | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'B'"       | unsigned char        | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'u'"       | wchar_t              | Unicode文字(unicode | 2                       | (1)     |
|             |                      | 型)                 |                         |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'w'"       | Py_UCS4              | Unicode文字(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. 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 で非推奨、バージョン 3.16 で削除: Please migrate to
   "'w'" typecode.

2. Added in version 3.13.

3. The IEEE 754 binary16 "half precision" type was introduced in the
   2008 revision of the IEEE 754 standard. This type is not widely
   supported by C compilers.  It's available as _Float16 type, if the
   compiler supports the Annex H of the C23 standard.

   Added in version 3.15.

4. Complex types ("Zf" and "Zd") are available unconditionally,
   regardless on support for complex types (the Annex G of the C11
   standard) by the C compiler. As specified in the C11 standard, each
   complex type is represented by a two-element C array containing,
   respectively, the real and imaginary parts.

   Added in version 3.15.

参考:

  The ctypes and struct modules, as well as third-party modules like
  numpy, use similar -- but slightly different -- type codes.

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

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

array.typecodes

   A tuple with all available type codes.

   バージョン 3.15 で変更: The type changed from "str" to "tuple".

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

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.

   Array objects support the ordinary mutable *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 *bytes-like objects* are supported.

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

   typecode

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

   itemsize

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

   append(value, /)

      Append a new item with the specified value to the end of the
      array.

   buffer_info()

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

      注釈:

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

   byteswap()

      "Byteswap" all items of the array.  This is only supported for
      values which are 1, 2, 4, 8 or 16 bytes in size; for other types
      of values, "RuntimeError" is raised.  It is useful when reading
      data from a file written on a machine with a different byte
      order.  Note, that for complex types the order of components
      (the real part, followed by imaginary part) is preserved.

   count(value, /)

      Return the number of occurrences of *value* in the array.

   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(ustr, /)

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

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

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

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

   insert(index, value, /)

      Insert a new item *value* in the array before position *index*.
      Negative values are treated as being relative to the end of the
      array.

   pop(index=-1, /)

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

   remove(value, /)

      Remove the first occurrence of *value* from the array.

   clear()

      Remove all elements from the array.

      Added in version 3.13.

   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'" or "'w'"; 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'" 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 パッケージは、別の配列型を定義しています。
