remote-curl: die directly with http error messages
[git.git] / Documentation / technical / api-sha1-array.txt
blob45d1c517cd862878198db6023d5fdbd35f9fbb6c
1 sha1-array API
2 ==============
4 The sha1-array API provides storage and manipulation of sets of SHA1
5 identifiers. The emphasis is on storage and processing efficiency,
6 making them suitable for large lists. Note that the ordering of items is
7 not preserved over some operations.
9 Data Structures
10 ---------------
12 `struct sha1_array`::
14         A single array of SHA1 hashes. This should be initialized by
15         assignment from `SHA1_ARRAY_INIT`.  The `sha1` member contains
16         the actual data. The `nr` member contains the number of items in
17         the set.  The `alloc` and `sorted` members are used internally,
18         and should not be needed by API callers.
20 Functions
21 ---------
23 `sha1_array_append`::
24         Add an item to the set. The sha1 will be placed at the end of
25         the array (but note that some operations below may lose this
26         ordering).
28 `sha1_array_lookup`::
29         Perform a binary search of the array for a specific sha1.
30         If found, returns the offset (in number of elements) of the
31         sha1. If not found, returns a negative integer. If the array is
32         not sorted, this function has the side effect of sorting it.
34 `sha1_array_clear`::
35         Free all memory associated with the array and return it to the
36         initial, empty state.
38 `sha1_array_for_each_unique`::
39         Efficiently iterate over each unique element of the list,
40         executing the callback function for each one. If the array is
41         not sorted, this function has the side effect of sorting it.
43 Examples
44 --------
46 -----------------------------------------
47 void print_callback(const unsigned char sha1[20],
48                     void *data)
50         printf("%s\n", sha1_to_hex(sha1));
53 void some_func(void)
55         struct sha1_array hashes = SHA1_ARRAY_INIT;
56         unsigned char sha1[20];
58         /* Read objects into our set */
59         while (read_object_from_stdin(sha1))
60                 sha1_array_append(&hashes, sha1);
62         /* Check if some objects are in our set */
63         while (read_object_from_stdin(sha1)) {
64                 if (sha1_array_lookup(&hashes, sha1) >= 0)
65                         printf("it's in there!\n");
67         /*
68          * Print the unique set of objects. We could also have
69          * avoided adding duplicate objects in the first place,
70          * but we would end up re-sorting the array repeatedly.
71          * Instead, this will sort once and then skip duplicates
72          * in linear time.
73          */
74         sha1_array_for_each_unique(&hashes, print_callback, NULL);
76 -----------------------------------------