string-list: document that string_list_insert() inserts unique strings

[git.git] / Documentation / technical / api-string-list.txt

diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt
index 293bb15d206e71f57e906b33ca27ee05e3429521..5a0c14fcebfcf4d5cbad4900d062703412c501e1 100644 (file)
--- a/Documentation/technical/api-string-list.txt
+++ b/Documentation/technical/api-string-list.txt
@@ -29,6 +29,9 @@ member (you need this if you add things later) and you should set the
 
 . Can sort an unsorted list using `sort_string_list`.
 
+. Can remove individual items of an unsorted list using
+  `unsorted_string_list_delete_item`.
+
 . Finally it should free the list using `string_list_clear`.
 
 Example:
@@ -38,8 +41,8 @@ struct string_list list;
 int i;
 
 memset(&list, 0, sizeof(struct string_list));
-string_list_append("foo", &list);
-string_list_append("bar", &list);
+string_list_append(&list, "foo");
+string_list_append(&list, "bar");
 for (i = 0; i < list.nr; i++)
        printf("%s\n", list.items[i].string)
 ----
@@ -80,7 +83,9 @@ Functions
 
        Insert a new element to the string_list. The returned pointer can be
        handy if you want to write something to the `util` pointer of the
-       string_list_item containing the just added string.
+       string_list_item containing the just added string. If the given
+       string already exists the insertion will be skipped and the
+       pointer to the existing item returned.
 +
 Since this function uses xrealloc() (which die()s if it fails) if the
 list needs to grow, it is safe not to check the pointer. I.e. you may
@@ -104,10 +109,21 @@ write `string_list_insert(...)->util = ...;`.
 `unsorted_string_list_has_string`::
 
        It's like `string_list_has_string()` but for unsorted lists.
+
+`unsorted_string_list_lookup`::
+
+       It's like `string_list_lookup()` but for unsorted lists.
 +
-This function needs to look through all items, as opposed to its
+The above two functions need to look through all items, as opposed to their
 counterpart for sorted lists, which performs a binary search.
 
+`unsorted_string_list_delete_item`::
+
+       Remove an item from a string_list. The `string` pointer of the items
+       will be freed in case the `strdup_strings` member of the string_list
+       is set. The third parameter controls if the `util` pointer of the
+       items should be freed or not.
+
 Data structures
 ---------------