src/sn_comparator.h

   1 /**
   2  * \file sn_comparator.h
   3  * \brief The sn_comparator_t class and associated methods.
   4  *
   5  * \verbatim
   6  * libsortnetwork - src/sn_comparator.h
   7  * Copyright (C) 2008-2010  Florian octo Forster
   8  *
   9  * This program is free software; you can redistribute it and/or modify it
  10  * under the terms of the GNU General Public License as published by the
  11  * Free Software Foundation; only version 2 of the License is applicable.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License along
  19  * with this program; if not, write to the Free Software Foundation, Inc.,
  20  * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  21  *
  22  * Authors:
  23  *   Florian octo Forster <ff at octo.it>
  24  * \endverbatim
  25  **/
  26
  27 #ifndef SN_COMPARATOR_H
  28 #define SN_COMPARATOR_H 1
  29
  30 /**
  31  * Struct representing a comparator. Don't access the members of this struct
  32  * directly, use the macros below instead.
  33  */
  34 struct sn_comparator_s
  35 {
  36   int min; /**< Index of the line onto which the smaller element will be put. */
  37   int max; /**< Index of the line onto which the larger element will be put. */
  38   void *user_data; /**< Pointer to user data. */
  39   void (*free_func) (void *); /**< Pointer to a function used to free the user data pointer. */
  40 };
  41 typedef struct sn_comparator_s sn_comparator_t;
  42
  43 /** Returns the "left" line, i.e. the line with the smaller index. */
  44 #define SN_COMP_LEFT(c)  (((c)->min < (c)->max) ? (c)->min : (c)->max)
  45 /** Returns the "right" line, i.e. the line with the larger index. */
  46 #define SN_COMP_RIGHT(c) (((c)->min > (c)->max) ? (c)->min : (c)->max)
  47 /** Returns the index of the line onto which the smaller element will be put. */
  48 #define SN_COMP_MIN(c) (c)->min
  49 /** Returns the index of the line onto which the larger element will be put. */
  50 #define SN_COMP_MAX(c) (c)->max
  51
  52 /** Expands to the user data pointer. */
  53 #define SN_COMP_USER_DATA(c) (c)->user_data
  54 /** Expands to the free-function pointer. */
  55 #define SN_COMP_FREE_FUNC(c) (c)->free_func
  56
  57 /**
  58  * Allocates, initializes and returns a new comparator object. The returned
  59  * pointer must be freed by sn_comparator_destroy().
  60  *
  61  * \param min Index of the line onto which the smaller element will be put.
  62  * \param max Index of the line onto which the larger element will be put.
  63  * \return The newly allocated object or \c NULL on failure.
  64  */
  65 sn_comparator_t *sn_comparator_create (int min, int max);
  66
  67 /**
  68  * Destroys a comparator object, freeing all allocated space.
  69  *
  70  * \param c Pointer to the comparator object. This pointer must be allocated by
  71  *   sn_comparator_create().
  72  */
  73 void sn_comparator_destroy (sn_comparator_t *c);
  74
  75 /**
  76  * Inverts a comparator by switching the minimum and maximum indexes stored in
  77  * the comparator.
  78  *
  79  * \param c Pointer to the comparator.
  80  */
  81 void sn_comparator_invert (sn_comparator_t *c);
  82
  83 /**
  84  * Shifts the indexes stored in the comparator by a constant offset. If the
  85  * index becomes too large, it will "wrap around".
  86  *
  87  * \param c The comparator to modify.
  88  * \param sw The offset by which to shift the indexes.
  89  * \param inputs_num The number of lines / inputs of the comparator network.
  90  *   This number is used to wrap large indexes around.
  91  */
  92 void sn_comparator_shift (sn_comparator_t *c, int sw, int inputs_num);
  93
  94 /**
  95  * Swaps two line indexes by replacing all occurrences of one index with
  96  * another index and vice versa. If the comparator does not touch either line,
  97  * this is a no-op.
  98  *
  99  * \param c The comparator to modify.
 100  * \param con0 Index of the first line.
 101  * \param con1 Index of the second line.
 102  */
 103 void sn_comparator_swap (sn_comparator_t *c, int con0, int con1);
 104
 105 /**
 106  * Compares two comparators and returns less than zero, zero, or greater than
 107  * zero if the first comparator is smaller than, equal to or larger than the
 108  * second comparator, respectively.
 109  *
 110  * \param c0 Pointer to the first comparator.
 111  * \param c1 Pointer to the second comparator.
 112  */
 113 int sn_comparator_compare (const sn_comparator_t *c0,
 114     const sn_comparator_t *c1);
 115
 116 #endif /* SN_COMPARATOR_H */
 117
 118 /* vim: set shiftwidth=2 softtabstop=2 : */