Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Related Pages

TreeAgenda


Detailed Description

implemention of an agenda interface using an unbalanced binary search tree.

This module exports an agenda as used in the CDG netsearch module. The agenda manages a set of elements annoted with the ratings. Elements can be inserted according to their rating, and the first element can be retrieved.The agenda is not responsible for determining the rating of an element;it can only deal with pairs(subsequently called items) of elements and scores.

Todo:
Actually the b-tree used here can be implemented in a more general way to be more usefull. An agenda is just one way to use a b-treeish storage organization.

Data Structures

Defines

Functions


Function Documentation

Pointer taBest TreeAgenda  a  ) 
 

returns the best entry (= first) from the agenda.

Parameters:
a the TreeAgenda from which the best item has to be retrieved.
Returns:
the best item in a (or NULL if a is empty).The item remains in the agenda.
Definition at line 533 of file treeagenda.c.

int taCheckNode TreeAgenda  a,
int  index,
Boolean  recursive,
Boolean  better
 

performs internal consistency checks on a TreeAgenda.

This is only for debugging purposes.

Parameters:
a the TreeAgenda that has to be checked.
index the index of the node in the treeagenda.
recursive is TRUE if repetition occurs and FALSE otherwise.
better is TRUE if better consistency and FALSE otherwise.
Returns:
the number of nodes that are checked.
Definition at line 145 of file treeagenda.c.

References taPrintNode().

Referenced by taInsert().

void taDelete TreeAgenda  a  ) 
 

deletes the specified agenda.

The function deallocates all the items in a using *freeState(). Then it deallocates all the entries and the agenda itself.

Parameters:
a the ListAgenda that has to be deleted.
Definition at line 625 of file treeagenda.c.

References taDeleteNode().

int taDeleteNode TreeAgenda  a,
int  index,
Boolean  delete
 

deletes a node.

Parameters:
a the TreeAgenda in which a node has to be deleted.
index the index of the node that has to be deleted in TreeAgenda.
delete TRUE if the item itself is also deallocated and FALSE otherwise.
Definition at line 199 of file treeagenda.c.

Referenced by taDelete().

Boolean taInsert TreeAgenda  a,
double  score,
Pointer  state
 

inserts a new entry into the agenda.

Parameters:
a the TreeAgenda into which a new element has to be inserted.
state the item that is inserted into the TreeAgenda a.
score the state is sorted into the list according to the score.
Returns:
FALSE if the agenda has been truncated and TRUE if we were able to insert the item without any unpleasant side effects. This is going to be reported only once.

If the insertion leads to an overflow,then one of the elements from the tree is deallocated.Note that the element to be removed may be the state itself. Definition at line 379 of file treeagenda.c.

References taCheckNode(), and taPrintNode().

Boolean taIsEmpty TreeAgenda  a  ) 
 

checks if the specified TreeAgenda is empty.

Parameters:
a the TreeAgenda for which emptiness has to be checked.
Returns:
TRUE if agenda a is empty and FALSE otherwise.
Definition at line 337 of file treeagenda.c.

Boolean taIsTruncated TreeAgenda  a  ) 
 

checks for the truncation of the TreeAgenda a.

Parameters:
a the TreeAgenda on which the function taIsTruncated is performed.
Returns:
TRUE if the agenda is already truncated and FALSE otherwise.
Definition at line 348 of file treeagenda.c.

void taIteratorDelete TreeAgendaIterator  ai  ) 
 

deletes the iterator object.

The function deallocates the tree element that was used by the iterator.

Parameters:
ai the iterator object that has to be deleted.
Definition at line 702 of file treeagenda.c.

TreeAgendaIterator taIteratorNew TreeAgenda  a  ) 
 

creates a new iterator object.

This function creates a new iterator for TreeAgenda a.

Parameters:
a the TreeAgenda for which a new iterator has to be created.
Returns:
a new TreeAgendaIterator that will return all items of a sorted by score.
Definition at line 649 of file treeagenda.c.

Pointer taIteratorNextElement TreeAgendaIterator  ai  ) 
 

returns the next item in iterator object.

Parameters:
ai the iterator of the TreeAgenda a.
Returns:
the best item in the underlying agenda that was not already returned by the iterator.
Definition at line 666 of file treeagenda.c.

int taMaxSize TreeAgenda  a  ) 
 

retrieves the size limit of the agenda.

Parameters:
a the TreeAgenda for which the maximum size has to be determined.
Returns:
the max number of entries that can be held by the TreeAgenda a.
Definition at line 315 of file treeagenda.c.

int taMaxSizeSoFar TreeAgenda  a  ) 
 

retrieves the largest attained size of the agenda.

Parameters:
a the TreeAgenda for which the largest size has to be retrieved.
Returns:
the maximum size occupied by the agenda a so far.
Definition at line 326 of file treeagenda.c.

TreeAgenda taNew int  maxsize,
VoidFunction *  f
 

creates a new agenda.

Parameters:
maxsize determines the desired maximal size of an agenda.
f the function for deallocating the element.
Returns:
a pointer to the new structure that can hold upto maxsize entries.
The agenda cannot determine whether it is safe to call this function on an element or not.Passing the wrong function to a taNew() results undefined behaviour. Definition at line 239 of file treeagenda.c.

void taPrintNode TreeAgenda  a,
int  index
 

prints a node.

It is used by the taCheckNode().

Parameters:
a the TreeAgenda whose node has to be printed.
index the index of the node that has to be printed.
Definition at line 104 of file treeagenda.c.

Referenced by taCheckNode(), taInsert(), and taRemoveBest().

Pointer taRemoveBest TreeAgenda  a  ) 
 

removes and returns best entry (= first) from the agenda.

Parameters:
a the TreeAgenda from which the best item has to be retrieved.
Returns:
the best item in a.The corresponding entry is removed and deallocated.
It must not be called on an empty agenda.
Definition at line 549 of file treeagenda.c.

References taPrintNode().

Boolean taResetTruncated TreeAgenda  a  ) 
 

reset the agenda truncation warning.

Parameters:
a the TreeAgenda whose truncationWarning will be set to FALSE.
Returns:
the old value of the truncationWarning
Definition at line 359 of file treeagenda.c.

Boolean taSetVerbosity TreeAgenda  a,
Boolean  b
 

sets verbosity flag.

Parameters:
a the TreeAgenda whose verbosity property is set
b a Boolean which we set the verbosity to
Returns:
the old verbosity state
Definition at line 289 of file treeagenda.c.

int taSize TreeAgenda  a  ) 
 

retrieves size of the agenda.

Parameters:
a the TreeAgenda for which the size has to be retrieved.
Returns:
the current number of entries in the TreeAgenda a.
Definition at line 304 of file treeagenda.c.

Boolean taVerbosity TreeAgenda  a  ) 
 

gets verbosity flag.

Parameters:
a the TreeAgenda whose verbosity property is set
Returns:
the verbosity state
Definition at line 278 of file treeagenda.c.


BLAH 0.95 (20 Oct 2004)