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 (cursor=NULL, 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 */