001: /*
002: ******************************************************************************
003: * Copyright (C) 1996-2004, International Business Machines Corporation and *
004: * others. All Rights Reserved. *
005: ******************************************************************************
006: */
007:
008: package com.ibm.icu.util;
009:
010: /**
011: * <p>Interface for enabling iteration over sets of <int index, int value>,
012: * where index is the sorted integer index in ascending order and value, its
013: * associated integer value.</p>
014: * <p>The result for each iteration is the consecutive range of
015: * <int index, int value> with the same value. Result is represented by
016: * <start, limit, value> where</p>
017: * <ul>
018: * <li> start is the starting integer of the result range
019: * <li> limit is 1 after the maximum integer that follows start, such that
020: * all integers between start and (limit - 1), inclusive, have the same
021: * associated integer value.
022: * <li> value is the integer value that all integers from start to (limit - 1)
023: * share in common.
024: * </ul>
025: * <p>
026: * Hence value(start) = value(start + 1) = .... = value(start + n) = .... =
027: * value(limit - 1). However value(start -1) != value(start) and
028: * value(limit) != value(start).
029: * </p>
030: * <p>Most implementations will be created by factory methods, such as the
031: * character type iterator in UCharacter.getTypeIterator. See example below.
032: * </p>
033: * Example of use:<br>
034: * <pre>
035: * RangeValueIterator iterator = UCharacter.getTypeIterator();
036: * RangeValueIterator.Element result = new RangeValueIterator.Element();
037: * while (iterator.next(result)) {
038: * System.out.println("Codepoint \\u" +
039: * Integer.toHexString(result.start) +
040: * " to codepoint \\u" +
041: * Integer.toHexString(result.limit - 1) +
042: * " has the character type " + result.value);
043: * }
044: * </pre>
045: * @author synwee
046: * @stable ICU 2.6
047: */
048: public interface RangeValueIterator {
049: // public inner class ---------------------------------------------
050:
051: /**
052: * Return result wrapper for com.ibm.icu.util.RangeValueIterator.
053: * Stores the start and limit of the continous result range and the
054: * common value all integers between [start, limit - 1] has.
055: * @stable ICU 2.6
056: */
057: public class Element {
058: // public data member ---------------------------------------------
059:
060: /**
061: * Starting integer of the continuous result range that has the same
062: * value
063: * @stable ICU 2.6
064: */
065: public int start;
066: /**
067: * (End + 1) integer of continuous result range that has the same
068: * value
069: * @stable ICU 2.6
070: */
071: public int limit;
072: /**
073: * Gets the common value of the continous result range
074: * @stable ICU 2.6
075: */
076: public int value;
077:
078: // public constructor --------------------------------------------
079:
080: /**
081: * Empty default constructor to make javadoc happy
082: * @stable ICU 2.4
083: */
084: public Element() {
085: }
086: }
087:
088: // public methods -------------------------------------------------
089:
090: /**
091: * <p>Gets the next maximal result range with a common value and returns
092: * true if we are not at the end of the iteration, false otherwise.</p>
093: * <p>If the return boolean is a false, the contents of elements will not
094: * be updated.</p>
095: * @param element for storing the result range and value
096: * @return true if we are not at the end of the iteration, false otherwise.
097: * @see Element
098: * @stable ICU 2.6
099: */
100: public boolean next(Element element);
101:
102: /**
103: * Resets the iterator to the beginning of the iteration.
104: * @stable ICU 2.6
105: */
106: public void reset();
107: }
|