/* ****************************************************************************** * Copyright (C) 1996-2010, International Business Machines Corporation and * * others. All Rights Reserved. * ****************************************************************************** */ package com.ibm.icu.util; /** *
Interface for enabling iteration over sets of <int, Object>, where * int is the sorted integer index in ascending order, and Object its * associated value.
*The ValueIterator allows iterations over integer indexes in the range * of Integer.MIN_VALUE to Integer.MAX_VALUE inclusive. Implementations of * ValueIterator should specify their own maximum subrange within the above * range that is meaningful to its applications.
*Most implementations will be created by factory methods, such as the * character name iterator in UCharacter.getNameIterator. See example below. *
* Example of use:* ValueIterator iterator = UCharacter.getNameIterator(); * ValueIterator.Element result = new ValueIterator.Element(); * iterator.setRange(UCharacter.MIN_VALUE, UCharacter.MAX_VALUE); * while (iterator.next(result)) { * System.out.println("Codepoint \\u" + * Integer.toHexString(result.integer) + * " has the character name " + (String)result.value); * } ** @author synwee * @stable ICU 2.6 */ public interface ValueIterator { // public inner class --------------------------------------------- /** *
The return result container of each iteration. Stores the next * integer index and its associated value Object.
* @stable ICU 2.6 */ public static final class Element { // public data members ---------------------------------------- /** * Integer index of the current iteration * @stable ICU 2.6 */ public int integer; /** * Gets the Object value associated with the integer index. * @stable ICU 2.6 */ public Object value; // public constructor ------------------------------------------ /** * Empty default constructor to make javadoc happy * @stable ICU 2.4 */ public Element() { } } // public methods ------------------------------------------------- /** *Returns the next result for this iteration and returns * true if we are not at the end of the iteration, false otherwise.
*If this returns a false, the contents of elements will not * be updated.
* @param element for storing the result index and value * @return true if we are not at the end of the iteration, false otherwise. * @see Element * @stable ICU 2.6 */ public boolean next(Element element); /** *Resets the iterator to start iterating from the integer index * Integer.MIN_VALUE or X if a setRange(X, Y) has been called previously. *
* @stable ICU 2.6 */ public void reset(); /** *Restricts the range of integers to iterate and resets the iteration * to begin at the index argument start.
*If setRange(start, end) is not performed before next(element) is * called, the iteration will start from the integer index * Integer.MIN_VALUE and end at Integer.MAX_VALUE.
** If this range is set outside the meaningful range specified by the * implementation, next(element) will always return false. *
* @param start first integer in the range to iterate * @param limit one more than the last integer in the range * @exception IllegalArgumentException thrown when attempting to set an * illegal range. E.g limit <= start * @stable ICU 2.6 */ public void setRange(int start, int limit); }