"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/ 。
