UnicodeMatcher::matches()
jpayne@69: * indicating the degree of match.
jpayne@69: * @stable ICU 2.4
jpayne@69: */
jpayne@69: enum UMatchDegree {
jpayne@69: /**
jpayne@69: * Constant returned by matches() indicating a
jpayne@69: * mismatch between the text and this matcher. The text contains
jpayne@69: * a character which does not match, or the text does not contain
jpayne@69: * all desired characters for a non-incremental match.
jpayne@69: * @stable ICU 2.4
jpayne@69: */
jpayne@69: U_MISMATCH,
jpayne@69:
jpayne@69: /**
jpayne@69: * Constant returned by matches() indicating a
jpayne@69: * partial match between the text and this matcher. This value is
jpayne@69: * only returned for incremental match operations. All characters
jpayne@69: * of the text match, but more characters are required for a
jpayne@69: * complete match. Alternatively, for variable-length matchers,
jpayne@69: * all characters of the text match, and if more characters were
jpayne@69: * supplied at limit, they might also match.
jpayne@69: * @stable ICU 2.4
jpayne@69: */
jpayne@69: U_PARTIAL_MATCH,
jpayne@69:
jpayne@69: /**
jpayne@69: * Constant returned by matches() indicating a
jpayne@69: * complete match between the text and this matcher. For an
jpayne@69: * incremental variable-length match, this value is returned if
jpayne@69: * the given text matches, and it is known that additional
jpayne@69: * characters would not alter the extent of the match.
jpayne@69: * @stable ICU 2.4
jpayne@69: */
jpayne@69: U_MATCH
jpayne@69: };
jpayne@69:
jpayne@69: /**
jpayne@69: * UnicodeMatcher defines a protocol for objects that can
jpayne@69: * match a range of characters in a Replaceable string.
jpayne@69: * @stable ICU 2.4
jpayne@69: */
jpayne@69: class U_COMMON_API UnicodeMatcher /* not : public UObject because this is an interface/mixin class */ {
jpayne@69:
jpayne@69: public:
jpayne@69: /**
jpayne@69: * Destructor.
jpayne@69: * @stable ICU 2.4
jpayne@69: */
jpayne@69: virtual ~UnicodeMatcher();
jpayne@69:
jpayne@69: /**
jpayne@69: * Return a UMatchDegree value indicating the degree of match for
jpayne@69: * the given text at the given offset. Zero, one, or more
jpayne@69: * characters may be matched.
jpayne@69: *
jpayne@69: * Matching in the forward direction is indicated by limit >
jpayne@69: * offset. Characters from offset forwards to limit-1 will be
jpayne@69: * considered for matching.
jpayne@69: *
jpayne@69: * Matching in the reverse direction is indicated by limit <
jpayne@69: * offset. Characters from offset backwards to limit+1 will be
jpayne@69: * considered for matching.
jpayne@69: *
jpayne@69: * If limit == offset then the only match possible is a zero
jpayne@69: * character match (which subclasses may implement if desired).
jpayne@69: *
jpayne@69: * As a side effect, advance the offset parameter to the limit of
jpayne@69: * the matched substring. In the forward direction, this will be
jpayne@69: * the index of the last matched character plus one. In the
jpayne@69: * reverse direction, this will be the index of the last matched
jpayne@69: * character minus one.
jpayne@69: *
jpayne@69: * Note: This method is not const because some classes may jpayne@69: * modify their state as the result of a match. jpayne@69: * jpayne@69: * @param text the text to be matched jpayne@69: * @param offset on input, the index into text at which to begin jpayne@69: * matching. On output, the limit of the matched text. The jpayne@69: * number of matched characters is the output value of offset jpayne@69: * minus the input value. Offset should always point to the jpayne@69: * HIGH SURROGATE (leading code unit) of a pair of surrogates, jpayne@69: * both on entry and upon return. jpayne@69: * @param limit the limit index of text to be matched. Greater jpayne@69: * than offset for a forward direction match, less than offset for jpayne@69: * a backward direction match. The last character to be jpayne@69: * considered for matching will be text.charAt(limit-1) in the jpayne@69: * forward direction or text.charAt(limit+1) in the backward jpayne@69: * direction. jpayne@69: * @param incremental if TRUE, then assume further characters may jpayne@69: * be inserted at limit and check for partial matching. Otherwise jpayne@69: * assume the text as given is complete. jpayne@69: * @return a match degree value indicating a full match, a partial jpayne@69: * match, or a mismatch. If incremental is FALSE then jpayne@69: * U_PARTIAL_MATCH should never be returned. jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: virtual UMatchDegree matches(const Replaceable& text, jpayne@69: int32_t& offset, jpayne@69: int32_t limit, jpayne@69: UBool incremental) = 0; jpayne@69: jpayne@69: /** jpayne@69: * Returns a string representation of this matcher. If the result of jpayne@69: * calling this function is passed to the appropriate parser, it jpayne@69: * will produce another matcher that is equal to this one. jpayne@69: * @param result the string to receive the pattern. Previous jpayne@69: * contents will be deleted. jpayne@69: * @param escapeUnprintable if TRUE then convert unprintable jpayne@69: * character to their hex escape representations, \\uxxxx or jpayne@69: * \\Uxxxxxxxx. Unprintable characters are those other than jpayne@69: * U+000A, U+0020..U+007E. jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: virtual UnicodeString& toPattern(UnicodeString& result, jpayne@69: UBool escapeUnprintable = FALSE) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Returns TRUE if this matcher will match a character c, where c jpayne@69: * & 0xFF == v, at offset, in the forward direction (with limit > jpayne@69: * offset). This is used by RuleBasedTransliterator for jpayne@69: * indexing. jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: virtual UBool matchesIndexValue(uint8_t v) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Union the set of all characters that may be matched by this object jpayne@69: * into the given set. jpayne@69: * @param toUnionTo the set into which to union the source characters jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: virtual void addMatchSetTo(UnicodeSet& toUnionTo) const = 0; jpayne@69: }; jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */ jpayne@69: jpayne@69: #endif