Using entries 11 – Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) User Manual

Page 489

C H A P T E R 1 1

Data Storage and Retrieval

Using Newton Data Storage Objects

11-57

Note that if the query used to generate the cursor specifies a

beginKey

value, the

CountEntries

method starts counting at the first valid entry having an index key

value equal to or greater than the

beginKey

value. Similarly, if the query that

generated the cursor used an

endKey

value, the

CountEntries

method stops

counting at the last valid entry having an index key value equal to or less than the

endKey

value.

Note that the use of the

CountEntries

method is somewhat time-consuming and

may increase your application’s heap space requirements; for performance reasons,
use this method only when necessary.

Getting the Current Entry’s Index Key

The

EntryKey

cursor method returns the index key data associated with the

current cursor entry without reading the entry into the NewtonScript heap. Note,
however, that under certain circumstances the value returned by this method does
not match the entry’s index key data exactly. For more information, see “Limitations
of Index Keys” on page 11-52.

Copying Cursors

You can clone a cursor to use for browsing soup entries without disturbing the
original cursor. Do not use the global functions

Clone

DeepClone

to clone

cursors. Instead, use the

Clone

method of the cursor to be copied, as shown in the

following code fragment:

local namesUSoup:= GetUnionSoupAlways(ROM_CardFileSoupName);

local namesCursor := namesUSoup:Query(nil);

local cursorCopy:= namesCursor:Clone();

Using Entries

This section discusses the functions and methods that work with soup entry objects
returned by cursors. This section describes

■

adding entries to soups

■

removing entries from soups

■

saving references to entries

■

modifying entries

■

replacing entries

■

sharing entry data

■

copying entry data

■

using the entry cache effectively