Module tuple

type box_tuple_format_t¶

box_tuple_format_t *box_tuple_format_default(void)¶

Формат кортежа.

Каждому кортежу соответствует определенный формат (класс). По умолчанию, используется формат для создания кортежей, не привязанных к определенному спейсу.

type box_tuple_t¶: Кортеж

box_tuple_t *box_tuple_new(box_tuple_format_t *format, const char *tuple, const char *tuple_end)¶

Выделение и инициализация нового кортежа из сырых данных MsgPack-массива.

Параметры:	format (box_tuple_format_t) – формат кортежа. Используйте box_tuple_format_default() для создания кортежа независимо от спейса. tuple* (const char) – данные кортежа в формате MsgPack-массива ([ field1, field2, …]) tuple_end* (const char*) – конец данных `data`
Результат:	NULL при нехватке памяти
Результат:	в остальных случаях кортеж

См. также box.tuple.new()

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

При работе с кортежами в обязанности разработчика входит выделение достаточного места, уделяя особое внимание записи данных с помощью таких msgpuck-функций, как mp_encode_array().

int box_tuple_ref(box_tuple_t *tuple)¶

Увеличение значения счетчика количества ссылок на кортеж.

Для кортежей подсчитываются ссылки. Все функции, которые возвращают кортежи, обеспечивают внутренний подсчет ссылок для последнего возвращенного кортежа до следующего вызова API-функции, которая передает управление или возвращает другой кортеж.

Следует увеличивать значение счетчика количества ссылок перед длительной обработкой кортежей в коде. Сборщик мусора в Lua не будет удалять кортежи с ссылками, даже если другой файбер удалит их из спейса. После обработки уменьшите значение счетчика количества ссылок с помощью box_tuple_unref(), иначе кортеж будет допускать утечку.

Параметры:	tuple (box_tuple_t*) – кортеж
Результат:	-1 в случае ошибки
Результат:	0 в остальных случаях

См. также box_tuple_unref()

void box_tuple_unref(box_tuple_t *tuple)¶

Увеличение значения счетчика количества ссылок на кортеж.

Параметры:	tuple (box_tuple_t*) – кортеж

См. также box_tuple_ref()

uint32_t box_tuple_field_count(const box_tuple_t *tuple)¶

Возврат количества полей в кортеже (размер MsgPack-массива).

Параметры:	tuple (box_tuple_t*) – кортеж

size_t box_tuple_bsize(const box_tuple_t *tuple)¶

Возврат количества байтов, используемых для хранения внутренних данных кортежа (MsgPack-массив).

Параметры:	tuple (box_tuple_t*) – кортеж

ssize_t box_tuple_to_buf(const box_tuple_t *tuple, char *buf, size_t size)¶

Передача сырых MsgPack-данных в буфер памяти buf размера size.

Хранение полей кортежа в буфере памяти.

При успешном выполнении функция возвращает количество записанных байтов. Если размер буфера недостаточный, возвращается количество байтов, которое было бы записано, если бы было достаточно места.

Результат:	-1 в случае ошибки
Результат:	количество записанных байтов при успешном выполнении.

box_tuple_format_t *box_tuple_format(const box_tuple_t *tuple)¶

Возврат взаимосвязанного формата.

Параметры:	tuple (box_tuple_t*) – кортеж
Результат:	формат кортежа

const char *box_tuple_field(const box_tuple_t *tuple, uint32_t field_id)¶

Возврат поля кортежа в MsgPack-формате. Результатом будет указатель на сырые данные в формате MessagePack, которые можно расшифровать с помощью функций mp_decode. Пример можно увидеть в программе практикума read.c.

Буфер действует до следующего вызова функции box_tuple_*.

Параметры:	tuple (box_tuple_t) – кортеж field_id* (uint32_t) – индекс с основанием 0 в MsgPack-массиве.
Результат:	NULL, если i >= box_tuple_field_count()
Результат:	в остальных случаях msgpack

enum field_type¶

enumerator ::FIELD_TYPE_ANY¶

enumerator ::FIELD_TYPE_UNSIGNED¶

enumerator ::FIELD_TYPE_STRING¶

enumerator ::FIELD_TYPE_NUMBER¶

enumerator ::FIELD_TYPE_DOUBLE¶

enumerator ::FIELD_TYPE_INTEGER¶

enumerator ::FIELD_TYPE_BOOLEAN¶

enumerator ::FIELD_TYPE_VARBINARY¶

enumerator ::FIELD_TYPE_SCALAR¶

enumerator ::FIELD_TYPE_DECIMAL¶

enumerator ::FIELD_TYPE_ARRAY¶

enumerator ::FIELD_TYPE_MAX¶

Допустимые типы данных для полей кортежа.

Нельзя использовать макросы STRS/ENUM для типов, поскольку есть несоответствие между именем enum (STRING) и литералом имени типа («STR»). STR уже используется в качестве типа в Objective-C.

type box_key_def_t¶: Определение ключа

box_key_def_t *box_key_def_new(uint32_t *fields, uint32_t *types, uint32_t part_count)¶

Создание определения ключа с полям ключа с переданными типами по переданным позициям.

Можно использовать для создания формата кортежа и/или сопоставления кортежей.

Параметры:	fields (uint32_t) – массив с идентификаторами поля ключа types* (uint32_t) – массив с типами поля ключа part_count (uint32_t) – количество полей ключа
Результат:	определение ключа, если выполнено
Результат:	NULL в случае ошибки

