# `array` --- 高效率的數值型態陣列

這個模組定義了一個物件型別，可以簡潔的表達一個包含基本數值的陣列：字元、整數、浮點數。陣列是一個非常類似 list 的序列型態，除了陣列會限制儲存的物件型別。在建立陣列時可以使用一個字元的 type code 來指定儲存的資料型別。下面是 type codes 的定義。

Type code | C Type | Python Type | 最小所需的位元組 | 註解
--- | --- | --- | --- | ---
`'b'` | signed char | int | 1 |
`'B'` | unsigned char | int | 1 |
`'u'` | Py_UNICODE | Unicode character | 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'` | float | float | 4 |
`'d'` | double | float | 8 |

註解：

1. `u` type code 對應到的是 Python 過去的 unicode 字母（ `Py_UNICODE` 是 `wchar_t` ）。根據平台不同，他有可能是 16 bits 或 32 bits。

   `'u'` 會跟著 `Py_UNICODE` API 的停用一起被移除。

   Deprecated since version 3.3, will be removed in version 4.0.

實際上數值的表示方法是被機器的架構所決定（更精準地說，被 C 的實作方法決定）。實際的大小可以透過 `itemsize` 屬性存取。

這個模組定義了下方的型別：

class `array.``array`(typecode[, initializer])

  一個新的陣列中的元素被 typecode 限制，並由選用的 initializer 參數初始化， initializer 必須是一個 list、 bytes-like object 或包含適當型別變數的 iterable 。

  如果指定一個 list 或 string ，新的陣列初始化時會傳入 `fromlist()` 、 `frombytes()` 或 `fromunicode()` 方法（參照下方）將元素新增到其中。其他型態的變數則會傳入 `extend()` 方法初始化。

  引发一个 审计事件 `array.__new__` 附带参数 `typecode`, `initializer`。

`array.``typecodes`

  一個包含所有可用的 type code 的字串。

数组对象支持普通的序列操作如索引、切片、拼接和重复等。 当使用切片赋值时，所赋的值必须为具有相同类型码的数组对象；所有其他情况都将引发 `TypeError`。 数组对象也实现了缓冲区接口，可以用于所有支持 字节类对象 的场合。

提供下方的資料物件與方法。

`array.``typecode`

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

`array.``itemsize`

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

`array.``append`(x)

  新增一個元素 x 到陣列的最尾端。

`array.``buffer_info`()

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

  備註

  當使用來自 C 或 C++ 程式碼（這是唯一使得這個資訊有效的途徑） 的陣列物件時，更適當的做法是使用陣列物件支援的緩衝區介面。這個方法維護了向後兼容性，並應該在新的程式碼中避免。關於緩衝區介面的文件在 缓冲协议 。

`array.``byteswap`()

  "Byteswap" 所有陣列中的物件。這只有支援物件長度為 1、2、4 或 8 位元組的陣列，其他型別的值會導致 `RuntimeError` 。這在從機器讀取位元順序不同的檔案時很有用。

`array.``count`(x)

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

`array.``extend`(iterable)

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

`array.``frombytes`(s)

  從字串中新增元素。讀取時會將字串當作一個陣列，裡面包含了 machine value（就像從檔案中使用 `fromfile()` 方法讀出的資料）。

  3.2 版新加入: 為了更明確，之前的 `fromstring()` 被更名為 `frombytes()` 。

`array.``fromfile`(f, n)

  從 file object f 讀取 n 個 machine value 類型的元素，接著將這些元素加入陣列的最尾端。如果只有少於 n 個有效的元素會產生 `EOFError` 錯誤，但有效的元素仍然會被加入陣列中。 f 必須是一個真正的內建檔案物件，其他擁有 `read()` 方法的不行。

`array.``fromlist`(list)

  從 list 中新增元素。這等價於 `for x in list: a.append(x)` ，除了有型態錯誤產生時，陣列會保持原狀不會被更改。

`array.``fromunicode`(s)

  用給定的 unicode 字串擴展這個陣列。陣列必須是型態 `u` 的陣列；其他的型態會產生 `ValueError` 錯誤。使用 `array.frombytes(unicodestring.encode(enc))` 來新增 Unicode 資料到一個其他型態的陣列。

`array.``index`(x)

  回傳最小的 i ，使得 i 是陣列中第一個 x 出現的索引值。

`array.``insert`(i, x)

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

`array.``pop`([i])

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

`array.``remove`(x)

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

`array.``reverse`()

  將整個陣列的元素按照順序逆轉。

`array.``tobytes`()

  將陣列轉為另一個 machine values 的陣列並回傳他的位元組表示（跟用 `tofile()` 方法寫入檔案時的位元序列相同）。

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

`array.``tofile`(f)

  將所有元素 （以 machine code 的形式）寫入 file object f 。

`array.``tolist`()

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

`array.``tounicode`()

  將陣列轉為一個字串。陣列的型態必須為 `u` 。其他型態的陣列會產生 `ValueError` 錯誤。使用 `array.tobytes().decode(enc)` 將其他型態的陣列轉為字串。

当一个数组对象被打印或转换为字符串时，它会表示为 `array(typecode, initializer)`。 如果数组为空则 initializer 会被省略，否则如果 typecode 为 `'u'` 则它是一个字符串，否则它是一个数字列表。 使用 `eval()` 保证能将字符串转换回具有相同类型和值的数组，只要 `array` 类已通过 `from array import array` 被引入。 例如:

    array('l')
    array('u', 'hello \u2641')
    array('l', [1, 2, 3, 4, 5])
    array('d', [1.0, 2.0, 3.14])

也參考

模組 `struct`

  將包含不同資料類型的二進位資料包裝與解開包裝。

模組 `xdrlib`

  將 External Data Representation (XDR) 的資料包裝與解開包裝，這用在一些遠端操作的系統 ( remote procedure call systems ) 。

Numerical Python 文档

  Python 數值運算的擴充 (The Numeric Python extension, NumPy) 定義了另一個陣列型態，更多關於 Python 的數值運算參考 http://www.numpy.org/ 。