background image
C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects
11-55
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
.
© 2007-2017, o7 studio » при воспроизведении материала сайта ссылка обязательна