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