API NpyString

Примеры

npy_string_allocator *allocator = NpyString_acquire_allocator(
        (PyArray_StringDTypeObject *)descr);

npy_static_string sdata = {0, NULL};
npy_packed_static_string *packed_string = (npy_packed_static_string *)buf;
int is_null = 0;

is_null = NpyString_load(allocator, packed_string, &sdata);

if (is_null == -1) {
    // failed to load string, set error
    return -1;
}
else if (is_null) {
    // handle missing string
    // sdata->buf is NULL
    // sdata->size is 0
}
else {
    // sdata->buf is a pointer to the beginning of a string
    // sdata->size is the size of the string
}
NpyString_release_allocator(allocator);

char *str = "Hello world";
size_t size = 11;
npy_packed_static_string *packed_string = (npy_packed_static_string *)buf;

npy_string_allocator *allocator = NpyString_acquire_allocator(
        (PyArray_StringDTypeObject *)descr);

// copy contents of str into packed_string
if (NpyString_pack(allocator, packed_string, str, size) == -1) {
    // string packing failed, set error
    return -1;
}

// packed_string contains a copy of "Hello world"

NpyString_release_allocator(allocator);

Типы

typenpy_packed_static_string

Непрозрачная структура, представляющая «упакованные» закодированные строки. Отдельные элементы буферов массивов являются экземплярами этой структуры. Прямой доступ к данным в структуре не определен, и в будущих версиях библиотеки представление строк может измениться.

typenpy_static_string

Распакованная строка, предоставляющая доступ к данным строки UTF-8.

typedef struct npy_unpacked_static_string {
    size_t size;
    const char *buf;
} npy_static_string;

size_tsize

Размер строки в байтах.

constchar*buf

Буфер строки. Содержит байты, закодированные в UTF-8. В настоящее время не заканчивается нулевым символом, но в будущем мы можем добавить завершение нулевым символом, поэтому не полагайтесь на его наличие или отсутствие.

Обратите внимание, что это const буфер. Если вы хотите изменить элемент в массиве, вам необходимо создать новую строку и упаковать её в элемент массива.

typenpy_string_allocator

Непрозрачный указатель на объект, который обрабатывает выделение памяти для строк. Перед использованием выделения памяти необходимо захватить блокировку выделения, а после завершения работы с управляемыми выделением строками освободить блокировку.

typePyArray_StringDTypeObject

C-структура, лежащая в основе экземпляров StringDType в Python. Атрибуты хранят настройки, с которыми был создан объект, экземпляр npy_string_allocator , управляющий выделением памяти для строк в массивах, связанных с экземпляром DType, и несколько атрибутов, кеширующих информацию об отсутствующем объекте строки, которая обычно нужна в реализации преобразований и циклах ufunc.

typedef struct {
    PyArray_Descr base;
    PyObject *na_object;
    char coerce;
    char has_nan_na;
    char has_string_na;
    char array_owned;
    npy_static_string default_string;
    npy_static_string na_name;
    npy_string_allocator *allocator;
} PyArray_StringDTypeObject;

PyArray_Descrbase

Базовый объект. Используйте этот член для доступа к полям, общим для всех объектов описателей.

PyObject*na_object

Ссылка на объект, представляющий нулевое значение. Если нулевого значения нет (по умолчанию), это будет NULL.

charcoerce

1, если включено приведение типов строк, 0 в противном случае.

charhas_nan_na

1, если отсутствующий объект строки (если есть) подобен NaN, 0 в противном случае.

charhas_string_na

1, если отсутствующий объект строки (если есть) является строкой, 0 в противном случае.

chararray_owned

1, если массив владеет экземпляром StringDType, 0 в противном случае.

npy_static_stringdefault_string

Строка по умолчанию, используемая в операциях. Если отсутствующий объект строки является строкой, здесь будут содержаться данные строки для отсутствующей строки.

npy_static_stringna_name

Имя отсутствующего объекта строки, если есть. В противном случае пустая строка.

