The Tor Browser / file comparison

comparison: intl/icu/source/i18n/unicode/usearch.h

intl/icu/source/i18n/unicode/usearch.h

branch
TOR_BUG_3246
changeset 4
fc2d59ddac77
equal deleted inserted replaced
-1:000000000000 0:6e1be6e9b090
1 /*
2 **********************************************************************
3 * Copyright (C) 2001-2011 IBM and others. All rights reserved.
4 **********************************************************************
5 * Date Name Description
6 * 06/28/2001 synwee Creation.
7 **********************************************************************
8 */
9 #ifndef USEARCH_H
10 #define USEARCH_H
11
12 #include "unicode/utypes.h"
13
14 #if !UCONFIG_NO_COLLATION && !UCONFIG_NO_BREAK_ITERATION
15
16 #include "unicode/localpointer.h"
17 #include "unicode/ucol.h"
18 #include "unicode/ucoleitr.h"
19 #include "unicode/ubrk.h"
20
21 /**
22 * \file
23 * \brief C API: StringSearch
24 *
25 * C Apis for an engine that provides language-sensitive text searching based
26 * on the comparison rules defined in a <tt>UCollator</tt> data struct,
27 * see <tt>ucol.h</tt>. This ensures that language eccentricity can be
28 * handled, e.g. for the German collator, characters &szlig; and SS will be matched
29 * if case is chosen to be ignored.
30 * See the <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/collation/ICU_collation_design.htm">
31 * "ICU Collation Design Document"</a> for more information.
32 * <p>
33 * The algorithm implemented is a modified form of the Boyer Moore's search.
34 * For more information see
35 * <a href="http://icu-project.org/docs/papers/efficient_text_searching_in_java.html">
36 * "Efficient Text Searching in Java"</a>, published in <i>Java Report</i>
37 * in February, 1999, for further information on the algorithm.
38 * <p>
39 * There are 2 match options for selection:<br>
40 * Let S' be the sub-string of a text string S between the offsets start and
41 * end <start, end>.
42 * <br>
43 * A pattern string P matches a text string S at the offsets <start, end>
44 * if
45 * <pre>
46 * option 1. Some canonical equivalent of P matches some canonical equivalent
47 * of S'
48 * option 2. P matches S' and if P starts or ends with a combining mark,
49 * there exists no non-ignorable combining mark before or after S'
50 * in S respectively.
51 * </pre>
52 * Option 2. will be the default.
53 * <p>
54 * This search has APIs similar to that of other text iteration mechanisms
55 * such as the break iterators in <tt>ubrk.h</tt>. Using these
56 * APIs, it is easy to scan through text looking for all occurances of
57 * a given pattern. This search iterator allows changing of direction by
58 * calling a <tt>reset</tt> followed by a <tt>next</tt> or <tt>previous</tt>.
59 * Though a direction change can occur without calling <tt>reset</tt> first,
60 * this operation comes with some speed penalty.
61 * Generally, match results in the forward direction will match the result
62 * matches in the backwards direction in the reverse order
63 * <p>
64 * <tt>usearch.h</tt> provides APIs to specify the starting position
65 * within the text string to be searched, e.g. <tt>usearch_setOffset</tt>,
66 * <tt>usearch_preceding</tt> and <tt>usearch_following</tt>. Since the
67 * starting position will be set as it is specified, please take note that
68 * there are some dangerous positions which the search may render incorrect
69 * results:
70 * <ul>
71 * <li> The midst of a substring that requires normalization.
72 * <li> If the following match is to be found, the position should not be the
73 * second character which requires to be swapped with the preceding
74 * character. Vice versa, if the preceding match is to be found,
75 * position to search from should not be the first character which
76 * requires to be swapped with the next character. E.g certain Thai and
77 * Lao characters require swapping.
78 * <li> If a following pattern match is to be found, any position within a
79 * contracting sequence except the first will fail. Vice versa if a
80 * preceding pattern match is to be found, a invalid starting point
81 * would be any character within a contracting sequence except the last.
82 * </ul>
83 * <p>
84 * A breakiterator can be used if only matches at logical breaks are desired.
85 * Using a breakiterator will only give you results that exactly matches the
86 * boundaries given by the breakiterator. For instance the pattern "e" will
87 * not be found in the string "\u00e9" if a character break iterator is used.
88 * <p>
89 * Options are provided to handle overlapping matches.
90 * E.g. In English, overlapping matches produces the result 0 and 2
91 * for the pattern "abab" in the text "ababab", where else mutually
92 * exclusive matches only produce the result of 0.
93 * <p>
94 * Though collator attributes will be taken into consideration while
95 * performing matches, there are no APIs here for setting and getting the
96 * attributes. These attributes can be set by getting the collator
97 * from <tt>usearch_getCollator</tt> and using the APIs in <tt>ucol.h</tt>.
98 * Lastly to update String Search to the new collator attributes,
99 * usearch_reset() has to be called.
100 * <p>
101 * Restriction: <br>
102 * Currently there are no composite characters that consists of a
103 * character with combining class > 0 before a character with combining
104 * class == 0. However, if such a character exists in the future, the
105 * search mechanism does not guarantee the results for option 1.
106 *
107 * <p>
108 * Example of use:<br>
109 * <pre><code>
110 * char *tgtstr = "The quick brown fox jumped over the lazy fox";
111 * char *patstr = "fox";
112 * UChar target[64];
113 * UChar pattern[16];
114 * UErrorCode status = U_ZERO_ERROR;
115 * u_uastrcpy(target, tgtstr);
116 * u_uastrcpy(pattern, patstr);
117 *
118 * UStringSearch *search = usearch_open(pattern, -1, target, -1, "en_US",
119 * NULL, &status);
120 * if (U_SUCCESS(status)) {
121 * for (int pos = usearch_first(search, &status);
122 * pos != USEARCH_DONE;
123 * pos = usearch_next(search, &status))
124 * {
125 * printf("Found match at %d pos, length is %d\n", pos,
126 * usearch_getMatchLength(search));
127 * }
128 * }
129 *
130 * usearch_close(search);
131 * </code></pre>
132 * @stable ICU 2.4
133 */
134
135 /**
136 * DONE is returned by previous() and next() after all valid matches have
137 * been returned, and by first() and last() if there are no matches at all.
138 * @stable ICU 2.4
139 */
140 #define USEARCH_DONE -1
141
142 /**
143 * Data structure for searching
144 * @stable ICU 2.4
145 */
146 struct UStringSearch;
147 /**
148 * Data structure for searching
149 * @stable ICU 2.4
150 */
151 typedef struct UStringSearch UStringSearch;
152
153 /**
154 * @stable ICU 2.4
155 */
156 typedef enum {
157 /** Option for overlapping matches */
158 USEARCH_OVERLAP,
159 /**
160 * Option for canonical matches. option 1 in header documentation.
161 * The default value will be USEARCH_OFF
162 */
163 USEARCH_CANONICAL_MATCH,
164 /**
165 * Option to control how collation elements are compared.
166 * The default value will be USEARCH_STANDARD_ELEMENT_COMPARISON.
167 * @stable ICU 4.4
168 */
169 USEARCH_ELEMENT_COMPARISON,
170
171 USEARCH_ATTRIBUTE_COUNT
172 } USearchAttribute;
173
174 /**
175 * @stable ICU 2.4
176 */
177 typedef enum {
178 /** Default value for any USearchAttribute */
179 USEARCH_DEFAULT = -1,
180 /** Value for USEARCH_OVERLAP and USEARCH_CANONICAL_MATCH */
181 USEARCH_OFF,
182 /** Value for USEARCH_OVERLAP and USEARCH_CANONICAL_MATCH */
183 USEARCH_ON,
184 /**
185 * Value (default) for USEARCH_ELEMENT_COMPARISON;
186 * standard collation element comparison at the specified collator
187 * strength.
188 * @stable ICU 4.4
189 */
190 USEARCH_STANDARD_ELEMENT_COMPARISON,
191 /**
192 * Value for USEARCH_ELEMENT_COMPARISON;
193 * collation element comparison is modified to effectively provide
194 * behavior between the specified strength and strength - 1. Collation
195 * elements in the pattern that have the base weight for the specified
196 * strength are treated as "wildcards" that match an element with any
197 * other weight at that collation level in the searched text. For
198 * example, with a secondary-strength English collator, a plain 'e' in
199 * the pattern will match a plain e or an e with any diacritic in the
200 * searched text, but an e with diacritic in the pattern will only
201 * match an e with the same diacritic in the searched text.
202 * @stable ICU 4.4
203 */
204 USEARCH_PATTERN_BASE_WEIGHT_IS_WILDCARD,
205 /**
206 * Value for USEARCH_ELEMENT_COMPARISON.
207 * collation element comparison is modified to effectively provide
208 * behavior between the specified strength and strength - 1. Collation
209 * elements in either the pattern or the searched text that have the
210 * base weight for the specified strength are treated as "wildcards"
211 * that match an element with any other weight at that collation level.
212 * For example, with a secondary-strength English collator, a plain 'e'
213 * in the pattern will match a plain e or an e with any diacritic in the
214 * searched text, but an e with diacritic in the pattern will only
215 * match an e with the same diacritic or a plain e in the searched text.
216 * @stable ICU 4.4
217 */
218 USEARCH_ANY_BASE_WEIGHT_IS_WILDCARD,
219
220 USEARCH_ATTRIBUTE_VALUE_COUNT
221 } USearchAttributeValue;
222
223 /* open and close ------------------------------------------------------ */
224
225 /**
226 * Creating a search iterator data struct using the argument locale language
227 * rule set. A collator will be created in the process, which will be owned by
228 * this search and will be deleted in <tt>usearch_close</tt>.
229 * @param pattern for matching
230 * @param patternlength length of the pattern, -1 for null-termination
231 * @param text text string
232 * @param textlength length of the text string, -1 for null-termination
233 * @param locale name of locale for the rules to be used
234 * @param breakiter A BreakIterator that will be used to restrict the points
235 * at which matches are detected. If a match is found, but
236 * the match's start or end index is not a boundary as
237 * determined by the <tt>BreakIterator</tt>, the match will
238 * be rejected and another will be searched for.
239 * If this parameter is <tt>NULL</tt>, no break detection is
240 * attempted.
241 * @param status for errors if it occurs. If pattern or text is NULL, or if
242 * patternlength or textlength is 0 then an
243 * U_ILLEGAL_ARGUMENT_ERROR is returned.
244 * @return search iterator data structure, or NULL if there is an error.
245 * @stable ICU 2.4
246 */
247 U_STABLE UStringSearch * U_EXPORT2 usearch_open(const UChar *pattern,
248 int32_t patternlength,
249 const UChar *text,
250 int32_t textlength,
251 const char *locale,
252 UBreakIterator *breakiter,
253 UErrorCode *status);
254
255 /**
256 * Creating a search iterator data struct using the argument collator language
257 * rule set. Note, user retains the ownership of this collator, thus the
258 * responsibility of deletion lies with the user.
259 * NOTE: string search cannot be instantiated from a collator that has
260 * collate digits as numbers (CODAN) turned on.
261 * @param pattern for matching
262 * @param patternlength length of the pattern, -1 for null-termination
263 * @param text text string
264 * @param textlength length of the text string, -1 for null-termination
265 * @param collator used for the language rules
266 * @param breakiter A BreakIterator that will be used to restrict the points
267 * at which matches are detected. If a match is found, but
268 * the match's start or end index is not a boundary as
269 * determined by the <tt>BreakIterator</tt>, the match will
270 * be rejected and another will be searched for.
271 * If this parameter is <tt>NULL</tt>, no break detection is
272 * attempted.
273 * @param status for errors if it occurs. If collator, pattern or text is NULL,
274 * or if patternlength or textlength is 0 then an
275 * U_ILLEGAL_ARGUMENT_ERROR is returned.
276 * @return search iterator data structure, or NULL if there is an error.
277 * @stable ICU 2.4
278 */
279 U_STABLE UStringSearch * U_EXPORT2 usearch_openFromCollator(
280 const UChar *pattern,
281 int32_t patternlength,
282 const UChar *text,
283 int32_t textlength,
284 const UCollator *collator,
285 UBreakIterator *breakiter,
286 UErrorCode *status);
287
288 /**
289 * Destroying and cleaning up the search iterator data struct.
290 * If a collator is created in <tt>usearch_open</tt>, it will be destroyed here.
291 * @param searchiter data struct to clean up
292 * @stable ICU 2.4
293 */
294 U_STABLE void U_EXPORT2 usearch_close(UStringSearch *searchiter);
295
296 #if U_SHOW_CPLUSPLUS_API
297
298 U_NAMESPACE_BEGIN
299
300 /**
301 * \class LocalUStringSearchPointer
302 * "Smart pointer" class, closes a UStringSearch via usearch_close().
303 * For most methods see the LocalPointerBase base class.
304 *
305 * @see LocalPointerBase
306 * @see LocalPointer
307 * @stable ICU 4.4
308 */
309 U_DEFINE_LOCAL_OPEN_POINTER(LocalUStringSearchPointer, UStringSearch, usearch_close);
310
311 U_NAMESPACE_END
312
313 #endif
314
315 /* get and set methods -------------------------------------------------- */
316
317 /**
318 * Sets the current position in the text string which the next search will
319 * start from. Clears previous states.
320 * This method takes the argument index and sets the position in the text
321 * string accordingly without checking if the index is pointing to a
322 * valid starting point to begin searching.
323 * Search positions that may render incorrect results are highlighted in the
324 * header comments
325 * @param strsrch search iterator data struct
326 * @param position position to start next search from. If position is less
327 * than or greater than the text range for searching,
328 * an U_INDEX_OUTOFBOUNDS_ERROR will be returned
329 * @param status error status if any.
330 * @stable ICU 2.4
331 */
332 U_STABLE void U_EXPORT2 usearch_setOffset(UStringSearch *strsrch,
333 int32_t position,
334 UErrorCode *status);
335
336 /**
337 * Return the current index in the string text being searched.
338 * If the iteration has gone past the end of the text (or past the beginning
339 * for a backwards search), <tt>USEARCH_DONE</tt> is returned.
340 * @param strsrch search iterator data struct
341 * @see #USEARCH_DONE
342 * @stable ICU 2.4
343 */
344 U_STABLE int32_t U_EXPORT2 usearch_getOffset(const UStringSearch *strsrch);
345
346 /**
347 * Sets the text searching attributes located in the enum USearchAttribute
348 * with values from the enum USearchAttributeValue.
349 * <tt>USEARCH_DEFAULT</tt> can be used for all attributes for resetting.
350 * @param strsrch search iterator data struct
351 * @param attribute text attribute to be set
352 * @param value text attribute value
353 * @param status for errors if it occurs
354 * @see #usearch_getAttribute
355 * @stable ICU 2.4
356 */
357 U_STABLE void U_EXPORT2 usearch_setAttribute(UStringSearch *strsrch,
358 USearchAttribute attribute,
359 USearchAttributeValue value,
360 UErrorCode *status);
361
362 /**
363 * Gets the text searching attributes.
364 * @param strsrch search iterator data struct
365 * @param attribute text attribute to be retrieve
366 * @return text attribute value
367 * @see #usearch_setAttribute
368 * @stable ICU 2.4
369 */
370 U_STABLE USearchAttributeValue U_EXPORT2 usearch_getAttribute(
371 const UStringSearch *strsrch,
372 USearchAttribute attribute);
373
374 /**
375 * Returns the index to the match in the text string that was searched.
376 * This call returns a valid result only after a successful call to
377 * <tt>usearch_first</tt>, <tt>usearch_next</tt>, <tt>usearch_previous</tt>,
378 * or <tt>usearch_last</tt>.
379 * Just after construction, or after a searching method returns
380 * <tt>USEARCH_DONE</tt>, this method will return <tt>USEARCH_DONE</tt>.
381 * <p>
382 * Use <tt>usearch_getMatchedLength</tt> to get the matched string length.
383 * @param strsrch search iterator data struct
384 * @return index to a substring within the text string that is being
385 * searched.
386 * @see #usearch_first
387 * @see #usearch_next
388 * @see #usearch_previous
389 * @see #usearch_last
390 * @see #USEARCH_DONE
391 * @stable ICU 2.4
392 */
393 U_STABLE int32_t U_EXPORT2 usearch_getMatchedStart(
394 const UStringSearch *strsrch);
395
396 /**
397 * Returns the length of text in the string which matches the search pattern.
398 * This call returns a valid result only after a successful call to
399 * <tt>usearch_first</tt>, <tt>usearch_next</tt>, <tt>usearch_previous</tt>,
400 * or <tt>usearch_last</tt>.
401 * Just after construction, or after a searching method returns
402 * <tt>USEARCH_DONE</tt>, this method will return 0.
403 * @param strsrch search iterator data struct
404 * @return The length of the match in the string text, or 0 if there is no
405 * match currently.
406 * @see #usearch_first
407 * @see #usearch_next
408 * @see #usearch_previous
409 * @see #usearch_last
410 * @see #USEARCH_DONE
411 * @stable ICU 2.4
412 */
413 U_STABLE int32_t U_EXPORT2 usearch_getMatchedLength(
414 const UStringSearch *strsrch);
415
416 /**
417 * Returns the text that was matched by the most recent call to
418 * <tt>usearch_first</tt>, <tt>usearch_next</tt>, <tt>usearch_previous</tt>,
419 * or <tt>usearch_last</tt>.
420 * If the iterator is not pointing at a valid match (e.g. just after
421 * construction or after <tt>USEARCH_DONE</tt> has been returned, returns
422 * an empty string. If result is not large enough to store the matched text,
423 * result will be filled with the partial text and an U_BUFFER_OVERFLOW_ERROR
424 * will be returned in status. result will be null-terminated whenever
425 * possible. If the buffer fits the matched text exactly, a null-termination
426 * is not possible, then a U_STRING_NOT_TERMINATED_ERROR set in status.
427 * Pre-flighting can be either done with length = 0 or the API
428 * <tt>usearch_getMatchLength</tt>.
429 * @param strsrch search iterator data struct
430 * @param result UChar buffer to store the matched string
431 * @param resultCapacity length of the result buffer
432 * @param status error returned if result is not large enough
433 * @return exact length of the matched text, not counting the null-termination
434 * @see #usearch_first
435 * @see #usearch_next
436 * @see #usearch_previous
437 * @see #usearch_last
438 * @see #USEARCH_DONE
439 * @stable ICU 2.4
440 */
441 U_STABLE int32_t U_EXPORT2 usearch_getMatchedText(const UStringSearch *strsrch,
442 UChar *result,
443 int32_t resultCapacity,
444 UErrorCode *status);
445
446 #if !UCONFIG_NO_BREAK_ITERATION
447
448 /**
449 * Set the BreakIterator that will be used to restrict the points at which
450 * matches are detected.
451 * @param strsrch search iterator data struct
452 * @param breakiter A BreakIterator that will be used to restrict the points
453 * at which matches are detected. If a match is found, but
454 * the match's start or end index is not a boundary as
455 * determined by the <tt>BreakIterator</tt>, the match will
456 * be rejected and another will be searched for.
457 * If this parameter is <tt>NULL</tt>, no break detection is
458 * attempted.
459 * @param status for errors if it occurs
460 * @see #usearch_getBreakIterator
461 * @stable ICU 2.4
462 */
463 U_STABLE void U_EXPORT2 usearch_setBreakIterator(UStringSearch *strsrch,
464 UBreakIterator *breakiter,
465 UErrorCode *status);
466
467 /**
468 * Returns the BreakIterator that is used to restrict the points at which
469 * matches are detected. This will be the same object that was passed to the
470 * constructor or to <tt>usearch_setBreakIterator</tt>. Note that
471 * <tt>NULL</tt>
472 * is a legal value; it means that break detection should not be attempted.
473 * @param strsrch search iterator data struct
474 * @return break iterator used
475 * @see #usearch_setBreakIterator
476 * @stable ICU 2.4
477 */
478 U_STABLE const UBreakIterator * U_EXPORT2 usearch_getBreakIterator(
479 const UStringSearch *strsrch);
480
481 #endif
482
483 /**
484 * Set the string text to be searched. Text iteration will hence begin at the
485 * start of the text string. This method is useful if you want to re-use an
486 * iterator to search for the same pattern within a different body of text.
487 * @param strsrch search iterator data struct
488 * @param text new string to look for match
489 * @param textlength length of the new string, -1 for null-termination
490 * @param status for errors if it occurs. If text is NULL, or textlength is 0
491 * then an U_ILLEGAL_ARGUMENT_ERROR is returned with no change
492 * done to strsrch.
493 * @see #usearch_getText
494 * @stable ICU 2.4
495 */
496 U_STABLE void U_EXPORT2 usearch_setText( UStringSearch *strsrch,
497 const UChar *text,
498 int32_t textlength,
499 UErrorCode *status);
500
501 /**
502 * Return the string text to be searched.
503 * @param strsrch search iterator data struct
504 * @param length returned string text length
505 * @return string text
506 * @see #usearch_setText
507 * @stable ICU 2.4
508 */
509 U_STABLE const UChar * U_EXPORT2 usearch_getText(const UStringSearch *strsrch,
510 int32_t *length);
511
512 /**
513 * Gets the collator used for the language rules.
514 * <p>
515 * Deleting the returned <tt>UCollator</tt> before calling
516 * <tt>usearch_close</tt> would cause the string search to fail.
517 * <tt>usearch_close</tt> will delete the collator if this search owns it.
518 * @param strsrch search iterator data struct
519 * @return collator
520 * @stable ICU 2.4
521 */
522 U_STABLE UCollator * U_EXPORT2 usearch_getCollator(
523 const UStringSearch *strsrch);
524
525 /**
526 * Sets the collator used for the language rules. User retains the ownership
527 * of this collator, thus the responsibility of deletion lies with the user.
528 * This method causes internal data such as Boyer-Moore shift tables to
529 * be recalculated, but the iterator's position is unchanged.
530 * @param strsrch search iterator data struct
531 * @param collator to be used
532 * @param status for errors if it occurs
533 * @stable ICU 2.4
534 */
535 U_STABLE void U_EXPORT2 usearch_setCollator( UStringSearch *strsrch,
536 const UCollator *collator,
537 UErrorCode *status);
538
539 /**
540 * Sets the pattern used for matching.
541 * Internal data like the Boyer Moore table will be recalculated, but the
542 * iterator's position is unchanged.
543 * @param strsrch search iterator data struct
544 * @param pattern string
545 * @param patternlength pattern length, -1 for null-terminated string
546 * @param status for errors if it occurs. If text is NULL, or textlength is 0
547 * then an U_ILLEGAL_ARGUMENT_ERROR is returned with no change
548 * done to strsrch.
549 * @stable ICU 2.4
550 */
551 U_STABLE void U_EXPORT2 usearch_setPattern( UStringSearch *strsrch,
552 const UChar *pattern,
553 int32_t patternlength,
554 UErrorCode *status);
555
556 /**
557 * Gets the search pattern
558 * @param strsrch search iterator data struct
559 * @param length return length of the pattern, -1 indicates that the pattern
560 * is null-terminated
561 * @return pattern string
562 * @stable ICU 2.4
563 */
564 U_STABLE const UChar * U_EXPORT2 usearch_getPattern(
565 const UStringSearch *strsrch,
566 int32_t *length);
567
568 /* methods ------------------------------------------------------------- */
569
570 /**
571 * Returns the first index at which the string text matches the search
572 * pattern.
573 * The iterator is adjusted so that its current index (as returned by
574 * <tt>usearch_getOffset</tt>) is the match position if one was found.
575 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
576 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>.
577 * @param strsrch search iterator data struct
578 * @param status for errors if it occurs
579 * @return The character index of the first match, or
580 * <tt>USEARCH_DONE</tt> if there are no matches.
581 * @see #usearch_getOffset
582 * @see #USEARCH_DONE
583 * @stable ICU 2.4
584 */
585 U_STABLE int32_t U_EXPORT2 usearch_first(UStringSearch *strsrch,
586 UErrorCode *status);
587
588 /**
589 * Returns the first index equal or greater than <tt>position</tt> at which
590 * the string text
591 * matches the search pattern. The iterator is adjusted so that its current
592 * index (as returned by <tt>usearch_getOffset</tt>) is the match position if
593 * one was found.
594 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
595 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>
596 * <p>
597 * Search positions that may render incorrect results are highlighted in the
598 * header comments. If position is less than or greater than the text range
599 * for searching, an U_INDEX_OUTOFBOUNDS_ERROR will be returned
600 * @param strsrch search iterator data struct
601 * @param position to start the search at
602 * @param status for errors if it occurs
603 * @return The character index of the first match following <tt>pos</tt>,
604 * or <tt>USEARCH_DONE</tt> if there are no matches.
605 * @see #usearch_getOffset
606 * @see #USEARCH_DONE
607 * @stable ICU 2.4
608 */
609 U_STABLE int32_t U_EXPORT2 usearch_following(UStringSearch *strsrch,
610 int32_t position,
611 UErrorCode *status);
612
613 /**
614 * Returns the last index in the target text at which it matches the search
615 * pattern. The iterator is adjusted so that its current
616 * index (as returned by <tt>usearch_getOffset</tt>) is the match position if
617 * one was found.
618 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
619 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>.
620 * @param strsrch search iterator data struct
621 * @param status for errors if it occurs
622 * @return The index of the first match, or <tt>USEARCH_DONE</tt> if there
623 * are no matches.
624 * @see #usearch_getOffset
625 * @see #USEARCH_DONE
626 * @stable ICU 2.4
627 */
628 U_STABLE int32_t U_EXPORT2 usearch_last(UStringSearch *strsrch,
629 UErrorCode *status);
630
631 /**
632 * Returns the first index less than <tt>position</tt> at which the string text
633 * matches the search pattern. The iterator is adjusted so that its current
634 * index (as returned by <tt>usearch_getOffset</tt>) is the match position if
635 * one was found.
636 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
637 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>
638 * <p>
639 * Search positions that may render incorrect results are highlighted in the
640 * header comments. If position is less than or greater than the text range
641 * for searching, an U_INDEX_OUTOFBOUNDS_ERROR will be returned.
642 * <p>
643 * When <tt>USEARCH_OVERLAP</tt> option is off, the last index of the
644 * result match is always less than <tt>position</tt>.
645 * When <tt>USERARCH_OVERLAP</tt> is on, the result match may span across
646 * <tt>position</tt>.
647 * @param strsrch search iterator data struct
648 * @param position index position the search is to begin at
649 * @param status for errors if it occurs
650 * @return The character index of the first match preceding <tt>pos</tt>,
651 * or <tt>USEARCH_DONE</tt> if there are no matches.
652 * @see #usearch_getOffset
653 * @see #USEARCH_DONE
654 * @stable ICU 2.4
655 */
656 U_STABLE int32_t U_EXPORT2 usearch_preceding(UStringSearch *strsrch,
657 int32_t position,
658 UErrorCode *status);
659
660 /**
661 * Returns the index of the next point at which the string text matches the
662 * search pattern, starting from the current position.
663 * The iterator is adjusted so that its current
664 * index (as returned by <tt>usearch_getOffset</tt>) is the match position if
665 * one was found.
666 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
667 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>
668 * @param strsrch search iterator data struct
669 * @param status for errors if it occurs
670 * @return The index of the next match after the current position, or
671 * <tt>USEARCH_DONE</tt> if there are no more matches.
672 * @see #usearch_first
673 * @see #usearch_getOffset
674 * @see #USEARCH_DONE
675 * @stable ICU 2.4
676 */
677 U_STABLE int32_t U_EXPORT2 usearch_next(UStringSearch *strsrch,
678 UErrorCode *status);
679
680 /**
681 * Returns the index of the previous point at which the string text matches
682 * the search pattern, starting at the current position.
683 * The iterator is adjusted so that its current
684 * index (as returned by <tt>usearch_getOffset</tt>) is the match position if
685 * one was found.
686 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
687 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>
688 * @param strsrch search iterator data struct
689 * @param status for errors if it occurs
690 * @return The index of the previous match before the current position,
691 * or <tt>USEARCH_DONE</tt> if there are no more matches.
692 * @see #usearch_last
693 * @see #usearch_getOffset
694 * @see #USEARCH_DONE
695 * @stable ICU 2.4
696 */
697 U_STABLE int32_t U_EXPORT2 usearch_previous(UStringSearch *strsrch,
698 UErrorCode *status);
699
700 /**
701 * Reset the iteration.
702 * Search will begin at the start of the text string if a forward iteration
703 * is initiated before a backwards iteration. Otherwise if a backwards
704 * iteration is initiated before a forwards iteration, the search will begin
705 * at the end of the text string.
706 * @param strsrch search iterator data struct
707 * @see #usearch_first
708 * @stable ICU 2.4
709 */
710 U_STABLE void U_EXPORT2 usearch_reset(UStringSearch *strsrch);
711
712 #ifndef U_HIDE_INTERNAL_API
713 /**
714 * Simple forward search for the pattern, starting at a specified index,
715 * and using using a default set search options.
716 *
717 * This is an experimental function, and is not an official part of the
718 * ICU API.
719 *
720 * The collator options, such as UCOL_STRENGTH and UCOL_NORMALIZTION, are honored.
721 *
722 * The UStringSearch options USEARCH_CANONICAL_MATCH, USEARCH_OVERLAP and
723 * any Break Iterator are ignored.
724 *
725 * Matches obey the following constraints:
726 *
727 * Characters at the start or end positions of a match that are ignorable
728 * for collation are not included as part of the match, unless they
729 * are part of a combining sequence, as described below.
730 *
731 * A match will not include a partial combining sequence. Combining
732 * character sequences are considered to be inseperable units,
733 * and either match the pattern completely, or are considered to not match
734 * at all. Thus, for example, an A followed a combining accent mark will
735 * not be found when searching for a plain (unaccented) A. (unless
736 * the collation strength has been set to ignore all accents).
737 *
738 * When beginning a search, the initial starting position, startIdx,
739 * is assumed to be an acceptable match boundary with respect to
740 * combining characters. A combining sequence that spans across the
741 * starting point will not supress a match beginning at startIdx.
742 *
743 * Characters that expand to multiple collation elements
744 * (German sharp-S becoming 'ss', or the composed forms of accented
745 * characters, for example) also must match completely.
746 * Searching for a single 's' in a string containing only a sharp-s will
747 * find no match.
748 *
749 *
750 * @param strsrch the UStringSearch struct, which references both
751 * the text to be searched and the pattern being sought.
752 * @param startIdx The index into the text to begin the search.
753 * @param matchStart An out parameter, the starting index of the matched text.
754 * This parameter may be NULL.
755 * A value of -1 will be returned if no match was found.
756 * @param matchLimit Out parameter, the index of the first position following the matched text.
757 * The matchLimit will be at a suitable position for beginning a subsequent search
758 * in the input text.
759 * This parameter may be NULL.
760 * A value of -1 will be returned if no match was found.
761 *
762 * @param status Report any errors. Note that no match found is not an error.
763 * @return TRUE if a match was found, FALSE otherwise.
764 *
765 * @internal
766 */
767 U_INTERNAL UBool U_EXPORT2 usearch_search(UStringSearch *strsrch,
768 int32_t startIdx,
769 int32_t *matchStart,
770 int32_t *matchLimit,
771 UErrorCode *status);
772
773 /**
774 * Simple backwards search for the pattern, starting at a specified index,
775 * and using using a default set search options.
776 *
777 * This is an experimental function, and is not an official part of the
778 * ICU API.
779 *
780 * The collator options, such as UCOL_STRENGTH and UCOL_NORMALIZTION, are honored.
781 *
782 * The UStringSearch options USEARCH_CANONICAL_MATCH, USEARCH_OVERLAP and
783 * any Break Iterator are ignored.
784 *
785 * Matches obey the following constraints:
786 *
787 * Characters at the start or end positions of a match that are ignorable
788 * for collation are not included as part of the match, unless they
789 * are part of a combining sequence, as described below.
790 *
791 * A match will not include a partial combining sequence. Combining
792 * character sequences are considered to be inseperable units,
793 * and either match the pattern completely, or are considered to not match
794 * at all. Thus, for example, an A followed a combining accent mark will
795 * not be found when searching for a plain (unaccented) A. (unless
796 * the collation strength has been set to ignore all accents).
797 *
798 * When beginning a search, the initial starting position, startIdx,
799 * is assumed to be an acceptable match boundary with respect to
800 * combining characters. A combining sequence that spans across the
801 * starting point will not supress a match beginning at startIdx.
802 *
803 * Characters that expand to multiple collation elements
804 * (German sharp-S becoming 'ss', or the composed forms of accented
805 * characters, for example) also must match completely.
806 * Searching for a single 's' in a string containing only a sharp-s will
807 * find no match.
808 *
809 *
810 * @param strsrch the UStringSearch struct, which references both
811 * the text to be searched and the pattern being sought.
812 * @param startIdx The index into the text to begin the search.
813 * @param matchStart An out parameter, the starting index of the matched text.
814 * This parameter may be NULL.
815 * A value of -1 will be returned if no match was found.
816 * @param matchLimit Out parameter, the index of the first position following the matched text.
817 * The matchLimit will be at a suitable position for beginning a subsequent search
818 * in the input text.
819 * This parameter may be NULL.
820 * A value of -1 will be returned if no match was found.
821 *
822 * @param status Report any errors. Note that no match found is not an error.
823 * @return TRUE if a match was found, FALSE otherwise.
824 *
825 * @internal
826 */
827 U_INTERNAL UBool U_EXPORT2 usearch_searchBackwards(UStringSearch *strsrch,
828 int32_t startIdx,
829 int32_t *matchStart,
830 int32_t *matchLimit,
831 UErrorCode *status);
832 #endif /* U_HIDE_INTERNAL_API */
833
834 #endif /* #if !UCONFIG_NO_COLLATION && !UCONFIG_NO_BREAK_ITERATION */
835
836 #endif

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial