git.ozlabs.org Git - ccan/blob - 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 */