Class TBtree

TBtree

Support

Supported from 5.0

Description

Provides ordering of entries by key value in a B+-tree (balanced tree) structure.

Entries and keys are handled as untyped TAny* parameters. You specify an entry in the tree to manipulate through a position (TBtreePos) variable. You can also use iterator functions, which take a TBtreeMark, to move through entries in the tree. The tree's settings can be persisted using a TBtreeToken.

To use this class, you must provide a page pool, based on MPagePool, in which to store entries in the tree, and a key handler, based on MBtreeKey, to provide order and keys.

Defined in TBtree:
ClearL(), DeleteAtL(), DeleteL(), EEqualTo, EGreaterEqual, EGreaterThan, ELessEqual, ELessThan, ExtractAtL(), FindL(), FirstL(), InsertL(), IsBroken(), IsDirty(), IsEmpty(), IsIntact(), LastL(), MarkBroken(), MarkCurrent(), MarkDirty(), NextL(), PreviousL(), RepairL(), ResetL(), Set(), TBtree(), TFind, Token()

See also:

• MBtreeKey
• MPagePool
• TBtreeMark
• TBtreePos
• TBtreeToken

TBtree(TBtreeMode aMode);

Description

Constructor that sets the B-tree mode.

Parameters

TBtreeMode aMode B-tree operating mode

TBtree(const TBtreeToken& aToken,TBtreeMode aMode);

Description

Constructor that sets the B-tree mode and initialisation parameters.

Parameters

const TBtreeToken& aToken Parameters with which to initialise B-tree TBtreeMode aMode B-tree operating mode

void Set(const TBtreeToken& aToken,TBtreeMode aMode);

Description

Initialises the B-tree.

Parameters

const TBtreeToken& aToken Parameters with which to initialise the B-tree TBtreeMode aMode B-tree operating mode

void ClearL();

Description

Resets the B-tree to have zero-height, and a null root, and deletes all index pages.

void DeleteAtL(TBtreePos& aPos);

Description

Deletes the entry at the specified position

Parameters

TBtreePos& aPos Position of the entry to delete

TBool DeleteL(const TAny* aKey);

Description

Deletes an entry.

Parameters

const TAny* aKey Pointer to the key of the entry to delete

Return value

TBool True if successful, false if the entry was not found

void ExtractAtL(const TBtreePos& aPos,TAny* anEntry,TInt aMaxLength) const;

Description

Gets the entry at the specified position.

Parameters

const TBtreePos& aPos Position of the entry to get TAny* anEntry Buffer into which to copy the entry TInt aMaxLength Length of the anEntry buffer. If the entry is longer than this, only the first aMaxLength bytes will be copied.

TBool FindL(TBtreePos& aPos,const TAny* aKey,TFind aMode=EEqualTo) const;

Description

Searches for an entry and returns its position.

Parameters

TBtreePos& aPos On return, the position of the entry found const TAny* aKey Pointer to the key of the entry for which to search TFind aMode=EEqualTo Type of search to perform

Return value

TBool True if search was successful, else false

TBool FirstL(TBtreePos& aPos) const;

Description

Goes to the first entry in the B-tree.

Parameters

TBtreePos& aPos On return, the position of the first entry

Return value

TBool True if there is a first entry, otherwise false

TBool InsertL(TBtreePos& aPos,const TAny* anEntry,TInt aLength,TAllowDuplicates aDup=ENoDuplicates);

Description

Inserts an entry into the tree.

Parameters

TBtreePos& aPos On return, the position of the entry inserted const TAny* anEntry Pointer to the entry to insert TInt aLength Length of entry TAllowDuplicates aDup=ENoDuplicates Flag to indicate whether duplicate entries are allowed in the tree

Return value

TBool True if successful, false if the entry was a duplicate and aDup was set to ENoDuplicates

TBool LastL(TBtreePos& aPos) const;

Description

Goes to the last entry in the B-tree.

Parameters

TBtreePos& aPos On return, the position of the last entry

Return value

TBool True if there are any entries, otherwise false

TBool NextL(TBtreePos& aPos) const;

Description

Gets the position of the entry following the specified entry.

Parameters

TBtreePos& aPos On return, the position of the next entry

Return value

TBool True if there are any more entries, otherwise false

TBool PreviousL(TBtreePos& aPos) const;

Description

Gets the position of the entry preceding the specified entry.

Parameters

TBtreePos& aPos On return, the position of the preceding entry

Return value

TBool True if there is a preceding entry, otherwise false

void ExtractAtL(const TBtreeMark& aMark,TAny* anEntry,TInt aMaxLength) const;

Description

Gets an entry at specified iterator position.

Parameters

const TBtreeMark& aMark Position of the entry to get TAny* anEntry Buffer into which to copy the entry TInt aMaxLength Length of anEntry buffer. If the entry is longer than this, only the first aMaxLength bytes are copied.

TBool NextL(TBtreeMark& aMark) const;

Description

Advances an iterator to the next entry.

Parameters

TBtreeMark& aMark Iterator to use. On return, the iterator is advanced to the next entry.

Return value

TBool True if successful, false if there is no next entry

TBool ResetL(TBtreeMark& aMark) const;

Description

Resets an iterator to the root of the tree.

Parameters

TBtreeMark& aMark Iterator to set

Return value

TBool True if successful, false if the B-tree is empty

TBool IsBroken() const;

Description

Tests if the broken flag has been set on the B-tree.

Any updates to the B-tree that fail will leave this flag set on the TBtree object. This indicates that the persistent tree data is broken (corrupt) and the tree needs to be repaired. In this state, none of the functions which use a TBtreePos will work, only those taking a TBtreeMark.

Return value

TBool True if the B-tree is broken, otherwise false.

TBool IsDirty() const;

Description

Tests if the dirty flag has been set on the B-tree.

Any updates to the B-tree will set this flag on the TBtree object. Applications can use this to determine if they need to flush the page pool and re-save the B-tree token, after which they can call MarkCurrent() to indicate that the persistent storage is now up-to-date with the TBtree object.

Return value

TBool True if the dirty flag has been set, otherwise false

TBool IsEmpty() const;

Description

Tests if the B-tree is empty.

Return value

TBool True if the B-tree is empty, otherwise false

TBool IsIntact() const;

Description

Tests if the broken flag has not been set on the B-tree .

Return value

TBool True if the B-tree is not broken, otherwise false.

void MarkBroken();

Description

Sets the broken flag.

void MarkCurrent();

Description

Clears the dirty flag.

void MarkDirty();

Description

Sets the dirty flag.

TBtreeToken Token() const;

Description

Gets an object that encapsulates the TBtree settings.

That object can then be used to externalise the settings.

Return value

TBtreeToken Encapsulates the TBtree settings.

TInt RepairL();

Description

Attempts to repair a broken B-tree.

If the operating mode (TBtreeMode) is set to EBtreeSecure, then the tree can be repaired without any loss of data. Otherwise, the tree must be deleted entirely using ClearL(), and reconstructed using other means.

Note that if multiple B-trees share a single store page pool, then reclaiming the pool will break all the other B-trees (but the Broken flag will not be set automatically). These trees can be repaired by calling MarkBroken() and then RepairL(), even if they were not of the EBtreeSecure type.

Return value

TInt Number of leaves in the tree

See also:

• TBtreeMode

TFind

Description

Sets the condition for a successful match when calling TBtree::Find().

EGreaterEqual Find the first entry greater than or equal to the search target. EEqualTo Find the first entry equal to the search target. ELessThan Find the last entry less than the search target. EGreaterThan Find the first entry greater than the search target. ELessEqual Find the last entry less than or equal to the search target.