check_type: fix incorrect documentation.
[ccan] / 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 false, 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 false;
171  *              printf("%s=>%i\n", member, *value);
172  *              return true;
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 */