check_type: fix incorrect documentation.
[ccan] / ccan / strset / strset.h
1 #ifndef CCAN_STRSET_H
2 #define CCAN_STRSET_H
3 #include "config.h"
4 #include <ccan/typesafe_cb/typesafe_cb.h>
5 #include <stdlib.h>
6 #include <stdbool.h>
7
8 /**
9  * struct strset - representation of a string set
10  *
11  * It's exposed here to allow you to embed it and so we can inline the
12  * trivial functions.
13  */
14 struct strset {
15         union {
16                 struct node *n;
17                 const char *s;
18         } u;
19 };
20
21 /**
22  * strset_init - initialize a string set (empty)
23  *
24  * For completeness; if you've arranged for it to be NULL already you don't
25  * need this.
26  *
27  * Example:
28  *      struct strset set;
29  *
30  *      strset_init(&set);
31  */
32 static inline void strset_init(struct strset *set)
33 {
34         set->u.n = NULL;
35 }
36
37 /**
38  * strset_empty - is this string set empty?
39  * @set: the set.
40  *
41  * Example:
42  *      if (!strset_empty(&set))
43  *              abort();
44  */
45 static inline bool strset_empty(const struct strset *set)
46 {
47         return set->u.n == NULL;
48 }
49
50 /**
51  * strset_get - is this a member of this string set?
52  * @set: the set.
53  * @member: the string to search for.
54  *
55  * Returns the member, or NULL if it isn't in the set (and sets errno
56  * = ENOENT).
57  *
58  * Example:
59  *      if (strset_get(&set, "hello"))
60  *              printf("hello is in the set\n");
61  */
62 char *strset_get(const struct strset *set, const char *member);
63
64 /**
65  * strset_add - place a member in the string set.
66  * @set: the set.
67  * @member: the string to place in the set.
68  *
69  * This returns false if we run out of memory (errno = ENOMEM), or
70  * (more normally) if that string already appears in the set (EEXIST).
71  *
72  * Note that the pointer is placed in the set, the string is not copied.  If
73  * you want a copy in the set, use strdup().
74  *
75  * Example:
76  *      if (!strset_add(&set, "goodbye"))
77  *              printf("goodbye was already in the set\n");
78  */
79 bool strset_add(struct strset *set, const char *member);
80
81 /**
82  * strset_del - remove a member from the string set.
83  * @set: the set.
84  * @member: the string to remove from the set.
85  *
86  * This returns the string which was passed to strset_add(), or NULL if
87  * the string was not in the map (in which case it sets errno = ENOENT).
88  *
89  * This means that if you allocated a string (eg. using strdup()), you can
90  * free it here.
91  *
92  * Example:
93  *      if (!strset_del(&set, "goodbye"))
94  *              printf("goodbye was not in the set?\n");
95  */
96 char *strset_del(struct strset *set, const char *member);
97
98 /**
99  * strset_clear - remove every member from the set.
100  * @set: the set.
101  *
102  * The set will be empty after this.
103  *
104  * Example:
105  *      strset_clear(&set);
106  */
107 void strset_clear(struct strset *set);
108
109 /**
110  * strset_iterate - ordered iteration over a set
111  * @set: the set.
112  * @handle: the function to call.
113  * @arg: the argument for the function (types should match).
114  *
115  * You should not alter the set within the @handle function!  If it returns
116  * false, the iteration will stop.
117  *
118  * Example:
119  *      static bool dump_some(const char *member, int *num)
120  *      {
121  *              // Only dump out num nodes.
122  *              if (*(num--) == 0)
123  *                      return false;
124  *              printf("%s\n", member);
125  *              return true;
126  *      }
127  *
128  *      static void dump_set(const struct strset *set)
129  *      {
130  *              int max = 100;
131  *              strset_iterate(set, dump_some, &max);
132  *              if (max < 0)
133  *                      printf("... (truncated to 100 entries)\n");
134  *      }
135  */
136 #define strset_iterate(set, handle, arg)                                \
137         strset_iterate_((set), typesafe_cb_preargs(bool, void *,        \
138                                                    (handle), (arg),     \
139                                                    const char *),       \
140                         (arg))
141 void strset_iterate_(const struct strset *set,
142                      bool (*handle)(const char *, void *), const void *data);
143
144
145 /**
146  * strset_prefix - return a subset matching a prefix
147  * @set: the set.
148  * @prefix: the prefix.
149  *
150  * This returns a pointer into @set, so don't alter @set while using
151  * the return value.  You can use strset_iterate(), strset_test() or
152  * strset_empty() on the returned pointer.
153  *
154  * Example:
155  *      static void dump_prefix(const struct strset *set, const char *prefix)
156  *      {
157  *              int max = 100;
158  *              printf("Nodes with prefix %s:\n", prefix);
159  *              strset_iterate(strset_prefix(set, prefix), dump_some, &max);
160  *              if (max < 0)
161  *                      printf("... (truncated to 100 entries)\n");
162  *      }
163  */
164 const struct strset *strset_prefix(const struct strset *set,
165                                    const char *prefix);
166
167 #endif /* CCAN_STRSET_H */