Версия:

Модуль tuple

Модуль tuple

box_tuple_format_t
box_tuple_format_t *box_tuple_format_default(void)

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

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

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() для создания кортежа независимо от спейса.
  • char* tuple (const) – данные кортежа в формате MsgPack-массива ([ field1, field2, …])
  • char* tuple_end (const) – конец данных data
Результат:

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

Результат:

в остальных случаях кортеж

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

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

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

int box_tuple_ref(box_tuple_t *tuple)

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

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

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

Параметры:
Результат:

-1 в случае ошибки

Результат:

0 в остальных случаях

См. также box_tuple_unref()

void box_tuple_unref(box_tuple_t *tuple)

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

Параметры:
Результат:

-1 в случае ошибки

Результат:

0 в остальных случаях

См. также box_tuple_ref()

uint32_t box_tuple_field_count(const box_tuple_t *tuple)

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

Параметры:
size_t box_tuple_bsize(const box_tuple_t *tuple)

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

Параметры:
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)

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

Параметры:
Результат:

формат кортежа

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_ARRAY
enumerator FIELD_TYPE_NUMBER
enumerator FIELD_TYPE_INTEGER
enumerator FIELD_TYPE_SCALAR
enumerator field_type_MAX

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

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

typedef struct key_def 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)

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

Параметры:
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)

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

Параметры:
  • box_tuple_t* tuple_a (const) – первый кортеж
  • box_tuple_t* tuple_b (const) – второй кортеж
  • box_key_def_t* key_def (const) – определение ключа
Результат:

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);

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

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

0, если key_fields(tuple) == parts(key)

Результат:

<0, если key_fields(tuple) < parts(key)

Результат:

>0, если key_fields(tuple) > parts(key)

См. также enum field_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() по окончании итерации.

Параметры:
Результат:

положение

void box_tuple_rewind(box_tuple_iterator_t *it)

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

Параметры:

После: 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_*.

Параметры:
Результат:

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)