The LevAWC Project
 All Data Structures Files Functions Variables Typedefs Enumerations Macros Pages
Typedefs | Functions
heap.h File Reference
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>

Go to the source code of this file.

Typedefs

typedef struct Heap_Heap
 

Functions

Heap HEAPinit (int(*compare)(const void *key1, const void *key2), void(*destroy)(void *data))
 
void HEAPdestroy (Heap hp)
 
int HEAPinsert (Heap hp, const void *data)
 
const void * HEAPpeek (Heap hp)
 
int HEAPextract (Heap hp, void **data)
 
int HEAPsize (Heap hp)
 
void HEAPprint (Heap hp, void(*callback)(const void *data))
 

Typedef Documentation

typedef struct Heap_* Heap

Use a typedef - to hide the interior of Heap_ - in the implementation file. This is how data hiding can be done in C.

Definition at line 42 of file heap.h.

Function Documentation

void HEAPdestroy ( Heap  hp)

Destroy the heap

The heap is destroyed - that is, all dynamically allocated memory occupied by the elements - will be destroyed. It is the user-defined callback function destroy, given as an argument to HEAPinit(), that is responsible for freeing dynamically allocated element data, when this function is called. If, on the other hand, destroy is set to NULL when HEAPinit() is called, all element data will be left untouched after the heap is dismounted and destroyed. When all elements and data have been deallocated - the rest of the heap is freed, too.

Parameters
[in]hp- a reference to current heap.
Returns
Nothing.
See Also
HEAPinit()

Definition at line 70 of file heap.c.

int HEAPextract ( Heap  hp,
void **  data 
)

Remove data from the top of the heap

When called, the 2nd parameter of this function, data, should reference an (external, user-defined) pointer. After the call - this referenced, external pointer has been redirected by this function, to point to the data of the removed element - if the call was succesful. The caller is responsible for the future of this memory - deallocating it, if needed, for example.

Parameters
[in]hp- reference to current heap.
[out]data- reference to a pointer. After the call, this referenced pointer has been redirected to point to the data of the removed element - if the call was successful. The caller is responsible for the future of this memory - deallocating it, for example.
Returns
Value 0 – if the call was OK - that is, element removed.
Value -1 – otherwise.

Definition at line 128 of file heap.c.

Heap HEAPinit ( int(*)(const void *key1, const void *key2)  compare,
void(*)(void *data)  destroy 
)

Initiate the heap

Parameters
[in]compare- a reference to a user-defined function, used by various heap operations to compare elements when operating on the heap. This function should return +1 - if key1 > key2 - 0 if the keys are equal - and -1 if key1 < key2. This goes for a top-heavy heap. If you want a bottom-heavy heap, you should swap the the conditions for returning 1 and -1 instead.
[in]destroy- a reference to a user-defined function, reponsible for freeing element data, when the heap is destroyed. If destroy is set to NULL - then element data will be left untouched upon heap destruction.
Returns
A reference - to a new, empty heap - if dynamic memory allocation for the ADT was successful - or NULL otherwise. Take really good care of this return value, since it will be needed as a parameter in subsequent calls - to the majority of other heap functions in this function interface - i.e. a sort of "handle" to the heap.

Definition at line 54 of file heap.c.

int HEAPinsert ( Heap  hp,
const void *  data 
)

Insert data into the heap

Inserts an element into the current heap - referenced by the parameter hp. The data to be inserted, is referenced by parameter data. It is the responsability of the caller to ensure, that this memory is valid as long as it is present in the heap.

Parameters
[in]hp- a reference to current heap.
[in]data- a reference to data to be inserted into the heap.
Returns
Value 0 - if insertion was succesful
Value -1 - otherwise.

Definition at line 85 of file heap.c.

const void* HEAPpeek ( Heap  hp)

Inspect the top-priority element of the heap

Parameters
[in]hp- a reference to the current heap.
Returns
A reference to the top-priority element of the current heap.

Definition at line 122 of file heap.c.

void HEAPprint ( Heap  hp,
void(*)(const void *data)  callback 
)

Print heap data on screen

Parameters
[in]hp- reference to current heap.
[in]callback- reference to user-defined callback function, that gets read access to element data via its parameter data - to do whatever is relevant. In this case it is a matter of formatting data for printing on screen. The printed data should be kept to a minimum (the key value, for example) in order not to clutter the screen. This function is primarily for small heaps - and debugging purposes.
Returns
Nothing.

Definition at line 215 of file heap.c.

int HEAPsize ( Heap  hp)

Get the size of the heap

Parameters
[in]hp- a reference to the current heap.
Returns
The size, that is, the number of elements in the heap.

Definition at line 209 of file heap.c.