Data Storage and Retrieval

Using Newton Data Storage Objects

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.