mirror of
https://github.com/git/git
synced 2024-08-24 18:26:02 +00:00
![Jeff King](/assets/img/avatar_default.png)
We provide oid_array_for_each_unique() for iterating over the de-duplicated items in an array. But it's awkward to use for two reasons: 1. It uses a callback, which means marshaling arguments into a struct and passing it to the callback with a void parameter. 2. The callback doesn't know the numeric index of the oid we're looking at. This is useful for things like progress meters. Iterating with a for-loop is much more natural for some cases, but the caller has to do the de-duping itself. However, we can provide a small helper to make this easier (see the docstring in the header for an example use). The caller does have to remember to sort the array first. We could add an assertion into the helper that array->sorted is set, but I didn't want to complicate what is otherwise a pretty fast code path. I also considered adding a full iterator type with init/next/end functions (similar to what we have for hashmaps). But it ended up making the callers much harder to read. This version keeps us close to a basic for-loop. Yet another option would be adding an option to sort the array and compact out the duplicates. This would mean iterating over the array an extra time, though that's probably not a big deal (we did just do an O(n log n) sort). But we'd still have to write a for-loop to iterate, so it doesn't really make anything easier for the caller. No new test, since we'll convert the callback iterator (which is covered by t0064, among other callers) to use the new code. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
138 lines
4.3 KiB
C
138 lines
4.3 KiB
C
#ifndef OID_ARRAY_H
|
|
#define OID_ARRAY_H
|
|
|
|
#include "hash.h"
|
|
|
|
/**
|
|
* The API provides storage and manipulation of sets of object identifiers.
|
|
* The emphasis is on storage and processing efficiency, making them suitable
|
|
* for large lists. Note that the ordering of items is not preserved over some
|
|
* operations.
|
|
*
|
|
* Examples
|
|
* --------
|
|
* -----------------------------------------
|
|
* int print_callback(const struct object_id *oid,
|
|
* void *data)
|
|
* {
|
|
* printf("%s\n", oid_to_hex(oid));
|
|
* return 0; // always continue
|
|
* }
|
|
*
|
|
* void some_func(void)
|
|
* {
|
|
* struct oid_array hashes = OID_ARRAY_INIT;
|
|
* struct object_id oid;
|
|
*
|
|
* // Read objects into our set
|
|
* while (read_object_from_stdin(oid.hash))
|
|
* oid_array_append(&hashes, &oid);
|
|
*
|
|
* // Check if some objects are in our set
|
|
* while (read_object_from_stdin(oid.hash)) {
|
|
* if (oid_array_lookup(&hashes, &oid) >= 0)
|
|
* printf("it's in there!\n");
|
|
*
|
|
* // Print the unique set of objects. We could also have
|
|
* // avoided adding duplicate objects in the first place,
|
|
* // but we would end up re-sorting the array repeatedly.
|
|
* // Instead, this will sort once and then skip duplicates
|
|
* // in linear time.
|
|
*
|
|
* oid_array_for_each_unique(&hashes, print_callback, NULL);
|
|
* }
|
|
*/
|
|
|
|
/**
|
|
* A single array of object IDs. This should be initialized by assignment from
|
|
* `OID_ARRAY_INIT`. The `oid` member contains the actual data. The `nr` member
|
|
* contains the number of items in the set. The `alloc` and `sorted` members
|
|
* are used internally, and should not be needed by API callers.
|
|
*/
|
|
struct oid_array {
|
|
struct object_id *oid;
|
|
size_t nr;
|
|
size_t alloc;
|
|
int sorted;
|
|
};
|
|
|
|
#define OID_ARRAY_INIT { NULL, 0, 0, 0 }
|
|
|
|
/**
|
|
* Add an item to the set. The object ID will be placed at the end of the array
|
|
* (but note that some operations below may lose this ordering).
|
|
*/
|
|
void oid_array_append(struct oid_array *array, const struct object_id *oid);
|
|
|
|
/**
|
|
* Perform a binary search of the array for a specific object ID. If found,
|
|
* returns the offset (in number of elements) of the object ID. If not found,
|
|
* returns a negative integer. If the array is not sorted, this function has
|
|
* the side effect of sorting it.
|
|
*/
|
|
int oid_array_lookup(struct oid_array *array, const struct object_id *oid);
|
|
|
|
/**
|
|
* Free all memory associated with the array and return it to the initial,
|
|
* empty state.
|
|
*/
|
|
void oid_array_clear(struct oid_array *array);
|
|
|
|
typedef int (*for_each_oid_fn)(const struct object_id *oid,
|
|
void *data);
|
|
/**
|
|
* Iterate over each element of the list, executing the callback function for
|
|
* each one. Does not sort the list, so any custom hash order is retained.
|
|
* If the callback returns a non-zero value, the iteration ends immediately
|
|
* and the callback's return is propagated; otherwise, 0 is returned.
|
|
*/
|
|
int oid_array_for_each(struct oid_array *array,
|
|
for_each_oid_fn fn,
|
|
void *data);
|
|
|
|
/**
|
|
* Iterate over each unique element of the list in sorted order, but otherwise
|
|
* behave like `oid_array_for_each`. If the array is not sorted, this function
|
|
* has the side effect of sorting it.
|
|
*/
|
|
int oid_array_for_each_unique(struct oid_array *array,
|
|
for_each_oid_fn fn,
|
|
void *data);
|
|
|
|
/**
|
|
* Apply the callback function `want` to each entry in the array, retaining
|
|
* only the entries for which the function returns true. Preserve the order
|
|
* of the entries that are retained.
|
|
*/
|
|
void oid_array_filter(struct oid_array *array,
|
|
for_each_oid_fn want,
|
|
void *cbdata);
|
|
|
|
/**
|
|
* Sort the array in order of ascending object id.
|
|
*/
|
|
void oid_array_sort(struct oid_array *array);
|
|
|
|
/**
|
|
* Find the next unique oid in the array after position "cur".
|
|
* The array must be sorted for this to work. You can iterate
|
|
* over unique elements like this:
|
|
*
|
|
* size_t i;
|
|
* oid_array_sort(array);
|
|
* for (i = 0; i < array->nr; i = oid_array_next_unique(array, i))
|
|
* printf("%s", oid_to_hex(array->oids[i]);
|
|
*
|
|
* Non-unique iteration can just increment with "i++" to visit each element.
|
|
*/
|
|
static inline size_t oid_array_next_unique(struct oid_array *array, size_t cur)
|
|
{
|
|
do {
|
|
cur++;
|
|
} while (cur < array->nr &&
|
|
oideq(array->oid + cur, array->oid + cur - 1));
|
|
return cur;
|
|
}
|
|
|
|
#endif /* OID_ARRAY_H */
|