idx = new Index();
t/f = idx.ins(str);
t/f = idx.del(str);
str = idx.loc( [str] );
The "objects" provided by JavaScript are arguably the language's most important feature and are much more flexible than the statically defined "classes" of other object-oriented languages such as C/C++ or Java. Conceptually, JavaScript objects are nothing more than associative arrays or collections of key+data pairs, where the "data" may be any type of JavaScript object, including strings, numbers, functions and other "objects". Each pair is identified by a unique name string or "key" and, in modern JavaScript implementations, they can be accessed extremely rapidly, almost as fast as the statically allocated members of class-based languages.
Unfortunately, these pairs cannot be accessed sequentially, in the sort order of their keys. This is a major disadvantage for the many applications which require this capability. The JSUS Index library (-jjsus.Index) provides collection objects whose key+data elements can be accessed both randomly and sequentially, in order of their keys and their data. In fact, Index object elements are really just simple strings, maintained internally in binary collating sequence. It is up to the programmer to decide how these strings are structured for sorting purposes.
Index objects are created quite conventionally using the new operator. Then, strings may be inserted and deleted using the ins() and del() methods. These return true on success and false on failure. The ins() method will fail if an identical string is already present in the Index. The del() method will fail if the passed string does not exactly match an existing string, as originally inserted. Otherwise, there's not much that can go wrong.
The loc() method is used to retrieve strings from an Index. It's optional str (string) argument is used to identify the desired element and typically contains all or part of a string already inserted into the Index. It may also contain a (partial) string which does not actually exist in the Index. On success, this method returns the first Index string which is equal to or greater than the argument string. If there is no equal or higher string it returns an empty string (which is not considered an error). The special strings '\u0000' and '\uFFFF' may be used to locate the first and last Index strings, respectively. If the argument string is omitted (or empty) the loc() method returns the next string in sequence, after the last one located.
Note that Index objects are not "persistent" and are not automatically backed by any file system object. They simply disappear when the program terminates (or earlier if destroyed using a delete operator). However, it is a simple task to serialize an Index object to a file by reading and writing all of it's strings sequentially. This is left as an exercise for the user.
The JSUS "Scroll" library — a Network Database Manager.