Module tuple

Tuple format.

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

Tuple

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.new()

Increase the reference counter of tuple.

Tuples are reference counted. All functions that return tuples guarantee that the last returned tuple is reference counted internally until the next call to API function that yields or returns another tuple.

You should increase the reference counter before taking tuples for long processing in your code. The Lua garbage collector will not destroy a tuple that has references, even if another fiber removes them from a space. After processing, decrement the reference counter using box_tuple_unref(), otherwise the tuple will leak.

Parameters:

• tuple (box_tuple_t*) — a tuple

Returns

-1 on error

Returns

0 otherwise

See also: box_tuple_unref()

Decrease the reference counter of tuple.

Parameters:

• tuple (box_tuple_t*) — a tuple

See also: box_tuple_ref()

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

Parameters:

• tuple (box_tuple_t*) — a tuple

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

Parameters:

• tuple (box_tuple_t*) — a tuple

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.

Return the associated format.

Parameters:

• tuple (box_tuple_t*) — a tuple

Returns

tuple format

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

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.

Key definition

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

Delete a key definition

Parameters:

• key_def (box_key_def_t*) — key definition to delete

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

Increment tuple format reference count

Parameters:

• tuple_format (box_tuple_format_t) — tuple format to ref

Decrement tuple format reference count

Parameters:

• tuple_format (box_tuple_format_t) — tuple format to unref

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)

See also: enum field_type

Compare a tuple with a key using key definition

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

Tuple iterator

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

Destroy and free tuple iterator

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

Rewind iterator to the initial position.

Parameters:

• it (box_tuple_iterator_t*) — a tuple iterator

After: box_tuple_position(it) == 0

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.

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.