API типов данных

Стандартный массив может содержать 25 различных типов данных (и имеет некоторую поддержку добавления собственных типов). Все эти типы данных имеют перечислимый тип, символ перечислимого типа и соответствующий объект скалярного типа массива Python (размещённый в иерархии). Также существуют стандартные C-определения типов для облегчения работы с элементами заданного типа данных. Для числовых типов также существуют эквивалентные C-определения типов с указанием разрядности и именованные числовые типы, что облегчает выбор желаемой точности.

Предупреждение

Имена типов в коде C следуют более строго соглашениям об именовании C. Имена типов в Python следуют соглашениям Python. Таким образом, NPY_FLOAT выбирает 32-битовое число с плавающей точкой в C, но numpy.float64 в Python соответствует 64-битовому double. Имена с указанием разрядности могут использоваться как в Python, так и в C для большей ясности.

Перечислимые типы

enumNPY_TYPES

Существует список перечислений, определяющих основные 25 типов данных плюс некоторые полезные общие имена. Всякий раз, когда код требует номера типа, запрашивается один из этих перечисленных типов. Все типы называются NPY_{NAME}:

enumeratorNPY_BOOL: Значение перечисления для булевого типа, хранящегося как один байт. Он может принимать только значения 0 и 1.

enumeratorNPY_BYTE

enumeratorNPY_INT8: Значение перечисления для целого числа со знаком с разрядностью 8 бит/1 байт.

enumeratorNPY_SHORT

enumeratorNPY_INT16: Значение перечисления для целого числа со знаком с разрядностью 16 бит/2 байта.

enumeratorNPY_INT

enumeratorNPY_INT32: Значение перечисления для целого числа со знаком с разрядностью 32 бит/4 байта.

enumeratorNPY_LONG: Эквивалентно либо NPY_INT, либо NPY_LONGLONG в зависимости от платформы.

enumeratorNPY_LONGLONG

enumeratorNPY_INT64: Значение перечисления для целого числа со знаком с разрядностью 64 бит/8 байт.

enumeratorNPY_UBYTE

enumeratorNPY_UINT8: Значение перечисления для целого числа без знака с разрядностью 8 бит/1 байт.

enumeratorNPY_USHORT

enumeratorNPY_UINT16: Значение перечисления для целого числа без знака с разрядностью 16 бит/2 байта.

enumeratorNPY_UINT

enumeratorNPY_UINT32: Значение перечисления для целого числа без знака с разрядностью 32 бит/4 байта.

enumeratorNPY_ULONG: Эквивалентно либо NPY_UINT, либо NPY_ULONGLONG в зависимости от платформы.

enumeratorNPY_ULONGLONG

enumeratorNPY_UINT64: Значение перечисления для целого числа без знака с разрядностью 64 бит/8 байт.

enumeratorNPY_HALF

enumeratorNPY_FLOAT16: Значение перечисления для плавающей точки типа IEEE 754-2008 с разрядностью 16 бит/2 байта.

enumeratorNPY_FLOAT

enumeratorNPY_FLOAT32: Значение перечисления для плавающей точки типа IEEE 754 с разрядностью 32 бит/4 байта.

enumeratorNPY_DOUBLE

enumeratorNPY_FLOAT64: Значение перечисления для плавающей точки типа IEEE 754 с разрядностью 64 бит/8 байт.

enumeratorNPY_LONGDOUBLE: Значение перечисления для плавающей точки платформенно-зависимого типа, имеющего размер не меньше NPY_DOUBLE, но большего на многих платформах.

enumeratorNPY_CFLOAT

enumeratorNPY_COMPLEX64: Значение перечисления для комплексного типа с разрядностью 64 бит/8 байт, состоящего из двух значений NPY_FLOAT.

enumeratorNPY_CDOUBLE

enumeratorNPY_COMPLEX128: Значение перечисления для комплексного типа с разрядностью 128 бит/16 байт, состоящего из двух значений NPY_DOUBLE.

enumeratorNPY_CLONGDOUBLE: Значение перечисления для платформенно-зависимого комплексного типа плавающей точки, состоящего из двух значений NPY_LONGDOUBLE.

enumeratorNPY_DATETIME: Значение перечисления для типа данных, хранящего даты или даты и время с точностью, основанной на выбираемых единицах даты или времени.

enumeratorNPY_TIMEDELTA: Значение перечисления для типа данных, хранящего длины интервалов времени в целых числах, выбранных единиц даты или времени.

enumeratorNPY_STRING: Значение перечисления для нуль-заполненных строковых данных байтов переменного размера. У строк есть фиксированный максимальный размер внутри данного массива.

enumeratorNPY_UNICODE: Значение перечисления для строк UCS4 переменного размера. У строк есть фиксированный максимальный размер внутри данного массива.

enumeratorNPY_VSTRING: Значение перечисления для строк UTF-8 переменной ширины. Обратите внимание, что этот тип данных хранит массив ссылок, а данные строк хранятся вне буфера массива. Используйте API C для работы с переменными строками NumPy, чтобы получить доступ к строковым данным в каждом элементе массива.

Примечание

Этот тип данных нового стиля и не включён в NPY_NTYPES_LEGACY.

enumeratorNPY_OBJECT: Значение перечисления для ссылок на произвольные объекты Python.

