"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                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'u'"       | wchar_t              | Unicode character   | 2                       | (1)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'w'"       | Py_UCS4              | Unicode character   | 4                       | (2)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'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                       | (3)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'f'"       | float                | float               | 4                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'d'"       | double               | float               | 8                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'Zf'"      | float complex        | complex             | 8                       | (4)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'Zd'"      | double complex       | complex             | 16                      | (4)     |
+-------------+----------------------+---------------------+-------------------------+---------+

註解：

1. 根據平台的不同，它有可能是 16 位元或者 32 位元。

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

   自從版本 3.3 後不推薦使用，已從版本 3.16 中移除。: 請改用 "'w'"
   typecode。

2. 在 3.13 版被加入.

3. 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 版被加入.

4. 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* 的地方使用。

   引發稽核事件 (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, /)

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

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

      將陣列轉為一個 Unicode 字串。陣列的型別必須為 "u" 或 "'w'"；其他
      型別的陣列會引發 "ValueError"。請使用
      "array.tobytes().decode(enc)" 來為其他型別的陣列轉為 Unicode 字
      串。

陣列物件的字串表示形式為 "array(typecode, initializer)"。若為空陣列則
參數 *initializer* 被省略，若 *typecode* 是 "'u'" 或 "'w'" 將被表示為
Unicode 字串，其他情況則被表示為由數字組成的 list。只要 "array" class
（類別）透過 "from array import array" 的方式引入，便能確保該字串表示
能透過 "eval()" 轉換回一個擁有相同型別及數值的陣列。如果它包含相應的浮
點值，"inf" 和 "nan" 也必須被定義。範例：

   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 套件定義了另一個陣列型別
