# `array` --- 効率的な数値配列

This module defines an object type which can compactly represent an array of basic values: characters, integers, floating-point 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文字(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 |
`'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 で非推奨、バージョン 3.16 で削除予定: Please migrate to `'w'` typecode.

2. Added in version 3.13.

参考

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

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

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

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()

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

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