include/xbt/dict.h

   1 /* $Id$ */
   2
   3 /* gras/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 _GRAS_DICT_H
  13 #define _GRAS_DICT_H
  14
  15 #ifdef  __cplusplus
  16 extern "C"
  17 #endif
  18
  19 /*####[ Type definition ]####################################################*/
  20 typedef struct gras_dict_ gras_dict_t;
  21
  22 /*####[ Simple dict  functions ]#############################################*/
  23
  24 void gras_dict_new(gras_dict_t **dict);
  25 void gras_dict_free(gras_dict_t **dict);
  26
  27
  28 void gras_dict_set    (gras_dict_t    *head,
  29                        const char     *key,
  30                        void           *data,
  31                        void_f_pvoid_t *free_ctn);
  32 void gras_dict_set_ext(gras_dict_t    *head,
  33                        const char     *key,
  34                        int             key_len,
  35                        void           *data,
  36                        void_f_pvoid_t *free_ctn);
  37
  38 /*----[ gras_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 gras_error_t gras_dict_get(gras_dict_t *head,const char *key,
  43                            /* OUT */void **data);
  44 gras_error_t gras_dict_get_ext(gras_dict_t *head,const char *key,
  45                                int key_len,
  46                                /* OUT */void **data);
  47 /*----[ gras_dict_remove ]---------------------------------------------------*/
  48 /* Remove the entry associated with the given #key#.                         */
  49 /* Returns if ok. Removing a non-existant key is ok.                         */
  50 /*---------------------------------------------------------------------------*/
  51 gras_error_t gras_dict_remove(gras_dict_t *head,const char *key);
  52
  53 gras_error_t gras_dict_remove_ext(gras_dict_t *head,const char *key,
  54                                   int key_len);
  55
  56 /*----[ gras_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 gras_dict_dump(gras_dict_t *head,
  61                     void (*output)(void*));
  62 /*----[ gras_dict_print ]----------------------------------------------------*/
  63 /* To dump multicache, this function dump a cache                            */
  64 /*---------------------------------------------------------------------------*/
  65 void gras_dict_print(void *data);
  66 /* To dump multicache, this one dumps a string                               */
  67 void gras_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 /*----[ gras_multidict_free ]------------------------------------------------*/
  76 /* This function does not exist. Use gras_dict_free instead.                 */
  77 /*---------------------------------------------------------------------------*/
  78
  79 /*----[ gras_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 gras_error_t gras_multidict_set(gras_dict_t **head,
  85                                 int keycount,char **key,
  86                                 void *data,void (*free_ctn)(void*));
  87
  88 gras_error_t gras_multidict_set_ext(gras_dict_t **head,
  89                                     int keycount,char **key,int *key_len,
  90                                     void *data,void_f_pvoid_t *free_ctn);
  91
  92 /*----[ gras_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 gras_error_t gras_multidict_get(gras_dict_t *head,
  97                                 int keycount,const char **key,
  98                                 /* OUT */void **data);
  99
 100 gras_error_t gras_multidict_get_ext(gras_dict_t *head,
 101                                     int keycount,const char **key,int *key_len,
 102                                     /* OUT */void **data);
 103
 104 /*----[ gras_multidict_remove ]----------------------------------------------*/
 105 /* Remove the entry associated with the given #key#.                         */
 106 /* Returns if ok. Removing a non-existant key is ok.                         */
 107 /*---------------------------------------------------------------------------*/
 108 gras_error_t gras_multidict_remove(gras_dict_t *head,
 109                                    int keycount,const char **key);
 110
 111 gras_error_t gras_multidict_remove_ext(gras_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 gras_dict_cursor_ gras_dict_cursor_t;
 119 /* creator/destructor */
 120 void gras_dict_cursor_new(const gras_dict_t *head,
 121                           /*OUT*/gras_dict_cursor_t **cursor);
 122 void         gras_dict_cursor_free(gras_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 gras_dict_cursor_rewind(gras_dict_cursor_t *cursor);
 127
 128
 129 gras_error_t gras_dict_cursor_get_key     (gras_dict_cursor_t *cursor,
 130                                            /*OUT*/char **key);
 131 gras_error_t gras_dict_cursor_get_data    (gras_dict_cursor_t *cursor,
 132                                            /*OUT*/void **data);
 133
 134
 135 void         gras_dict_cursor_first       (const gras_dict_t   *dict,
 136                                            gras_dict_cursor_t **cursor);
 137 void         gras_dict_cursor_step        (gras_dict_cursor_t  *cursor);
 138 int          gras_dict_cursor_get_or_free (gras_dict_cursor_t **cursor,
 139                                            char               **key,
 140                                            void               **data);
 141 #define gras_dict_foreach(dict,cursor,key,data)                        \
 142   for (cursor=NULL, gras_dict_cursor_first((dict),&(cursor)) ;         \
 143        gras_dict_cursor_get_or_free(&(cursor),&(key),(void**)(&data)); \
 144        gras_dict_cursor_step(cursor) )
 145
 146 #ifdef  __cplusplus
 147 }
 148 #endif
 149
 150 #endif /* _GRAS_DICT_H */