数据类型 API

标准数组可以有 25 种不同的数据类型(并且支持添加您自己的类型).这些数据类型都有一个枚举类型,一个枚举类型字符,以及一个相应的数组标量 Python 类型对象(放置在一个层次结构中).还有标准的 C typedef,可以更轻松地操作给定数据类型的元素.对于数字类型,还有位宽等效的 C typedef 和命名类型号,可以更轻松地选择所需的精度.

警告

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

备注

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

备注

新添加的 DTypes(例如 NPY_VSTRING )将不会在 NPY_NTYPES_LEGACY 中计算.

NPY_NOTYPE

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

NPY_USERDEF

用于旧版自定义数据类型的类型编号的开始. 新样式的用户 DTypes 当前未分配类型编号.

备注

用户 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

long double

type npy_clongdouble

long complex double

复数类型是具有 .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.哪些位宽可用取决于平台.粗体的位宽通常在所有平台上都可用.

时间和 timedelta

type npy_datetime

date 或 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