enumeratorNPY_VOID: В основном используется для хранения структурных типов данных, но может содержать произвольные двоичные данные.

Некоторые полезные псевдонимы вышеперечисленных типов

enumeratorNPY_INTP: Значение перечисления для целого числа со знаком типа Py_ssize_t (равно ssize_t если определено). Это тип, используемый для всех массивов индексов.

Изменено в версии 2.0: Ранее это было то же, что и intptr_t (одинакового размера с указателем). На практике это идентично, за исключением очень специфических платформ. Вы можете использовать символ 'p', обозначающий указатель.

enumeratorNPY_UINTP: Значение перечисления для целого беззнакового типа, идентичного типу size_t.

Изменено в версии 2.0: Ранее это было то же самое, что и uintptr_t (того же размера, что и указатель). На практике это идентично, за исключением узких платформ. Вы можете использовать символ 'P' для обозначения указателя.

enumeratorNPY_MASK: Значение перечисления типа, используемого для масок, например, с флагом итератора NPY_ITER_ARRAYMASK. Это эквивалентно NPY_UINT8.

enumeratorNPY_DEFAULT_TYPE: Тип по умолчанию для использования, когда тип dtype явно не указан, например, при вызове np.zero(shape). Это эквивалентно NPY_DOUBLE.

Другие полезные связанные константы:

NPY_NTYPES_LEGACY: Количество встроенных типов NumPy, написанных с использованием устаревшей системы DType. Новые типы NumPy будут написаны с использованием новой API DType и могут работать не так, как устаревшие DTypes. Используйте эту макрос, если вы хотите обработать устаревшие DTypes с помощью разных путей кода или если не хотите обновлять код, использующий NPY_NTYPES_LEGACY и не работает правильно с новыми DTypes.

Примечание

Новые добавленные типы, такие как NPY_VSTRING, не будут учитываться в NPY_NTYPES_LEGACY.

NPY_NOTYPE: Значение сигнала, гарантированно не являющееся допустимым номером перечисления типа.

NPY_USERDEF: Начало номеров типов, используемых для устаревших пользовательских типов данных. Типы пользовательских DTypes нового стиля в настоящее время не присваиваются номеру типа.

Примечание

Общее количество пользовательских типов данных ограничено значением ниже NPY_VSTRING. Более высокие значения зарезервированы для использования новых DTypes в будущем.

Различные символьные коды, указывающие на определённые типы, также являются частью перечисления. Ссылки на символы типов (если они вообще нужны) всегда должны использовать эти перечисления. Формат имеет вид 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. Вы можете создавать переменные в расширенном коде с помощью этих типов.

Булевы типы

типnpy_bool: unsigned char; Константы NPY_FALSE и NPY_TRUE также определены.

(Без)знаковые целые числа

Беззнаковые версии целых чисел можно определить, добавив префикс ‘u’ к имени целого числа.

типnpy_byte: char

типnpy_ubyte: unsigned char

типnpy_short: short

типnpy_ushort: unsigned short

типnpy_int: int

типnpy_uint: unsigned int

типnpy_int16: 16-битовое целое число

типnpy_uint16: 16-битовое беззнаковое целое число

типnpy_int32: 32-битовое целое число

типnpy_uint32: 32-битовое беззнаковое целое число

типnpy_int64: 64-битовое целое число

типnpy_uint64: 64-битовое беззнаковое целое число

типnpy_long: long int

типnpy_ulong: unsigned long int

типnpy_longlong: long long int

типnpy_ulonglong: unsigned long long int

типnpy_intp: Py_ssize_t (целое число со знаком, имеющее тот же размер, что и C size_t). Это правильное целое число для длин или индексации. На практике, обычно это размер указателя, но это не гарантируется.

Примечание

До NumPy 2.0, это было то же самое, что и Py_intptr_t. Хотя это лучше подходит, это не соответствовало фактическому использованию на практике. В Python-стороне мы по-прежнему поддерживаем np.dtype('p') для получения типа данных, совместимого с хранением указателей, а n — это правильный символ для ssize_t.

типnpy_uintp: C size_t/Py_size_t.

(Комплексные) числа с плавающей точкой

типnpy_half: 16-битовое число с плавающей точкой

типnpy_float: 32-битовое число с плавающей точкой

типnpy_cfloat: 32-битовое комплексное число с плавающей точкой

типnpy_double: 64-битовое число с двойной точностью

типnpy_cdouble: 64-битовое комплексное число с двойной точностью

типnpy_longdouble: long double

типnpy_clongdouble: комплексное число long double

Комплексные типы — это структуры с членами .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 для комплексных типов. Наличие битовой ширины зависит от платформы. Жирным шрифтом выделены битовые ширины, обычно доступные на всех платформах.

Время и timedelta

типnpy_datetime: дата или дата/время (псевдоним npy_int64)

типnpy_timedelta: продолжительность времени (псевдоним npy_int64)

Форматирование printf

Для помощи в печати определены следующие строки как правильные спецификаторы формата в командах printf и родственных командах.

NPY_LONGLONG_FMT

NPY_ULONGLONG_FMT

NPY_INTP_FMT

NPY_UINTP_FMT

NPY_LONGDOUBLE_FMT

© 2005–2024 NumPy Developers
Licensed under the 3-clause BSD License.
https://numpy.org/doc/2.0/reference/c-api/dtype.html