From: Junio C Hamano Date: Wed, 18 Jun 2008 03:17:26 +0000 (+0000) Subject: Autogenerated HTML docs for v1.5.6-rc3-21-g8c6b5 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=7562b87f6fcfb31a5fa52d2edfe866b5f1ee08d5;p=git.git Autogenerated HTML docs for v1.5.6-rc3-21-g8c6b5 --- diff --git a/technical/api-path-list.html b/technical/api-path-list.html index d271a790c..0588311ee 100644 --- a/technical/api-path-list.html +++ b/technical/api-path-list.html @@ -263,25 +263,228 @@ div.exampleblock-content {
-

Talk about <path-list.h>, things like

+

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:

+
    +
  1. +

    +Allocates and clears a struct path_list variable. +

    +
    2. +
  2. +

    +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.

    +
    3. +
  3. +

    +Adds new items to the list, using path_list_append or path_list_insert. +

    +
    4. +
  4. +

    +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. +

    +
    5. +
  5. +

    +Can sort an unsorted list using sort_path_list. +

    +
    6. +
  6. +

    +Finally it should free the list using path_list_clear. +

    +
    7. +
+

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

+
-

(Dscho)

+

Data structures

+
+ +

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.

+ +

Represents the list itself.

+
    +
  1. +

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

    +
    2. +
  2. +

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

    +
    3. +
  3. +

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

    +
    4. +
  4. +

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

    +
    5. +
diff --git a/technical/api-path-list.txt b/technical/api-path-list.txt index d07768317..9dbedd0a6 100644 --- a/technical/api-path-list.txt +++ b/technical/api-path-list.txt @@ -1,9 +1,126 @@ path-list API ============= -Talk about , 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 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/technical/api-run-command.html b/technical/api-run-command.html index 421b2f3a3..608967942 100644 --- a/technical/api-run-command.html +++ b/technical/api-run-command.html @@ -354,7 +354,7 @@ command to run in a sub-process.

  1. -allocates and clears (memset(&chld, 0, sizeof(chld));) a +allocates and clears (memset(&chld, 0, sizeof(chld));) a struct child_process variable;

    2. @@ -486,7 +486,7 @@ to produce output that the caller reads.

    1. -allocates and clears (memset(&asy, 0, sizeof(asy));) a +allocates and clears (memset(&asy, 0, sizeof(asy));) a struct async variable;

      2. @@ -564,7 +564,7 @@ It must not change the program's state that the caller of the diff --git a/technical/api-run-command.txt b/technical/api-run-command.txt index c364a22c8..3e1342acf 100644 --- a/technical/api-run-command.txt +++ b/technical/api-run-command.txt @@ -63,7 +63,7 @@ command to run in a sub-process. The caller: -1. allocates and clears (memset(&chld, '0', sizeof(chld));) a +1. allocates and clears (memset(&chld, 0, sizeof(chld));) a struct child_process variable; 2. initializes the members; 3. calls start_command(); @@ -136,7 +136,7 @@ to produce output that the caller reads. The caller: -1. allocates and clears (memset(&asy, '0', sizeof(asy));) a +1. allocates and clears (memset(&asy, 0, sizeof(asy));) a struct async variable; 2. initializes .proc and .data; 3. calls start_async();