summaryrefslogtreecommitdiff
path: root/Build/source/libs/icu/icu-4.6/i18n/unicode/bms.h
blob: 516e6aa2280dd2a9588f2db7ea738c584477d451 (plain)
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
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
/*
 * Copyright (C) 1996-2010, International Business Machines Corporation and Others.
 * All rights reserved.
 */

/**
 * \file 
 * \brief C API: Boyer-Moore StringSearch prototype.
 * \internal
 */

#ifndef _BMS_H
#define _BMS_H

#include "unicode/utypes.h"

#if !UCONFIG_NO_COLLATION && !UCONFIG_NO_BREAK_ITERATION

#include "unicode/ucol.h"

/**
 * A <code>UCD</code> object holds the Collator-specific data needed to
 * compute the length of the shortest string that can
 * generate a partcular list of CEs.
 *
 * <code>UCD</code> objects are quite expensive to compute. Because
 * of this, they are cached. When you call <code>ucd_open</code> it
 * returns a reference counted cached object. When you call <code>ucd_close</code>
 * the reference count on the object is decremented but the object is not deleted.
 *
 * If you do not need to reuse any unreferenced objects in the cache, you can call
 * <code>ucd_flushCCache</code>. If you no longer need any <code>UCD</code>
 * objects, you can call <code>ucd_freeCache</code>
 */
typedef void UCD;

/**
 * Open a <code>UCD</code> object.
 *
 * @param coll - the collator
 * @param status - will be set if any errors occur. 
 *
 * @return the <code>UCD</code> object. You must call
 *         <code>ucd_close</code> when you are done using the object.
 *
 * Note: if on return status is set to an error, the only safe
 * thing to do with the returned object is to call <code>ucd_close</code>.
 *
 * @internal ICU 4.0.1 technology preview
 */
U_CAPI UCD * U_EXPORT2
ucd_open(UCollator *coll, UErrorCode *status);

/**
 * Release a <code>UCD</code> object.
 *
 * @param ucd - the object
 *
 * @internal ICU 4.0.1 technology preview
 */
U_CAPI void U_EXPORT2
ucd_close(UCD *ucd);

/**
 * Get the <code>UCollator</code> object used to create a <code>UCD</code> object.
 * The <code>UCollator</code> object returned may not be the exact
 * object that was used to create this object, but it will have the
 * same behavior.
 *
 * @param ucd - the <code>UCD</code> object
 *
 * @return the <code>UCollator</code> used to create the given
 *         <code>UCD</code> object.
 *
 * @internal ICU 4.0.1 technology preview
 */
U_CAPI UCollator * U_EXPORT2
ucd_getCollator(UCD *ucd);

/**
 * <code>UCD</code> objects are expensive to compute, and so
 * may be cached. This routine will free the cached objects and delete
 * the cache.
 *
 * WARNING: Don't call this until you are have called <code>close</code>
 * for each <code>UCD</code> object that you have used. also,
 * DO NOT call this if another thread may be calling <code>ucd_flushCache</code>
 * at the same time.
 *
 * @internal ICU 4.0.1 technology preview
 */
U_CAPI void U_EXPORT2
ucd_freeCache();

/**
 * <code>UCD</code> objects are expensive to compute, and so
 * may be cached. This routine will remove any unused <code>UCD</code>
 * objects from the cache.
 *
 * @internal 4.0.1 technology preview
 */
U_CAPI void U_EXPORT2
ucd_flushCache();

