Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
The name path_list was correct for the first usage of that data structure, but it really is a general-purpose string list. $ perl -i -pe 's/path-list/string-list/g' $(git grep -l path-list) $ perl -i -pe 's/path_list/string_list/g' $(git grep -l path_list) $ git mv path-list.h string-list.h $ git mv path-list.c string-list.c $ perl -i -pe 's/has_path/has_string/g' $(git grep -l has_path) $ perl -i -pe 's/path/string/g' string-list.[ch] $ git mv Documentation/technical/api-path-list.txt \ Documentation/technical/api-string-list.txt $ perl -i -pe 's/strdup_paths/strdup_strings/g' $(git grep -l strdup_paths) ... and then fix all users of string-list to access the member "string" instead of "path". Documentation/technical/api-string-list.txt needed some rewrapping, too. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
- Loading branch information
Showing
28 changed files
with
556 additions
and
553 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Original file line | Diff line number | Diff line change |
---|---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.