← Back to branch summary

~alinuxninja/nginx-edge/trunk

« back to all changes in this revision

Viewing changes to debian/modules/ngx_pagespeed/psol/include/third_party/icu/source/i18n/unicode/usearch.h

  • Committer: Vivian
  • Date: 2015-12-04 18:20:11 UTC
  • Revision ID: git-v1:a36f2bc32e884f7473b3a47040e5411306144d7d
* Do not extract psol.tar.gz

Show diffs side-by-side

added added

removed removed

Lines of Context:
debian/modules/ngx_pagespeed/psol/include/third_party/icu/source/i18n/unicode/usearch.h
1
 
/*
2
 
**********************************************************************
3
 
*   Copyright (C) 2001-2010 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 greater than <tt>position</tt> at which the string 
590
 
* 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
 
* @param strsrch search iterator data struct
643
 
* @param position index position the search is to begin at
644
 
* @param status for errors if it occurs
645
 
* @return The character index of the first match preceding <tt>pos</tt>,
646
 
*         or <tt>USEARCH_DONE</tt> if there are no matches.
647
 
* @see #usearch_getOffset
648
 
* @see #USEARCH_DONE
649
 
* @stable ICU 2.4
650
 
*/
651
 
U_STABLE int32_t U_EXPORT2 usearch_preceding(UStringSearch *strsrch, 
652
 
                                               int32_t    position, 
653
 
                                               UErrorCode    *status);
654
 
    
655
 
/**
656
 
* Returns the index of the next point at which the string text matches the
657
 
* search pattern, starting from the current position.
658
 
* The iterator is adjusted so that its current 
659
 
* index (as returned by <tt>usearch_getOffset</tt>) is the match position if 
660
 
* one was found.
661
 
* If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
662
 
* the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>
663
 
* @param strsrch search iterator data struct
664
 
* @param status for errors if it occurs
665
 
* @return The index of the next match after the current position, or 
666
 
*         <tt>USEARCH_DONE</tt> if there are no more matches.
667
 
* @see #usearch_first
668
 
* @see #usearch_getOffset
669
 
* @see #USEARCH_DONE
670
 
* @stable ICU 2.4
671
 
*/
672
 
U_STABLE int32_t U_EXPORT2 usearch_next(UStringSearch *strsrch, 
673
 
                                          UErrorCode    *status);
674
 
 
675
 
/**
676
 
* Returns the index of the previous point at which the string text matches
677
 
* the search pattern, starting at the current position.
678
 
* The iterator is adjusted so that its current 
679
 
* index (as returned by <tt>usearch_getOffset</tt>) is the match position if 
680
 
* one was found.
681
 
* If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
682
 
* the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>
683
 
* @param strsrch search iterator data struct
684
 
* @param status for errors if it occurs
685
 
* @return The index of the previous match before the current position,
686
 
*         or <tt>USEARCH_DONE</tt> if there are no more matches.
687
 
* @see #usearch_last
688
 
* @see #usearch_getOffset
689
 
* @see #USEARCH_DONE
690
 
* @stable ICU 2.4
691
 
*/
692
 
U_STABLE int32_t U_EXPORT2 usearch_previous(UStringSearch *strsrch, 
693
 
                                              UErrorCode    *status);
694
 
    
695
 
/** 
696
 
* Reset the iteration.
697
 
* Search will begin at the start of the text string if a forward iteration 
698
 
* is initiated before a backwards iteration. Otherwise if a backwards 
699
 
* iteration is initiated before a forwards iteration, the search will begin
700
 
* at the end of the text string.
701
 
* @param strsrch search iterator data struct
702
 
* @see #usearch_first
703
 
* @stable ICU 2.4
704
 
*/
705
 
U_STABLE void U_EXPORT2 usearch_reset(UStringSearch *strsrch);
706
 
 
707
 
