#include "unicode/utypes.h"
#include "unicode/ucol.h"
#include "unicode/ucoleitr.h"
#include "unicode/ubrk.h"
Go to the source code of this file.
Defines | |
#define | USEARCH_DONE -1 |
DONE is returned by previous() and next() after all valid matches have been returned, and by first() and last() if there are no matches at all. | |
Typedefs | |
typedef UStringSearch | UStringSearch |
Data structure for searching. | |
Enumerations | |
enum | USearchAttribute { USEARCH_OVERLAP, USEARCH_CANONICAL_MATCH, USEARCH_ATTRIBUTE_COUNT } |
enum | USearchAttributeValue { USEARCH_DEFAULT = -1, USEARCH_OFF, USEARCH_ON, USEARCH_ATTRIBUTE_VALUE_COUNT } |
Functions | |
UStringSearch * | usearch_open (const UChar *pattern, int32_t patternlength, const UChar *text, int32_t textlength, const char *locale, UBreakIterator *breakiter, UErrorCode *status) |
Creating a search iterator data struct using the argument locale language rule set. | |
UStringSearch * | usearch_openFromCollator (const UChar *pattern, int32_t patternlength, const UChar *text, int32_t textlength, const UCollator *collator, UBreakIterator *breakiter, UErrorCode *status) |
Creating a search iterator data struct using the argument collator language rule set. | |
void | usearch_close (UStringSearch *searchiter) |
Destroying and cleaning up the search iterator data struct. | |
void | usearch_setOffset (UStringSearch *strsrch, int32_t position, UErrorCode *status) |
Sets the current position in the text string which the next search will start from. | |
int32_t | usearch_getOffset (const UStringSearch *strsrch) |
Return the current index in the string text being searched. | |
void | usearch_setAttribute (UStringSearch *strsrch, USearchAttribute attribute, USearchAttributeValue value, UErrorCode *status) |
Sets the text searching attributes located in the enum USearchAttribute with values from the enum USearchAttributeValue. | |
USearchAttributeValue | usearch_getAttribute (const UStringSearch *strsrch, USearchAttribute attribute) |
Gets the text searching attributes. | |
int32_t | usearch_getMatchedStart (const UStringSearch *strsrch) |
Returns the index to the match in the text string that was searched. | |
int32_t | usearch_getMatchedLength (const UStringSearch *strsrch) |
Returns the length of text in the string which matches the search pattern. | |
int32_t | usearch_getMatchedText (const UStringSearch *strsrch, UChar *result, int32_t resultCapacity, UErrorCode *status) |
Returns the text that was matched by the most recent call to usearch_first , usearch_next , usearch_previous , or usearch_last . | |
void | usearch_setBreakIterator (UStringSearch *strsrch, UBreakIterator *breakiter, UErrorCode *status) |
Set the BreakIterator that will be used to restrict the points at which matches are detected. | |
const UBreakIterator * | usearch_getBreakIterator (const UStringSearch *strsrch) |
Returns the BreakIterator that is used to restrict the points at which matches are detected. | |
void | usearch_setText (UStringSearch *strsrch, const UChar *text, int32_t textlength, UErrorCode *status) |
Set the string text to be searched. | |
const UChar * | usearch_getText (const UStringSearch *strsrch, int32_t *length) |
Return the string text to be searched. | |
UCollator * | usearch_getCollator (const UStringSearch *strsrch) |
Gets the collator used for the language rules. | |
void | usearch_setCollator (UStringSearch *strsrch, const UCollator *collator, UErrorCode *status) |
Sets the collator used for the language rules. | |
void | usearch_setPattern (UStringSearch *strsrch, const UChar *pattern, int32_t patternlength, UErrorCode *status) |
Sets the pattern used for matching. | |
const UChar * | usearch_getPattern (const UStringSearch *strsrch, int32_t *length) |
Gets the search pattern. | |
int32_t | usearch_first (UStringSearch *strsrch, UErrorCode *status) |
Returns the first index at which the string text matches the search pattern. | |
int32_t | usearch_following (UStringSearch *strsrch, int32_t position, UErrorCode *status) |
Returns the first index greater than position at which the string text matches the search pattern. | |
int32_t | usearch_last (UStringSearch *strsrch, UErrorCode *status) |
Returns the last index in the target text at which it matches the search pattern. | |
int32_t | usearch_preceding (UStringSearch *strsrch, int32_t position, UErrorCode *status) |
Returns the first index less than position at which the string text matches the search pattern. | |
int32_t | usearch_next (UStringSearch *strsrch, UErrorCode *status) |
Returns the index of the next point at which the string text matches the search pattern, starting from the current position. | |
int32_t | usearch_previous (UStringSearch *strsrch, UErrorCode *status) |
Returns the index of the previous point at which the string text matches the search pattern, starting at the current position. | |
void | usearch_reset (UStringSearch *strsrch) |
Reset the iteration. |
C Apis for an engine that provides language-sensitive text searching based on the comparison rules defined in a UCollator
data struct, see ucol.h
. This ensures that language eccentricity can be handled, e.g. for the German collator, characters ß and SS will be matched if case is chosen to be ignored. See the "ICU Collation Design Document" for more information.
The algorithm implemented is a modified form of the Boyer Moore's search. For more information see "Efficient Text Searching in Java", published in Java Report in February, 1999, for further information on the algorithm.
There are 2 match options for selection:
Let S' be the sub-string of a text string S between the offsets start and end <start, end>.
A pattern string P matches a text string S at the offsets <start, end> if
option 1. Some canonical equivalent of P matches some canonical equivalent of S' option 2. P matches S' and if P starts or ends with a combining mark, there exists no non-ignorable combining mark before or after S' in S respectively.Option 2. will be the default.
This search has APIs similar to that of other text iteration mechanisms such as the break iterators in ubrk.h
. Using these APIs, it is easy to scan through text looking for all occurances of a given pattern. This search iterator allows changing of direction by calling a reset
followed by a next
or previous
. Though a direction change can occur without calling reset
first, this operation comes with some speed penalty. Generally, match results in the forward direction will match the result matches in the backwards direction in the reverse order
usearch.h
provides APIs to specify the starting position within the text string to be searched, e.g. usearch_setOffset
, usearch_preceding
and usearch_following
. Since the starting position will be set as it is specified, please take note that there are some dangerous positions which the search may render incorrect results:
A breakiterator can be used if only matches at logical breaks are desired. Using a breakiterator will only give you results that exactly matches the boundaries given by the breakiterator. For instance the pattern "e" will not be found in the string "\u00e9" if a character break iterator is used.
Options are provided to handle overlapping matches. E.g. In English, overlapping matches produces the result 0 and 2 for the pattern "abab" in the text "ababab", where else mutually exclusive matches only produce the result of 0.
Though collator attributes will be taken into consideration while performing matches, there are no APIs here for setting and getting the attributes. These attributes can be set by getting the collator from usearch_getCollator
and using the APIs in ucol.h
. Lastly to update String Search to the new collator attributes, usearch_reset() has to be called.
Restriction:
Currently there are no composite characters that consists of a character with combining class > 0 before a character with combining class == 0. However, if such a character exists in the future, the search mechanism does not guarantee the results for option 1.
Example of use:
char *tgtstr = "The quick brown fox jumped over the lazy fox";
char *patstr = "fox";
UChar target[64];
UChar pattern[16];
UErrorCode status = U_ZERO_ERROR;
u_uastrcpy(target, tgtstr);
u_uastrcpy(pattern, patstr);
UStringSearch *search = usearch_open(pattern, -1, target, -1, "en_US",
NULL, &status);
if (U_SUCCESS(status)) {
for (int pos = usearch_first(search, &status);
pos != USEARCH_DONE;
pos = usearch_next(search, &status))
{
printf("Found match at %d pos, length is %d\n", pos,
usearch_getMatchLength(search));
}
}
usearch_close(search);
Definition in file usearch.h.
|
DONE is returned by previous() and next() after all valid matches have been returned, and by first() and last() if there are no matches at all.
|
|
Data structure for searching.
|
|
|
|
|
|
Destroying and cleaning up the search iterator data struct.
If a collator is created in
|
|
Returns the first index at which the string text matches the search pattern.
The iterator is adjusted so that its current index (as returned by
|
|
Returns the first index greater than
The iterator is adjusted so that its current index (as returned by Search positions that may render incorrect results are highlighted in the header comments. If position is less than or greater than the text range for searching, an U_INDEX_OUTOFBOUNDS_ERROR will be returned
|
|
Gets the text searching attributes.
|
|
Returns the BreakIterator that is used to restrict the points at which matches are detected.
This will be the same object that was passed to the constructor or to
|
|
Gets the collator used for the language rules.
Deleting the returned
|
|
Returns the length of text in the string which matches the search pattern.
This call returns a valid result only after a successful call to
|
|
Returns the index to the match in the text string that was searched.
This call returns a valid result only after a successful call to
Use
|
|
Returns the text that was matched by the most recent call to
If the iterator is not pointing at a valid match (e.g. just after construction or after
|
|
Return the current index in the string text being searched.
If the iteration has gone past the end of the text (or past the beginning for a backwards search),
|
|
Gets the search pattern.
|
|
Return the string text to be searched.
|
|
Returns the last index in the target text at which it matches the search pattern.
The iterator is adjusted so that its current index (as returned by
|
|
Returns the index of the next point at which the string text matches the search pattern, starting from the current position.
The iterator is adjusted so that its current index (as returned by
|
|
Creating a search iterator data struct using the argument locale language rule set.
A collator will be created in the process, which will be owned by this search and will be deleted in
|
|
Creating a search iterator data struct using the argument collator language rule set. Note, user retains the ownership of this collator, thus the responsibility of deletion lies with the user. NOTE: string search cannot be instantiated from a collator that has collate digits as numbers (CODAN) turned on.
|
|
Returns the first index less than
The iterator is adjusted so that its current index (as returned by Search positions that may render incorrect results are highlighted in the header comments. If position is less than or greater than the text range for searching, an U_INDEX_OUTOFBOUNDS_ERROR will be returned
|
|
Returns the index of the previous point at which the string text matches the search pattern, starting at the current position.
The iterator is adjusted so that its current index (as returned by
|
|
Reset the iteration. Search will begin at the start of the text string if a forward iteration is initiated before a backwards iteration. Otherwise if a backwards iteration is initiated before a forwards iteration, the search will begin at the end of the text string.
|
|
Sets the text searching attributes located in the enum USearchAttribute with values from the enum USearchAttributeValue.
|
|
Set the BreakIterator that will be used to restrict the points at which matches are detected.
|
|
Sets the collator used for the language rules. User retains the ownership of this collator, thus the responsibility of deletion lies with the user. This method causes internal data such as Boyer-Moore shift tables to be recalculated, but the iterator's position is unchanged.
|
|
Sets the current position in the text string which the next search will start from. Clears previous states. This method takes the argument index and sets the position in the text string accordingly without checking if the index is pointing to a valid starting point to begin searching. Search positions that may render incorrect results are highlighted in the header comments
|
|
Sets the pattern used for matching. Internal data like the Boyer Moore table will be recalculated, but the iterator's position is unchanged.
|
|
Set the string text to be searched. Text iteration will hence begin at the start of the text string. This method is useful if you want to re-use an iterator to search for the same pattern within a different body of text.
|