include/xbt/dict.h

   1 /* $Id$ */
   2
   3 /* xbt/dict.h -- api to a generic dictionary                                */
   4
   5 /* Copyright (c) 2003, 2004 Martin Quinson. All rights reserved.            */
   6
   7 /* This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the license (GNU LGPL) which comes with this package. */
   9
  10
  11 #ifndef _XBT_DICT_H
  12 #define _XBT_DICT_H
  13
  14 #include "xbt/misc.h" /* SG_BEGIN_DECL */
  15 #include "xbt/dynar.h" /* void_f_pvoid_t */
  16
  17 SG_BEGIN_DECL()
  18
  19 /** @addtogroup XBT_dict
  20  *  @brief The dictionnary data structure (comparable to hash tables)
  21  *
  22  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref XBT_API]
  23  *                <tr><td><b>Prev</b>   <td> [\ref XBT_dynar]
  24  *                <tr><td><b>Next</b>   <td> [\ref XBT_set]
  25  *                <tr><td><b>Down</b>   <td> [\ref XBT_dict_cons]        </table></center>
  26  *
  27  *  This section describes the API to a dictionnary structure that
  28  *  associates as string to a void* key. Even if it provides the same
  29  *  functionnality than an hash table, the implementation differs and the
  30  *  internal data-structure rather looks like a tree.
  31  *
  32  *  Here is a little example of use:
  33  *  \verbatim xbt_dict_t mydict = xbt_dict_new();
  34  char buff[512];
  35
  36  sprintf(buff,"some very precious data");
  37  xbt_dict_set(mydict,"my data", strdup(buff), free);
  38
  39  sprintf(buff,"another good stuff");
  40  xbt_dict_set(mydict,"my data", strdup(buff), free); // previous data gets erased (and freed) by second add \endverbatim
  41
  42  *
  43  */
  44
  45 /** @defgroup XBT_dict_cons Dict constructor and destructor
  46  *  @ingroup XBT_dict
  47  *
  48  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref XBT_API]::[\ref XBT_dict]
  49  *                <tr><td>   Prev       <td>
  50  *                <tr><td><b>Next</b>   <td> [\ref XBT_dict_basic]        </table></center>
  51  *
  52  *  @{
  53  */
  54
  55   /** \brief Dictionnary data type (opaque structure) */
  56   typedef struct xbt_dict_ *xbt_dict_t;
  57   xbt_dict_t xbt_dict_new(void);
  58   void xbt_dict_free(xbt_dict_t *dict);
  59
  60 /** @} */
  61 /** @defgroup XBT_dict_basic Dictionnaries basic usage
  62  *  @ingroup XBT_dict
  63  *
  64  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref XBT_API]::[\ref XBT_dict]
  65  *                <tr><td><b>Prev</b>   <td> [\ref XBT_dict_cons]
  66  *                <tr><td><b>Next</b>   <td> [\ref XBT_dict_nnul]        </table></center>
  67  *
  68  * Careful, those functions assume that the key is null-terminated.
  69  *
  70  *  @{
  71  */
  72
  73   void  xbt_dict_set(xbt_dict_t head, const char *key, void *data, void_f_pvoid_t *free_ctn);
  74   void *xbt_dict_get(xbt_dict_t head,const char *key);
  75   void *xbt_dict_get_or_null(xbt_dict_t dict, const char *key);
  76
  77   void xbt_dict_remove(xbt_dict_t head, const char *key);
  78   void xbt_dict_dump(xbt_dict_t head,void (*output)(void*));
  79
  80 /** @} */
  81 /** @defgroup XBT_dict_nnul Dictionnaries with non-nul terminated keys
  82  *  @ingroup XBT_dict
  83  *
  84  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref XBT_API]::[\ref XBT_dict]
  85  *                <tr><td><b>Prev</b>   <td> [\ref XBT_dict_basic]
  86  *                <tr><td><b>Next</b>   <td> [\ref XBT_dict_curs]        </table></center>
  87  *
  88  * Those functions work even with non-null terminated keys.
  89  *
  90  *  @{
  91  */
  92   void  xbt_dict_set_ext(xbt_dict_t     head,
  93                          const char     *key, int  key_len,
  94                          void           *data,
  95                          void_f_pvoid_t *free_ctn);
  96   void *xbt_dict_get_ext(xbt_dict_t head,const char *key, int key_len);
  97   void xbt_dict_remove_ext(xbt_dict_t head, const char *key, int key_len);
  98
  99
 100 /** @} */
 101 /** @defgroup XBT_dict_curs Cursors on dictionnaries
 102  *  @ingroup XBT_dict
 103  *
 104  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref XBT_API]::[\ref XBT_dict]
 105  *                <tr><td><b>Prev</b>   <td> [\ref XBT_dict_nnul]
 106  *                <tr><td><b>Next</b>   <td> [\ref XBT_dict_multi]        </table></center>
 107  *
 108  *  Don't get impressed, there is a lot of functions here, but traversing a
 109  *  dictionnary is imediate with the xbt_dict_foreach macro.
 110  *  You only need the other functions in rare cases (they are not used directly in SG itself).
 111  *
 112  *  Here is an example (assuming that the dictionnary contains strings, ie
 113  *  that the <tt>data</tt> argument of xbt_dict_set was always a null-terminated char*):
 114 \verbatim xbt_dict_cursor_t cursor=NULL;
 115  char *key,*data;
 116
 117  xbt_dict_foreach(head,cursor,key,data) {
 118     printf("   - Seen:  %s->%s\n",key,data);
 119  }\endverbatim
 120
 121  *
 122  *  \warning Do not add or remove entries to the cache while traversing !!
 123  *
 124  *  @{ */
 125
 126   /** @brief Cursor on dictionnaries (opaque type) */
 127   typedef struct xbt_dict_cursor_ *xbt_dict_cursor_t;
 128   xbt_dict_cursor_t xbt_dict_cursor_new(const xbt_dict_t head);
 129   void               xbt_dict_cursor_free(xbt_dict_cursor_t *cursor);
 130
 131   void xbt_dict_cursor_rewind(xbt_dict_cursor_t cursor);
 132
 133
 134   char * xbt_dict_cursor_get_key     (xbt_dict_cursor_t cursor);
 135   void * xbt_dict_cursor_get_data    (xbt_dict_cursor_t cursor);
 136
 137   void xbt_dict_cursor_first (const xbt_dict_t   dict,
 138                              xbt_dict_cursor_t *cursor);
 139   void         xbt_dict_cursor_step        (xbt_dict_cursor_t  cursor);
 140   int          xbt_dict_cursor_get_or_free (xbt_dict_cursor_t *cursor,
 141                                             char              **key,
 142                                             void              **data);
 143   /** @def xbt_dict_foreach
 144       @hideinitializer */
 145 #  define xbt_dict_foreach(dict,cursor,key,data)                       \
 146     for (cursor=NULL, xbt_dict_cursor_first((dict),&(cursor)) ;        \
 147          xbt_dict_cursor_get_or_free(&(cursor),&(key),(void**)(&data));\
 148          xbt_dict_cursor_step(cursor) )
 149
 150 /** @} */
 151 /** @defgroup XBT_dict_multi Multi-level dictionnaries
 152  *  @ingroup XBT_dict
 153  *
 154  * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref XBT_API]::[\ref XBT_dict]
 155  *                <tr><td><b>Prev</b>   <td> [\ref XBT_dict_curs]
 156  *                <tr><td>   Next       <td>              </table></center>
 157  *
 158  * They can be seen as dictionnary of multiple keys or as dictionnary of
 159  * dictionnary of ... of data. Most of the functions here work the same way
 160  * than their simple dictionnary counterpart.
 161  *
 162  * Note that there is no xbt_multidict_free neither xbt_multi_dict_new functions.
 163  * Use xbt_dict_free() and xbt_dict_new() instead.
 164  *
 165  * @{
 166  */
 167
 168 /** \brief To dump multicache, this function dumps a cache                           */
 169 void xbt_dict_print(void *data);
 170 /** \brief To dump multicache, this one dumps a string                               */
 171 void xbt_dict_prints(void *data);
 172
 173
 174 /*----[ xbt_multidict_set ]--------------------------------------------------*/
 175 void
 176 xbt_multidict_set(xbt_dict_t mdict,
 177                   xbt_dynar_t keys,
 178                   void *data,void (*free_ctn)(void*));
 179 void
 180 xbt_multidict_set_ext(xbt_dict_t mdict,
 181                       xbt_dynar_t keys, xbt_dynar_t lens,
 182                       void *data,void_f_pvoid_t *free_ctn);
 183
 184 /*----[ xbt_multidict_get ]--------------------------------------------------*/
 185 void *xbt_multidict_get    (xbt_dict_t mdict, xbt_dynar_t keys);
 186 void *xbt_multidict_get_ext(xbt_dict_t mdict, xbt_dynar_t keys, xbt_dynar_t lens);
 187
 188 /*----[ xbt_multidict_remove ]-----------------------------------------------*/
 189 /*---------------------------------------------------------------------------*/
 190 void xbt_multidict_remove(xbt_dict_t mdict, xbt_dynar_t keys);
 191 void xbt_multidict_remove_ext(xbt_dict_t mdict, xbt_dynar_t keys, xbt_dynar_t lens);
 192
 193 /** @} */
 194
 195 SG_END_DECL()
 196
 197 #endif /* _XBT_DICT_H */