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

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

此模块定义了一种对象类型，可以紧凑地表示由基本值（字符、整数、浮点数）
组成的数组。数组是序列类型，其行为与列表非常相似，不同之处在于其中存储
的对象类型是受限的，在数组对象创建时用单个字符的 *类型码* 来指定。已定
义的类型码如下：

+-------------+----------------------+---------------------+-------------------------+---------+
| 类型码      | C 类型               | Python 类型         | 以字节为单位的最小大小  | 备注    |
|=============|======================|=====================|=========================|=========|
| "'b'"       | signed char          | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'B'"       | unsigned char        | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'u'"       | wchar_t              | Unicode 字符        | 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" 作为 C 类型而不是已
   不建议使用的 "Py_UNICODE"。这个改变不会影响其行为，因为
   "Py_UNICODE" 自 Python 3.3 起就是 "wchar_t" 的别名。

   从 3.3 版起不建议使用，将在 4.0 版中移除.

值的实际表示是由机器架构（严格说是由 C 实现）决定的。实际大小可以通过
"array.itemsize" 属性来访问。

此模块定义了以下项目：

array.typecodes

   一个由所有可用的类型码组成的字符串。

此模块定义了以下类型：

class array.array(typecode[, initializer])

   一个由 *typecode* 限制类型的新数组，并通过可选的 *initializer* 进行
   初始化。*initializer* 必须为一个列表、*bytes-like object* 或在合适
   类型元素上迭代的可迭代对象。

   如果是一个列表或字符串，该 initializer 会被传给新数组的
   "fromlist()"，"frombytes()" 或 "fromunicode()" 方法（见下）以将初始
   项添加到数组中。其它将可迭代对象将被传给 "extend()" 方法。

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

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

   typecode

      在创建数组时指定的类型码字符。

   itemsize

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

   append(x)

      添加一个值为 *x* 的新项到数组末尾。

   buffer_info()

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

      备注:

        当在 C 或 C++ 编写的代码中使用数组对象时（这是有效使用此类信息
        的唯一方式），使用数组对象所支持的缓冲区接口更为适宜。 此方法
        仅保留用作向下兼容，应避免在新代码中使用。 缓冲区接口的文档参
        见 缓冲协议。

   byteswap()

      “字节对调”所有数组项。 此方法只支持大小为 1, 2, 4 或 8 字节的值
      ；对于其他值类型将引发 "RuntimeError"。 它适用于从不同字节序机器
      所生成的文件中读取数据的情况。

   count(x)

      返回 *x* 在数组中的出现次数。

   extend(iterable)

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

   frombytes(s)

      添加来自字节串的项，将字符节解读为机器值的数组（相当于使用
      "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(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)

      将值 *x* 作为新项插入数组的 *i* 位置之前。 负值将被视为相对于数
      组末尾的位置。

   pop([i])

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

   remove(x)

      从数组中移除首次出现的 *x*。

   reverse()

      反转数组中各项的顺序。

   tobytes()

      将数组转换为一个机器值数组并返回其字节表示（即相当与通过
      "tofile()" 方法写入到文件的字节序列。）

      3.2 新版功能: "tostring()" 被重命名为含义更准确的 "tobytes()"。

   tofile(f)

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

   tolist()

      将数组转换为包含相同项的普通列表。

   tounicode()

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

当一个数组对象被打印或转换为字符串时，它会表示为 "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) 数据。

  NumPy
     NumPy 软件包定义了另一种数组类型。
