array --- 高效的数值数组

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

类型码

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'

浮点数

浮点数

4

'd'

double

浮点数

8

备注

  1. 根据平台的不同，可以是 16 位或 32 位。

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

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

  2. 在 3.13 版本加入。

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

该模块定义了以下项：

array.typecodes

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

该模块定义了以下类型：

class array.array(typecode[, initializer])

一个新数组，其元素受 *typecode* 限制，并由可选的 *initializer* 值进行初始化，该值必须是 bytes 或 bytearray 对象、Unicode 字符串，或包含适当类型元素的可迭代对象。

如果给定一个 bytes 或 bytearray 对象，初始化程序将被传递给新数组的 frombytes() 方法；如果给定一个 Unicode 字符串，初始化程序将被传递给 fromunicode() 方法；否则，初始化程序的迭代器将被传递给 extend() 方法，以向数组添加初始项。

数组对象支持普通的序列操作，如索引、切片、拼接和重复。当使用切片赋值时，所赋的值必须是具有相同类型码的数组对象；在所有其他情况下，会引发 TypeError。数组对象也实现了缓冲区接口，并且可以在任何支持 类字节对象 的地方使用。

引发一个参数为 typecode, initializer 的 审计事件 array.__new__。

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

从 类字节对象 中追加项目，将其内容解释为机器值数组（就好像它是使用 fromfile() 方法从文件中读取的一样）。

在 3.2 版本加入: 为了清晰起见，fromstring() 已重命名为 frombytes()。

fromfile(f, n)

从 文件对象 *f* 中读取 *n* 个项（作为机器值），并将其追加到数组的末尾。如果可用的项少于 *n* 个，则引发 EOFError，但可用的项仍会插入到数组中。

fromlist(list)

从列表中追加项。这等效于 for x in list: a.append(x)，不同之处在于，如果出现类型错误，数组将保持不变。

fromunicode(s)

用给定的 Unicode 字符串中的数据扩展此数组。数组的类型码必须是 'u' 或 'w'；否则会引发 ValueError。要将 Unicode 数据追加到其他类型的数组中，请使用 array.frombytes(unicodestring.encode(enc))。

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

返回最小的 *i*，使得 *i* 是 *x* 在数组中首次出现的索引。可选参数 *start* 和 *stop* 可用于在数组的子切片中搜索 *x*。如果未找到 *x*，则引发 ValueError。

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

insert(i, x)

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

pop([i])

从数组中移除索引为 *i* 的项并返回它。可选参数默认为 -1，因此默认情况下会移除并返回最后一个项。

remove(x)

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

clear()

从数组中移除所有元素。

在 3.13 版本加入。

reverse()

反转数组中项的顺序。

tobytes()

将数组转换为机器值数组，并返回字节表示（与通过 tofile() 方法写入文件的字节序列相同）。

在 3.2 版本加入: 为了清晰起见，tostring() 已重命名为 tobytes()。

tofile(f)

将所有项（作为机器值）写入 文件对象 *f*。

tolist()

将数组转换为具有相同项的普通列表。

tounicode()

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

数组对象的字符串表示形式为 array(typecode, initializer)。如果数组为空，则省略 *initializer*；否则，如果 *typecode* 是 'u' 或 'w'，它是一个 Unicode 字符串，否则它是一个数字列表。只要通过 from array import array 导入了 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 包定义了另一种数组类型。