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:

Type code

C Type

Python Type

所需的最小位元組 (bytes)

註解

'b'

signed char

int

1

'B'

unsigned char

int

1

'w'

Py_UCS4

Unicode character

4

(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

'e'

_Float16

float

2

(2)

'f'

float

float

4

'd'

double

float

8

'Zf'

float complex

complex

8

(3)

'Zd'

double complex

complex

16

(3)

註解：

  1. 在 3.13 版被加入.

  2. 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.

    在 3.15 版被加入.

  3. 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.

    在 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])

一個新的陣列中的元素被 typecode 限制，並由選用的 initializer 參數初始化，initializer 必須是一個 bytes 或 bytearray 物件、一個 Unicode 字串或包含適當型別元素的可疊代物件 (iterable)。

如果給定的是一個 bytes 或 bytearray 物件，新的陣列初始化時會傳入 frombytes() 方法；如為 Unicode 字串則會傳入 fromunicode() 方法；其他情況時， 一個 initializer 的可疊代物件將被傳入 extend() 方法之中來將初始項目新增至陣列。

陣列支援常見的可變序列操作，包含索引 (indexing)、切片 (slicing)、串接 (concatenation)、相乘 (multiplication) 等。當使用切片進行賦值時，賦值的陣列必須具備相同的 type code，其他型別的數值將導致 TypeError。陣列同時也實作了緩衝區介面，可以在任何支援 bytes-like objects 的地方使用。

Arrays are generic over the type of their contents.

引發稽核事件 (auditing event) array.__new__ 並附帶引數 typecode、initializer。

typecode

typecode 字元被用在建立陣列時。

itemsize

陣列當中的一個元素在內部需要的位元組長度。

append(value, /)

新增一個指定值的新元素到陣列的最尾端。

buffer_info()

回傳一個 tuple (address, length) 表示目前的記憶體位置和陣列儲存元素的緩衝區記憶體長度。緩衝區的長度單位是位元組，並可以用 array.buffer_info()[1] * array.itemsize 計算得到。這偶爾會在底層操作需要記憶體位置的輸出輸入時很有用，例如 ioctl() 指令。只要陣列存在且沒有使用任何更改長度的操作時，回傳的數值就有效。

備註

當使用來自 C 或 C++ 程式碼（這是唯一使得這個資訊有效的途徑）的陣列物件時，更適當的做法是使用陣列物件支援的緩衝區介面。這個方法維護了向後兼容性，並應該在新的程式碼中避免。關於緩衝區介面的文件在緩衝協定 (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, /)

回傳 value 在陣列中出現了幾次。

extend(iterable, /)

從 iterable 中新增元素到陣列的尾端，如果 iterable 是另一個陣列，它必須有完全相同的 type code，如果不同會導致 TypeError。如果 iterable 不是一個陣列，它必須可以被疊代 (iterable) 且其中的元素必須是可以被加入陣列中的正確型別。

frombytes(buffer, /)

從 bytes-like object 中新增元素。讀取時會將其內容當作一個機器數值組成的陣列（就像從檔案中使用 fromfile() 方法讀出的資料）。

在 3.2 版被加入: 將 fromstring() 更名為 frombytes()，使其更加清晰易懂。

fromfile(f, n, /)

從 file object f 讀取 n 個元素（作為機器數值），接著將這些元素加入陣列的最尾端。如果只有少於 n 個有效的元素會導致 EOFError，但有效的元素仍然會被加入陣列中。

fromlist(list, /)

從 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 '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]])

回傳 i 的最小數值，使得 i 成為陣列之中第一次出現 value 的索引。選擇性的引數 start 及 stop 則可以被用來在指定的陣列空間中搜尋 value。如果 value 不存在將導致 ValueError。

在 3.10 版的變更: 新增選擇性的參數 start 及 stop。

insert(index, value, /)

在位置 index 之前插入一個元素 value。負數的索引值會從陣列尾端開始數。

pop(index=-1, /)

移除並回傳陣列索引值 i 的元素。選擇性的引數 i 預設為 -1，所以預設會刪除並回傳最後一個元素。

remove(value, /)

從陣列中刪除第一個出現的 value。

clear()

從陣列中刪除所有元素。

在 3.13 版被加入.

reverse()

反轉陣列中元素的順序。

tobytes()

將陣列轉為另一個機器數值組成的陣列並回傳它的位元組表示（跟用 tofile() 方法寫入檔案時的位元序列相同）。

在 3.2 版被加入: 為了明確性，過去的 tostring() 已更名為 tobytes()。

tofile(f, /)

將所有元素（作為機器數值）寫入 file object f。

tolist()

不更改元素，將陣列轉為一般的 list。

tounicode()

Convert the array to a Unicode string. The array must have a type '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 '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 套件定義了另一個陣列型別