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, 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

'e'

_Float16

float

2

(3)

'f'

float

float

4

'd'

double

float

8

'F'

float complex

complex

8

(4)

'D'

double complex

complex

16

(4)

备注：

  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.

  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.

    Added in version 3.15.

  4. Complex types (F and D) 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.

    Added in version 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

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

此模块定义了以下类型：

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, 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, /)

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 包定义了另一数组类型。