Documentation/technical/api-oid-array.txt

   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_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
  42         the callback returns a non-zero value, the iteration ends
  43         immediately and the callback's return is propagated; otherwise,
  44         0 is returned.
  45
  46 Examples
  47 --------
  48
  49 -----------------------------------------
  50 int print_callback(const struct object_id *oid,
  51                     void *data)
  52 {
  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 = OID_ARRAY_INIT;
  60         struct object_id oid;
  61
  62         /* Read objects into our set */
  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(oid.hash)) {
  68                 if (oid_array_lookup(&hashes, &oid) >= 0)
  69                         printf("it's in there!\n");
  70
  71         /*
  72          * Print the unique set of objects. We could also have
  73          * avoided adding duplicate objects in the first place,
  74          * but we would end up re-sorting the array repeatedly.
  75          * Instead, this will sort once and then skip duplicates
  76          * in linear time.
  77          */
  78         oid_array_for_each_unique(&hashes, print_callback, NULL);
  79 }
  80 -----------------------------------------