Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: S32BTREE.H
Link against: estor.lib

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:


Construction and destruction


TBtree()

IMPORT_C TBtree(TBtreeMode aMode);

Description

Constructor that sets the B-tree mode.

Parameters

TBtreeMode aMode

B-tree operating mode


TBtree()

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

[Top]


Member functions


Connect()

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


Set()

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


Token()

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.


IsDirty()

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


MarkCurrent()

inline void MarkCurrent();

Description

Clears the dirty flag.


MarkDirty()

inline void MarkDirty();

Description

Sets the dirty flag.


IsBroken()

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.


IsIntact()

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.


MarkBroken()

inline void MarkBroken();

Description

Sets the broken flag.


RepairL()

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


IsEmpty()

inline TBool IsEmpty() const;

Description

Tests if the B-tree is empty.

Return value

TBool

True if the B-tree is empty, otherwise false


ClearL()

IMPORT_C void ClearL();

Description

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


FirstL()

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


LastL()

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


NextL()

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


PreviousL()

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


FindL()

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


InsertL()

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


DeleteL()

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


DeleteAtL()

IMPORT_C void DeleteAtL(TBtreePos &aPos);

Description

Deletes the entry at the specified position

Parameters

TBtreePos &aPos

Position of the entry to delete


ExtractAtL()

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.


ResetL()

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


NextL()

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


ExtractAtL()

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.

[Top]


Member enumerations


Enum TFind

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.