3 /* gras/dict.h -- api to a generic dictionary */
5 /* Authors: Martin Quinson */
6 /* Copyright (C) 2003 the OURAGAN project. */
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. */
19 /*####[ Type definition ]####################################################*/
20 typedef struct gras_dict_ *gras_dict_t;
22 /*####[ Simple dict functions ]#############################################*/
24 gras_dict_t gras_dict_new(void);
25 void gras_dict_free(gras_dict_t *dict);
28 void gras_dict_set (gras_dict_t head,
31 void_f_pvoid_t *free_ctn);
32 void gras_dict_set_ext(gras_dict_t head,
36 void_f_pvoid_t *free_ctn);
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,
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);
53 gras_error_t gras_dict_remove_ext(gras_dict_t head,
54 const char *key, int key_len);
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);
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 /*###############################"###########################################*/
75 /*----[ gras_multidict_free ]------------------------------------------------*/
76 /* This function does not exist. Use gras_dict_free instead. */
77 /*---------------------------------------------------------------------------*/
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*));
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);
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);
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);
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);
111 gras_error_t gras_multidict_remove_ext(gras_dict_t head,
112 int keycount,const char **key,int *key_len);
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 gras_dict_cursor_t gras_dict_cursor_new(const gras_dict_t head);
121 void gras_dict_cursor_free(gras_dict_cursor_t *cursor);
123 /* back to first element
124 it is not enough to reinit the cache after an add/remove in cache*/
125 void gras_dict_cursor_rewind(gras_dict_cursor_t cursor);
128 gras_error_t gras_dict_cursor_get_key (gras_dict_cursor_t cursor,
130 gras_error_t gras_dict_cursor_get_data (gras_dict_cursor_t cursor,
133 void gras_dict_cursor_first (const gras_dict_t dict,
134 gras_dict_cursor_t *cursor);
135 void gras_dict_cursor_step (gras_dict_cursor_t cursor);
136 int gras_dict_cursor_get_or_free (gras_dict_cursor_t *cursor,
139 #define gras_dict_foreach(dict,cursor,key,data) \
140 for (cursor=NULL, gras_dict_cursor_first((dict),&(cursor)) ; \
141 gras_dict_cursor_get_or_free(&(cursor),&(key),(void**)(&data));\
142 gras_dict_cursor_step(cursor) )
148 #endif /* _GRAS_DICT_H */