void box_key_def_delete(box_key_def_t *key_def)¶

Удаление определения ключа

Параметры:	key_def (box_key_def_t*) – удаляемое определение ключа

box_tuple_format_t *box_tuple_format_new(struct key_def *keys, uint16_t key_count)¶

Возврат нового формата кортежа на основании переданных определений ключа

Параметры:	keys (key_def) – массив ключей, определенный для формата key_count (uint16_t) – количество ключей
Результат:	новый формат кортежа, если выполнено
Результат:	NULL в случае ошибки

void box_tuple_format_ref(box_tuple_format_t *format)¶

Увеличение значения подсчета ссылок на формат кортежа

Параметры:	tuple_format (box_tuple_format_t) – формат кортежа для ссылок

void box_tuple_format_unref(box_tuple_format_t *format)¶

Уменьшение значения подсчета ссылок на формат кортежа

Параметры:	tuple_format (box_tuple_format_t) – формат кортежа для уменьшения

int box_tuple_compare(const box_tuple_t *tuple_a, const box_tuple_t *tuple_b, const box_key_def_t *key_def)¶

Сопоставление кортежей, используя определение ключа

Параметры:	tuple_a (const box_tuple_t) – первый кортеж tuple_b* (const box_tuple_t) – второй кортеж key_def* (const box_key_def_t*) – определение ключа
Результат:	0, если `key_fields(tuple_a)` == `key_fields(tuple_b)`
Результат:	<0, если `key_fields(tuple_a)` < `key_fields(tuple_b)`
Результат:	>0, если `key_fields(tuple_a)` > `key_fields(tuple_b)`

См. также enum field_type

int box_tuple_compare_with_key(const box_tuple_t *tuple, const char *key, const box_key_def_t *key_def);¶

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

Параметры:	tuple (const box_tuple_t) – кортеж key* (const char) – ключ с заголовком MessagePack-массива key_def* (const box_key_def_t*) – определение ключа
Результат:	0, если `key_fields(tuple)` == `parts(key)`
Результат:	<0, если `key_fields(tuple)` < `parts(key)`
Результат:	>0, если `key_fields(tuple)` > `parts(key)`

См. также enum field_type

type box_tuple_iterator_t¶: Итератор кортежей

box_tuple_iterator_t *box_tuple_iterator(box_tuple_t *tuple)¶

Выделение и инициализация нового итератора кортежей. Итератор кортежей позволяет проводить итерацию по полям на корневом уровне MsgPack-массива.

Пример:

box_tuple_iterator_t* it = box_tuple_iterator(tuple);
if (it == NULL) {
    // обработка ошибок с помощью box_error_last()
}
const char* field;
while (field = box_tuple_next(it)) {
    // обработка сырых MsgPack-данных
}

// перемотка итератора на начальное положение
box_tuple_rewind(it)
assert(box_tuple_position(it) == 0);

// перемотка на три поля
field = box_tuple_seek(it, 3);
assert(box_tuple_position(it) == 4);

box_iterator_free(it);

void box_tuple_iterator_free(box_tuple_iterator_t *it)¶: Удаление и освобождение итератора кортежей

uint32_t box_tuple_position(box_tuple_iterator_t *it)¶

Возврат следующего положения с основанием 0 в итераторе. То есть функция возвращает идентификатор поля, который вернется при следующем вызове box_tuple_next(). Возвращается значение 0 после инициализации или перемотки и box_tuple_field_count() по окончании итерации.

Параметры:	it (box_tuple_iterator_t*) – итератор кортежей
Результат:	положение

void box_tuple_rewind(box_tuple_iterator_t *it)¶

Перемотка итератора в начальное положение.

Параметры:	it (box_tuple_iterator_t*) – итератор кортежей

После: box_tuple_position(it) == 0

const char *box_tuple_seek(box_tuple_iterator_t *it, uint32_t field_no)¶

Поиск итератора кортежей.

Результатом будет указатель на сырые MessagePack-данные, которые можно расшифровать с помощью функций mp_decode. Пример можно увидеть в программе практикума read.c. Возвращаемый буфер действует до следующего вызова API box_tuple_* . Запрашиваемый номер поля field_no возвращается при следующем вызове box_tuple_next(it).

Параметры:	it (box_tuple_iterator_t) – итератор кортежей field_no* (uint32_t) – номер поля – положение с основанием 0 в MsgPack-массиве

После:

box_tuple_position(it) == field_not, если возвращается не NULL.
box_tuple_position(it) == box_tuple_field_count(tuple), если возвращается NULL.

const char *box_tuple_next(box_tuple_iterator_t *it)¶

Возврат следующего поля кортежа из итератора кортежей.

Результатом будет указатель на сырые MessagePack-данные, которые можно расшифровать с помощью функций mp_decode. Пример можно увидеть в программе практикума read.c. Возвращаемый буфер действует до следующего вызова API box_tuple_*.

Параметры:	it (box_tuple_iterator_t*) – итератор кортежей
Результат:	NULL, если полей больше нет
Результат:	в остальных случаях MsgPack

Ранее: box_tuple_position() – это идентификатор с основанием 0 возвращаемого поля.

После: box_tuple_position(it) == box_tuple_field_count(tuple), если возвращается NULL.

box_tuple_t *box_tuple_update(const box_tuple_t *tuple, const char *expr, const char *expr_end)¶

box_tuple_t *box_tuple_upsert(const box_tuple_t *tuple, const char *expr, const char *expr_end)¶

Версия:

Module tuple