## TpHeap TpHeap — a heap queue of pointers |

## Synopsis

    #include <telepathy-glib/telepathy-glib.h>

                        TpHeap;
    TpHeap *            tp_heap_new                         (GCompareFunc comparator,
                                                             GDestroyNotify destructor);
    void                tp_heap_destroy                     (TpHeap *heap);
    void                tp_heap_clear                       (TpHeap *heap);
    void                tp_heap_add                         (TpHeap *heap,
                                                             gpointer element);
    void                tp_heap_remove                      (TpHeap *heap,
                                                             gpointer element);
    gpointer            tp_heap_peek_first                  (TpHeap *heap);
    gpointer            tp_heap_extract_first               (TpHeap *heap);
    guint               tp_heap_size                        (TpHeap *heap);

## Description

A heap queue of pointers.

## Details

### TpHeap

    typedef struct _TpHeap TpHeap;

Structure representing the heap queue. All fields are private.

### tp_heap_new ()

    TpHeap *            tp_heap_new                         (GCompareFunc comparator,
                                                             GDestroyNotify destructor);

`comparator` : | Comparator by which to order the pointers in the heap
`destructor` : | Function to call on the pointers when the heap is destroyed or cleared, or `NULL` if this is not needed
Returns : | A new, empty heap queue.

### tp_heap_destroy ()

    void                tp_heap_destroy                     (TpHeap *heap);

Destroy a TpHeap. The destructor, if any, is called on all items.

`heap` : | The heap queue

### tp_heap_clear ()

    void                tp_heap_clear                       (TpHeap *heap);

Remove all items from a TpHeap. The destructor, if any, is called on all items.

`heap` : | The heap queue

### tp_heap_add ()

    void                tp_heap_add                         (TpHeap *heap,
                                                             gpointer element);

Add element to the heap queue, maintaining correct order.

`heap` : | The heap queue
`element` : | An element

### tp_heap_remove ()

    void                tp_heap_remove                      (TpHeap *heap,
                                                             gpointer element);

Remove `element` from `heap`, if it's present. The destructor, if any, is not called.

`heap` : | The heap queue
`element` : | An element in the heap

### tp_heap_peek_first ()

    gpointer            tp_heap_peek_first                  (TpHeap *heap);

`heap` : | The heap queue
Returns : | The first item in the queue, or `NULL` if the queue is empty

### tp_heap_extract_first ()

    gpointer            tp_heap_extract_first               (TpHeap *heap);

Remove and return the first element in the queue. The destructor, if any, is not called.

`heap` : | The heap queue
Returns : | the removed element

### tp_heap_size ()

    guint               tp_heap_size                        (TpHeap *heap);

`heap` : | The heap queue
Returns : | The number of items in `heap`