Module tuple

type box_tuple_format_t¶

box_tuple_format_t *box_tuple_format_default(void)¶

Tuple format.

Each Tuple has an associated format (class). Default format is used to create tuples which are not attached to any particular space.

type box_tuple_t¶: Tuple

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

Allocate and initialize a new tuple from raw MsgPack Array data.

Parameters:	format (box_tuple_format_t) – tuple format. Use box_tuple_format_default() to create space-independent tuple. tuple* (const char) – tuple data in MsgPack Array format ([field1, field2, …]) tuple_end* (const char*) – the end of `data`
Returns:	NULL on out of memory
Returns:	tuple otherwise

See also: box_tuple_ref()

uint32_t box_tuple_field_count(const box_tuple_t *tuple)¶

Return the number of fields in a tuple (the size of MsgPack Array).

Parameters:	tuple (box_tuple_t*) – a tuple

size_t box_tuple_bsize(const box_tuple_t *tuple)¶

Return the number of bytes used to store internal tuple data (MsgPack Array).

Parameters:	tuple (box_tuple_t*) – a tuple

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

Dump raw MsgPack data to the memory buffer buf of size size.

Store tuple fields in the memory buffer.

Upon successful return, the function returns the number of bytes written. If buffer size is not enough then the return value is the number of bytes which would have been written if enough space had been available.

Returns:	-1 on error
Returns:	number of bytes written on success.

box_tuple_format_t *box_tuple_format(const box_tuple_t *tuple)¶

Return the associated format.

Parameters:	tuple (box_tuple_t*) – a tuple
Returns:	tuple format

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

Return the raw tuple field in MsgPack format. The result is a pointer to raw MessagePack data which can be decoded with mp_decode functions, for an example see the tutorial program read.c.

The buffer is valid until the next call to a box_tuple_* function.

Parameters:	tuple (box_tuple_t) – a tuple field_id* (uint32_t) – zero-based index in MsgPack array.
Returns:	NULL if i >= box_tuple_field_count()
Returns:	msgpack otherwise

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¶

Possible data types for tuple fields.

One cannot use STRS/ENUM macros for types because there is a mismatch between enum name (STRING) and type name literal (“STR”). STR is already used as a type in Objective C.

type box_key_def_t¶: Key definition

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

Create a key definition with the key fields with passed types on passed positions.

May be used for tuple format creation and/or tuple comparison.

Parameters:	fields (uint32_t) – array with key field identifiers types* (uint32_t) – array with key field types part_count (uint32_t) – the number of key fields
Returns:	key definition on success
Returns:	NULL on error

void box_key_def_delete(box_key_def_t *key_def)¶

Delete a key definition

Parameters:	key_def (box_key_def_t*) – key definition to delete

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

Return new in-memory tuple format based on passed key definitions

Parameters:	keys (key_def) – array of keys defined for the format key_count (uint16_t) – count of keys
Returns:	new tuple format on success
Returns:	NULL on error

void box_tuple_format_ref(box_tuple_format_t *format)¶

Increment tuple format reference count

Parameters:	tuple_format (box_tuple_format_t) – tuple format to ref

void box_tuple_format_unref(box_tuple_format_t *format)¶

Decrement tuple format reference count

Parameters:	tuple_format (box_tuple_format_t) – tuple format to unref

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

Compare tuples using key definition

Parameters:	tuple_a (const box_tuple_t) – the first tuple tuple_b* (const box_tuple_t) – the second tuple key_def* (const box_key_def_t*) – key definition
Returns:	0 if `key_fields(tuple_a)` == `key_fields(tuple_b)`
Returns:	<0 if `key_fields(tuple_a)` < `key_fields(tuple_b)`
Returns:	>0 if `key_fields(tuple_a)` > `key_fields(tuple_b)`

Parameters:	tuple (const box_tuple_t) – tuple key* (const char) – key with MessagePack array header key_def* (const box_key_def_t*) – key definition
Returns:	0 if `key_fields(tuple)` == `parts(key)`
Returns:	<0 if `key_fields(tuple)` < `parts(key)`
Returns:	>0 if `key_fields(tuple)` > `parts(key)`

See also: enum field_type

type box_tuple_iterator_t¶: Tuple iterator

box_tuple_iterator_t *box_tuple_iterator(box_tuple_t *tuple)¶

Allocate and initialize a new tuple iterator. The tuple iterator allows iterating over fields at the root level of a MsgPack array.

Example:

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 position
box_tuple_rewind(it)
assert(box_tuple_position(it) == 0);

// rewind three fields
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)¶: Destroy and free tuple iterator

uint32_t box_tuple_position(box_tuple_iterator_t *it)¶

Return zero-based next position in iterator. That is, this function returnы the field id of the field that will be returned by the next call to box_tuple_next(). Returned value is zero after initialization or rewind and box_tuple_field_count() after the end of iteration.

Parameters:	it (box_tuple_iterator_t*) – a tuple iterator
Returns:	position

void box_tuple_rewind(box_tuple_iterator_t *it)¶

Rewind iterator to the initial position.

Parameters:	it (box_tuple_iterator_t*) – a tuple iterator

After: box_tuple_position(it) == 0

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

Seek the tuple iterator.

The result is a pointer to raw MessagePack data which can be decoded with mp_decode functions, for an example see the tutorial program read.c. The returned buffer is valid until the next call to box_tuple_* API. The requested field_no is returned by the next call to box_tuple_next(it).

Parameters:	it (box_tuple_iterator_t) – a tuple iterator field_no* (uint32_t) – field number - zero-based position in MsgPack array

After:

box_tuple_position(it) == field_not if returned value is not NULL.
box_tuple_position(it) == box_tuple_field_count(tuple) if returned value is NULL.

const char *box_tuple_next(box_tuple_iterator_t *it)¶

Return the next tuple field from tuple iterator.

The result is a pointer to raw MessagePack data which can be decoded with mp_decode functions, for an example see the tutorial program read.c. The returned buffer is valid until next call to box_tuple_* API.

Parameters:	it (box_tuple_iterator_t*) – a tuple iterator
Returns:	NULL if there are no more fields
Returns:	MsgPack otherwise

Before: box_tuple_position() is zero-based ID of returned field.

After: box_tuple_position(it) == box_tuple_field_count(tuple) if returned value is 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)¶

Version:

Module tuple