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

C H A P T E R 1 1
Data Storage and Retrieval
11-56 Using Newton Data Storage Objects
You can use the Move method to move the cursor multiple positions. For example,
instead of coding incremental cursor movement as in the following example,
for i := 1 to 5 do myCursor:Next();
you can obtain faster results by using the Move method. The following code
fragment depicts a typical call to this method. After positioning the cursor, the
Move method returns the current entry.
// skip next four entries and return the fifth one or nil
local theEntry := myCursor:Move(5);
To move the cursor in large increments, it’s faster to use the GoTo and GoToKey
methods to position the cursor directly. You can use the GoToKey method to go
directly to the first indexed slot that has a particular value and return the entry
containing that slot, as shown in the following example:
// index spec for soup that generated myCursor
indxSpec: {structure: 'slot, path: 'name, type: 'string};
// go to the first entry that has
// the value "Nige" in the name slot
local theEntry := myCursor:GotoKey("Nige");
If the argument to the GoToKey method is not of the type specified by the soup’s
index spec, this method throws an exception. For example, the index spec in the
previous example specifies that the
name slot holds string data. If you pass a
symbol to the GoToKey method, it signals an error because this soup’s index holds
string data:
// throws exception - arg doesn’t match index data type
myCursor:GotoKey('name);
Counting the Number of Entries in Cursor Data 11
Because the user can add or delete entries at any time, it’s difficult to determine
with absolute certainty the number of entries referenced by a cursor. With that in
mind, you can use the
CountEntries cursor method to discover the number of
entries present in the set referenced by the cursor at the time the CountEntries
method executes.
To discover the number of entries in the entire soup, you can execute a very broad
query that includes all soup entries in the set referenced by the cursor and then
send a
CountEntries message to that cursor. For example:
local allEntriesCursor := mySoup:Query(nil);
local numEntries := allEntriesCursor:CountEntries();