Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Search  

usearch.h File Reference

#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. More...


Typedefs

typedef UStringSearch UStringSearch

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

U_CAPI UStringSearch *U_EXPORT2 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. More...

U_CAPI UStringSearch *U_EXPORT2 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. More...

U_CAPI void U_EXPORT2 usearch_close (UStringSearch *strsrch)
 Destroying and cleaning up the search iterator data struct. More...

U_CAPI void U_EXPORT2 usearch_setOffset (UStringSearch *strsrch, int32_t position, UErrorCode *status)
 Sets the current position in the text string which the next search will start from. More...

U_CAPI int32_t U_EXPORT2 usearch_getOffset (const UStringSearch *strsrch)
 Return the current index in the string text being searched. More...

U_CAPI void U_EXPORT2 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. More...

U_CAPI USearchAttributeValue
U_EXPORT2 
usearch_getAttribute (const UStringSearch *strsrch, USearchAttribute attribute)
 Gets the text searching attributes. More...

U_CAPI int32_t U_EXPORT2 usearch_getMatchedStart (const UStringSearch *strsrch)
 Returns the index to the match in the text string that was searched. More...

U_CAPI int32_t U_EXPORT2 usearch_getMatchedLength (const UStringSearch *strsrch)
 Returns the length of text in the string which matches the search pattern. More...

U_CAPI int32_t U_EXPORT2 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. More...

U_CAPI void U_EXPORT2 usearch_setBreakIterator (UStringSearch *strsrch, UBreakIterator *breakiter, UErrorCode *status)
 Set the BreakIterator that will be used to restrict the points at which matches are detected. More...

U_CAPI const UBreakIterator
*U_EXPORT2 
usearch_getBreakIterator (const UStringSearch *strsrch)
 Returns the BreakIterator that is used to restrict the points at which matches are detected. More...

U_CAPI void U_EXPORT2 usearch_setText (UStringSearch *strsrch, const UChar *text, int32_t textlength, UErrorCode *status)
 Set the string text to be searched. More...

U_CAPI const UChar *U_EXPORT2 usearch_getText (const UStringSearch *strsrch, int32_t *length)
 Return the string text to be searched. More...

U_CAPI UCollator *U_EXPORT2 usearch_getCollator (const UStringSearch *strsrch)
 Gets the collator used for the language rules. More...

U_CAPI void U_EXPORT2 usearch_setCollator (UStringSearch *strsrch, const UCollator *collator, UErrorCode *status)
 Sets the collator used for the language rules. More...

U_CAPI void U_EXPORT2 usearch_setPattern (UStringSearch *strsrch, const UChar *pattern, int32_t patternlength, UErrorCode *status)
 Sets the pattern used for matching. More...

U_CAPI const UChar *U_EXPORT2 usearch_getPattern (const UStringSearch *strsrch, int32_t *length)
 Gets the search pattern. More...

U_CAPI int32_t U_EXPORT2 usearch_first (UStringSearch *strsrch, UErrorCode *status)
 Returns the first index at which the string text matches the search pattern. More...

U_CAPI int32_t U_EXPORT2 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. More...

U_CAPI int32_t U_EXPORT2 usearch_last (UStringSearch *strsrch, UErrorCode *status)
 Returns the last index in the target text at which it matches the search pattern. More...

U_CAPI int32_t U_EXPORT2 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. More...

U_CAPI int32_t U_EXPORT2 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. More...

U_CAPI int32_t U_EXPORT2 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. More...

U_CAPI void U_EXPORT2 usearch_reset (UStringSearch *strsrch)
 Reset the iteration. More...


Define Documentation

#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.

Definition at line 129 of file usearch.h.


Typedef Documentation

typedef struct UStringSearch UStringSearch
 

Definition at line 135 of file usearch.h.


Enumeration Type Documentation

enum USearchAttribute
 

Enumeration values:
USEARCH_OVERLAP  Option for overlapping matches.
USEARCH_CANONICAL_MATCH  Option for canonical matches.

option 1 in header documentation. The default value will be USEARCH_OFF

USEARCH_ATTRIBUTE_COUNT 

Definition at line 137 of file usearch.h.

enum USearchAttributeValue
 

Enumeration values:
USEARCH_DEFAULT  default value for any USearchAttribute.
USEARCH_OFF  value for USEARCH_OVERLAP and USEARCH_CANONICAL_MATCH.
USEARCH_ON  value for USEARCH_OVERLAP and USEARCH_CANONICAL_MATCH.
USEARCH_ATTRIBUTE_VALUE_COUNT 

Definition at line 148 of file usearch.h.


Function Documentation

U_CAPI void U_EXPORT2 usearch_close UStringSearch   strsrch
 

