/**
* Adds the element with the specified priority to the
* end of the priority queue without ensuring the
* heap condition.
*
* This function has a time complexity of O(1).
*
* This function together with \Ref{pblPriorityQueueConstruct}()
* can be used to build a priority queue with N elements
* in time proportional to N.
*
* First create an empty queue with \Ref{pblPriorityQueueNew}()
* and ensure the queue has space for N elements via a
* call to \Ref{pblPriorityQueueEnsureCapacity}(),
* then add all elements via calls to this function
* and finally ensure the heap condition with a call
* to \Ref{pblPriorityQueueConstruct}().
*
* @return int rc >= 0: The size of the queue.
* @return int rc < 0: An error, see pbl_errno:
*
* <BR>PBL_ERROR_OUT_OF_MEMORY - Out of memory.
*/
int pblPriorityQueueAddLast( /* */
PblPriorityQueue * queue, /** The queue to use */
int priority, /** Priority of the element to be added */
void * element /** Element to be added to the queue */
)
{
int rc;
PblPriorityQueueEntry *newEntry = (PblPriorityQueueEntry *) pbl_malloc("pblPriorityQueueAddLast",
sizeof(PblPriorityQueueEntry));
if (!newEntry)
{
return -1;
}
newEntry->element = element;
newEntry->priority = priority;
rc = pblHeapAddLast((PblHeap *) queue, newEntry);
if (rc < 0)
{
PBL_FREE(newEntry);
return rc;
}
return pblHeapSize((PblHeap *) queue);
}
/**
* 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 number of elements in the priority queue.
*
* This function has a time complexity of O(1).
*
* @return int rc: The number of elements in the priority queue.
*/
int pblPriorityQueueSize( /* */
PblPriorityQueue * queue /** The queue to use */
)
{
return pblHeapSize((PblHeap *) queue);
}