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, Object>, where
012: * int is the sorted integer index in ascending order and Object, its
013: * associated value.</p>
014: * <p>The ValueIterator allows iterations over integer indexes in the range
015: * of Integer.MIN_VALUE to Integer.MAX_VALUE inclusive. Implementations of
016: * ValueIterator should specify their own maximum subrange within the above
017: * range that is meaningful to its applications.</p>
018: * <p>Most implementations will be created by factory methods, such as the
019: * character name iterator in UCharacter.getNameIterator. See example below.
020: * </p>
021: * Example of use:<br>
022: * <pre>
023: * ValueIterator iterator = UCharacter.getNameIterator();
024: * ValueIterator.Element result = new ValueIterator.Element();
025: * iterator.setRange(UCharacter.MIN_VALUE, UCharacter.MAX_VALUE);
026: * while (iterator.next(result)) {
027: * System.out.println("Codepoint \\u" +
028: * Integer.toHexString(result.integer) +
029: * " has the character name " + (String)result.value);
030: * }
031: * </pre>
032: * @author synwee
033: * @stable ICU 2.6
034: */
035: public interface ValueIterator {
036: // public inner class ---------------------------------------------
037:
038: /**
039: * <p>The return result container of each iteration. Stores the next
040: * integer index and its associated value Object.</p>
041: * @stable ICU 2.6
042: */
043: public static final class Element {
044: // public data members ----------------------------------------
045:
046: /**
047: * Integer index of the current iteration
048: * @stable ICU 2.6
049: */
050: public int integer;
051: /**
052: * Gets the Object value associated with the integer index.
053: * @stable ICU 2.6
054: */
055: public Object value;
056:
057: // public constructor ------------------------------------------
058:
059: /**
060: * Empty default constructor to make javadoc happy
061: * @stable ICU 2.4
062: */
063: public Element() {
064: }
065: }
066:
067: // public methods -------------------------------------------------
068:
069: /**
070: * <p>Gets the next result for this iteration and returns
071: * true if we are not at the end of the iteration, false otherwise.</p>
072: * <p>If the return boolean is a false, the contents of elements will not
073: * be updated.</p>
074: * @param element for storing the result index and value
075: * @return true if we are not at the end of the iteration, false otherwise.
076: * @see Element
077: * @stable ICU 2.6
078: */
079: public boolean next(Element element);
080:
081: /**
082: * <p>Resets the iterator to start iterating from the integer index
083: * Integer.MIN_VALUE or X if a setRange(X, Y) has been called previously.
084: * </p>
085: * @stable ICU 2.6
086: */
087: public void reset();
088:
089: /**
090: * <p>Restricts the range of integers to iterate and resets the iteration
091: * to begin at the index argument start.</p>
092: * <p>If setRange(start, end) is not performed before next(element) is
093: * called, the iteration will start from the integer index
094: * Integer.MIN_VALUE and end at Integer.MAX_VALUE.</p>
095: * <p>
096: * If this range is set outside the meaningful range specified by the
097: * implementation, next(element) will always return false.
098: * </p>
099: * @param start first integer in the range to iterate
100: * @param limit one more than the last integer in the range
101: * @exception IllegalArgumentException thrown when attempting to set an
102: * illegal range. E.g limit <= start
103: * @stable ICU 2.6
104: */
105: public void setRange(int start, int limit);
106: }
|