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