Submodule box.tuple

The box.tuple submodule provides read-only access for the tuple userdata type. It allows, for a single tuple: selective retrieval of the field contents, retrieval of information about size, iteration over all the fields, and conversion to a Lua table.

Below is a list of all box.tuple functions.

Name	Use
box.tuple.new()	Create a tuple
box.tuple.is()	Check whether a given object is a tuple
#tuple_object	Count tuple fields
box.tuple.bsize()	Get count of bytes in a tuple
tuple_object[field-number]	Get a tuple’s field by specifying a number
tuple_object[field-name]	Get a tuple’s field by specifying a name
tuple_object[field-path]	Get a tuple’s fields or parts by specifying a path
tuple_object:find(), tuple_object:findall()	Get the number of the first field/all fields matching the search value
tuple_object:next()	Get the next field value from tuple
tuple_object:pairs(), tuple_object:ipairs()	Prepare for iterating
tuple_object:totable()	Get a tuple’s fields as a table
tuple_object:tomap()	Get a tuple’s fields as a table along with key:value pairs
tuple_object:transform()	Remove (and replace) a tuple’s fields
tuple_object:unpack()	Get a tuple’s fields
tuple_object:update()	Update a tuple
tuple_object:upsert()	Update a tuple ignoring errors

How to convert tuples to/from Lua tables

This function will illustrate how to convert tuples to/from Lua tables and lists of scalars:

tuple = box.tuple.new({scalar1, scalar2, ... scalar_n}) -- scalars to tuple
lua_table = {tuple:unpack()}                            -- tuple to Lua table
lua_table = tuple:totable()                             -- tuple to Lua table
scalar1, scalar2, ... scalar_n = tuple:unpack()         -- tuple to scalars
tuple = box.tuple.new(lua_table)                        -- Lua table to tuple

Then it will find the field that contains ‘b’, remove that field from the tuple, and display how many bytes remain in the tuple. The function uses Tarantool box.tuple functions new(), unpack(), find(), transform(), bsize().

function example()
  local tuple1, tuple2, lua_table_1, scalar1, scalar2, scalar3, field_number
  local luatable1 = {}
  tuple1 = box.tuple.new({'a', 'b', 'c'})
  luatable1 = tuple1:totable()
  scalar1, scalar2, scalar3 = tuple1:unpack()
  tuple2 = box.tuple.new(luatable1[1],luatable1[2],luatable1[3])
  field_number = tuple2:find('b')
  tuple2 = tuple2:transform(field_number, 1)
  return 'tuple2 = ' , tuple2 , ' # of bytes = ' , tuple2:bsize()
end

… And here is what happens when one invokes the function:

tarantool> example()
---
- tuple2 =
- ['a', 'c']
- ' # of bytes = '
- 5
...

Version:

Submodule box.tuple

How to convert tuples to/from Lua tables