Documentation: update and rename api-sha1-array.txt
Since the structure and functions have changed names, update the code examples and the documentation. Rename the file to match the new name of the API. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
brian m. carlson committed
Mar 31, 2017 at 01:40 UTC
e239dabb1465d3ff927840b4fff15150a2170b4e
1 file changed
+22
-22
Documentation/technical/api-oid-array.txt
renamed
+22
-22
@@ -1,7 +1,7 @@
1
-sha1-array API
1
+oid-array API
2
==============
3
4
-The sha1-array API provides storage and manipulation of sets of SHA-1
4
+The oid-array API provides storage and manipulation of sets of object
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,10 +9,10 @@ not preserved over some operations.
9
Data Structures
10
---------------
11
12
-`struct sha1_array`::
12
+`struct oid_array`::
13
14
- A single array of SHA-1 hashes. This should be initialized by
15
- assignment from `SHA1_ARRAY_INIT`. The `sha1` member contains
14
+ A single array of object IDs. This should be initialized by
15
+ assignment from `OID_ARRAY_INIT`. The `oid` 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,22 +20,22 @@ Data Structures
20
Functions
21
---------
22
23
-`sha1_array_append`::
24
- Add an item to the set. The sha1 will be placed at the end of
23
+`oid_array_append`::
24
+ Add an item to the set. The object ID will be placed at the end of
25
the array (but note that some operations below may lose this
26
ordering).
27
28
-`sha1_array_lookup`::
29
- Perform a binary search of the array for a specific sha1.
28
+`oid_array_lookup`::
29
+ Perform a binary search of the array for a specific object ID.
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.
31
+ object ID. If not found, returns a negative integer. If the array
32
+ is not sorted, this function has the side effect of sorting it.
33
34
-`sha1_array_clear`::
34
+`oid_array_clear`::
35
Free all memory associated with the array and return it to the
36
initial, empty state.
37
38
-`sha1_array_for_each_unique`::
38
+`oid_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. If
@@ -47,25 +47,25 @@ Examples
47
--------
48
49
-----------------------------------------
50
-int print_callback(const unsigned char sha1[20],
50
+int print_callback(const struct object_id *oid,
51
void *data)
52
{
53
- printf("%s\n", sha1_to_hex(sha1));
53
+ printf("%s\n", oid_to_hex(oid));
54
return 0; /* always continue */
55
}
56
57
void some_func(void)
58
{
59
- struct sha1_array hashes = SHA1_ARRAY_INIT;
60
- unsigned char sha1[20];
59
+ struct sha1_array hashes = OID_ARRAY_INIT;
60
+ struct object_id oid;
61
62
/* Read objects into our set */
63
- while (read_object_from_stdin(sha1))
64
- sha1_array_append(&hashes, sha1);
63
+ while (read_object_from_stdin(oid.hash))
64
+ oid_array_append(&hashes, &oid);
65
66
/* Check if some objects are in our set */
67
- while (read_object_from_stdin(sha1)) {
68
- if (sha1_array_lookup(&hashes, sha1) >= 0)
67
+ while (read_object_from_stdin(oid.hash)) {
68
+ if (oid_array_lookup(&hashes, &oid) >= 0)
69
printf("it's in there!\n");
70
71
/*
@@ -75,6 +75,6 @@ void some_func(void)
75
* Instead, this will sort once and then skip duplicates
76
* in linear time.
77
*/
78
- sha1_array_for_each_unique(&hashes, print_callback, NULL);
78
+ oid_array_for_each_unique(&hashes, print_callback, NULL);
79
}
80
-----------------------------------------