TBtree Class Reference

#include <s32btree.h>

Link against: estor.lib

class TBtree

Public Member Enumerations
enum	TFind { EGreaterEqual, EEqualTo, ELessThan, EGreaterThan, ELessEqual }

Public Member Functions
	TBtree(TBtreeMode)
	TBtree(const TBtreeToken &, TBtreeMode)
IMPORT_C void	ClearL()
IMPORT_C void	Connect(MPagePool , const MBtreeKey , const MBtreeLeafOrg , const MBtreeIndexOrg )
IMPORT_C void	DeleteAtL(TBtreePos &)
IMPORT_C TBool	DeleteL(const TAny *)
IMPORT_C void	ExtractAtL(const TBtreePos &, TAny *, TInt)
IMPORT_C void	ExtractAtL(const TBtreeMark &, TAny *, TInt)
IMPORT_C TBool	FindL(TBtreePos &, const TAny *, TFind)
IMPORT_C TBool	FirstL(TBtreePos &)
IMPORT_C TBool	InsertL(TBtreePos &, const TAny *, TInt, TAllowDuplicates)
TBool	IsBroken()
TBool	IsDirty()
TBool	IsEmpty()
TBool	IsIntact()
IMPORT_C TBool	LastL(TBtreePos &)
void	MarkBroken()
void	MarkCurrent()
void	MarkDirty()
IMPORT_C TBool	NextL(TBtreePos &)
IMPORT_C TBool	NextL(TBtreeMark &)
IMPORT_C TBool	PreviousL(TBtreePos &)
IMPORT_C TInt	RepairL()
IMPORT_C TBool	ResetL(TBtreeMark &)
IMPORT_C void	Set(const TBtreeToken &, TBtreeMode)
IMPORT_C TBtreeToken	Token()

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

Member Enumeration Documentation

Enum TFind

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

Enumerator	Value	Description
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.

Constructor & Destructor Documentation

TBtree ( TBtreeMode )

IMPORT_C

TBtree

(

TBtreeMode

aMode

)

Constructor that sets the B-tree mode.

Parameter	Description
aMode	B-tree operating mode

TBtree ( const TBtreeToken &, TBtreeMode )

IMPORT_C	TBtree	(	const TBtreeToken &	aToken,
			TBtreeMode	aMode
		)

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

Parameter	Description
aToken	Parameters with which to initialise B-tree
aMode	B-tree operating mode

Member Function Documentation

ClearL ( )

IMPORT_C void

ClearL

(

)

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

Connect ( MPagePool , const MBtreeKey , const MBtreeLeafOrg , const MBtreeIndexOrg )

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

DeleteAtL ( TBtreePos & )

IMPORT_C void

DeleteAtL

(

TBtreePos &

aPos

)

Deletes the entry at the specified position

Parameter	Description
aPos	Position of the entry to delete

DeleteL ( const TAny * )

IMPORT_C TBool

DeleteL

(

const TAny *

aKey

)

Deletes an entry.

Parameter	Description
aKey	Pointer to the key of the entry to delete

Returns: True if successful, false if the entry was not found

ExtractAtL ( const TBtreePos &, TAny *, TInt )

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

Gets the entry at the specified position.

Parameter	Description
aPos	Position of the entry to get
anEntry	Buffer into which to copy the entry
aMaxLength	Length of the anEntry buffer. If the entry is longer than this, only the first aMaxLength bytes will be copied.

ExtractAtL ( const TBtreeMark &, TAny *, TInt )

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

Gets an entry at specified iterator position.

Parameter	Description
aMark	Position of the entry to get
anEntry	Buffer into which to copy the entry
aMaxLength	Length of anEntry buffer. If the entry is longer than this, only the first aMaxLength bytes are copied.

FindL ( TBtreePos &, const TAny *, TFind )

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

Searches for an entry and returns its position.

Parameter	Description
aPos	On return, the position of the entry found
aKey	Pointer to the key of the entry for which to search
aMode	Type of search to perform

Returns: True if search was successful, else false

FirstL ( TBtreePos & )

IMPORT_C TBool

FirstL

(

TBtreePos &

aPos

)

const

Goes to the first entry in the B-tree.

Parameter	Description
aPos	On return, the position of the first entry

Returns: True if there is a first entry, otherwise false

