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