Lua Tables — Ordered Iteration

Introduction

If you have imported the lulu.table module as

require 'lulu.table'

Then, you have access to a new iterator maker:

table.ordered_pairs(comparator)
Returns an iterator maker — a function that takes a table and returns an iterator. The iterator returns key-value pairs in a fixed order determined by the comparator argument.

Lau supplies a standard pairs method that iterates through all the key-value pairs in any table. However, that traversal is done in an undefined order and can vary from run to run.

Lua has no defined order for the keys in a general table. This contrasts with the keys in a pure Lua array where the indices are always stored in their natural order from 1 on.

We supply a counterpart iterator, table.ordered_pairs(comparator) that returns an iterator that traverses the keys in the table in a fixed order. By default, keys are sorted by type and then by value, so numeric keys come first in their natural order, and those are followed by the others where strings are sorted alphabetically.

If you supply a comparator argument it should take two key arguments k1, k2 and return true if you want k1 to appear before k2.

Example

local tbl = { frog = 1, badger = 2, eagle = 3 }
1for k, v in pairs(tbl) do print(k, v) end
print("--------")

2local iter = table.ordered_pairs()
for k, v in iter(tbl) do print(k, v) end
print("--------")

3iter = table.ordered_pairs(">")
for k, v in iter(tbl) do print(k, v) end

1

Lua’s standard pair method.

2

The ordered_pairs method uses the default key comparator function.

3

The ordered_pairs method uses a custom key comparator “function”.

outputs

1eagle   3
frog    1
badger  2
--------
2badger  2
eagle   3
frog    1
--------
3frog    1
eagle   3
badger  2

1

The key-value pairs are output in whatever undefined order Lua stores them.

2

The key-value pairs are output in our default increasing alphabetic order for the keys.

3

The key-value pairs are output in a custom-decreasing alphabetic order for the keys.

Comparator Functions

A custom comparator function can come in one of several forms:

1. You can use Lua functions like table.ordered_pairs(function(a,b) return a > b end).
2. You can use a string operator like table.ordered_pairs(">").
3. You can use a string {lulu.anon} like table.ordered_pairs("|a,b| a > b").
4. You can pass a “table” that happens to be *callable, i.e., it has a __call() metamethod that takes and compares two items.

There is more detail on the second and third options in the documentation for lulu.callable.

table.compare(a,b)

The table.compare function is the default comparator used by the table.ordered_pairs method. It compares two values, a and b, by type first and then by value.

Numeric keys come first and are sorted in natural order. String keys are sorted alphabetically.

See Also

table.keys
lulu.callable