/**
708
 
  *  Simple forward search for the pattern, starting at a specified index,
709
 
  *     and using using a default set search options.
710
 
  *
711
 
  *  This is an experimental function, and is not an official part of the
712
 
  *      ICU API.
713
 
  *
714
 
  *  The collator options, such as UCOL_STRENGTH and UCOL_NORMALIZTION, are honored.
715
 
  *
716
 
  *  The UStringSearch options USEARCH_CANONICAL_MATCH, USEARCH_OVERLAP and
717
 
  *  any Break Iterator are ignored.
718
 
  *
719
 
  *  Matches obey the following constraints:
720
 
  *
721
 
  *      Characters at the start or end positions of a match that are ignorable
722
 
  *      for collation are not included as part of the match, unless they
723
 
  *      are part of a combining sequence, as described below.
724
 
  *
725
 
  *      A match will not include a partial combining sequence.  Combining
726
 
  *      character sequences  are considered to be  inseperable units,
727
 
  *      and either match the pattern completely, or are considered to not match
728
 
  *      at all.  Thus, for example, an A followed a combining accent mark will 
729
 
  *      not be found when searching for a plain (unaccented) A.   (unless
730
 
  *      the collation strength has been set to ignore all accents).
731
 
  *
732
 
  *      When beginning a search, the initial starting position, startIdx,
733
 
  *      is assumed to be an acceptable match boundary with respect to
734
 
  *      combining characters.  A combining sequence that spans across the
735
 
  *      starting point will not supress a match beginning at startIdx.
736
 
  *
737
 
  *      Characters that expand to multiple collation elements
738
 
  *      (German sharp-S becoming 'ss', or the composed forms of accented
739
 
  *      characters, for example) also must match completely.
740
 
  *      Searching for a single 's' in a string containing only a sharp-s will 
741
 
  *      find no match.
742
 
  *
743
 
  *
744
 
  *  @param strsrch    the UStringSearch struct, which references both
745
 
  *                    the text to be searched  and the pattern being sought.
746
 
  *  @param startIdx   The index into the text to begin the search.
747
 
  *  @param matchStart An out parameter, the starting index of the matched text.
748
 
  *                    This parameter may be NULL.
749
 
  *                    A value of -1 will be returned if no match was found.
750
 
  *  @param matchLimit Out parameter, the index of the first position following the matched text.
751
 
  *                    The matchLimit will be at a suitable position for beginning a subsequent search
752
 
  *                    in the input text.
753
 
  *                    This parameter may be NULL.
754
 
  *                    A value of -1 will be returned if no match was found.
755
 
  *          
756
 
  *  @param status     Report any errors.  Note that no match found is not an error.
757
 
  *  @return           TRUE if a match was found, FALSE otherwise.
758
 
  *
759
 
  *  @internal
760
 
  */
761
 
U_INTERNAL UBool U_EXPORT2 usearch_search(UStringSearch *strsrch,
762
 
                                          int32_t        startIdx,
763
 
                                          int32_t        *matchStart,
764
 
                                          int32_t        *matchLimit,
765
 
                                          UErrorCode     *status);
766
 
 
767
 
/**
768
 
  *  Simple backwards search for the pattern, starting at a specified index,
769
 
  *     and using using a default set search options.
770
 
  *
771
 
  *  This is an experimental function, and is not an official part of the
772
 
  *      ICU API.
773
 
  *
774
 
  *  The collator options, such as UCOL_STRENGTH and UCOL_NORMALIZTION, are honored.
775
 
  *
776
 
  *  The UStringSearch options USEARCH_CANONICAL_MATCH, USEARCH_OVERLAP and
777
 
  *  any Break Iterator are ignored.
778
 
  *
779
 
  *  Matches obey the following constraints:
780
 
  *
781
 
  *      Characters at the start or end positions of a match that are ignorable
782
 
  *      for collation are not included as part of the match, unless they
783
 
  *      are part of a combining sequence, as described below.
784
 
  *
785
 
  *      A match will not include a partial combining sequence.  Combining
786
 
  *      character sequences  are considered to be  inseperable units,
787
 
  *      and either match the pattern completely, or are considered to not match
788
 
  *      at all.  Thus, for example, an A followed a combining accent mark will 
789
 
  *      not be found when searching for a plain (unaccented) A.   (unless
790
 
  *      the collation strength has been set to ignore all accents).
791
 
  *
792
 
  *      When beginning a search, the initial starting position, startIdx,
793
 
  *      is assumed to be an acceptable match boundary with respect to
794
 
  *      combining characters.  A combining sequence that spans across the
795
 
  *      starting point will not supress a match beginning at startIdx.
796
 
  *
797
 
  *      Characters that expand to multiple collation elements
798
 
  *      (German sharp-S becoming 'ss', or the composed forms of accented
799
 
  *      characters, for example) also must match completely.
800
 
  *      Searching for a single 's' in a string containing only a sharp-s will 
801
 
  *      find no match.
802
 
  *
803
 
  *
804
 
  *  @param strsrch    the UStringSearch struct, which references both
805
 
  *                    the text to be searched  and the pattern being sought.
806
 
  *  @param startIdx   The index into the text to begin the search.
807
 
  *  @param matchStart An out parameter, the starting index of the matched text.
808
 
  *                    This parameter may be NULL.
809
 
  *                    A value of -1 will be returned if no match was found.
810
 
  *  @param matchLimit Out parameter, the index of the first position following the matched text.
811
 
  *                    The matchLimit will be at a suitable position for beginning a subsequent search
812
 
  *                    in the input text.
813
 
  *                    This parameter may be NULL.
814
 
  *                    A value of -1 will be returned if no match was found.
815
 
  *          
816
 
  *  @param status     Report any errors.  Note that no match found is not an error.
817
 
  *  @return           TRUE if a match was found, FALSE otherwise.
818
 
  *
819
 
  *  @internal
820
 
  */
821
 
U_INTERNAL UBool U_EXPORT2 usearch_searchBackwards(UStringSearch *strsrch,
822
 
                                                   int32_t        startIdx,
823
 
                                                   int32_t        *matchStart,
824
 
                                                   int32_t        *matchLimit,
825
 
                                                   UErrorCode     *status);
826
 
 
827
 
#endif /* #if !UCONFIG_NO_COLLATION  && !UCONFIG_NO_BREAK_ITERATION */
828
 
 
829
 
#endif