table.sort

table.sort (t, f)

Sorts the table using the supplied function f as the comparison function for each element.

Function f should return true if the first element is < the second element. If the function omitted it defaults to the operator <.

Sorting is not stable, that is, the sequence of equal keys is not necessarily preserved.

t = { "the", "quick", "brown", "fox" }
table.sort (t)
table.foreachi (t, print)

 -->
 
1 brown
2 fox
3 quick
4 the

Sorting is really only relevant for numerically keyed tables. If you want to sort the keys for other types of tables you need to make a copy of the keys and sort that, like this:

t = { str = 42, dex = 10, wis = 100 }
ts = {} -- table to hold the keys
table.foreach (t, function (k, v) table.insert (ts, k) end )
table.sort (ts) -- sort keys
table.foreachi (ts, print) -- print sorted keys

 -->
 
1 dex
2 str
3 wis

Here is an example of a custom sort function. This is needed here because we are sorting tables, which do not have a natural "less than" operator:

t = {
    { str = 42, dex = 10, wis = 100 },
    { str = 18, dex = 30, wis = 5 }
    }

table.sort (t, function (k1, k2) return k1.str < k2.str end )

table.foreachi (t, function (k, v) table.foreach (v, print) end )

 -->
 
str 18
dex 30
wis 5
str 42
dex 10
wis 100

We can see from the results that the two tables were sorted into "str" order.

An alternative approach to supplying a comparison function for the sort would be to set up a metatable for the individual table items (not the container table) which specifies a __lt (less than) operator. Here is an example:

t = {
    { str = 42, dex = 10, wis = 100 },
    { str = 18, dex = 30, wis = 5 }
    }

mt =  { __lt = function (k1, k2) return k1.wis < k2.wis end }

-- apply metatable to all tables inside our table
for _, v in ipairs (t) do
  setmetatable (v, mt)
end -- for

table.sort (t)

table.foreachi (t, function (k, v) table.foreach (v, print) end )

 -->
 
str 18
dex 30
wis 5
str 42
dex 10
wis 100

In this case I have made a metatable "mt" which is then applied to each table item. It compares the "wis" field in this case. With this in place the sort can be called without a helper function. Of course, for speed purposes you would do this once (perhaps when creating the individual table entries) rather than every time you wanted to sort it.