Class TBtree

class TBtree;

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.

Members

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

See also:

• MBtreeKey
• MPagePool
• TBtreeMark
• TBtreePos
• TBtreeToken

IMPORT_C TBtree(TBtreeMode aMode);

Description

Constructor that sets the B-tree mode.

Parameters

TBtreeMode aMode B-tree operating mode

IMPORT_C 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

IMPORT_C void Connect(MPagePool *aPool, const MBtreeKey *aKey, const MBtreeLeafOrg *aLeafOrg, const MBtreeIndexOrg *anIndexOrg);

Description

Parameters

MPagePool *aPool const MBtreeKey *aKey const MBtreeLeafOrg *aLeafOrg const MBtreeIndexOrg *anIndexOrg

IMPORT_C 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

IMPORT_C 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.

inline 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

inline void MarkCurrent();

Description

Clears the dirty flag.

inline void MarkDirty();

Description

Sets the dirty flag.

inline 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.

inline 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.

inline void MarkBroken();

Description

Sets the broken flag.

IMPORT_C 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

inline TBool IsEmpty() const;

Description

Tests if the B-tree is empty.

Return value

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

IMPORT_C void ClearL();

Description

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

IMPORT_C 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

IMPORT_C 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

IMPORT_C 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

IMPORT_C 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

IMPORT_C 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 Type of search to perform

Return value

TBool True if search was successful, else false

IMPORT_C 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 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

IMPORT_C 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

IMPORT_C void DeleteAtL(TBtreePos &aPos);

Description

Deletes the entry at the specified position

Parameters

TBtreePos &aPos Position of the entry to delete

IMPORT_C 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.

IMPORT_C 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

IMPORT_C 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

IMPORT_C 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.

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.