Comparison.h (12151B)
1 /*************************************************************************************************** 2 3 Zyan Core Library (Zycore-C) 4 5 Original Author : Florian Bernd 6 7 * Permission is hereby granted, free of charge, to any person obtaining a copy 8 * of this software and associated documentation files (the "Software"), to deal 9 * in the Software without restriction, including without limitation the rights 10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 * copies of the Software, and to permit persons to whom the Software is 12 * furnished to do so, subject to the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be included in all 15 * copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 23 * SOFTWARE. 24 25 ***************************************************************************************************/ 26 27 /** 28 * @file 29 * Defines prototypes of general-purpose comparison functions. 30 */ 31 32 #ifndef ZYCORE_COMPARISON_H 33 #define ZYCORE_COMPARISON_H 34 35 #include <Zycore/Defines.h> 36 #include <Zycore/Types.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /* ============================================================================================== */ 43 /* Enums and types */ 44 /* ============================================================================================== */ 45 46 /** 47 * Defines the `ZyanEqualityComparison` function prototype. 48 * 49 * @param left A pointer to the first element. 50 * @param right A pointer to the second element. 51 * 52 * @return This function should return `ZYAN_TRUE` if the `left` element equals the `right` one 53 * or `ZYAN_FALSE`, if not. 54 */ 55 typedef ZyanBool (*ZyanEqualityComparison)(const void* left, const void* right); 56 57 /** 58 * Defines the `ZyanComparison` function prototype. 59 * 60 * @param left A pointer to the first element. 61 * @param right A pointer to the second element. 62 * 63 * @return This function should return values in the following range: 64 * `left == right -> result == 0` 65 * `left < right -> result < 0` 66 * `left > right -> result > 0` 67 */ 68 typedef ZyanI32 (*ZyanComparison)(const void* left, const void* right); 69 70 /* ============================================================================================== */ 71 /* Macros */ 72 /* ============================================================================================== */ 73 74 /* ---------------------------------------------------------------------------------------------- */ 75 /* Equality comparison functions */ 76 /* ---------------------------------------------------------------------------------------------- */ 77 78 /** 79 * Declares a generic equality comparison function for an integral data-type. 80 * 81 * @param name The name of the function. 82 * @param type The name of the integral data-type. 83 */ 84 #define ZYAN_DECLARE_EQUALITY_COMPARISON(name, type) \ 85 ZyanBool name(const type* left, const type* right) \ 86 { \ 87 ZYAN_ASSERT(left); \ 88 ZYAN_ASSERT(right); \ 89 \ 90 return (*left == *right) ? ZYAN_TRUE : ZYAN_FALSE; \ 91 } 92 93 /** 94 * Declares a generic equality comparison function that compares a single integral 95 * data-type field of a struct. 96 * 97 * @param name The name of the function. 98 * @param type The name of the integral data-type. 99 * @param field_name The name of the struct field. 100 */ 101 #define ZYAN_DECLARE_EQUALITY_COMPARISON_FOR_FIELD(name, type, field_name) \ 102 ZyanBool name(const type* left, const type* right) \ 103 { \ 104 ZYAN_ASSERT(left); \ 105 ZYAN_ASSERT(right); \ 106 \ 107 return (left->field_name == right->field_name) ? ZYAN_TRUE : ZYAN_FALSE; \ 108 } 109 110 /* ---------------------------------------------------------------------------------------------- */ 111 /* Comparison functions */ 112 /* ---------------------------------------------------------------------------------------------- */ 113 114 /** 115 * Declares a generic comparison function for an integral data-type. 116 * 117 * @param name The name of the function. 118 * @param type The name of the integral data-type. 119 */ 120 #define ZYAN_DECLARE_COMPARISON(name, type) \ 121 ZyanI32 name(const type* left, const type* right) \ 122 { \ 123 ZYAN_ASSERT(left); \ 124 ZYAN_ASSERT(right); \ 125 \ 126 if (*left < *right) \ 127 { \ 128 return -1; \ 129 } \ 130 if (*left > *right) \ 131 { \ 132 return 1; \ 133 } \ 134 return 0; \ 135 } 136 137 /** 138 * Declares a generic comparison function that compares a single integral data-type field 139 * of a struct. 140 * 141 * @param name The name of the function. 142 * @param type The name of the integral data-type. 143 * @param field_name The name of the struct field. 144 */ 145 #define ZYAN_DECLARE_COMPARISON_FOR_FIELD(name, type, field_name) \ 146 ZyanI32 name(const type* left, const type* right) \ 147 { \ 148 ZYAN_ASSERT(left); \ 149 ZYAN_ASSERT(right); \ 150 \ 151 if (left->field_name < right->field_name) \ 152 { \ 153 return -1; \ 154 } \ 155 if (left->field_name > right->field_name) \ 156 { \ 157 return 1; \ 158 } \ 159 return 0; \ 160 } 161 162 /* ---------------------------------------------------------------------------------------------- */ 163 164 /* ============================================================================================== */ 165 /* Exported functions */ 166 /* ============================================================================================== */ 167 168 /* ---------------------------------------------------------------------------------------------- */ 169 /* Default equality comparison functions */ 170 /* ---------------------------------------------------------------------------------------------- */ 171 172 /** 173 * Defines a default equality comparison function for pointer values. 174 * 175 * @param left A pointer to the first value. 176 * @param right A pointer to the second value. 177 * 178 * @return Returns `ZYAN_TRUE` if the `left` value equals the `right` one or `ZYAN_FALSE`, if 179 * not. 180 */ 181 ZYAN_INLINE ZYAN_DECLARE_EQUALITY_COMPARISON(ZyanEqualsPointer, void* const) 182 183 /** 184 * Defines a default equality comparison function for `ZyanBool` values. 185 * 186 * @param left A pointer to the first value. 187 * @param right A pointer to the second value. 188 * 189 * @return Returns `ZYAN_TRUE` if the `left` value equals the `right` one or `ZYAN_FALSE`, if 190 * not. 191 */ 192 ZYAN_INLINE ZYAN_DECLARE_EQUALITY_COMPARISON(ZyanEqualsBool, ZyanBool) 193 194 /** 195 * Defines a default equality comparison function for 8-bit numeric values. 196 * 197 * @param left A pointer to the first value. 198 * @param right A pointer to the second value. 199 * 200 * @return Returns `ZYAN_TRUE` if the `left` value equals the `right` one or `ZYAN_FALSE`, if 201 * not. 202 */ 203 ZYAN_INLINE ZYAN_DECLARE_EQUALITY_COMPARISON(ZyanEqualsNumeric8, ZyanU8) 204 205 /** 206 * Defines a default equality comparison function for 16-bit numeric values. 207 * 208 * @param left A pointer to the first value. 209 * @param right A pointer to the second value. 210 * 211 * @return Returns `ZYAN_TRUE` if the `left` value equals the `right` one or `ZYAN_FALSE`, if 212 * not. 213 */ 214 ZYAN_INLINE ZYAN_DECLARE_EQUALITY_COMPARISON(ZyanEqualsNumeric16, ZyanU16) 215 216 /** 217 * Defines a default equality comparison function for 32-bit numeric values. 218 * 219 * @param left A pointer to the first value. 220 * @param right A pointer to the second value. 221 * 222 * @return Returns `ZYAN_TRUE` if the `left` value equals the `right` one or `ZYAN_FALSE`, if 223 * not. 224 */ 225 ZYAN_INLINE ZYAN_DECLARE_EQUALITY_COMPARISON(ZyanEqualsNumeric32, ZyanU32) 226 227 /** 228 * Defines a default equality comparison function for 64-bit numeric values. 229 * 230 * @param left A pointer to the first value. 231 * @param right A pointer to the second value. 232 * 233 * @return Returns `ZYAN_TRUE` if the `left` value equals the `right` one or `ZYAN_FALSE`, if 234 * not. 235 */ 236 ZYAN_INLINE ZYAN_DECLARE_EQUALITY_COMPARISON(ZyanEqualsNumeric64, ZyanU64) 237 238 /* ---------------------------------------------------------------------------------------------- */ 239 /* Default comparison functions */ 240 /* ---------------------------------------------------------------------------------------------- */ 241 242 /** 243 * Defines a default comparison function for pointer values. 244 * 245 * @param left A pointer to the first value. 246 * @param right A pointer to the second value. 247 * 248 * @return Returns `0` if the `left` value equals the `right` one, `-1` if the `left` value is 249 * less than the `right` one, or `1` if the `left` value is greater than the `right` one. 250 */ 251 ZYAN_INLINE ZYAN_DECLARE_COMPARISON(ZyanComparePointer, void* const) 252 253 /** 254 * Defines a default comparison function for `ZyanBool` values. 255 * 256 * @param left A pointer to the first value. 257 * @param right A pointer to the second value. 258 * 259 * @return Returns `0` if the `left` value equals the `right` one, `-1` if the `left` value is 260 * less than the `right` one, or `1` if the `left` value is greater than the `right` one. 261 */ 262 ZYAN_INLINE ZYAN_DECLARE_COMPARISON(ZyanCompareBool, ZyanBool) 263 264 /** 265 * Defines a default comparison function for 8-bit numeric values. 266 * 267 * @param left A pointer to the first value. 268 * @param right A pointer to the second value. 269 * 270 * @return Returns `0` if the `left` value equals the `right` one, `-1` if the `left` value is 271 * less than the `right` one, or `1` if the `left` value is greater than the `right` one. 272 */ 273 ZYAN_INLINE ZYAN_DECLARE_COMPARISON(ZyanCompareNumeric8, ZyanU8) 274 275 /** 276 * Defines a default comparison function for 16-bit numeric values. 277 * 278 * @param left A pointer to the first value. 279 * @param right A pointer to the second value. 280 * 281 * @return Returns `0` if the `left` value equals the `right` one, `-1` if the `left` value is 282 * less than the `right` one, or `1` if the `left` value is greater than the `right` one. 283 */ 284 ZYAN_INLINE ZYAN_DECLARE_COMPARISON(ZyanCompareNumeric16, ZyanU16) 285 286 /** 287 * Defines a default comparison function for 32-bit numeric values. 288 * 289 * @param left A pointer to the first value. 290 * @param right A pointer to the second value. 291 * 292 * @return Returns `0` if the `left` value equals the `right` one, `-1` if the `left` value is 293 * less than the `right` one, or `1` if the `left` value is greater than the `right` one. 294 */ 295 ZYAN_INLINE ZYAN_DECLARE_COMPARISON(ZyanCompareNumeric32, ZyanU32) 296 297 /** 298 * Defines a default comparison function for 64-bit numeric values. 299 * 300 * @param left A pointer to the first value. 301 * @param right A pointer to the second value. 302 * 303 * @return Returns `0` if the `left` value equals the `right` one, `-1` if the `left` value is 304 * less than the `right` one, or `1` if the `left` value is greater than the `right` one. 305 */ 306 ZYAN_INLINE ZYAN_DECLARE_COMPARISON(ZyanCompareNumeric64, ZyanU64) 307 308 /* ---------------------------------------------------------------------------------------------- */ 309 310 /* ============================================================================================== */ 311 312 #ifdef __cplusplus 313 } 314 #endif 315 316 #endif /* ZYCORE_COMPARISON_H */