Data Storage and Retrieval

About Data Storage on Newton Devices

cursor is positioned on the next valid entry in index key order. Similarly, if a valid
entry is not found at the key value specified for an

endKey

or

endExclKey

value,

the cursor is positioned on the previous valid entry in index key order. (The cursor
is never positioned beyond the

endKey

value or before the

beginKey

value.)

For information on using index queries, see "Querying on Single-Slot Indexes"
beginning on page 11-39 and "Querying on Multiple-Slot Indexes" beginning on
page 11-47.

Tag-based Queries

11

Index queries can also include or exclude entries according to the presence of one
or more tags. A tag is an optional developer-defined symbol that resides in a
specified slot in the soup entry.

The symbols used as tags are stored as the key values in the soup's tags index. As
with any other index, the system maintains the tags index automatically and queries
can test values in this index without reading soup entries into memory. Thus, tag-
based queries are quick and efficient.

Unlike other indexes, the tags index alone cannot be used as the basis of an index
query--it does not sort entries (as other indexes do), it only selects or eliminates
entries according to their associated tag values. However, you need not specify an
additional index in order to query on tag values; when a separate index is not
specified, queries on tags test all entries in the soup.

The tags for which the query tests are specified by a tags query specification
frame or tags query spec supplied as part of the query spec. The tags query spec
can specify set operators such as

not

,

any

,

equal

, and

all

to create complex

filters based on tag values. For example, you could use these operators to query for
entries having the

'USA

or

'west

tags that do not have the

'California

tag.

The set operators used by tags query specs are described in greater detail in "Tag-
based Queries" beginning on page 11-14 of this book and "Tags Query
Specification Frame" (page 9-13) in Newton Programmer's Reference.

Customized Tests

11

The use of indexes, begin keys, end keys, and tags provides sufficient control over
query results for most uses; however, you can specify additional customized tests
when necessary. These tests take the form of an

indexValidTest

or

validTest

function that you define in the query spec.

The

indexValidTest

function tests the index key values associated with each

entry in the range of values over which the cursor iterates. This function returns

nil

for an entry that is to be rejected, and returns any non-

nil

value for an entry

that is to be included in the results of the query. Like all tests that manipulate index