Tarantool CE/EE Documentation portal logo
Помощь
Обновлена 15 сентября 2026 г. в 08:55

Модуль 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 Array.

Параметры:

  • format (box_tuple_format_t*) — формат кортежа. Чтобы создать кортеж, не зависящий от спейса, используйте box_tuple_format_default().
  • tuple (const char*) — данные кортежа в формате MsgPack Array ([field1, field2, ...])
  • tuple_end (const char*) — конец data

Возвращает

NULL при нехватке памяти

Возвращает

кортеж в противном случае

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

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 Array).

Параметры:

  • tuple (box_tuple_t*) — кортеж

size_t box_tuple_bsize(const box_tuple_t *tuple)

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

Параметры:

  • 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) — отсчитываемый с нуля индекс в массиве MsgPack.

Возвращает

NULL, если i >= box_tuple_field_count()

Возвращает

msgpack в противном случае

Возможные типы данных для полей кортежа.

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

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

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) {    // error handling using box_error_last()}const char* field;while (field = box_tuple_next(it)) {    // process raw MsgPack data}// rewind the iterator to the first positionbox_tuple_rewind(it)assert(box_tuple_position(it) == 0);// rewind three fieldsfield = 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)

Вернуть отсчитываемую с нуля следующую позицию в итераторе. То есть эта функция возвращает идентификатор поля, которое будет возвращено следующим вызовом box_tuple_next(). Возвращаемое значение равно нулю после инициализации или перемотки и 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) — номер поля — отсчитываемая с нуля позиция в массиве 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() — это отсчитываемый с нуля идентификатор возвращаемого поля.

После: 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)

Была ли статья полезна?

  • Была ли статья полезна?