service/protocol-plugin/lib/cpluff/libcpluff/util.h

   1 /*-------------------------------------------------------------------------
   2  * C-Pluff, a plug-in framework for C
   3  * Copyright 2007 Johannes Lehtinen
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining a
   6  * copy of this software and associated documentation files (the "Software"),
   7  * to deal in the Software without restriction, including without limitation
   8  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
   9  * and/or sell copies of the Software, and to permit persons to whom the
  10  * Software is furnished to do so, subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be included
  13  * in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  16  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  20  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  21  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22  *-----------------------------------------------------------------------*/
  23
  24 /** @file
  25  * Declarations for internal utility functions
  26  */
  27
  28 #ifndef UTIL_H_
  29 #define UTIL_H_
  30
  31 #include "../kazlib/list.h"
  32 #include "../kazlib/hash.h"
  33 #include "cpluff.h"
  34 #include "defines.h"
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif //__cplusplus
  39
  40
  41 /* ------------------------------------------------------------------------
  42  * Function declarations
  43  * ----------------------------------------------------------------------*/
  44
  45 // For operating on smallish pointer sets implemented as lists
  46
  47 /**
  48  * Compares pointers.
  49  *
  50  * @param ptr1 the first pointer
  51  * @param ptr2 the second pointer
  52  * @return zero if the pointers are equal, otherwise non-zero
  53  */
  54 CP_HIDDEN int cpi_comp_ptr(const void *ptr1, const void *ptr2) CP_GCC_CONST;
  55
  56 /**
  57  * Returns a hash value for a pointer.
  58  *
  59  * @param ptr the pointer being hashed
  60  * @return the corresponding hash value
  61  */
  62 CP_HIDDEN hash_val_t cpi_hashfunc_ptr(const void *ptr) CP_GCC_CONST;
  63
  64 /**
  65  * Adds a new pointer to a list if the pointer is not yet included.
  66  *
  67  * @param set the set being operated on
  68  * @param ptr the pointer being added
  69  * @return non-zero if the operation was successful, zero if allocation failed
  70  */
  71 CP_HIDDEN int cpi_ptrset_add(list_t *set, void *ptr);
  72
  73 /**
  74  * Removes a pointer from a pointer set, if it is included.
  75  *
  76  * @param set the set being operated on
  77  * @param ptr the pointer being removed
  78  * @return whether the pointer was contained in the set
  79  */
  80 CP_HIDDEN int cpi_ptrset_remove(list_t *set, const void *ptr);
  81
  82 /**
  83  * Returns whether a pointer is included in a pointer set.
  84  *
  85  * @param set the set being operated on
  86  * @param ptr the pointer
  87  * @return non-zero if the pointer is included, zero otherwise
  88  */
  89 CP_HIDDEN int cpi_ptrset_contains(list_t *set, const void *ptr) CP_GCC_PURE;
  90
  91
  92 // Other list processing utility functions
  93
  94 /**
  95  * Processes a node of the list by freeing the associated pointer and
  96  * deleting and destroying the node.
  97  *
  98  * @param list the list being processed
  99  * @param node the list node being processed
 100  * @param dummy a dummy argument to comply with prototype
 101  */
 102 CP_HIDDEN void cpi_process_free_ptr(list_t *list, lnode_t *node, void *dummy);
 103
 104
 105 // Version strings
 106
 107 /**
 108  * Compares two version strings. The comparison algorithm is derived from the
 109  * way Debian package management system compares package versions. First the
 110  * the longest prefix of each string composed entirely of non-digit characters
 111  * is determined. These are compared lexically so that all the letters sort
 112  * earlier than all the non-letters and otherwise the ordering is based on
 113  * ASCII values. If there is a difference it is returned. Otherwise the longest
 114  * prefix of remainder of each string composed entirely of digit characters
 115  * is determined. These are compared numerically with empty string interpreted
 116  * as zero. Again, if there is different it is returned. Otherwise the
 117  * comparison continues with a non-digit component and so on. A NULL version
 118  * is earlier than any non-NULL version. Two NULL versions are equal.
 119  *
 120  * @param v1 the first version string to compare or NULL
 121  * @param v2 the second version string to compare or NULL
 122  * @return less than, equal to or greater than zero when @a v1 < @a v2, @a v1 == @a v2 or @a v1 > @a v2, correspondingly
 123  */
 124 CP_HIDDEN int cpi_vercmp(const char *v1, const char *v2) CP_GCC_PURE;
 125
 126
 127 #ifdef __cplusplus
 128 }
 129 #endif //__cplusplus
 130
 131 #endif //UTIL_H_