git.ozlabs.org Git - ccan/blob - ccan/strgrp/strgrp.h

   1 /* GNU LGPL - see LICENSE file for details */
   2
   3 #ifndef STRGRP_H
   4 #define STRGRP_H
   5 #include <stdbool.h>
   6
   7 struct strgrp;
   8 struct strgrp_iter;
   9 struct strgrp_grp;
  10 struct strgrp_grp_iter;
  11 struct strgrp_item;
  12
  13 /**
  14  * Constructs a new strgrp instance.
  15  * @threshold: A value in [0.0, 1.0] describing the desired similarity of
  16  *     strings in a cluster
  17  *
  18  * @return A heap-allocated strgrp instance, or NULL if initialisation fails.
  19  * Ownership of the pointer resides with the caller, which must be freed with
  20  * strgrp_free.
  21  */
  22 struct strgrp *
  23 strgrp_new(double threshold);
  24
  25 /**
  26  * Find a group which best matches the provided string key.
  27  * @ctx: The strgrp instance to search
  28  * @str: The string key to cluster
  29  *
  30  * The returned group is the group providing the maximum score that is equal to
  31  * or above the configured threshold.
  32  *
  33  * @return A matched group, or NULL if no reasonable group is found. Ownership
  34  * of the returned pointer resides with the strgrp instance and it becomes
  35  * invalid if the strgrp instance is freed.
  36  */
  37 const struct strgrp_grp *
  38 strgrp_grp_for(struct strgrp *ctx, const char *str);
  39
  40 /**
  41  * Add a string key and arbitrary data value (together, an item) to the
  42  * appropriate group.
  43  * @ctx: The strgrp instance to add the string and data
  44  * @str: The string key used to select a group. The caller retains ownership of
  45  *     the pointer and may free or change the memory prior to freeing the
  46  *     strgrp instance.
  47  * @data: The data to attach to the group's new entry. The caller retains
  48  *     ownership of the pointer, but for correctness its lifetime should be at
  49  *     least equal to the lifetime of the strgrp instance.
  50  *
  51  * Returns the group to which the item was added. Ownership of the returned
  52  * pointer resides with the strgrp instance and it becomes invalid if the
  53  * strgrp instance is freed.
  54  */
  55 const struct strgrp_grp *
  56 strgrp_add(struct strgrp *ctx, const char *str, void *data);
  57
  58 /**
  59  * Create an iterator over the current groups.
  60  * @ctx: The strgrp instance to iterate over
  61  *
  62  * @return An iterator structure, or NULL if a failure occurred. Ownership of
  63  * the returned pointer is with the strgrp instance. The caller should pass the
  64  * pointer strgrp_iter_free when the iterator is exhausted. It is invalid to
  65  * call strgrp_iter_next or strgrp_iter_free on the returned pointer after the
  66  * strgrp instance has been freed.
  67  */
  68 struct strgrp_iter *
  69 strgrp_iter_new(struct strgrp *ctx);
  70
  71 /**
  72  * Extract the next group from a group iterator
  73  * @iter: The iterator in question
  74  *
  75  * Returns the next group in the iterator or NULL if no further groups exist.
  76  * Ownership of the returned pointer resides with the strgrp instance and
  77  * becomes invalid if the strgrp instance is freed.
  78  */
  79 const struct strgrp_grp *
  80 strgrp_iter_next(struct strgrp_iter *iter);
  81
  82 /**
  83  * Clean up a group iterator instance
  84  * @iter: The iterator to free
  85  */
  86 void
  87 strgrp_iter_free(struct strgrp_iter *iter);
  88
  89 /**
  90  * Extract the key for a group.
  91  * @grp: A strgrp_grp pointer
  92  *
  93  * A group's key is the input string that caused the creation of the group.
  94  *
  95  * Returns the group key. Ownership of the pointer resides with the grp
  96  * parameter and by extension the strgrp instance. The caller must duplicate
  97  * the string if the content is required beyond the lifetime of the strgrp
  98  * instance.
  99  */
 100 const char *
 101 strgrp_grp_key(const struct strgrp_grp *grp);
 102
 103 /**
 104  * Create an iterator over items in the provided group
 105  * @grp: The group whose items to iterate over
 106  *
 107  * @return An iterator structure, or NULL if a failure occurred. Ownership of
 108  * the returned pointer is with the strgrp instance. The caller should pass the
 109  * pointer strgrp_grp_iter_free when the iterator is exhausted. It is invalid
 110  * to call strgrp_grp_iter_next or strgrp_grp_iter_free on the returned pointer
 111  * after the strgrp instance has been freed.
 112  */
 113 struct strgrp_grp_iter *
 114 strgrp_grp_iter_new(const struct strgrp_grp *grp);
 115
 116 /**
 117  * Extract the next item from a item iterator
 118  * @iter: The iterator in question
 119  *
 120  * Returns the next group in the iterator or NULL if no further items exist.
 121  * Ownership of the returned pointer resides with the strgrp instance and
 122  * becomes invalid if the strgrp instance is freed.
 123  */
 124 const struct strgrp_item *
 125 strgrp_grp_iter_next(struct strgrp_grp_iter *iter);
 126
 127 /**
 128  * Clean up an item iterator instance
 129  * @iter: The iterator to free
 130  */
 131 void
 132 strgrp_grp_iter_free(struct strgrp_grp_iter *iter);
 133
 134 /**
 135  * Extract the key for an item
 136  *
 137  * @item: The item in question
 138  *
 139  * The key is the string input string which generated the item in the cluster.
 140  *
 141  * Returns the item key. Ownership of the pointer resides with the item
 142  * parameter and by extension the strgrp instance. The caller must duplicate
 143  * the string if the content is required beyond the lifetime of the strgrp
 144  * instance.
 145  */
 146 const char *
 147 strgrp_item_key(const struct strgrp_item *item);
 148
 149 /**
 150  * Extract the value for an item
 151  * @item: The item in question
 152  *
 153  * The value is the arbitrary pointer associated with the input string
 154  *
 155  * Returns the item value. The ownership of the pointer does not reside with
 156  * the strgrp instance, but for correctness should exceed the lifetime of the
 157  * strgrp instance.
 158  */
 159 void *
 160 strgrp_item_value(const struct strgrp_item *item);
 161
 162 /**
 163  * Destroy the strgrp instance
 164  *
 165  * @ctx: The strgrp instance in question
 166  */
 167 void
 168 strgrp_free(struct strgrp *ctx);
 169
 170 /**
 171  * Destroy the strgrp instance, but not before applying cb() to each item's value element
 172  * @ctx: The strgrp instance in question
 173  * @cb: The callback to execute against each item's value. This might be used
 174  *      to free the value data.
 175  */
 176 void
 177 strgrp_free_cb(struct strgrp *ctx, void (*cb)(void *data));
 178
 179
 180 /**
 181  * Dump the groupings to stdout.
 182  * @ctx: The strgrp instance in question
 183  */
 184 void
 185 strgrp_print(const struct strgrp *ctx);
 186 #endif