001: /*
002: *******************************************************************************
003: * Copyright (C) 2001-2004, International Business Machines Corporation and *
004: * others. All Rights Reserved. *
005: *******************************************************************************
006: */
007: package com.ibm.icu.text;
008:
009: /**
010: * <code>UnicodeMatcher</code> defines a protocol for objects that can
011: * match a range of characters in a Replaceable string.
012: * @stable ICU 2.0
013: */
014: public interface UnicodeMatcher {
015:
016: /**
017: * Constant returned by <code>matches()</code> indicating a
018: * mismatch between the text and this matcher. The text contains
019: * a character which does not match, or the text does not contain
020: * all desired characters for a non-incremental match.
021: * @stable ICU 2.0
022: */
023: public static final int U_MISMATCH = 0;
024:
025: /**
026: * Constant returned by <code>matches()</code> indicating a
027: * partial match between the text and this matcher. This value is
028: * only returned for incremental match operations. All characters
029: * of the text match, but more characters are required for a
030: * complete match. Alternatively, for variable-length matchers,
031: * all characters of the text match, and if more characters were
032: * supplied at limit, they might also match.
033: * @stable ICU 2.0
034: */
035: public static final int U_PARTIAL_MATCH = 1;
036:
037: /**
038: * Constant returned by <code>matches()</code> indicating a
039: * complete match between the text and this matcher. For an
040: * incremental variable-length match, this value is returned if
041: * the given text matches, and it is known that additional
042: * characters would not alter the extent of the match.
043: * @stable ICU 2.0
044: */
045: public static final int U_MATCH = 2;
046:
047: /**
048: * The character at index i, where i < contextStart || i >= contextLimit,
049: * is ETHER. This allows explicit matching by rules and UnicodeSets
050: * of text outside the context. In traditional terms, this allows anchoring
051: * at the start and/or end.
052: * @stable ICU 2.0
053: */
054: static final char ETHER = '\uFFFF';
055:
056: /**
057: * Return a UMatchDegree value indicating the degree of match for
058: * the given text at the given offset. Zero, one, or more
059: * characters may be matched.
060: *
061: * Matching in the forward direction is indicated by limit >
062: * offset. Characters from offset forwards to limit-1 will be
063: * considered for matching.
064: *
065: * Matching in the reverse direction is indicated by limit <
066: * offset. Characters from offset backwards to limit+1 will be
067: * considered for matching.
068: *
069: * If limit == offset then the only match possible is a zero
070: * character match (which subclasses may implement if desired).
071: *
072: * If U_MATCH is returned, then as a side effect, advance the
073: * offset parameter to the limit of the matched substring. In the
074: * forward direction, this will be the index of the last matched
075: * character plus one. In the reverse direction, this will be the
076: * index of the last matched character minus one.
077: *
078: * @param text the text to be matched
079: * @param offset on input, the index into text at which to begin
080: * matching. On output, the limit of the matched text. The
081: * number of matched characters is the output value of offset
082: * minus the input value. Offset should always point to the
083: * HIGH SURROGATE (leading code unit) of a pair of surrogates,
084: * both on entry and upon return.
085: * @param limit the limit index of text to be matched. Greater
086: * than offset for a forward direction match, less than offset for
087: * a backward direction match. The last character to be
088: * considered for matching will be text.charAt(limit-1) in the
089: * forward direction or text.charAt(limit+1) in the backward
090: * direction.
091: * @param incremental if TRUE, then assume further characters may
092: * be inserted at limit and check for partial matching. Otherwise
093: * assume the text as given is complete.
094: * @return a match degree value indicating a full match, a partial
095: * match, or a mismatch. If incremental is FALSE then
096: * U_PARTIAL_MATCH should never be returned.
097: * @stable ICU 2.0
098: */
099: public abstract int matches(Replaceable text, int[] offset,
100: int limit, boolean incremental);
101:
102: /**
103: * Returns a string representation of this matcher. If the result of
104: * calling this function is passed to the appropriate parser, it
105: * will produce another matcher that is equal to this one.
106: * @param escapeUnprintable if TRUE then convert unprintable
107: * character to their hex escape representations, \\uxxxx or
108: * \\Uxxxxxxxx. Unprintable characters are those other than
109: * U+000A, U+0020..U+007E.
110: * @stable ICU 2.0
111: */
112: public abstract String toPattern(boolean escapeUnprintable);
113:
114: /**
115: * Returns TRUE if this matcher will match a character c, where c
116: * & 0xFF == v, at offset, in the forward direction (with limit >
117: * offset). This is used by <tt>RuleBasedTransliterator</tt> for
118: * indexing.
119: *
120: * <p>Note: This API uses an int even though the value will be
121: * restricted to 8 bits in order to avoid complications with
122: * signedness (bytes convert to ints in the range -128..127).
123: * @stable ICU 2.0
124: */
125: public abstract boolean matchesIndexValue(int v);
126:
127: /**
128: * Union the set of all characters that may be matched by this object
129: * into the given set.
130: * @param toUnionTo the set into which to union the source characters
131: * @stable ICU 2.2
132: */
133: public abstract void addMatchSetTo(UnicodeSet toUnionTo);
134: }
135:
136: //eof
|