decorate.h

   1 #ifndef DECORATE_H
   2 #define DECORATE_H
   3
   4 /*
   5  * A data structure that associates Git objects to void pointers. See
   6  * t/helper/test-example-decorate.c for a demonstration of how to use these
   7  * functions.
   8  */
   9
  10 /*
  11  * An entry in the data structure.
  12  */
  13 struct decoration_entry {
  14         const struct object *base;
  15         void *decoration;
  16 };
  17
  18 /*
  19  * The data structure.
  20  *
  21  * This data structure must be zero-initialized.
  22  */
  23 struct decoration {
  24         /*
  25          * Not used by the decoration mechanism. Clients may use this for
  26          * whatever they want.
  27          */
  28         const char *name;
  29
  30         /*
  31          * The capacity of "entries".
  32          */
  33         unsigned int size;
  34
  35         /*
  36          * The number of real Git objects (that is, entries with non-NULL
  37          * "base").
  38          */
  39         unsigned int nr;
  40
  41         /*
  42          * The entries. This is an array of size "size", containing nr entries
  43          * with non-NULL "base" and (size - nr) entries with NULL "base".
  44          */
  45         struct decoration_entry *entries;
  46 };
  47
  48 /*
  49  * Add an association from the given object to the given pointer (which may be
  50  * NULL), returning the previously associated pointer. If there is no previous
  51  * association, this function returns NULL.
  52  */
  53 void *add_decoration(struct decoration *n, const struct object *obj, void *decoration);
  54
  55 /*
  56  * Return the pointer associated to the given object. If there is no
  57  * association, this function returns NULL.
  58  */
  59 void *lookup_decoration(struct decoration *n, const struct object *obj);
  60
  61 /*
  62  * Clear all decoration entries, releasing any memory used by the structure.
  63  * If free_cb is not NULL, it is called for every decoration value currently
  64  * stored.
  65  *
  66  * After clearing, the decoration struct can be used again. The "name" field is
  67  * retained.
  68  */
  69 void clear_decoration(struct decoration *n, void (*free_cb)(void *));
  70
  71 #endif