Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) User Manual

Page 472

C H A P T E R 1 1

Data Storage and Retrieval

11-40

Using Newton Data Storage Objects

particular slot, the soup must be indexed on that slot. For example, the following
example of a query returns a cursor to all soup entries that have a

name

slot. The

cursor sorts the entries according to the value of this slot. As first returned by the
query, the cursor points to the first entry in index order.

// mySoup is a valid soup indexed on the 'name slot

nameCursor:= mySoup:Query({indexPath:'name});

You can also use the cursor method

GoToKey

to go directly to the first entry

holding a specified name or value in an indexed slot. For examples of the use of
this method, see “Moving the Cursor” beginning on page 11-55.

Using

beginKey

and

endKey

values to limit your search can improve query

performance significantly. The following example is an index query that uses
a

beginKey

value and an

endKey

value to return entries for which

(11

≥

entry.number

≤

27 )

// mySoup is indexed on the 'number slot

local numCursor := mySoup:Query({indexPath: 'number,

beginKey: 11,

endKey: 27});

The index on the

number

slot potentially includes all entries that have a

number

slot. The index sorts entries on their index key values; unless otherwise specified,
the default index order is ascending. Thus, the query can use a

beginKey

value of

to skip over entries holding a value less than

in the

number

slot. The test

can be concluded quickly by specifying a maximum value beyond which the cursor
generated by this query does not proceed. In this case, the

endKey

value specifies

that the query result does not include entries having values greater than

in the

number

slot. When multiple entries hold a specified endrange value, all of them

are included in the result of a query that specifies that endrange value; for example,
if multiple entries in the

mySoup

soup hold the value

in their

number

slot, the

previous example includes all of these entries in its result.

The

beginKey

specification evaluates to a value that occupies a unique position in

the sorted index data for the soup. If no entry is associated with this value, the
cursor is positioned at the next valid entry in index order. For example, if the

mySoup

soup in the previous code fragment does not contain an entry having a

number

slot

that holds the value

, the next valid entry in index order is the first entry in the

range over which the cursor iterates.

Similarly, the

endKey

specification evaluates to a value that occupies a unique

position in the sorted index data for the soup. If no entry is associated with this
value, the cursor stops on the first valid entry in index order before the

endKey

value. For example, if the

mySoup

soup in the previous code fragment does not

contain an entry having a

number

slot that holds the value

, the last valid entry