Help: $generic_db

Showing help on '$generic_db'

Generic Database

This holds a collection of {string key, datum} pairs, where datum can be anything. At most one datum may be associated with any given string. Data may be anything (lists, strings, numbers, objectids). If you like, you can think of this as an array indexed by strings.
Verbs supplied include

:find(string) => datum, $ambiguous_match or $failed_match
:find_key(string) => full string key, $ambiguous_match or $failed_match
:find_exact(string) => datum or $failed_match (no partial matches)
:find_all(string) => list of all data corresponding to matching strings
:find_all_keys(string) => list of all matching strings

:insert(string,datum)
if the string is already present in the db,
changes the associated datum and returns {old_datum};
otherwise enters a new {string,datum} pair and return 0.
:delete(string)
if there is a datum associated with string,
remove this association and return {datum}; otherwise return 0.
:delete2(string,datum)
if the given datum is associated with string,
removes that association and return {datum},
if some other datum is associated with string, just return {other datum}
otherwise return 0.
:clearall([4|3])
removes all associations from the database.
optional argument changes the type of the database
(4 is normal, 3 is a kludge for when the data are simply boolean flags
i.e., this is a set of strings rather than a string-indexed array;
more on this below)

count [entries|chars] in this
provide some vague statistics about how big this thing is.

N.B. As entries get made, properties belonging to $generic_db.owner will be created on the db object itself. These properties will be created having flags as specified by .node_perms, which by default is "r", but can be changed to "" should you want to ensure that randoms don't have access to the raw information.

Implementation notes
- - - - - - - - - -
The representation is as a `trie', a tree in which each internal node corresponds to a prefix shared by two or more strings in the db.
Each internal node is kept in a property named " "+<prefix>, where <prefix> is a prefix shared by all strings in the subtree under this node.
The property value is a 4 element list

this.(" "+<prefix>)[1] = <common>
maximal continuation shared by all strings beginning with prefix
i.e., all these names actually begin with <prefix>+<common>

this.(" "+<prefix>)[2] = <continuations>
string of all characters <c> that can follow <prefix>+<common> for which
there is more than one string in the db beginning with <prefix>+<common>+<c>

this.(" "+<prefix>)[3] = <exact_matches>
list of all strings in this subtree for which
the character (or lack thereof) following the <prefix>+<common> substring
suffices to determine the string.

this.(" "+<prefix>)[4] = <data>
list of data corresponding to the strings in [3].

Child nodes are this.(" "+<prefix>+<common>+<c>)
for all <c> in this.(" "+<prefix>)[2].
The root node is this.(" ").
If, e.g., there are 2 or more strings in the db beginning with a,
there will be a node this.(" a").
If all of these strings actually begin with "ani", then this.(" a")[1]=="ni".
The db consisting of the 5 correspondences

{"animal", #1}
{"anime", #2}
{"anil", #3}
{"anile", #4}
{"banal", #5}

would be represented

this.(" ") =={"", "a", {"banal"}, {#5}}
this.(" a") =={"ni","lm", {}, {}}
this.(" anim")=={"", "", {"animal","anime"},{#1,#2}}
this.(" anil")=={"", "", {"anil","anile"}, {#3,#4}}

In some cases one may merely wish to hold a collection of strings without trying to associate a particular datum with each string. One may then instead set up a db without the fourth field on each of the properties. In this case the datum is taken to be the found string itself and that is what gets returned by :find*() in the event of a successful search. :find and :find_key are then equivalent as are :find_all and :find_all_keys. To setup the db this way, do a :clearall(3). :clearall(4) reverts to the above described type of db with a separately kept datum. Note that you can't change the type without emptying the db. 3 and 4 are currently the only db types allowed.