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_test - 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.
  56  *
  57  * Example:
  58  *      if (strset_test(&set, "hello"))
  59  *              printf("hello is in the set\n");
  60  */
  61 char *strset_test(const struct strset *set, const char *member);
  62
  63 /**
  64  * strset_set - place a member in the string set.
  65  * @set: the set.
  66  * @member: the string to place in the set.
  67  *
  68  * This returns false if we run out of memory (errno = ENOMEM), or
  69  * (more normally) if that string already appears in the set (EEXIST).
  70  *
  71  * Note that the pointer is placed in the set, the string is not copied.  If
  72  * you want a copy in the set, use strdup().
  73  *
  74  * Example:
  75  *      if (!strset_set(&set, "goodbye"))
  76  *              printf("goodbye was already in the set\n");
  77  */
  78 bool strset_set(struct strset *set, const char *member);
  79
  80 /**
  81  * strset_clear - remove a member from the string set.
  82  * @set: the set.
  83  * @member: the string to remove from the set.
  84  *
  85  * This returns the string which was passed to strset_set(), or NULL.
  86  * This means that if you allocated a string (eg. using strdup()), you can
  87  * free it here.
  88  *
  89  * Example:
  90  *      if (!strset_clear(&set, "goodbye"))
  91  *              printf("goodbye was not in the set?\n");
  92  */
  93 char *strset_clear(struct strset *set, const char *member);
  94
  95 /**
  96  * strset_destroy - remove every member from the set.
  97  * @set: the set.
  98  *
  99  * The set will be empty after this.
 100  *
 101  * Example:
 102  *      strset_destroy(&set);
 103  */
 104 void strset_destroy(struct strset *set);
 105
 106 /**
 107  * strset_iterate - ordered iteration over a set
 108  * @set: the set.
 109  * @handle: the function to call.
 110  * @arg: the argument for the function (types should match).
 111  *
 112  * You should not alter the set within the @handle function!  If it returns
 113  * true, the iteration will stop.
 114  *
 115  * Example:
 116  *      static bool dump_some(const char *member, int *num)
 117  *      {
 118  *              // Only dump out num nodes.
 119  *              if (*(num--) == 0)
 120  *                      return true;
 121  *              printf("%s\n", member);
 122  *              return false;
 123  *      }
 124  *
 125  *      static void dump_set(const struct strset *set)
 126  *      {
 127  *              int max = 100;
 128  *              strset_iterate(set, dump_some, &max);
 129  *              if (max < 0)
 130  *                      printf("... (truncated to 100 entries)\n");
 131  *      }
 132  */
 133 #define strset_iterate(set, handle, arg)                                \
 134         strset_iterate_((set), typesafe_cb_preargs(bool, void *,        \
 135                                                    (handle), (arg),     \
 136                                                    const char *),       \
 137                         (arg))
 138 void strset_iterate_(const struct strset *set,
 139                      bool (*handle)(const char *, void *), void *data);
 140
 141
 142 /**
 143  * strset_prefix - return a subset matching a prefix
 144  * @set: the set.
 145  * @prefix: the prefix.
 146  *
 147  * This returns a pointer into @set, so don't alter @set while using
 148  * the return value.  You can use strset_iterate(), strset_test() or
 149  * strset_empty() on the returned pointer.
 150  *
 151  * Example:
 152  *      static void dump_prefix(const struct strset *set, const char *prefix)
 153  *      {
 154  *              int max = 100;
 155  *              printf("Nodes with prefix %s:\n", prefix);
 156  *              strset_iterate(strset_prefix(set, prefix), dump_some, &max);
 157  *              if (max < 0)
 158  *                      printf("... (truncated to 100 entries)\n");
 159  *      }
 160  */
 161 const struct strset *strset_prefix(const struct strset *set,
 162                                    const char *prefix);
 163
 164 #endif /* CCAN_STRSET_H */