数据类型 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

布尔类型的枚举值,存储为一个字节.它只能设置为值 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

16 位/2 字节 IEEE 754-2008 兼容浮点类型的枚举值.

enumerator NPY_FLOAT

enumerator NPY_FLOAT32

32 位/4 字节 IEEE 754 兼容浮点类型的枚举值.

enumerator NPY_DOUBLE

enumerator NPY_FLOAT64

64 位/8 字节 IEEE 754 兼容浮点类型的枚举值.

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保存引用数组,字符串数据存储在数组缓冲区之外.使用用于处理numpy可变宽度静态字符串的C API来访问每个数组条目中的字符串数据.

备注

此DType是新式的,不包含在 NPY_NTYPES_LEGACY 中.

enumerator NPY_OBJECT

对任意Python对象的引用的枚举值.

enumerator NPY_VOID

主要用于保存结构dtypes,但可以包含任意二进制数据.

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

enumerator NPY_INTP

类型为 Py_ssize_t (如果已定义,则与 ssize_t 相同)的有符号整数的枚举值. 这是所有索引数组使用的类型.

在 2.0 版本发生变更: 以前,这与 intptr_t (与指针大小相同)相同. 实际上,除了非常小众的平台之外,这都是相同的. 您可以使用字符代码 'p' 表示指针含义.

enumerator NPY_UINTP

与 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 dtypes将使用新的DType API编写,并且可能无法以与旧版DType相同的方式运行. 如果您想使用不同的代码路径处理旧版DType,或者您不想更新使用 NPY_NTYPES_LEGACY 且无法与新DType正确工作的代码,请使用此宏.

备注

NPY_NTYPES_LEGACY 中将不包含新添加的DType,例如 NPY_VSTRING .

NPY_NOTYPE

保证不是有效类型枚举数字的信号值.

NPY_USERDEF

用于旧版自定义数据类型的类型编号的起始位置. 新样式的用户DType目前没有分配类型编号.

备注

用户dtypes的总数限制在 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 类型名称

每个数值数据类型和 bool 数据类型都有标准的变量类型.其中一些类型已经在 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

长双精度浮点数

type npy_clongdouble

长复数双精度浮点数

复数类型是具有 .real 和 .imag 成员(按该顺序)的结构体.

位宽名称

还存在特定位宽的带符号整数,无符号整数,浮点数和复数浮点数类型的 typedef.可用的类型名称有

npy_int{bits} , npy_uint{bits} , npy_float{bits} , 和 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