General:. The #idx
object is a skip list (behaves like a balanced binary tree). The compare
function scrutinizes key/value pairs holding them unique. It differs from the
#dict object which holds keys alone unique. This makes it behave like
the index at the back of a book. All words may have one or more pages. However,
if a word appears more than once on a page, it is listed only once. The
examples illustrate better than words.
Simple insertion and display as a
sequence: This illustrates how values and keys are entered into an index.
The :seq method returns the whole index as a sequence of couplets. It
is useful for illustrating the concepts and for testing but would not likely
find use for large indexes.
Access (indexing): When you
access (index) an index by key, you are returned all value instances for that
key as a sequence of sequences. If you supply a single index you can just
"disclose" (<) the result to get the sequence of values
for the key. If you supply more than one key (as in this example), you will
index out of the resulting sequence in correspondence to the order in which you
supplied the indices. If you supply an invalid key, the contents of the
corresponding item in the result will contain nothing (as illustrated here for
'x' )
Remove ( ~ ): Vector
operations should be intuitive. They perform extension of single keys to
multiple values and single values to multiple keys. They do not force
conformity as some of the vector objects do. This is because there is usually
no logical meaning for putting 3 things into two places. For removal, key value
pairs are supplied (as in this case we have two such pairs). The
"without" operator ( ~ ) leaves the index without the
key/value pairs. As with dictionaries, it is illogical to return the entire
index as the result (it could be huge). Thus, the removals are done "in
place".
Remove By Key: You remove all
items for a given key by just supplying the key alone.
Remove with ambiguity: Notice in
this example, there can be ambiguity when I remove. Do I mean remove the
"dk3/ck" key/value pair? Or do I mean remove the
"dk3" key and the "ck" key. To remove the
ambiguity enclose ('dk3' 'ck'>). Without the enclose (
> ) I would remove all the dk3's and all the ck's. I
need to get some experience with describing removals that can have this kind of
ambiguity. I want the power but I don't want the risk. If I find this
problematic, I will fall back to the less risky capability. Be careful and
experiment.