Data Storage and Retrieval

Using Newton Data Storage Objects

Moving the Cursor

11

This section describes various ways to position the cursor within the range of
entries it references.

Sometimes the following discussion refers to the "first" entry in a cursor. As you
know, the order imposed on cursor data is defined by the soup index used by the
query that generated the cursor. When you see mentions of the "first" entry in a
cursor, be aware that this phrasing really means "the first entry as defined by index
order (ascending or descending order)."

When first returned by a query, the cursor points to the first entry in the data set
that satisfies the query. Thus, to obtain the first entry in the data set referenced by a
newly created cursor, just send the

Entry

message to the cursor.

You can also position the cursor on the first entry in its data set by sending the

Reset

message. The

Reset

method moves the cursor to the first valid entry in the

query result and returns that entry. For example:

local cursor := mySoup:Query(nil);
// move the cursor ahead a bit
local anEntry := cursor:Move(3);
// go back to first entry
local firstEntry := cursor:Reset();

Note that if the query spec includes a

beginKey

value, the

Reset

method returns

the first valid entry at or after the

beginKey

value in index order.

To obtain the last entry in the set of entries referenced by the cursor, send the

ResetToEnd

cursor message, as shown in the following example:

local cursor := mySoup: Query({indexPath: 'name,

endKey: "ZZ"});

local lastCursorEntry := cursor:ResetToEnd();

Note that if the query spec includes an

endKey

value, the

ResetToEnd

method

positions the cursor on the last valid entry in index order at or before the specified

endKey

value. For example, if you specify an

endKey

value of

"Z"

but the last

valid entry previous to that in index order has the key value

"gardenia"

, the

entry associated with the

"gardenia"

key value is returned.

The cursor can be advanced to the next entry in index order or moved back to the
previous entry by the

Next

and

Prev

methods, respectively. After these methods

move the cursor, they return the current entry. If sending either of these messages
positions the cursor outside of the range of valid entries, it returns

nil

.