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