2 * \file sn_comparator.h
3 * \brief The sn_comparator_t class and associated methods.
6 * libsortnetwork - src/sn_comparator.h
7 * Copyright (C) 2008-2010 Florian octo Forster
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.
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
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
24 * Florian octo Forster <ff at octo.it>
28 #ifndef SN_COMPARATOR_H
29 #define SN_COMPARATOR_H 1
35 * Struct representing a comparator. Don't access the members of this struct
36 * directly, use the macros below instead.
38 struct sn_comparator_s
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. */
45 typedef struct sn_comparator_s sn_comparator_t;
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
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
62 * Allocates, initializes and returns a new comparator object. The returned
63 * pointer must be freed by sn_comparator_destroy().
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.
69 sn_comparator_t *sn_comparator_create (int min, int max);
72 * Destroys a comparator object, freeing all allocated space.
74 * \param c Pointer to the comparator object. This pointer must be allocated by
75 * sn_comparator_create().
77 void sn_comparator_destroy (sn_comparator_t *c);
80 * Inverts a comparator by switching the minimum and maximum indexes stored in
83 * \param c Pointer to the comparator.
85 void sn_comparator_invert (sn_comparator_t *c);
88 * Shifts the indexes stored in the comparator by a constant offset. If the
89 * index becomes too large, it will "wrap around".
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.
96 void sn_comparator_shift (sn_comparator_t *c, int sw, int inputs_num);
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,
103 * \param c The comparator to modify.
104 * \param con0 Index of the first line.
105 * \param con1 Index of the second line.
107 void sn_comparator_swap (sn_comparator_t *c, int con0, int con1);
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.
114 * \param c0 Pointer to the first comparator.
115 * \param c1 Pointer to the second comparator.
117 int sn_comparator_compare (const sn_comparator_t *c0,
118 const sn_comparator_t *c1);
120 uint64_t sn_comparator_get_hashval (const sn_comparator_t *c);
122 #endif /* SN_COMPARATOR_H */
124 /* vim: set shiftwidth=2 softtabstop=2 : */