"array" --- 高效率的數值型陣列
******************************

======================================================================

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

+-------------+----------------------+---------------------+-------------------------+---------+
| Type code   | C Type               | Python Type         | 所需的最小位元組        | 註解    |
|             |                      |                     | (bytes)                 |         |
|=============|======================|=====================|=========================|=========|
| "'b'"       | signed char          | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'B'"       | unsigned char        | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'u'"       | wchar_t              | 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. 根據平台的不同，它有可能是 16 位元或者 32 位元。

   3.9 版更變: 目前 "array(‘u’)" 使用 "wchar_t" 取代已棄用的
   "Py_UNICODE" 作為 C type。這個異動並沒有影響到它的作用，因爲自從
   Python 3.3 開始 "Py_UNICODE" 即為 "wchar_t" 的別名。

   自從版本 3.3 後不推薦使用，將會自版本 4.0 中移除。.

The actual representation of values is determined by the machine
architecture (strictly speaking, by the C implementation).  The actual
size can be accessed through the "array.itemsize" attribute.

The module defines the following item:

array.typecodes

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

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

class array.array(typecode[, initializer])

   一個新的陣列中的元素被 *typecode* 限制，並由選用的 *initializer* 參
   數初始化，*initializer* 必須是一個 list、*bytes-like object*（類位
   元組串物件）或包含適當型別變數的可疊代物件 (iterable)。

   如果指定一個 list 或 string，新的陣列初始化時會傳入 "fromlist()"、
   "frombytes()" 或 "fromunicode()" 方法（參照下方）將元素新增到其中。
   其他情況時， 一個 iterable initializer 將被傳入 "extend()" 方法之中
   。

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

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

   typecode

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

   itemsize

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

   append(x)

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

   buffer_info()

      Return a tuple "(address, length)" giving the current memory
      address and the length in elements of the buffer used to hold
      array's contents.  The size of the memory buffer in bytes can be
      computed as "array.buffer_info()[1] * array.itemsize".  This is
      occasionally useful when working with low-level (and inherently
      unsafe) I/O interfaces that require memory addresses, such as
      certain "ioctl()" operations.  The returned numbers are valid as
      long as the array exists and no length-changing operations are
      applied to it.

      備註:

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

   byteswap()

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

   count(x)

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

   extend(iterable)

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

   frombytes(s)

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

      3.2 版新加入: "fromstring()" is renamed to "frombytes()" for
      clarity.

   fromfile(f, n)

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

   fromlist(list)

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

   fromunicode(s)

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

   index(x[, start[, stop]])

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

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

   insert(i, x)

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

   pop([i])

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

   remove(x)

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

   reverse()

      反轉陣列中元素的順序。

   tobytes()

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

      3.2 版新加入: "tostring()" is renamed to "tobytes()" for
      clarity.

   tofile(f)

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

   tolist()

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

   tounicode()

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

當一個陣列物件被列印或轉換成字串時，它會被表示為 "array(typecode,
initializer)"。若為空陣列則參數 *initializer* 被省略，若 *typecode* 是
"’u’" 將被表示為字串，其他情況則被表示為由數字組成的 list。只要
"array" class（類別）透過 "from array import array" 的方式引入，便能確
保該字串能透過 "eval()" 轉換回一個擁有相同型別及數值的陣列。範例：

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

  NumPy
     NumPy 套件定義了另一個陣列型別
