diff options
Diffstat (limited to 'Documentation/technical')
| -rw-r--r-- | Documentation/technical/api-path-list.txt | 126 | ||||
| -rw-r--r-- | Documentation/technical/api-string-list.txt | 128 |
2 files changed, 128 insertions, 126 deletions
diff --git a/Documentation/technical/api-path-list.txt b/Documentation/technical/api-path-list.txt deleted file mode 100644 index 9dbedd0a6..000000000 --- a/Documentation/technical/api-path-list.txt +++ /dev/null @@ -1,126 +0,0 @@ -path-list API -============= - -The path_list API offers a data structure and functions to handle sorted -and unsorted string lists. - -The name is a bit misleading, a path_list may store not only paths but -strings in general. - -The caller: - -. Allocates and clears a `struct path_list` variable. - -. Initializes the members. You might want to set the flag `strdup_paths` - 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. - -. 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`. - -Example: - ----- -struct path_list list; -int i; - -memset(&list, 0, sizeof(struct path_list)); -path_list_append("foo", &list); -path_list_append("bar", &list); -for (i = 0; i < list.nr; i++) - printf("%s\n", list.items[i].path) ----- - -NOTE: 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_path_list_has_path()), -because the complexity would be quadratic again (but with a worse factor). - -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. -+ -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 -write `path_list_insert(...)->util = ...;`. - -`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. -+ -This function needs to look through all items, as opposed to its -counterpart for sorted lists, which performs a binary search. - -Data structures ---------------- - -* `struct path_list_item` - -Represents 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 to avoid reallocating at every insertion. - You should not tamper with it. -. Setting the `strdup_paths` member to 1 will strdup() the strings - before adding them, see above. diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt new file mode 100644 index 000000000..92b3ecdae --- /dev/null +++ b/Documentation/technical/api-string-list.txt @@ -0,0 +1,128 @@ +string-list API +=============== + +The string_list API offers a data structure and functions to handle sorted +and unsorted string lists. + +The 'string_list' struct used to be called 'path_list', but was renamed +because it is not specific to paths. + +The caller: + +. Allocates and clears a `struct string_list` variable. + +. 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. + +. Adds new items to the list, using `string_list_append` or + `string_list_insert`. + +. 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. + +. Can sort an unsorted list using `sort_string_list`. + +. Finally it should free the list using `string_list_clear`. + +Example: + +---- +struct string_list list; +int i; + +memset(&list, 0, sizeof(struct string_list)); +string_list_append("foo", &list); +string_list_append("bar", &list); +for (i = 0; i < list.nr; i++) + printf("%s\n", list.items[i].path) +---- + +NOTE: 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). + +Functions +--------- + +* General ones (works with sorted and unsorted lists as well) + +`print_string_list`:: + + Dump a string_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 string_list, each one in its own line. + +`string_list_clear`:: + + Free 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 second + parameter controls if the `util` pointer of the items should be freed + or not. + +* Functions for sorted lists only + +`string_list_has_string`:: + + Determine if the string_list has a given string or not. + +`string_list_insert`:: + + 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. ++ +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 +write `string_list_insert(...)->util = ...;`. + +`string_list_lookup`:: + + Look up a given string in the string_list, returning the containing + string_list_item. If the string is not found, NULL is returned. + +* Functions for unsorted lists only + +`string_list_append`:: + + Append a new string to the end of the string_list. + +`sort_string_list`:: + + Make an unsorted list sorted. + +`unsorted_string_list_has_string`:: + + It's like `string_list_has_string()` but for unsorted lists. ++ +This function needs to look through all items, as opposed to its +counterpart for sorted lists, which performs a binary search. + +Data structures +--------------- + +* `struct string_list_item` + +Represents 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 string_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 to avoid reallocating at every insertion. + You should not tamper with it. +. Setting the `strdup_strings` member to 1 will strdup() the strings + before adding them, see above. |