Dictionary

The Dictionary: module provides a string-keyed dictionary. All methods follow the ByRef convention.

Call	Effect
`Dictionary:New name`	Create an empty dictionary
`Dictionary:Set(key, val, name)`	Insert or overwrite a key
`Dictionary:Get(key, name, outVar)`	Read value → `outVar` (`0` if key absent)
`Dictionary:Has(key, name, outVar)`	`true` if key exists → `outVar`
`Dictionary:Remove(key, name)`	Delete a key
`Dictionary:Size(name, outVar)`	Number of entries → `outVar`
`Dictionary:Keys(name, listName)`	Populate a pre-declared `List:String` with all keys (order unspecified)
`Dictionary:Clear(name)`	Remove all entries
`Dictionary:SetList(key, listName, name)`	Store a copy of `listName` under `key`
`Dictionary:GetList(key, name, listName)`	Retrieve list stored at `key` into `listName`
`Dictionary:SetDictionary(key, innerName, name)`	Store a copy of `innerName` under `key`
`Dictionary:GetDictionary(key, name, innerName)`	Retrieve inner dictionary at `key` into `innerName`

Dictionary:New scores;
Dictionary:Set("Alice", 95, scores);
Dictionary:Set("Bob", 82, scores);

Var:Number val;
Dictionary:Get("Alice", scores, val);
Konsol:Print(val);          // 95

Var:Boolean found;
Dictionary:Has("Carol", scores, found);
Konsol:Print(found);        // false

Var:Number sz;
Dictionary:Size(scores, sz);
Konsol:Print(sz);           // 2

List:String keys;
Dictionary:Keys(scores, keys);
List:Size(keys, sz);
Konsol:Print(sz);           // 2

// Dictionary of lists
List:Number nums;
List:Push(1, nums);
List:Push(2, nums);
Dictionary:SetList("evens", nums, scores);

List:Number retrieved;
Dictionary:GetList("evens", scores, retrieved);

Examples

// 24_dictionary.ks - Dictionary module (string-keyed dictionary)

Var:Number sz;
Var:Boolean found;
Var:Number numVal;
Var:String strVal;

Konsol:Print("=== set / get ===");
Dictionary:New scores;
Dictionary:Set("Alice", 95, scores);
Dictionary:Set("Bob", 82, scores);
Dictionary:Set("Carol", 77, scores);
Dictionary:Get("Alice", scores, numVal);
Konsol:Print(numVal);       // 95
Dictionary:Get("Bob", scores, numVal);
Konsol:Print(numVal);       // 82

Konsol:Print("=== has ===");
Dictionary:Has("Carol", scores, found);
Konsol:Print(found);       // true
Dictionary:Has("Dave", scores, found);
Konsol:Print(found);       // false

Konsol:Print("=== size ===");
Dictionary:Size(scores, sz);
Konsol:Print(sz);          // 3

Konsol:Print("=== overwrite ===");
Dictionary:Set("Bob", 90, scores);
Dictionary:Get("Bob", scores, numVal);
Konsol:Print(numVal);      // 90

Konsol:Print("=== remove ===");
Dictionary:Remove("Carol", scores);
Dictionary:Has("Carol", scores, found);
Konsol:Print(found);       // false
Dictionary:Size(scores, sz);
Konsol:Print(sz);          // 2

Konsol:Print("=== missing key returns 0 ===");
Dictionary:Get("nobody", scores, numVal);
Konsol:Print(numVal);      // 0

Konsol:Print("=== string values ===");
Dictionary:New capitals;
Dictionary:Set("France", "Paris", capitals);
Dictionary:Set("Japan", "Tokyo", capitals);
Dictionary:Set("Egypt", "Cairo", capitals);
Dictionary:Get("Japan", capitals, strVal);
Konsol:Print(strVal);      // Tokyo

Konsol:Print("=== keys ===");
Dictionary:New small;
Dictionary:Set("x", 1, small);
Dictionary:Set("y", 2, small);
List:New keyList:String;
Dictionary:Keys(small, keyList);
List:Size(keyList, sz);
Konsol:Print(sz);          // 2

Konsol:Print("=== clear ===");
Dictionary:Clear(small);
Dictionary:Size(small, sz);
Konsol:Print(sz);          // 0