include/xbt/dict.h

   1 /* $Id$ */
   2
   3 /* xbt/dict.h -- api to a generic dictionary                               */
   4
   5 /* Copyright (c) 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" /* BEGIN_DECL */
  15
  16 #ifdef  __cplusplus
  17 extern "C"
  18 #endif
  19
  20 /*####[ Type definition ]####################################################*/
  21 typedef struct xbt_dict_ *xbt_dict_t;
  22
  23 /*####[ Simple dict  functions ]#############################################*/
  24
  25 xbt_dict_t xbt_dict_new(void);
  26 void xbt_dict_free(xbt_dict_t *dict);
  27
  28
  29 void xbt_dict_set    (xbt_dict_t     head,
  30                        const char     *key,
  31                        void           *data,
  32                        void_f_pvoid_t *free_ctn);
  33 void xbt_dict_set_ext(xbt_dict_t     head,
  34                        const char     *key,
  35                        int             key_len,
  36                        void           *data,
  37                        void_f_pvoid_t *free_ctn);
  38
  39 /*----[ xbt_dict_get ]------------------------------------------------------*/
  40 /* Search the given #key#. data=NULL when not found.                         */
  41 /* Returns true if anything went ok, and false on internal error.            */
  42 /*---------------------------------------------------------------------------*/
  43 xbt_error_t xbt_dict_get(xbt_dict_t head,const char *key,
  44                            /* OUT */void **data);
  45 xbt_error_t xbt_dict_get_ext(xbt_dict_t head,const char *key,
  46                                int key_len,
  47                                /* OUT */void **data);
  48 /*----[ xbt_dict_remove ]---------------------------------------------------*/
  49 /* Remove the entry associated with the given #key#.                         */
  50 /* Returns if ok. Removing a non-existant key is ok.                         */
  51 /*---------------------------------------------------------------------------*/
  52 xbt_error_t xbt_dict_remove(xbt_dict_t head,const char *key);
  53
  54 xbt_error_t xbt_dict_remove_ext(xbt_dict_t head,
  55                                   const char *key, int key_len);
  56
  57 /*----[ xbt_dict_dump ]-----------------------------------------------------*/
  58 /* Outputs the content of the structure. (for debuging purpose)              */
  59 /* #output# is a function to output the data.If NULL, data won't be displayed*/
  60 /*---------------------------------------------------------------------------*/
  61 void xbt_dict_dump(xbt_dict_t head,
  62                     void (*output)(void*));
  63 /*----[ xbt_dict_print ]----------------------------------------------------*/
  64 /* To dump multicache, this function dump a cache                            */
  65 /*---------------------------------------------------------------------------*/
  66 void xbt_dict_print(void *data);
  67 /* To dump multicache, this one dumps a string                               */
  68 void xbt_dict_prints(void *data);
  69
  70
  71 /*####[ Multi cache functions ]##############################################*/
  72 /* The are cache of cache of data. Any function there works the same way     */
  73 /*  than their simple cache counterpart.                                     */
  74 /*###############################"###########################################*/
  75
  76 /*----[ xbt_multidict_free ]------------------------------------------------*/
  77 /* This function does not exist. Use xbt_dict_free instead.                 */
  78 /*---------------------------------------------------------------------------*/
  79
  80 /*----[ xbt_multidict_set ]-------------------------------------------------*/
  81 /* Insert the data in the structure under the #keycount# #key#s.             */
  82 /* The key are destroyed in the process. Think to strdup it before.          */
  83 /* Returns if it was ok or not                                               */
  84 /*---------------------------------------------------------------------------*/
  85 xbt_error_t xbt_multidict_set(xbt_dict_t *head,
  86                                 int keycount,char **key,
  87                                 void *data,void (*free_ctn)(void*));
  88
  89 xbt_error_t xbt_multidict_set_ext(xbt_dict_t *head,
  90                                     int keycount,char **key,int *key_len,
  91                                     void *data,void_f_pvoid_t *free_ctn);
  92
  93 /*----[ xbt_multidict_get ]-------------------------------------------------*/
  94 /* Search the given #key#. data=NULL when not found.                         */
  95 /* Returns true if anything went ok, and false on internal error.            */
  96 /*---------------------------------------------------------------------------*/
  97 xbt_error_t xbt_multidict_get(xbt_dict_t head,
  98                                 int keycount,const char **key,
  99                                 /* OUT */void **data);
 100
 101 xbt_error_t xbt_multidict_get_ext(xbt_dict_t head,
 102                                     int keycount,const char **key,int *key_len,
 103                                     /* OUT */void **data);
 104
 105 /*----[ xbt_multidict_remove ]----------------------------------------------*/
 106 /* Remove the entry associated with the given #key#.                         */
 107 /* Returns if ok. Removing a non-existant key is ok.                         */
 108 /*---------------------------------------------------------------------------*/
 109 xbt_error_t xbt_multidict_remove(xbt_dict_t head,
 110                                    int keycount,const char **key);
 111
 112 xbt_error_t xbt_multidict_remove_ext(xbt_dict_t head,
 113                                        int keycount,const char **key,int *key_len);
 114
 115 /*####[ Cache cursor functions ]#############################################*/
 116 /* To traverse (simple) caches                                               */
 117 /* Don't add or remove entries to the cache while traversing !!!             */
 118 /*###########################################################################*/
 119 typedef struct xbt_dict_cursor_ *xbt_dict_cursor_t;
 120 /* creator/destructor */
 121 xbt_dict_cursor_t xbt_dict_cursor_new(const xbt_dict_t head);
 122 void               xbt_dict_cursor_free(xbt_dict_cursor_t *cursor);
 123
 124 /* back to first element
 125    it is not enough to reinit the cache after an add/remove in cache*/
 126 void xbt_dict_cursor_rewind(xbt_dict_cursor_t cursor);
 127
 128
 129 xbt_error_t xbt_dict_cursor_get_key     (xbt_dict_cursor_t cursor,
 130                                            /*OUT*/char **key);
 131 xbt_error_t xbt_dict_cursor_get_data    (xbt_dict_cursor_t cursor,
 132                                            /*OUT*/void **data);
 133
 134 void xbt_dict_cursor_first (const xbt_dict_t   dict,
 135                              xbt_dict_cursor_t *cursor);
 136 void         xbt_dict_cursor_step        (xbt_dict_cursor_t  cursor);
 137 int          xbt_dict_cursor_get_or_free (xbt_dict_cursor_t *cursor,
 138                                            char              **key,
 139                                            void              **data);
 140 #define xbt_dict_foreach(dict,cursor,key,data)                       \
 141   for (cursor=NULL, xbt_dict_cursor_first((dict),&(cursor)) ;        \
 142        xbt_dict_cursor_get_or_free(&(cursor),&(key),(void**)(&data));\
 143        xbt_dict_cursor_step(cursor) )
 144
 145 #ifdef  __cplusplus
 146 }
 147 #endif
 148
 149 #endif /* _XBT_DICT_H */