Data Storage and Retrieval

About Data Storage on Newton Devices

unless this behavior is requested explicitly, the words

"blackSmith"

and

"Smithsonian"

would also be found by this query.

A text query is slower than its words query counterpart. Text queries do not require
significantly more heap space than other kinds of queries.

For more information about performing text queries, see "Querying for Text"
beginning on page 11-43.

Cursors

11

The

Query

method returns a cursor, which is an object that iterates over the set of

entries satisfying the query spec and returns entries in response to the messages it
receives. Cursors return entries in index key order. As entries in the soup are added,
deleted, and changed, the set of entries the cursor references is updated
dynamically, even after the original query has been performed.

Recall that after selecting a subrange of all entries in the soup, a query can use
various tests to eliminate certain entries within that range. If viewed within the
context of the entire soup index, the final set of valid entries is discontiguous--that
is, it includes gaps occupied by entries that did not meet the criteria established by
the query spec. However, the cursor presents this subset as a continuous range of
entries, as depicted in Figure 11-5.

Initially, the cursor points to the first entry in index order that satisfies the query.
The cursor supplies methods that allow you to determine its current position, retrieve
the entry referenced by its current position, or specify a new position. The cursor
may be moved incrementally, moved to the position occupied by a specified entry
or key, or reset to an initial position that is not necessarily the first entry in the valid
set. Note that it is possible to move the cursor incrementally to a position outside
the valid range of entries, in which case the cursor returns

nil

instead of an entry.

For information about using cursors, see "Using Cursors" beginning on page 11-53.