Destroying and cleaning up the search iterator data struct.

If a collator is created in usearch_open, it will be destroyed here.

Parameters:
searchiter  data struct to clean up
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI int32_t U_EXPORT2 usearch_first UStringSearch   strsrch,
UErrorCode   status
 

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 usearch_getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE.

Parameters:
strsrch  search iterator data struct
status  for errors if it occurs
Returns:
The character index of the first match, or USEARCH_DONE if there are no matches.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI int32_t U_EXPORT2 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.

The iterator is adjusted so that its current index (as returned by usearch_getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE

Search positions that may render incorrect results are highlighted in the header comments.

Parameters:
strsrch  search iterator data struct
position  to start the search at
status  for errors if it occurs
Returns:
The character index of the first match following pos, or USEARCH_DONE if there are no matches.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI USearchAttributeValue U_EXPORT2 usearch_getAttribute const UStringSearch   strsrch,
USearchAttribute    attribute
 

Gets the text searching attributes.

Parameters:
strsrch  search iterator data struct
attribute  text attribute to be retrieve
Returns:
text attribute value
See also:
usearch_setAttribute
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI const UBreakIterator* U_EXPORT2 usearch_getBreakIterator const UStringSearch   strsrch
 

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 usearch_setBreakIterator. Note that NULL is a legal value; it means that break detection should not be attempted.

Parameters:
strsrch  search iterator data struct
Returns:
break iterator used
See also:
usearch_setBreakIterator
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI UCollator* U_EXPORT2 usearch_getCollator const UStringSearch   strsrch
 

Gets the collator used for the language rules.

Deleting the returned UCollator before calling usearch_close would cause the string search to fail. usearch_close will delete the collator if this search owns it.

Parameters:
strsrch  search iterator data struct
Returns:
collator
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI int32_t U_EXPORT2 usearch_getMatchedLength const UStringSearch   strsrch
 

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 usearch_first, usearch_next, usearch_previous, or usearch_last. Just after construction, or after a searching method returns USEARCH_DONE, this method will return 0.

Parameters:
strsrch  search iterator data struct
Returns:
The length of the match in the string text, or 0 if there is no match currently.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI int32_t U_EXPORT2 usearch_getMatchedStart const UStringSearch   strsrch
 

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 usearch_first, usearch_next, usearch_previous, or usearch_last. Just after construction, or after a searching method returns USEARCH_DONE, this method will return USEARCH_DONE.

Use usearch_getMatchedLength to get the matched string length.

Parameters:
strsrch  search iterator data struct
Returns:
index to a substring within the text string that is being searched.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI int32_t U_EXPORT2 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.

If the iterator is not pointing at a valid match (e.g. just after construction or after USEARCH_DONE has been returned, returns an empty string. If result is not large enough to store the matched text, result will be filled with the partial text and an U_BUFFER_OVERFLOW_ERROR will be returned in status. result will be null-terminated whenever possible. If the buffer fits the matched text exactly, a null-termination is not possible, then a U_STRING_NOT_TERMINATED_ERROR set in status. Pre-flighting can be either done with length = 0 or the API usearch_getMatchLength().

Parameters:
strsrch  search iterator data struct
result  UChar buffer to store the matched string
resultCapacity  length of the result buffer
status  error returned if result is not large enough
Returns:
exact length of the matched text, not counting the null-termination
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI int32_t U_EXPORT2 usearch_getOffset const UStringSearch   strsrch
 

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), USEARCH_DONE is returned.

Parameters:
strsrch  search iterator data struct
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI const UChar* U_EXPORT2 usearch_getPattern const UStringSearch   strsrch,
int32_t   length
 

Gets the search pattern.

Parameters:
strsrch  search iterator data struct
length  return length of the pattern, -1 indicates that the pattern is null-terminated
Returns:
pattern string
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI const UChar* U_EXPORT2 usearch_getText const UStringSearch   strsrch,
int32_t   length
 

Return the string text to be searched.

Parameters:
strsrch  search iterator data struct
length  returned string text length
Returns:
string text
See also:
usearch_setText
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI int32_t U_EXPORT2 usearch_last UStringSearch   strsrch,
UErrorCode   status
 

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 usearch_getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE.

Parameters:
strsrch  search iterator data struct
status  for errors if it occurs
Returns:
The index of the first match, or USEARCH_DONE if there are no matches.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI int32_t U_EXPORT2 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.

The iterator is adjusted so that its current index (as returned by usearch_getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE

Parameters:
strsrch  search iterator data struct
status  for errors if it occurs
Returns:
The index of the next match after the current position, or USEARCH_DONE if there are no more matches.
See also:
usearch_first
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI UStringSearch* U_EXPORT2 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.

A collator will be created in the process, which will be owned by this search and will be deleted in usearch_close.

Parameters:
pattern  for matching
patternlength  length of the pattern, -1 for null-termination
text  text string
textlength  length of the text string, -1 for null-termination
locale  name of locale for the rules to be used
breakiter  A BreakIterator that will be used to restrict the points at which matches are detected. If a match is found, but the match's start or end index is not a boundary as determined by the BreakIterator, the match will be rejected and another will be searched for. If this parameter is NULL, no break detection is attempted.
status  for errors if it occurs. If pattern or text is NULL, or if patternlength or textlength is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned.
Returns:
search iterator data structure, or NULL if there is an error.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI UStringSearch* U_EXPORT2 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.

Note, user retains the ownership of this collator, thus the responsibility of deletion lies with the user.

Parameters:
pattern  for matching
patternlength  length of the pattern, -1 for null-termination
text  text string
textlength  length of the text string, -1 for null-termination
collator  used for the language rules
breakiter  A BreakIterator that will be used to restrict the points at which matches are detected. If a match is found, but the match's start or end index is not a boundary as determined by the BreakIterator, the match will be rejected and another will be searched for. If this parameter is NULL, no break detection is attempted.
status  for errors if it occurs. If collator, pattern or text is NULL, or if patternlength or textlength is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned.
Returns:
search iterator data structure, or NULL if there is an error.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI int32_t U_EXPORT2 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.

The iterator is adjusted so that its current index (as returned by usearch_getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE

Search positions that may render incorrect results are highlighted in the header comments.

Parameters:
strsrch  search iterator data struct
position  index position the search is to begin at
status  for errors if it occurs
Returns:
The character index of the first match preceding pos, or USEARCH_DONE if there are no matches.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI int32_t U_EXPORT2 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.

The iterator is adjusted so that its current index (as returned by usearch_getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE

Parameters:
strsrch  search iterator data struct
status  for errors if it occurs
Returns:
The index of the previous match before the current position, or USEARCH_DONE if there are no more matches.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI void U_EXPORT2 usearch_reset UStringSearch   strsrch
 

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.

Parameters:
strsrch  search iterator data struct
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI void U_EXPORT2 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.

USEARCH_DEFAULT can be used for all attributes for resetting.

Parameters:
strsrch  search iterator data struct
attribute  text attribute to be set
value  text attribute value
status  for errors if it occurs
See also:
usearch_getAttribute
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI void U_EXPORT2 usearch_setBreakIterator UStringSearch   strsrch,
UBreakIterator   breakiter,
UErrorCode   status
 

Set the BreakIterator that will be used to restrict the points at which matches are detected.

Parameters:
strsrch  search iterator data struct
breakiter  A BreakIterator that will be used to restrict the points at which matches are detected. If a match is found, but the match's start or end index is not a boundary as determined by the BreakIterator, the match will be rejected and another will be searched for. If this parameter is NULL, no break detection is attempted.
status  for errors if it occurs
See also:
usearch_getBreakIterator
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI void U_EXPORT2 usearch_setCollator UStringSearch   strsrch,
const UCollator   collator,
UErrorCode   status
 

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.

Parameters:
strsrch  search iterator data struct
collator  to be used
status  for errors if it occurs
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI void U_EXPORT2 usearch_setOffset UStringSearch   strsrch,
int32_t    position,
UErrorCode   status
 

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

Parameters:
strsrch  search iterator data struct
position  position to start next search from.
status  error status if any.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI void U_EXPORT2 usearch_setPattern UStringSearch   strsrch,
const UChar   pattern,
int32_t    patternlength,
UErrorCode   status
 

Sets the pattern used for matching.

Internal data like the Boyer Moore table will be recalculated, but the iterator's position is unchanged.

Parameters:
strsrch  search iterator data struct
pattern  string
patternlength  pattern length, -1 for null-terminated string
status  for errors if it occurs. If text is NULL, or textlength is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned with no change done to strsrch.
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.

U_CAPI void U_EXPORT2 usearch_setText UStringSearch   strsrch,
const UChar   text,
int32_t    textlength,
UErrorCode   status
 

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.

Parameters:
strsrch  search iterator data struct
text  new string to look for match
textlength  length of the new string, -1 for null-termination
status  for errors if it occurs. If text is NULL, or textlength is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned with no change done to strsrch.
See also:
usearch_getText
Draft:
This API has been introduced in ICU 2.0. It is still in draft state and may be modified in a future release.


Generated on Tue Apr 9 11:30:24 2002 for ICU 2.1 by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001