Cursor Functions
cursor:Entry()
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()
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()
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)
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)
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()
cursor
back to the first entry that satisfies the query.
cursor:ResetToEnd()
cursor
forward to the last entry that satisfies the query.
cursor:WhichEnd()
'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)
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()
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()
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.
Clone
or DeepClone
on a cursor; use this Clone
method instead.
MapCursor(cursor, applyFunction)
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