Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Fixed licence and copyright. No more reference to da GRAS possee or the
[simgrid.git] / 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 */