Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
f6e70b0a68eab4df3cd817ee4269b9f0346c4bd8
[simgrid.git] / include / 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 gras_error_t gras_dict_new(gras_dict_t **dict);
25 void         gras_dict_free(gras_dict_t **dict);
26
27
28 gras_error_t gras_dict_insert    (gras_dict_t    *head,
29                                   const char     *key,
30                                   void           *data,
31                                   void_f_pvoid_t *free_ctn);
32 gras_error_t gras_dict_insert_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_retrieve ]-------------------------------------------------*/
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_retrieve(gras_dict_t *head,const char *key,
43                        /* OUT */void **data);
44 gras_error_t gras_dict_retrieve_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 /* Returns if it was ok or not                                               */
60 /*---------------------------------------------------------------------------*/
61 gras_error_t gras_dict_dump(gras_dict_t *head,
62                             void (*output)(void*));
63 /*----[ gras_dict_print ]----------------------------------------------------*/
64 /* To dump multicache, this function dump a cache                            */
65 /*---------------------------------------------------------------------------*/
66 void gras_dict_print(void *data);
67 /* To dump multicache, this one dumps a string                               */
68 void gras_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 /*----[ gras_multidict_free ]------------------------------------------------*/
77 /* This function does not exist. Use gras_dict_free instead.                 */
78 /*---------------------------------------------------------------------------*/
79
80 /*----[ gras_multidict_insert ]----------------------------------------------*/
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 gras_error_t gras_multidict_insert(gras_dict_t **head,
86                                    int keycount,char **key,
87                                    void *data,void (*free_ctn)(void*));
88
89 gras_error_t gras_multidict_insert_ext(gras_dict_t **head,
90                                        int keycount,char **key,int *key_len,
91                                        void *data,void_f_pvoid_t *free_ctn);
92
93 /*----[ gras_multidict_retrieve ]--------------------------------------------*/
94 /* Search the given #key#. data=NULL when not found.                         */
95 /* Returns true if anything went ok, and false on internal error.            */
96 /*---------------------------------------------------------------------------*/
97 gras_error_t gras_multidict_retrieve(gras_dict_t *head,
98                                      int keycount,const char **key,
99                                      /* OUT */void **data);
100
101 gras_error_t gras_multidict_retrieve_ext(gras_dict_t *head,
102                                          int keycount,const char **key,int *key_len,
103                                          /* OUT */void **data);
104
105 /*----[ gras_multidict_remove ]----------------------------------------------*/
106 /* Remove the entry associated with the given #key#.                         */
107 /* Returns if ok. Removing a non-existant key is ok.                         */
108 /*---------------------------------------------------------------------------*/
109 gras_error_t gras_multidict_remove(gras_dict_t *head,
110                                    int keycount,const char **key);
111
112 gras_error_t gras_multidict_remove_ext(gras_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 gras_dict_cursor_ gras_dict_cursor_t;
120 /* creator/destructor */
121 gras_error_t gras_dict_cursor_new(const gras_dict_t *head,
122                                   /*OUT*/gras_dict_cursor_t **cursor);
123 void         gras_dict_cursor_free(gras_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 gras_error_t gras_dict_cursor_rewind(gras_dict_cursor_t *cursor);
128
129
130 gras_error_t gras_dict_cursor_get_key     (gras_dict_cursor_t *cursor,
131                                            /*OUT*/char **key);
132 gras_error_t gras_dict_cursor_get_data    (gras_dict_cursor_t *cursor,
133                                            /*OUT*/void **data);
134
135
136 void         gras_dict_cursor_first       (const gras_dict_t   *dict,
137                                            gras_dict_cursor_t **cursor);
138 void         gras_dict_cursor_step        (gras_dict_cursor_t  *cursor);
139 int          gras_dict_cursor_get_or_free (gras_dict_cursor_t **cursor,
140                                            char               **key,
141                                            void               **data);
142 #define gras_dict_foreach(dict,cursor,key,data)                \
143   for (gras_dict_cursor_first((dict),&(cursor)) ;              \
144        gras_dict_cursor_get_or_free(&(cursor),&(key),(void**)(&data)); \
145        gras_dict_cursor_step(cursor) )
146
147 #ifdef  __cplusplus
148 }
149 #endif
150
151 #endif /* _GRAS_DICT_H */