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 |
| tuple_object.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:format() | Get the format of a tuple |
| tuple_object.info() | Get information about the tuple |
| 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 |
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
...