API tinsert

From TableLibraryTutorial of lua-users.org.

table.insert(table, [pos,] value) tinsert(table[, pos], value)

Insert a given value into a table. If a position is given insert the value before the element currently at that position:

> t = { 1,3,"four" } > table.insert(t, 2, "two") -- insert "two" at position before element 2 > = table.concat(t, ", ") 1, two, 3, four

If no position is specified we append the value to the end of the table:

> table.insert(t, 5)        -- no position given so append to end > = table.concat(t, ", ") 1, two, 3, four, 5

When a table has an element inserted both the size of the table and the element indices are updated:

> t = { 1,"two",3 }              -- create a table > = table.getn(t)                -- find current size 3 > table.foreach(t, print)        -- display the table contents 1      1 2       two 3      3 > table.insert(t, 1, "inserted")  -- insert an element at the start > = table.concat(t, ", ")        -- see what we have inserted, 1, two, 3 > = table.getn(t)                -- find the size 4 > table.foreach(t, print)        -- the indexes have been updated 1      inserted 2      1 3       two 4      3

When no position is specified the element is inserted at the end of the table according to the calculated size. The size of a table may be user specified and not reflect the number of elements, e.g.,

> t = { 1,"two",3; n=10 } -- create a table with user size > table.insert(t, "end")  -- insert with no position inserts at "end" > table.foreach(t, print) -- display the table contents 1      1 2       two 3      3 11      end n      11

Speed
If you are appending to an integer-indexed table, it is always faster to track the size yourself, as this example demonstrates (clocked on a 3Ghz P4)

local t = {} local tinsert=table.insert local b = os.clock local n=1 t.n=1 for i=1,5e6 do table.insert(t, "") -- 2.25s - extra cost of looking up table. subkeys tinsert(t, "")      -- 2.02s - local function call is slightly faster t[#t+1] = ""        -- 1.72s - a lot of the cost seems to be #t local tn=t.n; t[tn]=""; t.n=tn+1  -- 1.19s - storing "n" in the table t[n]="";n=n+1       -- 0.88s - storing "n" in a local t[i]=""             -- 0.78s - cheat, we don't have "i" usually -- empty  -- 0.08s overhead for the loop end local e = os.clock print(e-b)