string-list.hon commit conditional markdown preprocessing (c8b1cd9)
   1#ifndef STRING_LIST_H
   2#define STRING_LIST_H
   3
   4/**
   5 * The string_list API offers a data structure and functions to handle
   6 * sorted and unsorted arrays of strings.  A "sorted" list is one whose
   7 * entries are sorted by string value in `strcmp()` order.
   8 *
   9 * The caller:
  10 *
  11 * . Allocates and clears a `struct string_list` variable.
  12 *
  13 * . Initializes the members. You might want to set the flag `strdup_strings`
  14 *   if the strings should be strdup()ed. For example, this is necessary
  15 *   when you add something like git_path("..."), since that function returns
  16 *   a static buffer that will change with the next call to git_path().
  17 *
  18 * If you need something advanced, you can manually malloc() the `items`
  19 * member (you need this if you add things later) and you should set the
  20 * `nr` and `alloc` members in that case, too.
  21 *
  22 * . Adds new items to the list, using `string_list_append`,
  23 *   `string_list_append_nodup`, `string_list_insert`,
  24 *   `string_list_split`, and/or `string_list_split_in_place`.
  25 *
  26 * . Can check if a string is in the list using `string_list_has_string` or
  27 *   `unsorted_string_list_has_string` and get it from the list using
  28 *   `string_list_lookup` for sorted lists.
  29 *
  30 * . Can sort an unsorted list using `string_list_sort`.
  31 *
  32 * . Can remove duplicate items from a sorted list using
  33 *   `string_list_remove_duplicates`.
  34 *
  35 * . Can remove individual items of an unsorted list using
  36 *   `unsorted_string_list_delete_item`.
  37 *
  38 * . Can remove items not matching a criterion from a sorted or unsorted
  39 *   list using `filter_string_list`, or remove empty strings using
  40 *   `string_list_remove_empty_items`.
  41 *
  42 * . Finally it should free the list using `string_list_clear`.
  43 *
  44 * Example:
  45 *
  46 *     struct string_list list = STRING_LIST_INIT_NODUP;
  47 *     int i;
  48 *
  49 *     string_list_append(&list, "foo");
  50 *     string_list_append(&list, "bar");
  51 *     for (i = 0; i < list.nr; i++)
  52 *             printf("%s\n", list.items[i].string)
  53 *
  54 * NOTE: It is more efficient to build an unsorted list and sort it
  55 * afterwards, instead of building a sorted list (`O(n log n)` instead of
  56 * `O(n^2)`).
  57 *
  58 * However, if you use the list to check if a certain string was added
  59 * already, you should not do that (using unsorted_string_list_has_string()),
  60 * because the complexity would be quadratic again (but with a worse factor).
  61 */
  62
  63/**
  64 * Represents an item of the list. The `string` member is a pointer to the
  65 * string, and you may use the `util` member for any purpose, if you want.
  66 */
  67struct string_list_item {
  68        char *string;
  69        void *util;
  70};
  71
  72typedef int (*compare_strings_fn)(const char *, const char *);
  73
  74/**
  75 * Represents the list itself.
  76 *
  77 * . The array of items are available via the `items` member.
  78 * . The `nr` member contains the number of items stored in the list.
  79 * . The `alloc` member is used to avoid reallocating at every insertion.
  80 *   You should not tamper with it.
  81 * . Setting the `strdup_strings` member to 1 will strdup() the strings
  82 *   before adding them, see above.
  83 * . The `compare_strings_fn` member is used to specify a custom compare
  84 *   function, otherwise `strcmp()` is used as the default function.
  85 */
  86struct string_list {
  87        struct string_list_item *items;
  88        unsigned int nr, alloc;
  89        unsigned int strdup_strings:1;
  90        compare_strings_fn cmp; /* NULL uses strcmp() */
  91};
  92
  93#define STRING_LIST_INIT_NODUP { NULL, 0, 0, 0, NULL }
  94#define STRING_LIST_INIT_DUP   { NULL, 0, 0, 1, NULL }
  95
  96/* General functions which work with both sorted and unsorted lists. */
  97
  98/**
  99 * Initialize the members of the string_list, set `strdup_strings`
 100 * member according to the value of the second parameter.
 101 */
 102void string_list_init(struct string_list *list, int strdup_strings);
 103
 104/** Callback function type for for_each_string_list */
 105typedef int (*string_list_each_func_t)(struct string_list_item *, void *);
 106
 107/**
 108 * Apply `want` to each item in `list`, retaining only the ones for which
 109 * the function returns true.  If `free_util` is true, call free() on
 110 * the util members of any items that have to be deleted.  Preserve
 111 * the order of the items that are retained.
 112 */
 113void filter_string_list(struct string_list *list, int free_util,
 114                        string_list_each_func_t want, void *cb_data);
 115
 116/**
 117 * Free a string_list. The `string` pointer of the items will be freed
 118 * in case the `strdup_strings` member of the string_list is set. The
 119 * second parameter controls if the `util` pointer of the items should
 120 * be freed or not.
 121 */
 122void string_list_clear(struct string_list *list, int free_util);
 123
 124/**
 125 * Callback type for `string_list_clear_func`.  The string associated
 126 * with the util pointer is passed as the second argument
 127 */
 128typedef void (*string_list_clear_func_t)(void *p, const char *str);
 129
 130/** Call a custom clear function on each util pointer */
 131void string_list_clear_func(struct string_list *list, string_list_clear_func_t clearfunc);
 132
 133/**
 134 * Apply `func` to each item. If `func` returns nonzero, the
 135 * iteration aborts and the return value is propagated.
 136 */
 137int for_each_string_list(struct string_list *list,
 138                         string_list_each_func_t func, void *cb_data);
 139
 140/** Iterate over each item, as a macro. */
 141#define for_each_string_list_item(item,list)            \
 142        for (item = (list)->items;                      \
 143             item && item < (list)->items + (list)->nr; \
 144             ++item)
 145
 146/**
 147 * Remove any empty strings from the list.  If free_util is true, call
 148 * free() on the util members of any items that have to be deleted.
 149 * Preserve the order of the items that are retained.
 150 */
 151void string_list_remove_empty_items(struct string_list *list, int free_util);
 152
 153/* Use these functions only on sorted lists: */
 154
 155/** Determine if the string_list has a given string or not. */
 156int string_list_has_string(const struct string_list *list, const char *string);
 157int string_list_find_insert_index(const struct string_list *list, const char *string,
 158                                  int negative_existing_index);
 159
 160/**
 161 * Insert a new element to the string_list. The returned pointer can
 162 * be handy if you want to write something to the `util` pointer of
 163 * the string_list_item containing the just added string. If the given
 164 * string already exists the insertion will be skipped and the pointer
 165 * to the existing item returned.
 166 *
 167 * Since this function uses xrealloc() (which die()s if it fails) if the
 168 * list needs to grow, it is safe not to check the pointer. I.e. you may
 169 * write `string_list_insert(...)->util = ...;`.
 170 */
 171struct string_list_item *string_list_insert(struct string_list *list, const char *string);
 172
 173/**
 174 * Remove the given string from the sorted list.  If the string
 175 * doesn't exist, the list is not altered.
 176 */
 177void string_list_remove(struct string_list *list, const char *string,
 178                        int free_util);
 179
 180/**
 181 * Check if the given string is part of a sorted list. If it is part of the list,
 182 * return the coresponding string_list_item, NULL otherwise.
 183 */
 184struct string_list_item *string_list_lookup(struct string_list *list, const char *string);
 185
 186/*
 187 * Remove all but the first of consecutive entries with the same
 188 * string value.  If free_util is true, call free() on the util
 189 * members of any items that have to be deleted.
 190 */
 191void string_list_remove_duplicates(struct string_list *sorted_list, int free_util);
 192
 193
 194/* Use these functions only on unsorted lists: */
 195
 196/**
 197 * Add string to the end of list.  If list->strdup_string is set, then
 198 * string is copied; otherwise the new string_list_entry refers to the
 199 * input string.
 200 */
 201struct string_list_item *string_list_append(struct string_list *list, const char *string);
 202
 203/**
 204 * Like string_list_append(), except string is never copied.  When
 205 * list->strdup_strings is set, this function can be used to hand
 206 * ownership of a malloc()ed string to list without making an extra
 207 * copy.
 208 */
 209struct string_list_item *string_list_append_nodup(struct string_list *list, char *string);
 210
 211/**
 212 * Sort the list's entries by string value in `strcmp()` order.
 213 */
 214void string_list_sort(struct string_list *list);
 215
 216/**
 217 * Like `string_list_has_string()` but for unsorted lists. Linear in
 218 * size of the list.
 219 */
 220int unsorted_string_list_has_string(struct string_list *list, const char *string);
 221
 222/**
 223 * Like `string_list_lookup()` but for unsorted lists. Linear in size
 224 * of the list.
 225 */
 226struct string_list_item *unsorted_string_list_lookup(struct string_list *list,
 227                                                     const char *string);
 228/**
 229 * Remove an item from a string_list. The `string` pointer of the
 230 * items will be freed in case the `strdup_strings` member of the
 231 * string_list is set. The third parameter controls if the `util`
 232 * pointer of the items should be freed or not.
 233 */
 234void unsorted_string_list_delete_item(struct string_list *list, int i, int free_util);
 235
 236/**
 237 * Split string into substrings on character `delim` and append the
 238 * substrings to `list`.  The input string is not modified.
 239 * list->strdup_strings must be set, as new memory needs to be
 240 * allocated to hold the substrings.  If maxsplit is non-negative,
 241 * then split at most maxsplit times.  Return the number of substrings
 242 * appended to list.
 243 *
 244 * Examples:
 245 *   string_list_split(l, "foo:bar:baz", ':', -1) -> ["foo", "bar", "baz"]
 246 *   string_list_split(l, "foo:bar:baz", ':', 0) -> ["foo:bar:baz"]
 247 *   string_list_split(l, "foo:bar:baz", ':', 1) -> ["foo", "bar:baz"]
 248 *   string_list_split(l, "foo:bar:", ':', -1) -> ["foo", "bar", ""]
 249 *   string_list_split(l, "", ':', -1) -> [""]
 250 *   string_list_split(l, ":", ':', -1) -> ["", ""]
 251 */
 252int string_list_split(struct string_list *list, const char *string,
 253                      int delim, int maxsplit);
 254
 255/*
 256 * Like string_list_split(), except that string is split in-place: the
 257 * delimiter characters in string are overwritten with NULs, and the
 258 * new string_list_items point into string (which therefore must not
 259 * be modified or freed while the string_list is in use).
 260 * list->strdup_strings must *not* be set.
 261 */
 262int string_list_split_in_place(struct string_list *list, char *string,
 263                               int delim, int maxsplit);
 264#endif /* STRING_LIST_H */