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