数据类型 API#

标准数组可以拥有 25 种不同的数据类型（并且支持添加您自己的类型）。所有这些数据类型都有一个枚举类型、一个枚举类型字符以及一个对应的数组标量 Python 类型对象（位于一个层级结构中）。还提供了标准的 C typedefs，以便更容易地操作给定数据类型的元素。对于数值类型，还提供了按位宽相等的 C typedefs 和命名类型编号，以便更容易地选择所需的精度。

警告

C 代码中的类型名称遵循 C 命名约定。这些类型的 Python 名称遵循 Python 约定。因此，NPY_FLOAT 在 C 中表示 32 位浮点数，而在 Python 中，numpy.float64 对应于 64 位双精度浮点数。按位宽命名的类型在 Python 和 C 中都可以用于提高清晰度。

枚举类型#

enum NPY_TYPES#

提供了一个枚举类型列表，其中包含基本的 25 种数据类型以及一些有用的通用名称。每当代码需要类型编号时，都会请求其中一个枚举类型。所有类型都称为 NPY_{NAME}

enumerator NPY_BOOL#: 布尔类型的枚举值，存储为 1 字节。它只能设置为 0 和 1。

enumerator NPY_BYTE#

enumerator NPY_INT8#: 8 位/1 字节有符号整数的枚举值。

enumerator NPY_SHORT#

enumerator NPY_INT16#: 16 位/2 字节有符号整数的枚举值。

enumerator NPY_INT#

enumerator NPY_INT32#: 32 位/4 字节有符号整数的枚举值。

enumerator NPY_LONG#: 根据平台，等同于 NPY_INT 或 NPY_LONGLONG。

enumerator NPY_LONGLONG#

enumerator NPY_INT64#: 64 位/8 字节有符号整数的枚举值。

enumerator NPY_UBYTE#

enumerator NPY_UINT8#: 8 位/1 字节无符号整数的枚举值。

enumerator NPY_USHORT#

enumerator NPY_UINT16#: 16 位/2 字节无符号整数的枚举值。

enumerator NPY_UINT#

enumerator NPY_UINT32#: 32 位/4 字节无符号整数的枚举值。

enumerator NPY_ULONG#: 根据平台，等同于 NPY_UINT 或 NPY_ULONGLONG。

enumerator NPY_ULONGLONG#

enumerator NPY_UINT64#: 64 位/8 字节无符号整数的枚举值。

enumerator NPY_HALF#

enumerator NPY_FLOAT16#: 符合 IEEE 754-2008 标准的 16 位/2 字节浮点类型的枚举值。

enumerator NPY_FLOAT#

enumerator NPY_FLOAT32#: 符合 IEEE 754 标准的 32 位/4 字节浮点类型的枚举值。

enumerator NPY_DOUBLE#

enumerator NPY_FLOAT64#: 符合 IEEE 754 标准的 64 位/8 字节浮点类型的枚举值。

enumerator NPY_LONGDOUBLE#: 平台特定的浮点类型的枚举值，该类型至少与 NPY_DOUBLE 一样大，但在许多平台上更大。

enumerator NPY_CFLOAT#

enumerator NPY_COMPLEX64#: 由两个 NPY_FLOAT 值组成的 64 位/8 字节复数类型的枚举值。

enumerator NPY_CDOUBLE#

enumerator NPY_COMPLEX128#: 由两个 NPY_DOUBLE 值组成的 128 位/16 字节复数类型的枚举值。

enumerator NPY_CLONGDOUBLE#: 由两个 NPY_LONGDOUBLE 值组成的平台特定复数浮点类型的枚举值。

enumerator NPY_DATETIME#: 包含日期或日期时间的数据类型的枚举值，其精度基于可选的日期或时间单位。

enumerator NPY_TIMEDELTA#: 包含时间长度的数据类型的枚举值，以可选的日期或时间单位的整数表示。

enumerator NPY_STRING#: 固定最大长度的、用空字符填充的字节字符串的枚举值。在给定的数组中，字符串具有固定的最大长度。

enumerator NPY_UNICODE#: 可变长度 UCS4 字符串的枚举值。在给定的数组中，字符串具有固定的最大长度。

