Dictionaries are known by various other names, including hashes and associative arrays. Dictionaries in Onyx associate keys with values. Keys and values can be of any type, but for each dictionary, all keys are unique. For example, the following dictionary cannot exist:
< 42 `Some value' 42 `Another value' >
To demonstrate this, the following example creates a dictionary with the first key/value pair listed above, then inserts the second key/value pair.
onyx:0> <42 `Some value'> onyx:1> dup 1 sprint <42 `Some value'> onyx:1> dup 42 `Another value' put onyx:1> dup 1 sprint <42 `Another value'> onyx:1>
When the second key/value pair is inserted, it replaces the first pair.
Actually, there is one way to create a dictionary, then modify it such that multiple entries have the same key. However, doing so is a very bad idea, and is only discussed here as an example of something not to do. Dictionary keys are merely references (in the case of composite objects), so if a string is modified after being used as a dictionary key, the dictionary will no longer be able to access the key/value pair associated with that string. The following code creates a dictionary with two key/value pairs, then changes one of the keys.
onyx:0> $foostr `foo' def onyx:0> $barstr `bar' def onyx:0> $d <foostr 0 barstr 1> def onyx:0> foostr barstr copy pop onyx:0> d 1 sprint <`foo' 1 `foo' 1> onyx:0> d `foo' undef onyx:0> d 1 sprint <`foo' 0> onyx:0>
Bad things are clearly happening here, and in fact there are other similar problems that surface, even if a key remains unique after being changed. This is because during insertion, the key string is hashed, and inserted into a hash table accordingly. A different string is likely to hash to a different slot in the hash table, which means that the key/value pair becomes inaccessible.
In summary, do not change strings while they are being used as dictionary keys. Onyx does not prevent the use of strings for dictionary keys, since it would be limiting, but this feature can be abused.