/**
 * BMS
 *
 * This object holds the information needed to do a Collation sensitive Boyer-Moore search. It encapulates
 * the pattern, the "bad character" and "good suffix" tables, the Collator-based data needed to compute them,
 * and a reference to the text being searched.
 *
 * To do a search, you first need to get a <code>UCD</code> object by calling <code>ucd_open</code>.
 * Then you construct a <code>BMS</code> object from the <code>UCD</code> object, the pattern
 * string and the target string. Then you call the <code>search</code> method. Here's a code sample:
 *
 * <pre>
 * void boyerMooreExample(UCollator *collator, UChar *pattern, int32_t patternLen, UChar *target, int32_t targetLength)
 * {
 *     UErrorCode status = U_ZERO_ERROR;
 *     int32_t offset = 0, start = -1, end = -1;
 *     UCD *ucd = NULL);
 *     BMS *bms = NULL;
 *
 *     ucd = ucd_open(collator, &status);
 *     if (U_FAILURE(status)) {
 *         // could not create a UCD object
 *         return;
 *     }
 *
 *     BMS *bms = bms_open(ucd, pattern, patternLength, target, targetlength, &status);
 *     if (U_FAILURE(status)) {
 *         // could not create a BMS object
 *         ucd_close(ucd);
 *         return;
 *     }
 *
 *
 *     // Find all matches
 *     while (bms_search(bms, offset, &start, &end)) {
 *         // process the match between start and end
 *         ...
 *
 *         // advance past the match
 *         offset = end; 
 *     }
 *
 *     // at this point, if offset == 0, there were no matches
 *     if (offset == 0) {
 *         // handle the case of no matches
 *     }
 *
 *     bms_close(bms);
 *     ucd_close(ucd);
 *
 *     // UCD objects are cached, so the call to
 *     // ucd_close doesn't delete the object.
 *     // Call this if you don't need the object any more.
 *     ucd_flushCache();
 * }
 * </pre>
 *
 * NOTE: This is a technology preview. The final version of this API may not bear any resenblence to this API.
 *
 * Knows linitations:
 *   1) Backwards searching has not been implemented.
 *
 *   2) For Han and Hangul characters, this code ignores any Collation tailorings. In general,
 *      this isn't a problem, but in Korean locals, at strength 1, Hangul characters are tailored
 *      to be equal to Han characters with the same pronounciation. Because this code ignroes
 *      tailorings, searching for a Hangul character will not find a Han character and visa-versa.
 *
 *   3) In some cases, searching for a pattern that needs to be normalized and ends
 *      in a discontiguous contraction may fail. The only known cases of this are with
 *      the Tibetan script. For example searching for the pattern
 *      "\u0F7F\u0F80\u0F81\u0F82\u0F83\u0F84\u0F85" will fail. (This case is artificial. We've
 *      been unable to find a pratical, real-world example of this failure.)  
 *
 * NOTE: This is a technology preview. The final version of this API may not bear any resenblence to this API.
 *
 * @internal ICU 4.0.1 technology preview
 */
struct BMS;
typedef struct BMS BMS; /**< @see BMS */

/**
 * Construct a <code>MBS</code> object.
 *
 * @param ucd - A <code>UCD</code> object holding the Collator-sensitive data
 * @param pattern - the string for which to search
 * @param patternLength - the length of the string for which to search
 * @param target - the string in which to search
 * @param targetLength - the length of the string in which to search
 * @param status - will be set if any errors occur. 
 *
 * @return the <code>BMS</code> object.
 *
 * Note: if on return status is set to an error, the only safe
 * thing to do with the returned object is to call
 * <code>bms_close</code>.
 *
 * @internal ICU 4.0.1 technology preview
 */
U_CAPI BMS * U_EXPORT2
bms_open(UCD *ucd,
         const UChar *pattern, int32_t patternLength,
         const UChar *target,  int32_t targetLength,
         UErrorCode  *status);

/**
 * Close a <code>BMS</code> object and release all the
 * storage associated with it.
 *
 * @param bms - the <code>BMS</code> object to close.
 * @internal ICU 4.0.1 technology preview
 */
U_CAPI void U_EXPORT2
bms_close(BMS *bms);

/**
 * Test the pattern to see if it generates any CEs.
 *
 * @param bms - the <code>BMS</code> object
 * @return <code>TRUE</code> if the pattern string did not generate any CEs
 *
 * @internal ICU 4.0.1 technology preview
 */
U_CAPI UBool U_EXPORT2
bms_empty(BMS *bms);

/**
 * Get the <code>UCD</code> object used to create
 * a given <code>BMS</code> object.
 *
 * @param bms - the <code>BMS</code> object
 *
 * @return - the <code>UCD</code> object used to create
 *           the given <code>BMS</code> object.
 *
 * @internal ICU 4.0.1 technology preview
 */
U_CAPI UCD * U_EXPORT2
bms_getData(BMS *bms);

/**
 * Search for the pattern string in the target string.
 *
 * @param bms - the <code>BMS</code> object
 * @param offset - the offset in the target string at which to begin the search
 * @param start - will be set to the starting offset of the match, or -1 if there's no match
 * @param end - will be set to the ending offset of the match, or -1 if there's no match
 *
 * @return <code>TRUE</code> if the match succeeds, <code>FALSE</code> otherwise.
 *
 * @internal ICU 4.0.1 technology preview
 */
U_CAPI UBool U_EXPORT2
bms_search(BMS *bms, int32_t offset, int32_t *start, int32_t *end);

/**
 * Set the target string for the match.
 *
 * @param bms - the <code>BMS</code> object
 * @param target - the new target string
 * @param targetLength - the length of the new target string
 * @param status - will be set if any errors occur. 
 *
 * @internal ICU 4.0.1 technology preview
 */
U_CAPI void U_EXPORT2
bms_setTargetString(BMS *bms, const UChar *target, int32_t targetLength, UErrorCode *status);

#endif

#endif /* _BMS_H */