3 /* xbt/dict.h -- api to a generic dictionary */
5 /* Copyright (c) 2003, 2004 Martin Quinson. All rights reserved. */
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. */
14 #include "xbt/misc.h" /* BEGIN_DECL */
15 #include "xbt/error.h"
19 /*####[ Type definition ]####################################################*/
20 /** \brief Dictionnary data type
23 typedef struct xbt_dict_ *xbt_dict_t;
25 /*####[ Simple dict functions ]#############################################*/
27 xbt_dict_t xbt_dict_new(void);
28 void xbt_dict_free(xbt_dict_t *dict);
31 void xbt_dict_set (xbt_dict_t head,
34 void_f_pvoid_t *free_ctn);
35 void xbt_dict_set_ext(xbt_dict_t head,
39 void_f_pvoid_t *free_ctn);
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,
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);
56 xbt_error_t xbt_dict_remove_ext(xbt_dict_t head,
57 const char *key, int key_len);
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);
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 /*###############################"###########################################*/
78 /*----[ xbt_multidict_free ]------------------------------------------------*/
79 /* This function does not exist. Use xbt_dict_free instead. */
80 /*---------------------------------------------------------------------------*/
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*));
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);
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);
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);
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);
114 xbt_error_t xbt_multidict_remove_ext(xbt_dict_t head,
115 int keycount,const char **key,int *key_len);
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);
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);
131 xbt_error_t xbt_dict_cursor_get_key (xbt_dict_cursor_t cursor,
133 xbt_error_t xbt_dict_cursor_get_data (xbt_dict_cursor_t cursor,
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,
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) )
149 #endif /* _XBT_DICT_H */