General:. This page generally describes new functionality in the 94 series of revisions and uploads. This is Working Documentation that with maturity will be moved to the Master Documentation.
This revision introduces another container class: #idx: Index. An
index is a dictionary allowing multiple occurrences of the key but not multiple
occurrences of the key/value pair. For example, the index at the back of a book
lists words along with one or more pages where the word may be found in the
book. If the word appears more than once on a page, it is listed only once.
Indexing data out of the index object returns a sequence of sequences. Each
outer sequence element corresponds to the respective key. Each inner sequence
element is a value for the index. As usual, the examples speak better than
words.
The index object implements the one-to-many relationship case of a relational
table. There may be many values for a key. However, all values are unique.
Adding to an index:. This very
simple example adds to values for the key 'x'. It then indexes the key out of
the index. Finally it uses the ":seq" method to return the
entire index as a sequence. Notice, the indexed key is not returned. Only a
sequence of its values is returned.
Removing from an index:. The
common without ( ~ ) operator is used to remove items from an index.
This illustrates two keys with two values each. First, all values for the key
"y" is removed and the index object is dumped showing only the
"x" keyed values are left. The ('x' 'a' ) item is removed.
This is the key "x" whose value is "a". It is delivered as
a pair by enclosing (e.g. 'x''z'> ).
Vector insertion:. A vector
value argment and a conforming vector key argument can be used to insert values
into the index in bulk. This is much more efficient than looping through the
individual pairs. You can also put a single value in multiple keys or a vector
value in a single key. You should experiment to be sure you are accomplishing
your intentions.
Indexing out of #idx
object:. Because the index object items may have more than one value
per key, indexing by key returns a sequence of sequences. The outer sequence
items correspond to the indexing keys. The inner sequences are the values for
those respective keys. This differs from the dictionary object which
only has one value per key and therefore returns a simple sequence of values
when indexed.