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

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

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

+-------------+----------------------+---------------------+-------------------------+---------+
| 类型码      | C 类型               | Python 类型         | 以字节表示的最小尺寸    | 注释    |
|=============|======================|=====================|=========================|=========|
| "'b'"       | signed char          | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'B'"       | unsigned char        | int                 | 1                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'u'"       | Py_UNICODE           | Unicode 字符        | 2                       | (1)     |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'h'"       | signed short         | int                 | 2                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'H'"       | unsigned short       | int                 | 2                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'i'"       | signed int           | int                 | 2                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'I'"       | 无符号整型           | int                 | 2                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'l'"       | signed long          | int                 | 4                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'L'"       | 无符号长整型         | int                 | 4                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'q'"       | signed long long     | int                 | 8                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'Q'"       | 无符号 long long     | int                 | 8                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'f'"       | float                | float               | 4                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+
| "'d'"       | double               | float               | 8                       |         |
+-------------+----------------------+---------------------+-------------------------+---------+

注释:

1. "'u'" 类型码对应于 Python 中已过时的 unicode 字符 ("Py_UNICODE"
   即 "wchar_t")。 根据系统平台的不同，它可能是 16 位或 32 位。

   "'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* 值进行初始化，该值必须为一个列表、*bytes-like object*
   或包含正确类型元素的可迭代对象。

   如果给定一个列表或字符串，该 initializer 会被传给新数组的
   "fromlist()", "frombytes()" 或 "fromunicode()" 方法（见下文）以将初
   始条目添加到数组中。 否则会将可迭代对象作为 initializer 传给
   "extend()" 方法。

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

array.typecodes

   包含所有可用类型码的字符串。

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

以下数据项和方法也受到支持：

array.typecode

   用于创建数组的类型码字符。

array.itemsize

   在内部表示中一个数组项的字节长度。

array.append(x)

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

array.buffer_info()

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

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

array.byteswap()

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

array.count(x)

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

array.extend(iterable)

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

array.frombytes(s)

   Appends items from the string, interpreting the string as an array
   of machine values (as if it had been read from a file using the
   "fromfile()" method).

   3.2 新版功能: "fromstring()" is renamed to "frombytes()" for
   clarity.

array.fromfile(f, n)

   Read *n* items (as machine values) from the *file object* *f* and
   append them to the end of the array.  If less than *n* items are
   available, "EOFError" is raised, but the items that were available
   are still inserted into the array. *f* must be a real built-in file
   object; something else with a "read()" method won't do.

array.fromlist(list)

   Append items from the list.  This is equivalent to "for x in list:
   a.append(x)" except that if there is a type error, the array is
   unchanged.

array.fromstring()

   Deprecated alias for "frombytes()".

array.fromunicode(s)

   Extends this array with data from the given unicode string.  The
   array must be a type "'u'" array; otherwise a "ValueError" is
   raised.  Use "array.frombytes(unicodestring.encode(enc))" to append
   Unicode data to an array of some other type.

array.index(x)

   Return the smallest *i* such that *i* is the index of the first
   occurrence of *x* in the array.

array.insert(i, x)

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

array.pop([i])

   Removes the item with the index *i* from the array and returns it.
   The optional argument defaults to "-1", so that by default the last
   item is removed and returned.

array.remove(x)

   Remove the first occurrence of *x* from the array.

array.reverse()

   Reverse the order of the items in the array.

array.tobytes()

   Convert the array to an array of machine values and return the
   bytes representation (the same sequence of bytes that would be
   written to a file by the "tofile()" method.)

   3.2 新版功能: "tostring()" is renamed to "tobytes()" for clarity.

array.tofile(f)

   Write all items (as machine values) to the *file object* *f*.

array.tolist()

   Convert the array to an ordinary list with the same items.

array.tostring()

   Deprecated alias for "tobytes()".

array.tounicode()

   Convert the array to a unicode string.  The array must be a type
   "'u'" array; otherwise a "ValueError" is raised. Use
   "array.tobytes().decode(enc)" to obtain a unicode string from an
   array of some other type.

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

  Numerical Python 文档
     Numeric Python 扩展 (NumPy) 定义了另一种数组类型；请访问
     http://www.numpy.org/ 了解有关 Numerical Python 的更多信息。
