Data Storage and Retrieval

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();