git.ozlabs.org Git - ccan/blob - ccan/strmap/strmap.h

   1 #ifndef CCAN_STRMAP_H
   2 #define CCAN_STRMAP_H
   3 #include "config.h"
   4 #include <ccan/tcon/tcon.h>
   5 #include <ccan/typesafe_cb/typesafe_cb.h>
   6 #include <stdlib.h>
   7 #include <stdbool.h>
   8
   9 /**
  10  * struct strmap - representation of a string map
  11  *
  12  * It's exposed here to allow you to embed it and so we can inline the
  13  * trivial functions.
  14  */
  15 struct strmap {
  16         union {
  17                 struct node *n;
  18                 const char *s;
  19         } u;
  20         void *v;
  21 };
  22
  23 /**
  24  * STRMAP_MEMBERS - declare members for a type-specific strmap.
  25  * @type: type for this map's values, or void * for any pointer.
  26  *
  27  * You use this to create your own typed strmap for a particular type.
  28  * You can use an integer type, *but* remember you can't use "0" as a
  29  * value!
  30  *
  31  * Example:
  32  *      struct strmap_intp {
  33  *              STRMAP_MEMBERS(int *);
  34  *      };
  35  */
  36 #define STRMAP_MEMBERS(type)                    \
  37         struct strmap raw;                      \
  38         TCON(type canary)
  39
  40
  41 /**
  42  * strmap_init - initialize a string map (empty)
  43  * @map: the typed strmap to initialize.
  44  *
  45  * For completeness; if you've arranged for it to be NULL already you don't
  46  * need this.
  47  *
  48  * Example:
  49  *      struct strmap_intp map;
  50  *
  51  *      strmap_init(&map);
  52  */
  53 #define strmap_init(map) strmap_init_(&(map)->raw)
  54
  55 static inline void strmap_init_(struct strmap *map)
  56 {
  57         map->u.n = NULL;
  58 }
  59
  60 /**
  61  * strmap_empty - is this string map empty?
  62  * @map: the typed strmap to check.
  63  *
  64  * Example:
  65  *      if (!strmap_empty(&map))
  66  *              abort();
  67  */
  68 #define strmap_empty(map) strmap_empty_(&(map)->raw)
  69
  70 static inline bool strmap_empty_(const struct strmap *map)
  71 {
  72         return map->u.n == NULL;
  73 }
  74
  75 /**
  76  * strmap_get - get a value from a string map
  77  * @map: the typed strmap to search.
  78  * @member: the string to search for.
  79  *
  80  * Returns the value, or NULL if it isn't in the map (and sets errno = ENOENT).
  81  *
  82  * Example:
  83  *      int *val = strmap_get(&map, "hello");
  84  *      if (val)
  85  *              printf("hello => %i\n", *val);
  86  */
  87 #define strmap_get(map, member) \
  88         tcon_cast((map), canary, strmap_get_(&(map)->raw, (member)))
  89 void *strmap_get_(const struct strmap *map, const char *member);
  90
  91 /**
  92  * strmap_add - place a member in the string map.
  93  * @map: the typed strmap to add to.
  94  * @member: the string to place in the map.
  95  * @v: the (non-NULL) value.
  96  *
  97  * This returns false if we run out of memory (errno = ENOMEM), or
  98  * (more normally) if that string already appears in the map (EEXIST).
  99  *
 100  * Note that the pointer is placed in the map, the string is not copied.  If
 101  * you want a copy in the map, use strdup().  Similarly for the value.
 102  *
 103  * Example:
 104  *      val = malloc(sizeof *val);
 105  *      *val = 17;
 106  *      if (!strmap_add(&map, "goodbye", val))
 107  *              printf("goodbye was already in the map\n");
 108  */
 109 #define strmap_add(map, member, value)                          \
 110         strmap_add_(&tcon_check((map), canary, (value))->raw,   \
 111                     (member), (void *)(value))
 112
 113 bool strmap_add_(struct strmap *map, const char *member, const void *value);
 114
 115 /**
 116  * strmap_del - remove a member from the string map.
 117  * @map: the typed strmap to delete from.
 118  * @member: the string to remove from the map.
 119  * @valuep: the value (if non-NULL)
 120  *
 121  * This returns the string which was passed to strmap_map(), or NULL if
 122  * it was not in the map (and sets errno = ENOENT).
 123  *
 124  * This means that if you allocated a string (eg. using strdup()), you
 125  * can free it here.  Similarly, the value is returned in @valuep if
 126  * @valuep is not NULL.
 127  *
 128  * Example:
 129  *      if (!strmap_del(&map, "goodbye", NULL))
 130  *              printf("goodbye was not in the map?\n");
 131  */
 132 #define strmap_del(map, member, valuep)                                 \
 133         strmap_del_(&tcon_check_ptr((map), canary, valuep)->raw,        \
 134                     (member), (void **)valuep)
 135 char *strmap_del_(struct strmap *map, const char *member, void **valuep);
 136
 137 /**
 138  * strmap_clear - remove every member from the map.
 139  * @map: the typed strmap to clear.
 140  *
 141  * The map will be empty after this.
 142  *
 143  * Example:
 144  *      strmap_clear(&map);
 145  */
 146 #define strmap_clear(map) strmap_clear_(&(map)->raw)
 147
 148 void strmap_clear_(struct strmap *map);
 149
 150 /**
 151  * strmap_iterate - ordered iteration over a map
 152  * @map: the typed strmap to iterate through.
 153  * @handle: the function to call.
 154  * @arg: the argument for the function (types should match).
 155  *
 156  * @handle's prototype should be:
 157  *      bool @handle(const char *member, type value, typeof(arg) arg)
 158  *
 159  * If @handle returns true, the iteration will stop.
 160  * You should not alter the map within the @handle function!
 161  *
 162  * Example:
 163  *      struct strmap_intp {
 164  *              STRMAP_MEMBERS(int *);
 165  *      };
 166  *      static bool dump_some(const char *member, int *value, int *num)
 167  *      {
 168  *              // Only dump out num nodes.
 169  *              if (*(num--) == 0)
 170  *                      return true;
 171  *              printf("%s=>%i\n", member, *value);
 172  *              return false;
 173  *      }
 174  *
 175  *      static void dump_map(const struct strmap_intp *map)
 176  *      {
 177  *              int max = 100;
 178  *              strmap_iterate(map, dump_some, &max);
 179  *              if (max < 0)
 180  *                      printf("... (truncated to 100 entries)\n");
 181  *      }
 182  */
 183 #define strmap_iterate(map, handle, arg)                                \
 184         strmap_iterate_(&(map)->raw,                                    \
 185                         typesafe_cb_cast(bool (*)(const char *,         \
 186                                                   void *, void *),      \
 187                                          bool (*)(const char *,         \
 188                                                   tcon_type((map), canary), \
 189                                                   __typeof__(arg)), (handle)), \
 190                         (arg))
 191 void strmap_iterate_(const struct strmap *map,
 192                      bool (*handle)(const char *, void *, void *),
 193                      const void *data);
 194
 195 /**
 196  * strmap_prefix - return a submap matching a prefix
 197  * @map: the map.
 198  * @prefix: the prefix.
 199  *
 200  * This returns a pointer into @map, so don't alter @map while using
 201  * the return value.  You can use strmap_iterate(), strmap_get() or
 202  * strmap_empty() on the returned pointer.
 203  *
 204  * Example:
 205  *      static void dump_prefix(const struct strmap_intp *map,
 206  *                              const char *prefix)
 207  *      {
 208  *              int max = 100;
 209  *              printf("Nodes with prefix %s:\n", prefix);
 210  *              strmap_iterate(strmap_prefix(map, prefix), dump_some, &max);
 211  *              if (max < 0)
 212  *                      printf("... (truncated to 100 entries)\n");
 213  *      }
 214  */
 215 #if HAVE_TYPEOF
 216 #define strmap_prefix(map, prefix) \
 217         ((const __typeof__(map))strmap_prefix_(&(map)->raw, (prefix)))
 218 #else
 219 #define strmap_prefix(map, prefix) \
 220         ((const void *)strmap_prefix_(&(map)->raw, (prefix)))
 221 #endif
 222
 223 const struct strmap *strmap_prefix_(const struct strmap *map,
 224                                     const char *prefix);
 225
 226 #endif /* CCAN_STRMAP_H */