"array" --- 高效的数值数组
**************************

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

This module defines an object type which can compactly represent an
array of basic values: characters, integers, floating-point 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*,
which is a single character.  The following type codes are defined:

+-------------+----------------------+---------------------+-------------------------+---------+
| 类型码      | C 类型               | Python 类型         | 最小字节数              | 备注    |
|=============|======================|=====================|=========================|=========|
| "'b'"       | signed char          | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'B'"       | unsigned char        | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'u'"       | wchar_t              | Unicode 字符        | 2                       | (1)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'w'"       | Py_UCS4              | Unicode 字符        | 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                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'f'"       | float                | float               | 4                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'d'"       | double               | float               | 8                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+

备注：

1. 可能为 16 位或 32 位，取决于具体的平台。

   在 3.9 版本发生变更: "array('u')" 现在使用 "wchar_t" 作为 C 类型而
   不是已不建议使用的 "Py_UNICODE"。这个改变不会影响其行为，因为
   "Py_UNICODE" 自 Python 3.3 起就是 "wchar_t" 的别名。

   从 3.3 版起已弃用，将在 3.16 版中移除: 请迁移到 "'w'" 类型码。

2. Added in version 3.13.

参见:

  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 string with all available type codes.

此模块定义了以下类型：

class array.array(typecode[, initializer])

   一个由 *typecode* 限定其条目的新数组，并能根据可选的 *initializer*
   值来初始化。*initializer* 必须是 "bytes" 或 "bytearray" 对象、
   Unicode 字符串或元素类型合适的可迭代对象。

   如果给定了一个 "bytes" 或 "bytearray" 对象，则将 *initializer* 传给
   新数组的 "frombytes()" 方法；如果给定了一个 Unicode 字符串，则将
   *initializer* 传给 "fromunicode()" 方法；在其他情况下，则将
   *initializer* 的迭代器传给 "extend()" 方法以向数组添加初始条目。

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

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

   typecode

      在创建数组时使用的类型码字符。

   itemsize

      内部表示中，单个数组项的长度。单位为字节。

   append(value, /)

      Append a new item with the specified value to the end of the
      array.

   buffer_info()

      返回一个元组 "(address, length)" 给出存放数组内容的内存缓冲区的
      当前地址和长度（以元素个数为单位）。以字节为单位的内存缓冲区大小
      可通过 "array.buffer_info()[1] * array.itemsize" 来计算。工作在
      需要内存地址的底层（因此天然地不够安全）的 I/O 接口上时，这有时
      会有用，例如某些 "ioctl()" 操作。只要数组还存在，并且没有对其应
      用过改变长度的操作，则返回的数值就是有效的。

      备注:

        只有在使用以 C 或 C++ 编写的代码中的数组对象时，才能有效利用该
        信息，但此时，更合理的是，使用数组对象支持的缓冲区接口。因此，
        该方法的存在仅仅是为了向后兼容性，应避免在新代码中使用。缓冲区
        接口的文档参见 缓冲协议.

   byteswap()

      "Byteswap" all items of the array.  This is only supported for
      values which are 1, 2, 4, or 8 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.

   count(value, /)

      Return the number of occurrences of *value* in the array.

   extend(iterable, /)

      将来自 *iterable* 的项添加到数组末尾。如果 *iterable* 是另一个数
      组，它必须具有 *完全* 相同的类型码；否则将引发 "TypeError"。如果
      *iterable* 不是一个数组，则它必须为可迭代对象且其元素的类型须为
      可添加到数组的适当类型。

   frombytes(buffer, /)

      添加来自 *bytes-like object* 的条目，将其内容解读为由机器值组成
      的数组（就像是使用 "fromfile()" 方法从文件中读取内容一样）。

      Added in version 3.2: "fromstring()" 被重命名为含义更准确的
      "frombytes()"。

   fromfile(f, n, /)

      从 *file object* *f* 中读取 *n* 项（视为机器值）并将它们添加到数
      组末尾。如果可用的项少于 *n* 项，则会引发 "EOFError"，但可用的项
      仍然会被加进数组。

   fromlist(list, /)

      将来自列表的项添加到数组末尾。等价于 "for x in list:
      a.append(x)"，而不同之处在于，若发生类型错误，数组则不会被改变。

   fromunicode(ustr, /)

      使用来自给定的 Unicode 字符串的数据扩展该数组。该数组的类型码必
      须为 "'u'" 或 "'w'"；否则将引发 "ValueError"。请使用
      "array.frombytes(unicodestring.encode(enc))" 将 Unicode 数据添加
      到其他类型的数组。

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

      Return the smallest *i* such that *i* is the index of the first
      occurrence of *value* in the array.  The optional arguments
      *start* and *stop* can be specified to search for *value* within
      a subsection of the array.  Raise "ValueError" if *value* is not
      found.

      在 3.10 版本发生变更: 添加了可选的 *start* 和 *stop* 形参。

   insert(index, value, /)

      Insert a new item *value* in the array before position *index*.
      Negative values are treated as being relative to the end of the
      array.

   pop(index=-1, /)

      从数组中移除下标为 *i* 的项并将其返回。可选参数默认值为 "-1"，因
      此默认移除并返回末项。

   remove(value, /)

      从数组中移除第一个出现的 *value*。

   clear()

      从数组中移除所有元素。

      Added in version 3.13.

   reverse()

      反转数组中各项的顺序。

   tobytes()

      将数组转换为一个由机器值组成的数组并返回其字节表示（和用
      "tofile()" 方法写入文件的字节序列相同）。

      Added in version 3.2: "tostring()" 被重命名为含义更准确的
      "tobytes()"。

   tofile(f, /)

      将所有项（作为机器值）写入 *file object* *f*。

   tolist()

      将数组转换为由相同的项组成的普通列表。

   tounicode()

      将数组转换为一个 Unicode 字符串。数组的类型必须为 "'u'" 或 "'w'"
      ；否则将引发 "ValueError"。 请使用 "array.tobytes().decode(enc)"
      来从其他类型的数组获取 Unicode 字符串。

数组对象的字符串表示形式是 "array(typecode, initializer)"。如果数组为
空则 *initializer* 将被省略，否则如果 *typecode* 为 "'u'" 或 "'w'" 则
为 Unicode 字符串，否则为由数字组成的列表。只要 "array" 类是使用 "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 包定义了另一数组类型。
