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