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

C H A P T E R 1 1
Data Storage and Retrieval
11-14 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