npy_string_allocatorallocator

Экземпляр выделения памяти, связанный с массивом, который владеет этим экземпляром описателя. К выделению памяти следует обращаться только после получения блокировки allocator_lock, а блокировка должна быть освобождена немедленно после того, как выделение больше не требуется.

Функции

npy_string_allocator*NpyString_acquire_allocator(constPyArray_StringDTypeObject*descr)

Получить мьютекс, блокирующий аллокатор, прикрепленный к descr. Необходимо вызвать NpyString_release_allocator для аллокатора, возвращённого этой функцией, ровно один раз. Обратите внимание, что функции, требующие GIL, не должны вызываться, пока захвачен мьютекс аллокатора, так как это может привести к тупику.

voidNpyString_acquire_allocators(size_tn_descriptors, PyArray_Descr*constdescrs[], npy_string_allocator*allocators[])

Одновременно получить мьютексы, блокирующие аллокаторы, прикреплённые к нескольким дескрипторам. Записывает указатель на связанный аллокатор в массив allocators для каждого дескриптора StringDType в массиве. Если какой-либо из дескрипторов не является экземпляром StringDType, в массив allocators записывается NULL для этого элемента.

n_descriptors — количество дескрипторов в массиве descrs, которое должно быть проверено. Любой дескриптор после n_descriptors элементов игнорируется. Произойдёт переполнение буфера, если массив descrs не содержит n_descriptors элементов.

Если указатели на один и тот же дескриптор передаются несколько раз, мьютекс аллокатора приобретается только один раз, но соответствующие указатели на аллокатор устанавливаются корректно. Мьютексы аллокаторов должны быть освобождены после возвращения этой функции, см. NpyString_release_allocators.

Обратите внимание, что функции, требующие GIL, не должны вызываться, пока захвачен мьютекс аллокатора, так как это может привести к тупику.

voidNpyString_release_allocator(npy_string_allocator*allocator)

Освободить мьютекс, блокирующий аллокатор. Это необходимо вызвать ровно один раз после получения мьютекса аллокатора и выполнения всех операций, требующих аллокатор.

Если вам нужно освободить несколько аллокаторов, см. NpyString_release_allocators, который может правильно обработать освобождение аллокатора один раз, когда ему передано несколько ссылок на один и тот же аллокатор.

voidNpyString_release_allocators(size_tlength, npy_string_allocator*allocators[])

Освободить мьютексы, блокирующие N аллокаторов. length — длина массива allocators. Элементы со значением NULL игнорируются.

Если указатели на один и тот же аллокатор передаются несколько раз, мьютекс аллокатора освобождается только один раз.

intNpyString_load(npy_string_allocator*allocator, constnpy_packed_static_string*packed_string, npy_static_string*unpacked_string)

Извлечь упакованное содержимое packed_string в unpacked_string.

unpacked_string — это доступное для чтения представление данных packed_string и не должно использоваться для изменения данных строки. Если packed_string — это пустая строка, то unpacked_string.buf устанавливается в NULL-указатель. Возвращает -1, если распаковка строки завершается неудачно, возвращает 1, если packed_string — пустая строка, и возвращает 0 в противном случае.

Полезный шаблон — определить экземпляр npy_static_string, размещённый в стеке, инициализированный {0, NULL}, и передать указатель на строку, размещённую в стеке, для распаковки, в эту функцию. Эта функция может использоваться для одновременной распаковки строки и определения, является ли она пустой строкой.

intNpyString_pack_null(npy_string_allocator*allocator, npy_packed_static_string*packed_string)

Упаковать пустую строку в packed_string. Возвращает 0 при успехе и -1 при неудаче.

intNpyString_pack(npy_string_allocator*allocator, npy_packed_static_string*packed_string, constchar*buf, size_tsize)

Скопировать и упаковать первые size элементов буфера, указанного buf, в packed_string. Возвращает 0 при успехе и -1 при неудаче.