資料類型 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#: 主要用於保存 struct dtype，但可以包含任意二進制資料。

以下是一些上述類型的有用別名

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 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} 和 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#: 日期或日期時間（npy_int64 的別名）

type npy_timedelta#: 時間長度（npy_int64 的別名）

Printf 格式化#

為了在列印時提供協助，以下字串被定義為 printf 和相關命令中正確的格式指定符。

NPY_LONGLONG_FMT#

NPY_ULONGLONG_FMT#

NPY_INTP_FMT#

NPY_UINTP_FMT#

NPY_LONGDOUBLE_FMT#