mirror of
https://github.com/git/git.git
synced 2024-10-31 22:37:54 +01:00
e239dabb14
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>
80 lines
2.4 KiB
Text
80 lines
2.4 KiB
Text
oid-array API
|
|
==============
|
|
|
|
The oid-array 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.
|
|
|
|
Data Structures
|
|
---------------
|
|
|
|
`struct oid_array`::
|
|
|
|
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.
|
|
|
|
Functions
|
|
---------
|
|
|
|
`oid_array_append`::
|
|
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).
|
|
|
|
`oid_array_lookup`::
|
|
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.
|
|
|
|
`oid_array_clear`::
|
|
Free all memory associated with the array and return it to the
|
|
initial, empty state.
|
|
|
|
`oid_array_for_each_unique`::
|
|
Efficiently iterate over each unique element of the list,
|
|
executing the callback function for each one. If the array is
|
|
not sorted, this function has the side effect of sorting it. If
|
|
the callback returns a non-zero value, the iteration ends
|
|
immediately and the callback's return is propagated; otherwise,
|
|
0 is returned.
|
|
|
|
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 sha1_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);
|
|
}
|
|
-----------------------------------------
|