From: Florian Forster Date: Wed, 19 May 2010 15:59:17 +0000 (+0200) Subject: src/sn_comparator.h: Add Doxygen documentation. X-Git-Tag: v1.0.0~31 X-Git-Url: https://git.verplant.org/?a=commitdiff_plain;h=db9c59d0b8c87dce7c2dd3e409c8c5c844d1f2e6;p=sort-networks.git src/sn_comparator.h: Add Doxygen documentation. --- diff --git a/src/sn_comparator.c b/src/sn_comparator.c index 4176c7c..18361e4 100644 --- a/src/sn_comparator.c +++ b/src/sn_comparator.c @@ -88,11 +88,9 @@ void sn_comparator_swap (sn_comparator_t *c, int con0, int con1) } } /* void sn_comparator_swap */ -int sn_comparator_compare (const void *v0, const void *v1) +int sn_comparator_compare (const sn_comparator_t *c0, + const sn_comparator_t *c1) { - sn_comparator_t *c0 = (sn_comparator_t *) v0; - sn_comparator_t *c1 = (sn_comparator_t *) v1; - if (SN_COMP_LEFT (c0) < SN_COMP_LEFT (c1)) return (-1); else if (SN_COMP_LEFT (c0) > SN_COMP_LEFT (c1)) diff --git a/src/sn_comparator.h b/src/sn_comparator.h index 09c2b57..db46982 100644 --- a/src/sn_comparator.h +++ b/src/sn_comparator.h @@ -27,25 +27,84 @@ #ifndef SN_COMPARATOR_H #define SN_COMPARATOR_H 1 +/** + * Struct representing a comparator. Don't access the members of this struct + * directly, use the macros below instead. + */ struct sn_comparator_s { - int min; - int max; + int min; /**< Index of the line onto which the smaller element will be put. */ + int max; /**< Index of the line onto which the larger element will be put. */ }; typedef struct sn_comparator_s sn_comparator_t; +/** Returns the "left" line, i.e. the line with the smaller index. */ #define SN_COMP_LEFT(c) (((c)->min < (c)->max) ? (c)->min : (c)->max) +/** Returns the "right" line, i.e. the line with the larger index. */ #define SN_COMP_RIGHT(c) (((c)->min > (c)->max) ? (c)->min : (c)->max) +/** Returns the index of the line onto which the smaller element will be put. */ #define SN_COMP_MIN(c) (c)->min +/** Returns the index of the line onto which the larger element will be put. */ #define SN_COMP_MAX(c) (c)->max +/** + * Allocates, initializes and returns a new comparator object. The returned + * pointer must be freed by sn_comparator_destroy(). + * + * \param min Index of the line onto which the smaller element will be put. + * \param max Index of the line onto which the larger element will be put. + * \return The newly allocated object or \c NULL on failure. + */ sn_comparator_t *sn_comparator_create (int min, int max); + +/** + * Destroys a comparator object, freeing all allocated space. + * + * \param c Pointer to the comparator object. This pointer must be allocated by + * sn_comparator_create(). + */ void sn_comparator_destroy (sn_comparator_t *c); + +/** + * Inverts a comparator by switching the minimum and maximum indexes stored in + * the comparator. + * + * \param c Pointer to the comparator. + */ void sn_comparator_invert (sn_comparator_t *c); + +/** + * Shifts the indexes stored in the comparator by a constant offset. If the + * index becomes too large, it will "wrap around". + * + * \param c The comparator to modify. + * \param sw The offset by which to shift the indexes. + * \param inputs_num The number of lines / inputs of the comparator network. + * This number is used to wrap large indexes around. + */ void sn_comparator_shift (sn_comparator_t *c, int sw, int inputs_num); + +/** + * Swaps two line indexes by replacing all occurrences of one index with + * another index and vice versa. If the comparator does not touch either line, + * this is a no-op. + * + * \param c The comparator to modify. + * \param con0 Index of the first line. + * \param con1 Index of the second line. + */ void sn_comparator_swap (sn_comparator_t *c, int con0, int con1); -int sn_comparator_compare (const void *, const void *); +/** + * Compares two comparators and returns less than zero, zero, or greater than + * zero if the first comparator is smaller than, equal to or larger than the + * second comparator, respectively. + * + * \param c0 Pointer to the first comparator. + * \param c1 Pointer to the second comparator. + */ +int sn_comparator_compare (const sn_comparator_t *c0, + const sn_comparator_t *c1); #endif /* SN_COMPARATOR_H */