Signed-off-by: Miklos Vajna <vmiklos@xxxxxxxxxxxxxx> --- Updated patch, obviously we want to init the struct with '\0', not '0'. Documentation/technical/api-path-list.txt | 92 +++++++++++++++++++++++++++- 1 files changed, 88 insertions(+), 4 deletions(-) diff --git a/Documentation/technical/api-path-list.txt b/Documentation/technical/api-path-list.txt index d077683..313d088 100644 --- a/Documentation/technical/api-path-list.txt +++ b/Documentation/technical/api-path-list.txt @@ -1,9 +1,93 @@ path-list API ============= -Talk about <path-list.h>, things like +The path_list API offers a data structure and functions to handle sorted +and unsorted string lists. -* it is not just paths but strings in general; -* the calling sequence. +The name is a bit misleading, a path_list may store not only paths but +strings in general. -(Dscho) +The caller: + +. Allocates and clears (`memset(&list, \'\0', sizeof(list));`) a + `struct path_list` variable. + +. Initializes the members. You can manually set the `items` member, but + then you have to set `nr`, accordingly. Also don't forget to set + `strdup_paths` if you need it. + +. Adds new items to the list, using `path_list_append` or `path_list_insert`. + +. Can check if a string is in the list using `path_list_has_path` or + `unsorted_path_list_has_path` and get it from the list using + `path_list_lookup` for sorted lists. + +. Can sort an unsorted list using `sort_path_list`. + +. Finally it should free the list using `path_list_clear`. + +Functions +--------- + +* General ones (works with sorted and unsorted lists as well) + +`print_path_list`:: + + Dump a path_list to stdout, useful mainly for debugging purposes. It + can take an optional header argument and it writes out the + string-pointer pairs of the path_list, each one in its own line. + +`path_list_clear`:: + + Free a path_list. The `path` pointer of the items will be freed in case + the `strdup_paths` member of the path_list is set. The second parameter + controls if the `util` pointer of the items should be freed or not. + +* Functions for sorted lists only + +`path_list_has_path`:: + + Determine if the path_list has a given string or not. + +`path_list_insert`:: + + Insert a new element to the path_list. The returned pointer can be handy + if you want to write something to the `util` pointer of the + path_list_item containing the just added string. + +`path_list_lookup`:: + + Look up a given string in the path_list, returning the containing + path_list_item. If the string is not found, NULL is returned. + +* Functions for unsorted lists only + +`path_list_append`:: + + Append a new string to the end of the path_list. + +`sort_path_list`:: + + Make an unsorted list sorted. + +`unsorted_path_list_has_path`:: + + It's like `path_list_has_path()` but for unsorted lists. + +Data structures +--------------- + +* `struct path_list_item` + +Represent an item of the list. The `path` member is a pointer to the +string, and you may use the `util` member for any purpose, if you want. + +* `struct path_list` + +Represents the list itself. + +. The array of items are available via the `items` member. +. The `nr` member contains the number of items stored in the list. +. The `alloc` member is used for `ALLOC_GROW()`. +. Setting the `strdup_paths` member to 1 means that the added paths are + copied to the path list and not just a pointer to them is stored. -- 1.5.6.rc2.dirty -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
