Encoding Lists

This tutorial shows how to encode lists of values in the TIER format. The mapping we will be focusing on in this tutorial is standard.list which is located in the tier.standard submodule.

In TIER a list is a sequence of items. It is an aggregate mapping that uses an element mapping to encode and decode the elements in the sequence. The element mapping can be any kind of mapping including a list mapping, so it is possible to create lists of lists if wanted.

Before we dig into mapping lua lists to a TIER encoding first we need to explain what a lua list is. For the purpose of mappings a lua list is a lua sequence, that is, a lua table where the set of its positive numeric keys is equal to {1..n}.

Creation

--Creates a list mapping
--element_mapping is the mapping used for the 
--                elements of the list
standard.list(elemen_mapping)

Usage Example

local tier  = require"tier"
local primitive = tier.primitive
local standard  = tier.standard

local outfile = io.open("Lists.dat", "wb")

--A mapping from a table with integer numbers.
local int_list_mapping = standard.list(primitive.int32)
local int_list_1 = { 1, 2, 3, 4, 5 }
local int_list_2 = { 0, 2 }

--Encode a couple of different integer lists.
tier.encode(outfile, int_list_1, int_list_mapping)
tier.encode(outfile, int_list_2, int_list_mapping)

--A mapping from an List of List of floats.
local float_lists_mapping = standard.list(standard.list(primitive.float))
local float_list_data =
{
   { 0, 1, 0 },
   { 1 },
   { 0, 1, 2 , 3 ,4, 5 }
}

--Encode the list of float list data.
tier.encode(outfile, float_list_data, float_lists_mapping)
outfile:close()

--We can now read back the values.
local infile = io.open("Lists.dat", "rb")
local int_list_a = tier.decode(infile, int_list_mapping)
local int_list_b = tier.decode(infile, int_list_mapping)
local float_list = tier.decode(infile, float_lists_mapping)
infile:close()

This marks the end of this tutorial. In the next tutorial Encoding Arrays we will take a look at encoding lua tables as arrays of values. The array mapping is very similar to the list mapping, the only thing that is different is that arrays are of fixed size.