enumerator NPY_VSTRING#: UTF-8 可变宽度字符串的枚举值。请注意，此 DType 包含一个引用数组，字符串数据存储在数组缓冲区之外。要访问每个数组条目中的字符串数据，请使用 C API 处理 NumPy 可变宽度静态字符串。

注意

此 DType 是新式 DType，不包含在 NPY_NTYPES_LEGACY 中。

enumerator NPY_OBJECT#: 任意 Python 对象引用的枚举值。

enumerator NPY_VOID#: 主要用于存储结构体 DType，但也可以包含任意二进制数据。

上述类型的一些有用别名是

enumerator NPY_INTP#: 类型 Py_ssize_t（如果定义了，则与 ssize_t 相同）的有符号整数的枚举值。这是所有索引数组使用的类型。

版本 2.0 中已更改：以前，这与 intptr_t（指针大小相同）相同。在实践中，除了在非常小众的平台上，这都是相同的。您可以使用字符代码 'p' 来表示指针含义。

enumerator NPY_UINTP#: 与 C size_t 相同的无符号整数类型的枚举值。

版本 2.0 中已更改：以前，这与 uintptr_t（指针大小相同）相同。在实践中，除了在非常小众的平台上，这都是相同的。您可以使用字符代码 'P' 来表示指针含义。

enumerator NPY_MASK#: 用于掩码的类型的枚举值，例如与 NPY_ITER_ARRAYMASK 迭代器标志一起使用。这等同于 NPY_UINT8。

enumerator NPY_DEFAULT_TYPE#: 在未明确指定 dtype 时使用的默认类型，例如在调用 np.zero(shape) 时。这等同于 NPY_DOUBLE。

其他有用的相关常量是

NPY_NTYPES_LEGACY#: 使用旧式 DType 系统编写的内置 NumPy 类型的数量。新的 NumPy DType 将使用新的 DType API 编写，并且可能与旧式 DType 的行为不同。如果您想使用不同的代码路径处理旧式 DType，或者您不想更新使用 NPY_NTYPES_LEGACY 且与新 DType 不能正常工作的代码，请使用此宏。

注意

新添加的 DType，如 NPY_VSTRING，将不会计入 NPY_NTYPES_LEGACY。

NPY_NOTYPE#: 一个保证不是有效类型枚举数的信号值。

NPY_USERDEF#: 用于旧式自定义数据类型的类型编号的起始点。新式用户 DType 目前**不**被分配类型编号。

注意

用户 DType 的总数限制在 NPY_VSTRING 以下。更高的数字保留给未来的新式 DType 使用。

指示某些类型的各种字符代码也是枚举列表的一部分。类型字符的引用（如果需要的话）应始终使用这些枚举。其形式为 NPY_{NAME}LTR，其中 {NAME} 可以是

BOOL, BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG, LONGLONG, ULONGLONG, HALF, FLOAT, DOUBLE, LONGDOUBLE, CFLOAT, CDOUBLE, CLONGDOUBLE, DATETIME, TIMEDELTA, OBJECT, STRING, UNICODE, VSTRING, VOID

INTP, UINTP

GENBOOL, SIGNED, UNSIGNED, FLOATING, COMPLEX

后者组的 {NAME}s 对应于数组接口类型字符串规范中使用的字母。

定义#

整数的最大值和最小值#

NPY_MAX_INT{bits}, NPY_MAX_UINT{bits}, NPY_MIN_INT{bits}: 这些为 {bits} = 8, 16, 32, 64, 128 和 256 定义，并提供相应（无符号）整数类型的最大（最小）值。注意：实际整数类型可能并非在所有平台上都可用（例如，128 位和 256 位整数很罕见）。
NPY_MIN_{type}: 这些为 {type} = BYTE, SHORT, INT, LONG, LONGLONG, INTP 定义。
NPY_MAX_{type}: 这些为所有定义的 {type} = BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG, LONGLONG, ULONGLONG, INTP, UINTP 定义。

数据类型的位数#

所有 NPY_SIZEOF_{CTYPE} 常量都有对应的 NPY_BITSOF_{CTYPE} 常量定义。 NPY_BITSOF_{CTYPE} 常量提供数据类型的位数。具体来说，可用的 {CTYPE}s 是

BOOL, CHAR, SHORT, INT, LONG, LONGLONG, FLOAT, DOUBLE, LONGDOUBLE

