sha1-array: move doc to sha1-array.h
Move the documentation from Documentation/technical/api-oid-array.txt to sha1-array.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file. Also documentation/technical/api-oid-array.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and synchronized with the documentation in the header file. Signed-off-by: Heba Waly <heba.waly@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Heba Waly committed
Nov 17, 2019 at 21:04 UTC
405c6b1fbc699a9651e3a555612fd7a31590a509
3 files changed
+81
-91
Documentation/technical/api-oid-array.txt
deleted
-90
@@ -1,90 +0,0 @@
1
-oid-array API
2
-==============
3
-
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.
8
-
9
-Data Structures
10
----------------
11
-
12
-`struct oid_array`::
13
-
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.
19
-
20
-Functions
21
----------
22
-
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
-`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
- 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
-`oid_array_clear`::
35
- Free all memory associated with the array and return it to the
36
- initial, empty state.
37
-
38
-`oid_array_for_each`::
39
- Iterate over each element of the list, executing the callback
40
- function for each one. Does not sort the list, so any custom
41
- hash order is retained. If the callback returns a non-zero
42
- value, the iteration ends immediately and the callback's
43
- return is propagated; otherwise, 0 is returned.
44
-
45
-`oid_array_for_each_unique`::
46
- Iterate over each unique element of the list in sorted order,
47
- but otherwise behave like `oid_array_for_each`. If the array
48
- is not sorted, this function has the side effect of sorting
49
- it.
50
-
51
-`oid_array_filter`::
52
- Apply the callback function `want` to each entry in the array,
53
- retaining only the entries for which the function returns true.
54
- Preserve the order of the entries that are retained.
55
-
56
-Examples
57
---------
58
-
59
------------------------------------------
60
-int print_callback(const struct object_id *oid,
61
- void *data)
62
-{
63
- printf("%s\n", oid_to_hex(oid));
64
- return 0; /* always continue */
65
-}
66
-
67
-void some_func(void)
68
-{
69
- struct sha1_array hashes = OID_ARRAY_INIT;
70
- struct object_id oid;
71
-
72
- /* Read objects into our set */
73
- while (read_object_from_stdin(oid.hash))
74
- oid_array_append(&hashes, &oid);
75
-
76
- /* Check if some objects are in our set */
77
- while (read_object_from_stdin(oid.hash)) {
78
- if (oid_array_lookup(&hashes, &oid) >= 0)
79
- printf("it's in there!\n");
80
-
81
- /*
82
- * Print the unique set of objects. We could also have
83
- * avoided adding duplicate objects in the first place,
84
- * but we would end up re-sorting the array repeatedly.
85
- * Instead, this will sort once and then skip duplicates
86
- * in linear time.
87
- */
88
- oid_array_for_each_unique(&hashes, print_callback, NULL);
89
-}
90
------------------------------------------
sha1-array.c
+1
-1
@@ -48,7 +48,7 @@ int oid_array_for_each(struct oid_array *array,
48
{
49
int i;
50
51
- /* No oid_array_sort() here! See the api-oid-array.txt docs! */
51
+ /* No oid_array_sort() here! See sha1-array.h */
52
53
for (i = 0; i < array->nr; i++) {
54
int ret = fn(array->oid + i, data);
sha1-array.h
+80
@@ -1,6 +1,52 @@
1
#ifndef SHA1_ARRAY_H
2
#define SHA1_ARRAY_H
3
4
+/**
5
+ * The API provides storage and manipulation of sets of object identifiers.
6
+ * The emphasis is on storage and processing efficiency, making them suitable
7
+ * for large lists. Note that the ordering of items is not preserved over some
8
+ * operations.
9
+ *
10
+ * Examples
11
+ * --------
12
+ * -----------------------------------------
13
+ * int print_callback(const struct object_id *oid,
14
+ * void *data)
15
+ * {
16
+ * printf("%s\n", oid_to_hex(oid));
17
+ * return 0; // always continue
18
+ * }
19
+ *
20
+ * void some_func(void)
21
+ * {
22
+ * struct sha1_array hashes = OID_ARRAY_INIT;
23
+ * struct object_id oid;
24
+ *
25
+ * // Read objects into our set
26
+ * while (read_object_from_stdin(oid.hash))
27
+ * oid_array_append(&hashes, &oid);
28
+ *
29
+ * // Check if some objects are in our set
30
+ * while (read_object_from_stdin(oid.hash)) {
31
+ * if (oid_array_lookup(&hashes, &oid) >= 0)
32
+ * printf("it's in there!\n");
33
+ *
34
+ * // Print the unique set of objects. We could also have
35
+ * // avoided adding duplicate objects in the first place,
36
+ * // but we would end up re-sorting the array repeatedly.
37
+ * // Instead, this will sort once and then skip duplicates
38
+ * // in linear time.
39
+ *
40
+ * oid_array_for_each_unique(&hashes, print_callback, NULL);
41
+ * }
42
+ */
43
+
44
+/**
45
+ * A single array of object IDs. This should be initialized by assignment from
46
+ * `OID_ARRAY_INIT`. The `oid` member contains the actual data. The `nr` member
47
+ * contains the number of items in the set. The `alloc` and `sorted` members
48
+ * are used internally, and should not be needed by API callers.
49
+ */
50
struct oid_array {
51
struct object_id *oid;
52
int nr;
@@ -10,18 +56,52 @@ struct oid_array {
56
57
#define OID_ARRAY_INIT { NULL, 0, 0, 0 }
58
59
+/**
60
+ * Add an item to the set. The object ID will be placed at the end of the array
61
+ * (but note that some operations below may lose this ordering).
62
+ */
63
void oid_array_append(struct oid_array *array, const struct object_id *oid);
64
+
65
+/**
66
+ * Perform a binary search of the array for a specific object ID. If found,
67
+ * returns the offset (in number of elements) of the object ID. If not found,
68
+ * returns a negative integer. If the array is not sorted, this function has
69
+ * the side effect of sorting it.
70
+ */
71
int oid_array_lookup(struct oid_array *array, const struct object_id *oid);
72
+
73
+/**
74
+ * Free all memory associated with the array and return it to the initial,
75
+ * empty state.
76
+ */
77
void oid_array_clear(struct oid_array *array);
78
79
typedef int (*for_each_oid_fn)(const struct object_id *oid,
80
void *data);
81
+/**
82
+ * Iterate over each element of the list, executing the callback function for
83
+ * each one. Does not sort the list, so any custom hash order is retained.
84
+ * If the callback returns a non-zero value, the iteration ends immediately
85
+ * and the callback's return is propagated; otherwise, 0 is returned.
86
+ */
87
int oid_array_for_each(struct oid_array *array,
88
for_each_oid_fn fn,
89
void *data);
90
+
91
+/**
92
+ * Iterate over each unique element of the list in sorted order, but otherwise
93
+ * behave like `oid_array_for_each`. If the array is not sorted, this function
94
+ * has the side effect of sorting it.
95
+ */
96
int oid_array_for_each_unique(struct oid_array *array,
97
for_each_oid_fn fn,
98
void *data);
99
+
100
+/**
101
+ * Apply the callback function `want` to each entry in the array, retaining
102
+ * only the entries for which the function returns true. Preserve the order
103
+ * of the entries that are retained.
104
+ */
105
void oid_array_filter(struct oid_array *array,
106
for_each_oid_fn want,
107
void *cbdata);