include/xbt/set.h

   1 /* xbt/set.h -- api to a generic dictionary                                 */
   2
   3 /* Copyright (c) 2004 Martin Quinson. All rights reserved.                  */
   4
   5 /* This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the license (GNU LGPL) which comes with this package. */
   7
   8 #ifndef _XBT_SET_H
   9 #define _XBT_SET_H
  10
  11 #include "xbt/misc.h"           /* SG_BEGIN_DECL */
  12 #include "xbt/function_types.h"
  13
  14 SG_BEGIN_DECL()
  15
  16 /** @addtogroup XBT_set
  17  *  @brief A data container consisting in \ref XBT_dict and \ref XBT_dynar
  18  *
  19  *  The elements stored in such a data structure can be retrieve both by
  20  *  name and by ID. For this to work, the first fields of the structures
  21  *  stored must begin with the following fields:
  22  *  \verbatim struct {
  23  unsigned int ID;
  24  char        *name;
  25  unsigned int name_len;
  26  // my other fields, constituting the payload
  27 } my_element_type_t; \endverbatim
  28  *
  29  *  Since we are casting elements around, no protection is ensured by the
  30  * compiler. It is thus safer to define the headers using the macro
  31  * defined to that extend:
  32  *  \verbatim struct {
  33  XBT_SET_HEADERS;
  34
  35  // my other fields, constituting the payload
  36 } my_element_type_t; \endverbatim
  37  *
  38  *  It is now possible to remove an element from such a data structure.
  39  *
  40  *  @todo
  41  *  Such a datastructure was necessary/useful to store the GRAS type
  42  *  descriptions, but it should be reworked to become generic.
  43  *
  44  */
  45 /** @defgroup XBT_set_cons Set and set elements, constructor/destructor
  46  *  @ingroup XBT_set
  47  *
  48  *  @{
  49  */
  50 /** \brief Opaque type representing a set */
  51      typedef struct xbt_set_ *xbt_set_t;
  52
  53 #define XBT_SET_HEADERS \
  54   unsigned int ID;      \
  55   char        *name;    \
  56   unsigned int name_len
  57
  58 /** \brief It must be possible to cast set elements to this type */
  59      typedef struct xbt_set_elm_ {
  60        unsigned int ID; /**< Identificator (system assigned) */
  61        char *name;      /**< Name (user assigned) */
  62        unsigned int name_len;
  63                         /**< Length of the name */
  64      } s_xbt_set_elm_t, *xbt_set_elm_t;
  65
  66 /*####[ Functions ]##########################################################*/
  67 XBT_PUBLIC(xbt_set_t) xbt_set_new(void);
  68 XBT_PUBLIC(void) xbt_set_free(xbt_set_t * set);
  69
  70 /** @} */
  71 /** @defgroup XBT_set_basic Sets basic usage
  72  *  @ingroup XBT_set
  73  *
  74  *  @{
  75  */
  76
  77 XBT_PUBLIC(void) xbt_set_add(xbt_set_t set, xbt_set_elm_t elm,
  78                              void_f_pvoid_t free_func);
  79 XBT_PUBLIC(void) xbt_set_remove(xbt_set_t set, xbt_set_elm_t elm);
  80 XBT_PUBLIC(void) xbt_set_remove_by_name(xbt_set_t set, const char *key);
  81 XBT_PUBLIC(xbt_set_elm_t) xbt_set_get_by_name_or_null(xbt_set_t set,
  82                                                       const char *key);
  83 XBT_PUBLIC(void) xbt_set_remove_by_name_ext(xbt_set_t set, const char *key,
  84                                             int key_len);
  85 XBT_PUBLIC(void) xbt_set_remove_by_id(xbt_set_t set, int id);
  86
  87 XBT_PUBLIC(xbt_set_elm_t) xbt_set_get_by_name(xbt_set_t set, const char *key);
  88 XBT_PUBLIC(xbt_set_elm_t) xbt_set_get_by_name_ext(xbt_set_t set,
  89                                                   const char *key,
  90                                                   int key_len);
  91 XBT_PUBLIC(xbt_set_elm_t) xbt_set_get_by_id(xbt_set_t set, int id);
  92
  93 XBT_PUBLIC(unsigned long) xbt_set_length(const xbt_set_t set);
  94
  95
  96 /** @} */
  97 /** @defgroup XBT_set_curs Sets cursors
  98  *  @ingroup XBT_set
  99  *
 100  *  \warning Don't add or remove entries to the cache while traversing
 101  *
 102  *  @{
 103  */
 104
 105 /** @brief Cursor type */
 106      typedef struct xbt_set_cursor_ *xbt_set_cursor_t;
 107
 108 XBT_PUBLIC(void) xbt_set_cursor_first(xbt_set_t set,
 109                                       xbt_set_cursor_t * cursor);
 110 XBT_PUBLIC(void) xbt_set_cursor_step(xbt_set_cursor_t cursor);
 111 XBT_PUBLIC(int) xbt_set_cursor_get_or_free(xbt_set_cursor_t * cursor,
 112                                            xbt_set_elm_t * elm);
 113
 114 /** @brief Iterates over the whole set
 115  *  @hideinitializer
 116  */
 117 #define xbt_set_foreach(set,cursor,elm)                       \
 118   for ((cursor) = NULL, xbt_set_cursor_first((set),&(cursor)) ;   \
 119        xbt_set_cursor_get_or_free(&(cursor),(xbt_set_elm_t*)&(elm));          \
 120        xbt_set_cursor_step(cursor) )
 121
 122 /* @} */
 123 SG_END_DECL()
 124 #endif /* _XBT_SET_H */