1 /* GNU LGPL - see LICENSE file for details */
10 struct strgrp_grp_iter;
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
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
23 strgrp_new(double threshold);
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
30 * The returned group is the group providing the maximum score that is equal to
31 * or above the configured threshold.
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.
37 const struct strgrp_grp *
38 strgrp_grp_for(struct strgrp *ctx, const char *str);
41 * Add a string key and arbitrary data value (together, an item) to the
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
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.
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.
55 const struct strgrp_grp *
56 strgrp_add(struct strgrp *ctx, const char *str, void *data);
59 * Create an iterator over the current groups.
60 * @ctx: The strgrp instance to iterate over
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.
69 strgrp_iter_new(struct strgrp *ctx);
72 * Extract the next group from a group iterator
73 * @iter: The iterator in question
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.
79 const struct strgrp_grp *
80 strgrp_iter_next(struct strgrp_iter *iter);
83 * Clean up a group iterator instance
84 * @iter: The iterator to free
87 strgrp_iter_free(struct strgrp_iter *iter);
90 * Extract the key for a group.
91 * @grp: A strgrp_grp pointer
93 * A group's key is the input string that caused the creation of the group.
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
101 strgrp_grp_key(const struct strgrp_grp *grp);
104 * Create an iterator over items in the provided group
105 * @grp: The group whose items to iterate over
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.
113 struct strgrp_grp_iter *
114 strgrp_grp_iter_new(const struct strgrp_grp *grp);
117 * Extract the next item from a item iterator
118 * @iter: The iterator in question
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.
124 const struct strgrp_item *
125 strgrp_grp_iter_next(struct strgrp_grp_iter *iter);
128 * Clean up an item iterator instance
129 * @iter: The iterator to free
132 strgrp_grp_iter_free(struct strgrp_grp_iter *iter);
135 * Extract the key for an item
137 * @item: The item in question
139 * The key is the string input string which generated the item in the cluster.
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
147 strgrp_item_key(const struct strgrp_item *item);
150 * Extract the value for an item
151 * @item: The item in question
153 * The value is the arbitrary pointer associated with the input string
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
160 strgrp_item_value(const struct strgrp_item *item);
163 * Destroy the strgrp instance
165 * @ctx: The strgrp instance in question
168 strgrp_free(struct strgrp *ctx);
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.
177 strgrp_free_cb(struct strgrp *ctx, void (*cb)(void *data));
181 * Dump the groupings to stdout.
182 * @ctx: The strgrp instance in question
185 strgrp_print(const struct strgrp *ctx);