/**
* Changes the priority of the element at the specified position of the
* priority queue, maintaining the heap condition of the queue.
*
* This function has a time complexity of O(Log N),
* with N being the number of elements in the queue.
*
* @return int rc >= 0: The index of the element after the priority change.
* @return int rc < 0: An error see pbl_errno:
*
* <BR>PBL_ERROR_OUT_OF_BOUNDS - Index is out of range (index < 0 || index >= size()).
*/
int pblPriorityQueueChangePriorityAt( /* */
PblPriorityQueue * queue, /** The queue to use */
int index, /** The index at which the priority is to be changed */
int priority /** The new priority of the element */
)
{
PblPriorityQueueEntry *entry =
(PblPriorityQueueEntry *)pblHeapGet( (PblHeap *)queue, index );
if( entry == (PblPriorityQueueEntry *)-1 )
{
return -1;
}
if( priority < entry->priority )
{
int size = pblHeapSize( (PblHeap *)queue );
entry->priority = priority;
// For zero based arrays all entries with an index bigger
// than 'size / 2 - 1' do not have any children.
//
// Decreasing the priority cannot violate the heap condition
// for entries with no children
//
if( index <= size / 2 - 1 )
{
// The heap condition only needs to be ensured
// if the entry has children
//
return pblHeapEnsureCondition( queue, index );
}
}
else if( priority > entry->priority )
{
entry->priority = priority;
// Increasing the priority cannot violate the heap condition
// for the top entry at index 0
//
if( index > 0 )
{
// The heap condition needs to ensured
//
return pblHeapEnsureCondition( queue, index );
}
}
return index;
}
/**
* Removes all of the elements from the priority queue.
*
* <B>Note:</B> No memory of the elements themselves is freed.
*
* This function has a time complexity of O(N),
* with N being the number of elements in the priority queue.
*
* @return void
*/
void pblPriorityQueueClear( /* */
PblPriorityQueue * queue /** The queue to clear */
)
{
int index;
// Loop over the heap and free the entries allocated
// by pblPriorityQueueAddLast()
//
for (index = pblHeapSize((PblHeap *) queue) - 1; index >= 0; index--)
{
void * ptr = pblHeapGet((PblHeap *) queue, index);
if (ptr != (void*) -1)
{
PBL_FREE(ptr);
}
}
pblHeapClear((PblHeap *) queue);
}
/**
* Returns the element at the specified position in the priority queue.
*
* This method has a time complexity of O(1).
*
* @return void * retptr != (void*)-1: The element at the specified position, may be NULL.
* @return void * retptr == (void*)-1: An error, see pbl_errno:
*
* <BR>PBL_ERROR_OUT_OF_BOUNDS - Index is out of range (index < 0 || index >= size()).
*/
void * pblPriorityQueueGet( /* */
PblPriorityQueue * queue, /** The queue to use */
int index, /** Index of the element to return */
int * priority /** On return contains the priority of the element */
)
{
PblPriorityQueueEntry *entry = (PblPriorityQueueEntry *) pblHeapGet((PblHeap *) queue, index);
if (entry == (PblPriorityQueueEntry *) -1)
{
return (void*) -1;
}
if (priority)
{
*priority = entry->priority;
}
return entry->element;
}