Tinderbox 8 Icon

Look-up tables

Look-up tables allow simple value arrays. This lets some discrete values be mapped onto other values. For example, suppose some notes record the state in which each customer resides. Each state is assigned to a region and it is useful to know the sales region for given customer. Previously, a usual approach would be a set of if() statements:

if($State=="AL") { $Region = "South";} 

However, this is a tedious process if there are many states - it needs a lot of if() statements.

Instead, for a Set, List, or String type of Attribute create a list of key/value pairs, separated by colons. Each colon-separated pair is then delimited from then next pair by a semi-colon as with a normal Tinderbox list - a semi-colon is not needed after the last pair. Thus:

Key1:Value1;Key2:Value2

$RegionList="AL:South;AK:NorthWest" 

Optionally a default value (for keys with no match) can be defined:

Key1:Value1;Key2:Value2;default:North

$RegionList="AL:South;AK:NorthWest;default:North" 

Keys should not consist of numbers only as this may confuse Tinderbox. Should you need to use numbered keys, perhaps because you are generating the look-up key based on a computed value, place a letter before the number. So, use 'x1' rather than just '1'.

Look-up tables allow actions like:

$Region=$RegionList.lookup($State) 

If the set does not contain the key value, .lookup() looks for an optional special default key ('default') and returns that key's value; if there is no default value defined or it defined with no value, .lookup() returns an empty string.

Realistically, if using lookup tables the lookup value list will be defined in one note and then referenced by all others. Thus the last example above is more likely:

$Region=$RegionList("config").lookup($State) 

Lookup tables are able to specify several keys that map to a common value. This is done by separating each key with the pipe character '|'. For example:

"Oliver|Micawber|Pip:Dickens;Tess:Hardy;Palliser|Finn:Trollope;default:anon" 

A structural representation of the above example is as follows. The first key/value set is in normal text, the second in italics, the third in bold, the default in plain text:

Key1-1|Key1-2|Key1-3:Value1;Key2-1:Value2;Key3-1|Key3-2:Value3;default:anon

The number of keys in each Key/Value set is discrete from other sets in the list.

Keys are matched on exact, case-sensitive, strings. In the above example "Tess" will return "Hardy" but "tess", "Tes" or "Tessa" would return "anon". If no default had been defined, an empty string "" would be returned instead for the non-matching values.

Lookup tables also permit ranges. For example, suppose the value of $MyString is:

Alaska-Connecticut: 1; Delaware-Nebraska: 2:default: 3 

Then $MyString.lookup("Alabama") would return 1, and $MyString.at("Illinois") would return 2.

Lookup tables can also work with numeric ranges. If $MyString is:

0-10: red; 10-20: blue; default: green 

Then $MyString.lookup(5.0) returns 'red'. Note that $MyString.lookup(5) (N.B. an integer without a decimal point) returns the fifth element of the list. Thus if the actual key is "5" use "5.0" to trigger the first behaviour.