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

   1 /*
   2  * This file is part of libFirm.
   3  * Copyright (C) 2012 University of Karlsruhe.
   4  */
   5
   6 /**
   7  * @file
   8  * @date    16.03.2007
   9  * @brief   a set of pointers with a custom compare function
  10  * @author  Matthias Braun
  11  */
  12 #ifndef FIRM_ADT_CPSET_H
  13 #define FIRM_ADT_CPSET_H
  14
  15 /**
  16  * @ingroup adt
  17  * @defgroup Pointer Set (custom Compare)
  18  * A pointer set with user-definable compare function
  19  * @{
  20  */
  21
  22 /**
  23  * The type of a cpset compare function.
  24  *
  25  * @param p1   pointer to an element
  26  * @param p2   pointer to another element
  27  *
  28  * @return  1 if the elements are identically, zero else
  29  */
  30 typedef int (*cpset_cmp_function) (const void *p1, const void *p2);
  31
  32 /**
  33  * The type of a cpset hash function.
  34  */
  35 typedef unsigned (*cpset_hash_function) (const void *obj);
  36
  37 /** @cond PRIVATE */
  38
  39 #define HashSet          cpset_t
  40 #define HashSetIterator  cpset_iterator_t
  41 #define HashSetEntry     cpset_hashset_entry_t
  42 #define ValueType        void*
  43 #define ADDITIONAL_DATA  cpset_cmp_function cmp_function; cpset_hash_function hash_function;
  44 #include "hashset.h"
  45 #undef ADDITIONAL_DATA
  46 #undef ValueType
  47 #undef HashSetEntry
  48 #undef HashSetIterator
  49 #undef HashSet
  50
  51 /** @endcond */
  52
  53 /** a pointer set with custom compare function */
  54 typedef struct cpset_t          cpset_t;
  55 /** iterator over a pointer set with custom compare function
  56  * @see #cpset_t */
  57 typedef struct cpset_iterator_t cpset_iterator_t;
  58
  59 /**
  60  * Initializes a cpset
  61  *
  62  * @param cpset           Pointer to allocated space for the cpset
  63  * @param hash_function   The hash function to use
  64  * @param cmp_function    The compare function to use
  65  */
  66 void cpset_init(cpset_t *cpset, cpset_hash_function hash_function,
  67                 cpset_cmp_function cmp_function);
  68
  69 /**
  70  * Initializes a cpset
  71  *
  72  * @param cpset              Pointer to allocated space for the cpset
  73  * @param hash_function      The hash function to use
  74  * @param cmp_function       The compare function to use
  75  * @param expected_elements  Number of elements expected in the cpset (roughly)
  76  */
  77 void cpset_init_size(cpset_t *cpset, cpset_hash_function hash_function,
  78                      cpset_cmp_function cmp_function,
  79                      size_t expected_elements);
  80
  81 /**
  82  * Destroys a cpset and frees the memory allocated for hashtable. The memory of
  83  * the cpset itself is not freed.
  84  *
  85  * @param cpset   Pointer to the cpset
  86  */
  87 void cpset_destroy(cpset_t *cpset);
  88
  89 /**
  90  * Inserts an element into a cpset.
  91  *
  92  * @param cpset   Pointer to the cpset
  93  * @param obj     Element to insert into the cpset
  94  * @returns       The element itself or a pointer to an existing element
  95  */
  96 void* cpset_insert(cpset_t *cpset, void *obj);
  97
  98 /**
  99  * Removes an element from a cpset. Does nothing if the cpset doesn't contain the
 100  * element.
 101  *
 102  * @param cpset   Pointer to the cpset
 103  * @param obj     Pointer to remove from the cpset
 104  */
 105 void cpset_remove(cpset_t *cpset, const void *obj);
 106
 107 /**
 108  * Tests whether a cpset contains a pointer
 109  *
 110  * @param cpset   Pointer to the cpset
 111  * @param obj     The pointer to find
 112  * @returns       An equivalent object to @p obj or NULL
 113  */
 114 void *cpset_find(const cpset_t *cpset, const void *obj);
 115
 116 /**
 117  * Returns the number of pointers contained in the cpset
 118  *
 119  * @param cpset   Pointer to the cpset
 120  * @returns       Number of pointers contained in the cpset
 121  */
 122 size_t cpset_size(const cpset_t *cpset);
 123
 124 /**
 125  * Initializes a cpset iterator. Sets the iterator before the first element in
 126  * the cpset.
 127  *
 128  * @param iterator   Pointer to already allocated iterator memory
 129  * @param cpset       Pointer to the cpset
 130  */
 131 void cpset_iterator_init(cpset_iterator_t *iterator, const cpset_t *cpset);
 132
 133 /**
 134  * Advances the iterator and returns the current element or NULL if all elements
 135  * in the cpset have been processed.
 136  * @attention It is not allowed to use cpset_insert or cpset_remove while
 137  *            iterating over a cpset.
 138  *
 139  * @param iterator  Pointer to the cpset iterator.
 140  * @returns         Next element in the cpset or NULL
 141  */
 142 void *cpset_iterator_next(cpset_iterator_t *iterator);
 143
 144 /**
 145  * Removed the element the iterator currently points to
 146  *
 147  * @param cpset     Pointer to the cpset
 148  * @param iterator  Pointer to the cpset iterator.
 149  */
 150 void cpset_remove_iterator(cpset_t *cpset, const cpset_iterator_t *iterator);
 151
 152 /** @} */
 153
 154 #endif