"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 的字串。

Array objects support the ordinary 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.

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

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

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

   "frombytes()" 方法的另一個（已經過時的）名字。

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

   "tobytes()" 方法的另一個（已經過時的）名字。

array.tounicode()

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

When an array object is printed or converted to a string, it is
represented as "array(typecode, initializer)".  The *initializer* is
omitted if the array is empty, otherwise it is a string if the
*typecode* is "'u'", otherwise it is a list of numbers.  The string 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". Examples:

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

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