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

C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects 11-41
at or before the position that would be occupied by 27 in the index is the last entry
in the range over which the cursor iterates.
To conduct the same query while excluding the endrange values, specify a
beginExclKey value instead of a beginKey value, and specify an endExclKey
value instead of an endKey value, as shown in the following code fragment:
// mySoup is indexed on the 'number slot
// return entries for which (11 > entry.number < 27 )
local numCursor := mySoup:Query({indexPath: 'number,
beginExclKey: 11,
endExclKey: 27});
Note that a query spec cannot include both the inclusive and exclusive forms of the
same endrange selector; for example, you cannot specify
beginKey and a
beginExclKey values in the same query spec. However, you can specify, for
example, a beginKey value and an endExclKey value in the same query spec.
Because the index sorts entries according to key values, a beginKey on a soup
indexed in descending key order may appear to act like an endKey on a soup
indexed in ascending order, and vice versa. For more information, see “Queries on
Descending Indexes” beginning on page 11-46.
Another way to find all entries having a particular value in a specified slot is to use
an
indexValidTest method, which can test any index key value without reading
its corresponding entry into the NewtonScript heap. The system passes index key
values to this function as the cursor moves. Your
indexValidTest must return a
non- nil value if the entry associated with the key value should be included in the
query result. For example, you could use an indexValidTest method to select
entries that hold even-number values in a specified slot, as shown in the following
code fragment:
// mySoup indexed on 'number slot
// select entries having a 'number slot that holds
// an even value between 19 and 58
local myCursor :=
mySoup:Query({ beginKey: 19, endExclKey: 58,
indexValidTest: func (key)
(key MOD 2 = 0)});
A less-preferred way to test entries is to provide a validTest function to test
entries individually. The use of a validTest increases the memory requirements
of the search because the system must read soup entries into the NewtonScript heap
in order to pass them to the
validTest function. Whenever possible, you should
avoid using validTest methods in favor of using indexValidTest methods.
Generally, you need not use a validTest method unless you must read the
entry’s data to determine whether to include it in the query result.