按位宽引用的枚举类型编号#

所有数值数据类型（整数、浮点数和复数）都有定义为特定枚举类型编号的常量。具体来说，按位宽类型引用哪个枚举类型取决于平台。特别是，可用的常量是 PyArray_{NAME}{BITS}，其中 {NAME} 是 INT, UINT, FLOAT, COMPLEX，而 {BITS} 可以是 8, 16, 32, 64, 80, 96, 128, 160, 192, 256 和 512。显然，并非所有平台的数值类型都提供所有位宽。通常提供 8、16、32、64 位整数；32、64 位浮点数；以及 64、128 位复数类型。

进一步的整数别名#

常量 NPY_INTP 和 NPY_UINTP 指的是 Py_ssize_t 和 size_t。虽然在实践中通常如此，但严格来说，这些类型不是指针大小，并且字符代码 'p' 和 'P' 可用于指针大小的整数。（在 NumPy 2 之前，intp 是指针大小，但这几乎从未匹配实际使用，这也是名称的原因。）

自 NumPy 2 起，还定义了 NPY_DEFAULT_INT。宏的值取决于运行时：自 NumPy 2 起，它映射到 NPY_INTP，而在早期版本中，它映射到 NPY_LONG。

C 类型名称#

对于每种数值数据类型和布尔数据类型，都有标准的变量类型。其中一些在 C 规范中已经可用。您可以在扩展代码中创建这些类型的变量。

布尔值#

type npy_bool#: unsigned char；常量 NPY_FALSE 和 NPY_TRUE 也已定义。

(无符号) 有符号整数#

整数的无符号版本可以通过在整数名称前面加上“u”来定义。

type npy_byte#: char

type npy_ubyte#: unsigned char

type npy_short#: short

type npy_ushort#: unsigned short

type npy_int#: int

type npy_uint#: unsigned int

type npy_int16#: 16 位整数

type npy_uint16#: 16 位无符号整数

type npy_int32#: 32 位整数

type npy_uint32#: 32 位无符号整数

type npy_int64#: 64 位整数

type npy_uint64#: 64 位无符号整数

type npy_long#: long int

type npy_ulong#: unsigned long int

type npy_longlong#: long long int

type npy_ulonglong#: unsigned long long int

type npy_intp#: Py_ssize_t（一个与 C size_t 大小相同的有符号整数）。这是长度或索引的正确整数。实际上，这通常是指针的大小，但并非保证如此。

注意

在 NumPy 2.0 之前，这与 Py_intptr_t 相同。虽然更匹配，但在实际使用中并不符合。在 Python 端，我们仍然支持 np.dtype('p') 来获取与存储指针兼容的 dtype，而 n 是 ssize_t 的正确字符。

type npy_uintp#: C size_t/Py_size_t。

(复数) 浮点数#

type npy_half#: 16 位浮点数

type npy_float#: 32 位浮点数

type npy_cfloat#: 32 位复数浮点数

type npy_double#: 64 位双精度浮点数

type npy_cdouble#: 64 位复数双精度浮点数

type npy_longdouble#: long double

type npy_clongdouble#: long complex double

复数类型是具有 **.real** 和 **.imag** 成员（按此顺序）的结构体。

按位宽命名的类型#

还为特定位宽的有符号整数、无符号整数、浮点数和复数浮点数类型提供了 typedef。可用的类型名称为

npy_int{bits}, npy_uint{bits}, npy_float{bits}, and npy_complex{bits}

其中 {bits} 是类型的位数，对于整数类型可以是 8, 16, 32, 64, 128 和 256；对于浮点类型可以是 16, 32, 64, 80, 96, 128 和 256；对于复数值类型可以是 32, 64, 128, 160, 192 和 512。哪些位宽可用取决于平台。粗体位宽通常在所有平台上都可用。

时间和时间差#

type npy_datetime#: 日期或日期时间（npy_int64 的别名）

type npy_timedelta#: 时间长度（npy_int64 的别名）

Printf 格式化#

为了帮助打印，以下字符串被定义为 printf 和相关命令中的正确格式说明符。

NPY_LONGLONG_FMT#

NPY_ULONGLONG_FMT#

NPY_INTP_FMT#

NPY_UINTP_FMT#

NPY_LONGDOUBLE_FMT#