InsertL ( TBtreePos &, const TAny *, TInt, TAllowDuplicates )

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

Inserts an entry into the tree.

Parameter	Description
aPos	On return, the position of the entry inserted
anEntry	Pointer to the entry to insert
aLength	Length of entry
aDup	Flag to indicate whether duplicate entries are allowed in the tree

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

IsBroken ( )

TBool

IsBroken

(

)

const [inline]

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.

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

IsDirty ( )

TBool

IsDirty

(

)

const [inline]

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.

Returns: True if the dirty flag has been set, otherwise false

IsEmpty ( )

TBool

IsEmpty

(

)

const [inline]

Tests if the B-tree is empty.

Returns: True if the B-tree is empty, otherwise false

IsIntact ( )

TBool

IsIntact

(

)

const [inline]

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

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

LastL ( TBtreePos & )

IMPORT_C TBool

LastL

(

TBtreePos &

aPos

)

const

Goes to the last entry in the B-tree.

Parameter	Description
aPos	On return, the position of the last entry

Returns: True if there are any entries, otherwise false

MarkBroken ( )

void

MarkBroken

(

)

[inline]

Sets the broken flag.

MarkCurrent ( )

void

MarkCurrent

(

)

[inline]

Clears the dirty flag.

MarkDirty ( )

void

MarkDirty

(

)

[inline]

Sets the dirty flag.

NextL ( TBtreePos & )

IMPORT_C TBool

NextL

(

TBtreePos &

aPos

)

const

Gets the position of the entry following the specified entry.

Parameter	Description
aPos	On return, the position of the next entry

Returns: True if there are any more entries, otherwise false

NextL ( TBtreeMark & )

IMPORT_C TBool

NextL

(

TBtreeMark &

aMark

)

const

Advances an iterator to the next entry.

Parameter	Description
aMark	Iterator to use. On return, the iterator is advanced to the next entry.

Returns: True if successful, false if there is no next entry

PreviousL ( TBtreePos & )

IMPORT_C TBool

PreviousL

(

TBtreePos &

aPos

)

const

Gets the position of the entry preceding the specified entry.

Parameter	Description
aPos	On return, the position of the preceding entry

Returns: True if there is a preceding entry, otherwise false

RepairL ( )

IMPORT_C TInt

RepairL

(

)

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.

ResetL ( TBtreeMark & )

IMPORT_C TBool

ResetL

(

TBtreeMark &

aMark

)

const

Resets an iterator to the root of the tree.

Parameter	Description
aMark	Iterator to set

Returns: True if successful, false if the B-tree is empty

Set ( const TBtreeToken &, TBtreeMode )

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

Initialises the B-tree.

Parameter	Description
aToken	Parameters with which to initialise the B-tree
aMode	B-tree operating mode

Token ( )

IMPORT_C TBtreeToken

Token

(

)

const

Gets an object that encapsulates the TBtree settings.

That object can then be used to externalise the settings.

Returns: Encapsulates the TBtree settings.

TBtree Class Reference

Detailed Description

Member Enumeration Documentation

Enum TFind

Constructor & Destructor Documentation

TBtree ( TBtreeMode )

TBtree ( const TBtreeToken &, TBtreeMode )

Member Function Documentation

ClearL ( )

Connect ( MPagePool *, const MBtreeKey *, const MBtreeLeafOrg *, const MBtreeIndexOrg * )

DeleteAtL ( TBtreePos & )

DeleteL ( const TAny * )

ExtractAtL ( const TBtreePos &, TAny *, TInt )

ExtractAtL ( const TBtreeMark &, TAny *, TInt )

FindL ( TBtreePos &, const TAny *, TFind )

FirstL ( TBtreePos & )

InsertL ( TBtreePos &, const TAny *, TInt, TAllowDuplicates )

IsBroken ( )

IsDirty ( )

IsEmpty ( )

IsIntact ( )

LastL ( TBtreePos & )

MarkBroken ( )

MarkCurrent ( )

MarkDirty ( )

NextL ( TBtreePos & )

NextL ( TBtreeMark & )

PreviousL ( TBtreePos & )

RepairL ( )

ResetL ( TBtreeMark & )

Set ( const TBtreeToken &, TBtreeMode )

Token ( )

Connect ( MPagePool , const MBtreeKey , const MBtreeLeafOrg , const MBtreeIndexOrg )