Cursor Functions

Moving Cursors

There are a number of functions that let you move the cursor around. You can go forward or backwards, jump a certain amount, or go to a particular location.

cursor:Entry()

This returns the current entry from cursor. If the entry gets removed from the soup while the cursor is still on it, Entry returns 'deleted and no longer rests on a soup entry.

cursor:Next()

As the name implies, this moves cursor to the next entry satisfying the query and then returns it. If you reach the end of the line and there is no next entry, Next returns nil.

cursor:Prev()

Straightforward as the last, this moves cursor backward to the previous entry that satisfies the query and returns it. If you are at the beginning and there is no previous entry, Prev returns nil.

cursor:Goto(entry)

This function moves cursor to entry. The entry must be an entry in the soup and must have already been returned by a call to Entry, Next, or Prev.

cursor:GotoKey(keyValue)

This moves cursor to the first entry with an indexed value equal to keyValue. If no such entry is present, the cursor is put on the next indexed entry. This method should only be called for queries that have specified an indexPath.

cursor:Reset()

This moves cursor back to the first entry that satisfies the query.

cursor:ResetToEnd()

This moves cursor forward to the last entry that satisfies the query.

cursor:WhichEnd()

This returns 'begin if cursor is before the first entry or'end if cursor is after the last entry. Otherwise, the return result is unspecified.

cursor:Move(numEntries)

This moves cursor forward or backward by numEntries. Move(1) is equivalent to Next. Move(-1) is equivalent to Prev(). This function is faster than repeatedly calling Next or Prev.

cursor:CountEntries()

The CountEntries method returns the number of entries that satisfy cursor's query. The following call:

total := cursor:CountEntries()

is equivalent to (but can in some cases be much faster than):

total := 0;
cursor:Reset();
e := cursor:Entry();
while e do begin
   total := total + 1;
   e := cursor:Next();
end;
total;

cursor:Clone()

The Clone method returns a new cursor that shares the same query as cursor. The new cursor has an independent location, and as such provides you a way to have multiple iterators over the same entries.

Note:

Don't use the global functions Clone or DeepClone on a cursor; use this Clone method instead.

MapCursor(cursor, applyFunction)

This function returns, in an array, a subset of the entries in the cursor. MapCursor calls applyFunction for each entry as a cursor iterates over it. applyFunction takes the entry as its parameter and returns a result. If applyFunction is itself nil, then MapCursor returns the full set of query entries. Otherwise, applyfunction returns either nil or a value; if it returns a value, it is appended to the MapCursor array.

An online version of Programming for the Newton using Macintosh, 2nd ed. Š1996, 1994, Julie McKeehan and Neil Rhodes.

Last modified: 1 DEC 1996