nsz Git - libfirm/blob - ir/adt/plist.h

   1 /**
   2  * Simple, non circular, double linked pointer list.
   3  * Created because the properties of the standard circular list were not
   4  * very well suited for the interference graph implementation.
   5  * This list uses an obstack and a free-list to efficiently manage its
   6  * elements.
   7  * @author Kimon Hoffmann
   8  * @date 17.07.2005
   9  * @note Until now the code is entirely untested so it probably contains
  10  *              plenty of errors.
  11  */
  12 #ifndef _PLIST_H_
  13 #define _PLIST_H_
  14
  15 #include <stddef.h>
  16
  17 /**
  18  * The Plist data type.
  19  */
  20 typedef struct PList PList;
  21
  22 /**
  23  * An element in the pointer list.
  24  */
  25 typedef struct PListElement PListElement;
  26
  27 /**
  28  * Creates a new pointer list.
  29  * @return The newly created pointer list.
  30  */
  31 PList* plist_new(void);
  32
  33 /**
  34  * Frees the passed pointer list.
  35  * After a call to this function all references to the list and any of
  36  * its elements are invalid.
  37  */
  38 void plist_free(PList* list);
  39
  40 /**
  41  * Returns the number of elements in a pointer list.
  42  * @param list the pointer list
  43  * @return The number of elements in a pointer list.
  44  */
  45 #define plist_count(list) \
  46         ((list)->elementCount)
  47
  48 /**
  49  * Inserts an element at the back of a pointer list.
  50  * @param list the pointer list to append the new element to.
  51  * @param value the element value to append.
  52  */
  53 void plist_insert_back(PList* list, void* value);
  54
  55 /**
  56  * Inserts an element at the front of a pointer list.
  57  * @param list the pointer list to prepend the new element to.
  58  * @param value the element value to prepend.
  59  */
  60 void plist_insert_front(PList* list, void* value);
  61
  62 /**
  63  * Inserts an element into a pointer list before the specified element,
  64  * which must be non null.
  65  * @param list the pointer list to insert the new element into.
  66  * @param element the list element before which the new element should
  67  *              be inserted. This element must be a part of @p list.
  68  * @param value the element value to insert.
  69  */
  70 void plist_insert_before(PList* list, PListElement* element, void* value);
  71
  72 /**
  73  * Inserts an element into a pointer list after the specified element,
  74  * which must be non null.
  75  * @param list the pointer list to insert the new element into.
  76  * @param element the list element after which the new element should
  77  *              be inserted. This element must be a part of @p list.
  78  * @param value the element value to insert.
  79  */
  80 void plist_insert_after(PList* list, PListElement* element, void* value);
  81
  82 /**
  83  * Erases the specified element from the pointer list.
  84  * @param list the pointer list from which the lement should be erased.
  85  * @param element the list element to erase. This element must be a part
  86  *              of @p list.
  87  */
  88 void plist_erase(PList* list, PListElement* element);
  89
  90 /**
  91  * Erases all elements from the specified pointer list.
  92  * @param list the pointer list that should be cleard.
  93  */
  94 void plist_clear(PList* list);
  95
  96 /**
  97  * Returns the first element of a pointer list.
  98  * @param list the pointer list to iterate
  99  * @return a pointer to the element or NULL if the list is empty
 100  */
 101  #define plist_first(list) \
 102         ((list)->firstElement)
 103
 104 /**
 105  * Returns the last element of a pointer list.
 106  * @param list the pointer list to iterate
 107  * @return a pointer to the element or NULL if the list is empty
 108  */
 109  #define plist_last(list) \
 110         ((list)->lastElement)
 111
 112 /**
 113  * Checks whether a pointer list element has a successor or not.
 114  * @param element the list element that should be queried for existance
 115  *              of a successor.
 116  * @return TRUE if @p element has a successor, otherwise FALSE.
 117  */
 118 #define plist_element_has_next(element) \
 119         ((element)->next != NULL)
 120
 121 /**
 122  * Checks whether a pointer list element has a predecessor or not.
 123  * @param element the list element that should be queried for existance
 124  *              of a predecessor.
 125  * @return TRUE if @p element has a successor, otherwise FALSE.
 126  */
 127 #define plist_element_has_prev(element) \
 128         ((element)->prev != NULL)
 129
 130 /**
 131  * Gets the successor of the passed list element.
 132  * @param element the list element to return the successor of.
 133  * @return The successor of @p element or NULL if @p element is the last
 134  *              element in the sequence.
 135  */
 136 #define plist_element_get_next(element) \
 137         ((element)->next)
 138
 139 /**
 140  * Gets the predecessor of the passed list element.
 141  * @param element the list element to return the predecessor of.
 142  * @return The predecessor of @p element or NULL if @p element is the last
 143  *              element in the sequence.
 144  */
 145 #define plist_element_get_prev(element) \
 146         ((element)->prev)
 147
 148 /**
 149  * Gets the value stored in the passed list element.
 150  * @param element the list element to return the value of.
 151  * @return The value stored in @p element.
 152  */
 153 #define plist_element_get_value(element) \
 154         ((element)->data)
 155
 156 #endif /*_PLIST_H_*/