Data Storage and Retrieval

About Data Storage on Newton Devices

key values,

indexValidTest

functions are fast and efficient because index key

values are always kept in memory.

Another kind of customized test, the

validTest

function, works like the

indexValidTest

function but tests the soup entry itself rather than its associated

index key value. To perform this test, the query must actually read the soup entry
into the NewtonScript heap, which takes more time and uses more memory than
tests which operate on index key values only. Thus, for performance reasons,

validTest

functions should be used only when absolutely necessary. It is

strongly suggested that you use index-based approaches to limit the range of
entries passed to the

validTest

function.

For information on using

indexValidTest

and

validTest

functions, see

"Querying on Single-Slot Indexes" beginning on page 11-39.

Text Queries

11

Queries can also select entries according to the presence of one or more specified
strings. For instructional purposes, this section describes separately each of the text
searches that queries can perform--remember, though, that a single query spec can
specify multiple tests for the query to perform on each soup entry it examines.

A words query tests all strings in each soup entry for a word beginning or for an
entire word. A text query is similar to a words query but its test is not limited to
word boundaries.

The default behavior for a words query is to test for word beginnings. For example,
a words query on the string

"smith"

would find the words

"smithe"

and

"smithereens"

. The word

"blacksmith"

would not be included in the results

of the search because the string

"smith"

is not at a word beginning. Because

words queries are not case sensitive, the word

"Smithsonian"

would also be

found by this query.

If you specify that the words query match only entire words, it returns only entries
containing the entire word

"smith"

or

"Smith"

and does not return any other

variations. You can also specify explicitly that the query be sensitive to case and
diacritics, causing it to return only the

"smith"

entry.

A words query is slower than a similar index query because it takes some time to
test all the string values in a soup entry. For information about performing words
queries, see "Querying for Text" beginning on page 11-43.

A text query is similar to a words query but its test is not limited to word
boundaries; that is, it tests all strings in each soup entry for one or more specified
strings, regardless of where they appear in the word. For example, a words query
on the string

"smith"

would find the words

"smithe"

and

"smithereens"

as

well as the word

"blacksmith"

. Because text queries are not case sensitive