dlls/ole32/dictionary.h

   1 /* Simple dictionary
   2  *
   3  * Copyright 2005 Juan Lang
   4  *
   5  * This is a pretty basic dictionary, or map if you prefer.  It's not
   6  * thread-safe.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  21  */
  22 #ifndef __DICTIONARY_H__
  23 #define __DICTIONARY_H__
  24
  25 #include <stdarg.h>
  26 #include "windef.h"
  27 #include "winbase.h"
  28
  29 struct dictionary;
  30
  31 /* Returns whether key a is less than, equal to, or greater than key b, in
  32  * the same way (a - b) would for integers or strcmp(a, b) would for ANSI
  33  * strings.
  34  */
  35 typedef int (*comparefunc)(const void *a, const void *b, void *extra);
  36
  37 /* Called for every element removed from the dictionary.  See
  38  * dictionary_destroy, dictionary_insert, and dictionary_remove.
  39  */
  40 typedef void (*destroyfunc)(void *k, void *v, void *extra);
  41
  42 /* Called for each element in the dictionary.  Return FALSE if you don't want
  43  * to enumerate any more.
  44  */
  45 typedef BOOL (*enumeratefunc)(const void *k, const void *v, void *extra,
  46  void *closure);
  47
  48 /* Constructs a dictionary, using c as a comparison function for keys.
  49  * If d is not NULL, it will be called whenever an item is about to be removed
  50  * from the table, for example when dictionary_remove is called for a key, or
  51  * when dictionary_destroy is called.
  52  * extra is passed to c (and d, if it's provided).
  53  * Assumes c is not NULL.
  54  */
  55 struct dictionary *dictionary_create(comparefunc c, destroyfunc d, void *extra);
  56
  57 /* Assumes d is not NULL. */
  58 void dictionary_destroy(struct dictionary *d);
  59
  60 /* Returns how many entries have been stored in the dictionary.  If two values
  61  * with the same key are inserted, only one is counted.
  62  */
  63 UINT dictionary_num_entries(struct dictionary *d);
  64
  65 /* Sets an element with key k and value v to the dictionary.  If a value
  66  * already exists with key k, its value is replaced, and the destroyfunc (if
  67  * set) is called for the previous item.
  68  * Assumes k and v can be bitwise-copied.
  69  * Both k and v are allowed to be NULL, in case you want to use integer
  70  * values for either the key or the value.
  71  * Assumes d is not NULL.
  72  */
  73 void dictionary_insert(struct dictionary *d, const void *k, const void *v);
  74
  75 /* If a value with key k has been inserted into the dictionary, *v is set
  76  * to its associated value.  Returns FALSE if the key is not found, and TRUE
  77  * if it is.  *v is undefined if it returns FALSE.  (It is not set to NULL,
  78  * because this dictionary doesn't prevent you from using NULL as a value
  79  * value; see dictionary_insert.)
  80  * Assumes d and v are not NULL.
  81  */
  82 BOOL dictionary_find(struct dictionary *d, const void *k, void **v);
  83
  84 /* Removes the element with key k from the dictionary.  Calls the destroyfunc
  85  * for the dictionary with the element if found (so you may destroy it if it's
  86  * dynamically allocated.)
  87  * Assumes d is not NULL.
  88  */
  89 void dictionary_remove(struct dictionary *d, const void *k);
  90
  91 void dictionary_enumerate(struct dictionary *d, enumeratefunc e, void *closure);
  92
  93 #endif /* ndef __DICTIONARY_H__ */