数据类型 API

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

警告

C代码中类型的名称更紧密地遵循C命名约定.这些类型的Python名称遵循Python约定.因此,:c:data: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

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

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

enumerator NPY_INTP

Py_ssize_t 类型的有符号整数的枚举值（如果定义了 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} 有

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

短

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

长整型

type npy_ulong

无符号长整型

type npy_longlong

长长整型

type npy_ulonglong

无符号长长整型

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

长 复杂 双精度

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

位宽名称

还有一些特定位宽的有符号整数、无符号整数、浮点数和复数浮点数的类型定义.可用的类型名称有

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