include/xbt/dict.h

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