The string_list API offers a data structure and functions to handle sorted and unsorted string lists. A "sorted" list is one whose entries are sorted by string value in strcmp() order.

The string_list struct used to be called path_list, but was renamed because it is not specific to paths.

The caller:

  1. Allocates and clears a struct string_list variable.

  2. Initializes the members. You might want to set the flag strdup_strings if the strings should be strdup()ed. For example, this is necessary when you add something like git_path("…"), since that function returns a static buffer that will change with the next call to git_path().

    If you need something advanced, you can manually malloc() the items member (you need this if you add things later) and you should set the nr and alloc members in that case, too.

  3. Adds new items to the list, using string_list_append, string_list_append_nodup, string_list_insert, string_list_split, and/or string_list_split_in_place.

  4. Can check if a string is in the list using string_list_has_string or unsorted_string_list_has_string and get it from the list using string_list_lookup for sorted lists.

  5. Can sort an unsorted list using string_list_sort.

  6. Can remove duplicate items from a sorted list using string_list_remove_duplicates.

  7. Can remove individual items of an unsorted list using unsorted_string_list_delete_item.

  8. Can remove items not matching a criterion from a sorted or unsorted list using filter_string_list, or remove empty strings using string_list_remove_empty_items.

  9. Finally it should free the list using string_list_clear.


struct string_list list = STRING_LIST_INIT_NODUP;
int i;

string_list_append(&list, "foo");
string_list_append(&list, "bar");
for (i = 0; i <; i++)
        printf("%s\n", list.items[i].string)
It is more efficient to build an unsorted list and sort it afterwards, instead of building a sorted list (O(n log n) instead of O(n^2)).

+ However, if you use the list to check if a certain string was added already, you should not do that (using unsorted_string_list_has_string()), because the complexity would be quadratic again (but with a worse factor).


Data structures

Represents an item of the list. The string member is a pointer to the string, and you may use the util member for any purpose, if you want.

Represents the list itself.

  1. The array of items are available via the items member.

  2. The nr member contains the number of items stored in the list.

  3. The alloc member is used to avoid reallocating at every insertion. You should not tamper with it.

  4. Setting the strdup_strings member to 1 will strdup() the strings before adding them, see above.

  5. The compare_strings_fn member is used to specify a custom compare function, otherwise strcmp() is used as the default function.