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 #include <stdint.h>
  32 #include <inttypes.h>
  33
  34 /**
  35  * Struct representing a comparator. Don't access the members of this struct
  36  * directly, use the macros below instead.
  37  */
  38 struct sn_comparator_s
  39 {
  40   int min; /**< Index of the line onto which the smaller element will be put. */
  41   int max; /**< Index of the line onto which the larger element will be put. */
  42   void *user_data; /**< Pointer to user data. */
  43   void (*free_func) (void *); /**< Pointer to a function used to free the user data pointer. */
  44 };
  45 typedef struct sn_comparator_s sn_comparator_t;
  46
  47 /** Returns the "left" line, i.e. the line with the smaller index. */
  48 #define SN_COMP_LEFT(c)  (((c)->min < (c)->max) ? (c)->min : (c)->max)
  49 /** Returns the "right" line, i.e. the line with the larger index. */
  50 #define SN_COMP_RIGHT(c) (((c)->min > (c)->max) ? (c)->min : (c)->max)
  51 /** Returns the index of the line onto which the smaller element will be put. */
  52 #define SN_COMP_MIN(c) (c)->min
  53 /** Returns the index of the line onto which the larger element will be put. */
  54 #define SN_COMP_MAX(c) (c)->max
  55
  56 /** Expands to the user data pointer. */
  57 #define SN_COMP_USER_DATA(c) (c)->user_data
  58 /** Expands to the free-function pointer. */
  59 #define SN_COMP_FREE_FUNC(c) (c)->free_func
  60
  61 /**
  62  * Allocates, initializes and returns a new comparator object. The returned
  63  * pointer must be freed by sn_comparator_destroy().
  64  *
  65  * \param min Index of the line onto which the smaller element will be put.
  66  * \param max Index of the line onto which the larger element will be put.
  67  * \return The newly allocated object or \c NULL on failure.
  68  */
  69 sn_comparator_t *sn_comparator_create (int min, int max);
  70
  71 /**
  72  * Destroys a comparator object, freeing all allocated space.
  73  *
  74  * \param c Pointer to the comparator object. This pointer must be allocated by
  75  *   sn_comparator_create().
  76  */
  77 void sn_comparator_destroy (sn_comparator_t *c);
  78
  79 /**
  80  * Inverts a comparator by switching the minimum and maximum indexes stored in
  81  * the comparator.
  82  *
  83  * \param c Pointer to the comparator.
  84  */
  85 void sn_comparator_invert (sn_comparator_t *c);
  86
  87 /**
  88  * Shifts the indexes stored in the comparator by a constant offset. If the
  89  * index becomes too large, it will "wrap around".
  90  *
  91  * \param c The comparator to modify.
  92  * \param sw The offset by which to shift the indexes.
  93  * \param inputs_num The number of lines / inputs of the comparator network.
  94  *   This number is used to wrap large indexes around.
  95  */
  96 void sn_comparator_shift (sn_comparator_t *c, int sw, int inputs_num);
  97
  98 /**
  99  * Swaps two line indexes by replacing all occurrences of one index with
 100  * another index and vice versa. If the comparator does not touch either line,
 101  * this is a no-op.
 102  *
 103  * \param c The comparator to modify.
 104  * \param con0 Index of the first line.
 105  * \param con1 Index of the second line.
 106  */
 107 void sn_comparator_swap (sn_comparator_t *c, int con0, int con1);
 108
 109 /**
 110  * Compares two comparators and returns less than zero, zero, or greater than
 111  * zero if the first comparator is smaller than, equal to or larger than the
 112  * second comparator, respectively.
 113  *
 114  * \param c0 Pointer to the first comparator.
 115  * \param c1 Pointer to the second comparator.
 116  */
 117 int sn_comparator_compare (const sn_comparator_t *c0,
 118     const sn_comparator_t *c1);
 119
 120 uint32_t sn_comparator_get_hashval (const sn_comparator_t *c);
 121
 122 #endif /* SN_COMPARATOR_H */
 123
 124 /* vim: set shiftwidth=2 softtabstop=2 : */