4 The string_list API offers a data structure and functions to handle sorted
5 and unsorted string lists.
7 The 'string_list' struct used to be called 'path_list', but was renamed
8 because it is not specific to paths.
12 . Allocates and clears a `struct string_list` variable.
14 . Initializes the members. You might want to set the flag `strdup_strings`
15 if the strings should be strdup()ed. For example, this is necessary
16 when you add something like git_path("..."), since that function returns
17 a static buffer that will change with the next call to git_path().
19 If you need something advanced, you can manually malloc() the `items`
20 member (you need this if you add things later) and you should set the
21 `nr` and `alloc` members in that case, too.
23 . Adds new items to the list, using `string_list_append`,
24 `string_list_append_nodup`, `string_list_insert`,
25 `string_list_split`, and/or `string_list_split_in_place`.
27 . Can check if a string is in the list using `string_list_has_string` or
28 `unsorted_string_list_has_string` and get it from the list using
29 `string_list_lookup` for sorted lists.
31 . Can sort an unsorted list using `sort_string_list`.
33 . Can remove individual items of an unsorted list using
34 `unsorted_string_list_delete_item`.
36 . Finally it should free the list using `string_list_clear`.
41 struct string_list list;
44 memset(&list, 0, sizeof(struct string_list));
45 string_list_append(&list, "foo");
46 string_list_append(&list, "bar");
47 for (i = 0; i < list.nr; i++)
48 printf("%s\n", list.items[i].string)
51 NOTE: It is more efficient to build an unsorted list and sort it
52 afterwards, instead of building a sorted list (`O(n log n)` instead of
55 However, if you use the list to check if a certain string was added
56 already, you should not do that (using unsorted_string_list_has_string()),
57 because the complexity would be quadratic again (but with a worse factor).
62 * General ones (works with sorted and unsorted lists as well)
66 Dump a string_list to stdout, useful mainly for debugging purposes. It
67 can take an optional header argument and it writes out the
68 string-pointer pairs of the string_list, each one in its own line.
72 Free a string_list. The `string` pointer of the items will be freed in
73 case the `strdup_strings` member of the string_list is set. The second
74 parameter controls if the `util` pointer of the items should be freed
77 * Functions for sorted lists only
79 `string_list_has_string`::
81 Determine if the string_list has a given string or not.
83 `string_list_insert`::
85 Insert a new element to the string_list. The returned pointer can be
86 handy if you want to write something to the `util` pointer of the
87 string_list_item containing the just added string. If the given
88 string already exists the insertion will be skipped and the
89 pointer to the existing item returned.
91 Since this function uses xrealloc() (which die()s if it fails) if the
92 list needs to grow, it is safe not to check the pointer. I.e. you may
93 write `string_list_insert(...)->util = ...;`.
95 `string_list_lookup`::
97 Look up a given string in the string_list, returning the containing
98 string_list_item. If the string is not found, NULL is returned.
100 * Functions for unsorted lists only
102 `string_list_append`::
104 Append a new string to the end of the string_list. If
105 `strdup_string` is set, then the string argument is copied;
106 otherwise the new `string_list_entry` refers to the input
109 `string_list_append_nodup`::
111 Append a new string to the end of the string_list. The new
112 `string_list_entry` always refers to the input string, even if
113 `strdup_string` is set. This function can be used to hand
114 ownership of a malloc()ed string to a `string_list` that has
119 Make an unsorted list sorted.
121 `unsorted_string_list_has_string`::
123 It's like `string_list_has_string()` but for unsorted lists.
125 `unsorted_string_list_lookup`::
127 It's like `string_list_lookup()` but for unsorted lists.
129 The above two functions need to look through all items, as opposed to their
130 counterpart for sorted lists, which performs a binary search.
132 `unsorted_string_list_delete_item`::
134 Remove an item from a string_list. The `string` pointer of the items
135 will be freed in case the `strdup_strings` member of the string_list
136 is set. The third parameter controls if the `util` pointer of the
137 items should be freed or not.
139 `string_list_split`::
140 `string_list_split_in_place`::
142 Split a string into substrings on a delimiter character and
143 append the substrings to a `string_list`. If `maxsplit` is
144 non-negative, then split at most `maxsplit` times. Return the
145 number of substrings appended to the list.
147 `string_list_split` requires a `string_list` that has `strdup_strings`
148 set to true; it leaves the input string untouched and makes copies of
149 the substrings in newly-allocated memory.
150 `string_list_split_in_place` requires a `string_list` that has
151 `strdup_strings` set to false; it splits the input string in place,
152 overwriting the delimiter characters with NULs and creating new
153 string_list_items that point into the original string (the original
154 string must therefore not be modified or freed while the `string_list`
161 * `struct string_list_item`
163 Represents an item of the list. The `string` member is a pointer to the
164 string, and you may use the `util` member for any purpose, if you want.
166 * `struct string_list`
168 Represents the list itself.
170 . The array of items are available via the `items` member.
171 . The `nr` member contains the number of items stored in the list.
172 . The `alloc` member is used to avoid reallocating at every insertion.
173 You should not tamper with it.
174 . Setting the `strdup_strings` member to 1 will strdup() the strings
175 before adding them, see above.