From: Michael Beck Date: Wed, 12 Feb 2003 14:24:02 +0000 (+0000) Subject: More doxygen comments added. X-Git-Url: http://nsz.repo.hu/git/?a=commitdiff_plain;h=edfa8c0f8013a06f12ba6c8e65c3c3b38df6bf7b;p=libfirm More doxygen comments added. [r760] --- diff --git a/ir/adt/pset.h b/ir/adt/pset.h index 6aa7dcbe2..3661d653d 100644 --- a/ir/adt/pset.h +++ b/ir/adt/pset.h @@ -14,41 +14,120 @@ #include -/** The type of a pset (Set of pointers) */ +/** + * The abstract type of a pset (Set of pointers). + * + * This kind of sets stores only pointer to elements, the elements itself + * must be stored somewere else. + * + * @see set + */ typedef struct pset pset; -/** a pset entry */ +/** The entry of a pset, representing an element pointer in the set and it's meta-information */ typedef struct { unsigned hash; void *dptr; } pset_entry; -/** the type of a pset compare function */ -typedef int (*pset_cmp_fun) (const void *, const void *); +/** + * The type of a set compare function. + * + * @param elt pointer to an element + * @param key pointer to another element + * + * @return + * 0 if the elements are identically, non-zero else + */ +typedef int (*pset_cmp_fun) (const void *elt, const void *key); + +/** + * Creates a new pset. + * + * @param func the compare function of this pset + * @param slots number of slots + * + * @returns + * created pset + */ +pset *new_pset (pset_cmp_fun func, int slots); + +/** + * Deletes a pset. + * + * @note + * This does NOT delete the elements of this pset, just it's pointers! + */ +void del_pset (pset *pset); + +/** + * Searches an element pointer in a pset. + * + * @param pset the pset to search in + * @param key the element to is searched + * @param hash the hash value of key + * + * @return + * the pointer of the found element in the pset of NULL if it was not found + */ +void *pset_find (pset *pset, const void *key, unsigned hash); + +/** + * Inserts an element pointer into a pset. + * + * @param pset the pset to insert in + * @param key a pointer to the element to be inserted + * @param hash the hash-value of the element + * + * @return a pointer to the inserted element + * + * @note + * It is not possible to insert on element more than once. If a element + * that should be inserted is already in the set, this functions does + * nothing but returning its set_entry. -/** Makes new hash table. Needs function to compare two nodes to - resolve hash value collision and the size. */ -pset *new_pset (pset_cmp_fun, int slots); + */ +void *pset_insert (pset *pset, const void *key, unsigned hash); -/** Deletes hash table */ -void del_pset (pset *); +/** + * Inserts an element pointer into a pset and returns its pset_entry. + * + * @param pset the pset to insert in + * @param key a pointer to the element to be inserted + * @param hash the hash-value of the element + * + * @return a pointer to the pset_entry of the inserted element + * + * @note + * It is not possible to insert on element more than once. If a element + * that should be inserted is already in the pset, this functions does + * nothing but returning its pset_entry. + */ +pset_entry *pset_hinsert (pset *pset, const void *key, unsigned hash); -/** Returns the pointer associated with pointer key. Hash is - the hash value computed from key. Returns Null if key not - in hash table. */ -void *pset_find (pset *, const void *key, unsigned hash); -void *pset_insert (pset *, const void *key, unsigned hash); -pset_entry *pset_hinsert (pset *, const void *key, unsigned hash); -void *pset_remove (pset *, const void *key, unsigned hash); +/** + * Removes an element from a pset. + * + * @param pset the pset to insert in + * @param key a pointer to the element to be inserted + * @param hash the hash-value of the element + * + * @return + * the pointer to the removed element + * + * @remark + * The current implementation did not allow to remove non-existing elements + */ +void *pset_remove (pset *pset, const void *key, unsigned hash); /** returns the first element of a pset */ -void *pset_first (pset *); +void *pset_first (pset *pset); /** returns the next element of a pset */ -void *pset_next (pset *); +void *pset_next (pset *pset); -/** breaks the iteration of a set. Must be called before the next pset_first() call */ -void pset_break (pset *); +/** Breaks the iteration of a set. Must be called before the next pset_first() call */ +void pset_break (pset *pset); #define new_pset(cmp, slots) (PSET_TRACE (new_pset) ((cmp), (slots))) #define pset_find(pset, key, hash) \ diff --git a/ir/adt/set.h b/ir/adt/set.h index 8d32bab88..96fbdd32a 100644 --- a/ir/adt/set.h +++ b/ir/adt/set.h @@ -14,39 +14,107 @@ #include -/** The type of a set. */ +/** + * The abstract type of a set. + * + * This sets stores copies of its elements, so there is no need + * to store the elements after there were added to a set. + * + * @see pset + */ typedef struct set set; -/** an entry of a set */ +/** The entry of a set, representing an element in the set and it's meta-information */ typedef struct set_entry { - unsigned hash; - size_t size; - int dptr[1]; /**< data copied in must not need more + unsigned hash; /**< the hash value of the element */ + size_t size; /**< the size of the element */ + int dptr[1]; /**< the element itself, data copied in must not need more alignment than this */ } set_entry; -/** the type of a set compare function */ +/** + * The type of a set compare function. + * + * @param elt pointer to an element + * @param key pointer to another element + * @param size size of the elements + * + * @return + * 0 if the elements are identically, non-zero else + */ typedef int (*set_cmp_fun) (const void *elt, const void *key, size_t size); -/** creates a new set */ -set *new_set (set_cmp_fun, int slots); +/** + * Creates a new set. + * + * @param func the compare function of this set + * @param slots number of slots + * + * @returns + * created set + */ +set *new_set (set_cmp_fun func, int slots); + +/** Deletes a set and all elements of it. */ +void del_set (set *set); + +/** + * Searches an element in a set. + * + * @param set the set to search in + * @param key the element to is searched + * @param size the size of key + * @param hash the hash value of key + * + * @return + * the address of the found element in the set of NULL if it was not found + */ +void *set_find (set *set, const void *key, size_t size, unsigned hash); -/** deletes a set */ -void del_set (set *); +/** + * Inserts an element into a set. + * + * @param set the set to insert in + * @param key a pointer to the element to be inserted + * @param size the size of the element that should be inserted + * @param hash the hash-value of the element + * + * @return a pointer to the inserted element + * + * @note + * It is not possible to insert on element more than once. If a element + * that should be inserted is already in the set, this functions does + * nothing but returning its pointer. + */ +void *set_insert (set *set, const void *key, size_t size, unsigned hash); -void *set_find (set *, const void *key, size_t, unsigned hash); -void *set_insert (set *, const void *key, size_t, unsigned hash); -set_entry *set_hinsert (set *, const void *key, size_t, unsigned hash); +/** + * Inserts an element into a set and returns its set_entry. + * + * @param set the set to insert in + * @param key a pointer to the element to be inserted + * @param size the size of the element that should be inserted + * @param hash the hash-value of the element + * + * @return a pointer to the set_entry of the inserted element + * + * @note + * It is not possible to insert on element more than once. If a element + * that should be inserted is already in the set, this functions does + * nothing but returning its set_entry. + */ +set_entry *set_hinsert (set *set, const void *key, size_t size, unsigned hash); -/** returns the first element of a set */ -void *set_first (set *); +/** Returns the first element of a set. */ +void *set_first (set *set); -/** returns the next element of a set */ -void *set_next (set *); +/** Returns the next element of a set. */ +void *set_next (set *set); -/** breaks the iteration of a set. Must be called before the next set_first() call */ -void set_break (set *); +/** Breaks the iteration of a set. Must be called before the next set_first() call */ +void set_break (set *set); +/* implementation specific */ #define new_set(cmp, slots) (SET_TRACE (new_set) ((cmp), (slots))) #define set_find(set, key, size, hash) \ _set_search ((set), (key), (size), (hash), _set_find)