Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) - Manual (Page 483)

C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects 11-51
This time around, the query again skips over the "Bates" entry in the process of
positioning the cursor at index value "P" . However, because no entry holds a
primary index key value of "P" , the cursor stops at the next valid entry in index
order. Further, because an identical index value was not found for the primary key
specification, the secondary and tertiary key selectors have no effect at all. Thus
the cursor stops on the first index value found after the position that
["P","Bruce",5] would occupy if it were present in the index data.
When an element of an array in a query spec is missing or nil , the Query method
does not test subordinate key values specified by the array. For example, the
presence of the
nil value in the endKey specification {endKey : ["bob",
nil, 55]} makes it equivalent to the {endKey : ["bob"]} specification.
One result of this behavior is that it is impossible to make a query ignore higher-
order sort keys while still testing on lower-order keys. For example, it is meaningless
to specify a value such as
[nil, validKey, … ] for the beginKey , beginExclKey ,
endKey , or endExclKey slot in a query spec—the nil -value primary element
specifies that the query is to ignore subsequent elements of the array.
If you want to be able to ignore key specifiers in a query spec selectively, you need
to define for your entries a default “
nil -equivalent” value that does have a position
in index order. For example, you could use the empty string ( "" ) for string key
values, either of the values 0 or MININT for integer key values, and the null
symbol ( '|| ) for symbolic key values.
Further, the presence of a nil -value index key in an entry suppresses the
evaluation of lower-order keys in that entry for sorting in the multiple-slot index.
For example, the entries in the following code fragment sort to the same position in
the multiple-slot index because as soon as the system encounters the
nil key value
in each entry’s secondary slot, it does not attempt to sort that entry any further:
{primary: "foo", secondary: nil, tertiary: "bar"}
{primary: "foo", secondary: nil, tertiary: "qux"}
Querying explicitly for nil key values ( nil -value slots) is not supported. Your
entries’ indexed slots must hold non- nil values to participate in queries.
For cursors generated against multiple-slot indexes, the cursor method GoToKey
accepts arrays of keys as its argument. You can use this method to experiment with
multiple-slot key specifications.
Similarly, for queries on multiple-slot indexes, the input passed to the
indexValidTest function is an array of key values, with the first key in the
array being the primary key, followed by any subordinate key values held by the
entry being tested.