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