Data Storage and Retrieval

Using Newton Data Storage Objects

following code fragment illustrates a query that returns entries having strings that
contain the substring

"Bob"

:

// find strings containing the substring "Bob"
local myCursor := mySoup:Query({text: "bob"});

This query finds entries containing words such as

"JoeBob"

, as well as those

containing words such as

"bob"

and

"Bobby"

.

Internationalized Sorting Order for Text Queries

11

Indexes are not normally sensitive to case, diacritical marks, or ligatures in string
values; however, index and query specifications can request this behavior
specifically. When internationalized index ordering is used, uppercase letters sort
first, followed by lowercase letters, diacritical marks, and ligatures. Thus, the letter

A

sorts before the letter

a

, which sorts before the letter

å

, which sorts before the

letter

á

, which sorts before the ligature

æ

.

To index string values in internationalized order, include an optional

sortID

slot

holding the value

1

in the index specification frame used to build a soup's index. A

cursor subsequently generated against that soup returns entries holding the
following strings in the order listed here:

"AA", "aa", "åå", "EE", "ÉÉ", "ee"

This internationalized indexing order is available only for indexes on string values.
When the

sortID

slot is missing from the index spec or this slot's value is

nil

,

the index generated is not sensitive to case, diacritics, or ligatures; in other words,
the index may not necessarily sort

"AA"

before

"aa"

, and so on.

If an index has internationalized ordering, find operations performed by cursors
generated against that index can be made sensitive to case and diacritics. To request
this behavior, include a non-

nil secOrder

slot in the query spec passed to the

Query

method of an internationally-indexed soup.

The value of the

secOrder

slot affects the use of the

beginKey

,

beginExclKey

,

endKey

, and

endExclKey

slots, as well as the

GoToKey

cursor method. For

example, sending the

GoToKey("åå")

message to the cursor generated by this

query returns the first entry found at or after the

"åå"

index value but does not

return entries holding values that vary in case, diacritics, and so on.

When the

secOrder

slot is missing or holds the value

nil

, find operations

carried out by cursor methods such as

GoToKey

ignore case and diacritics; that is,

they may return entries holding case and diacritic variations on the requested value.
For example, sending the

myCursor:GoToKey("åå")

message returns the first

entry found that holds any of the

"AA"

,

"aa"

, or

"åå"

values. However, the

cursor generated by this query still uses the sorting order provided by the