1/* 2****************************************************************************** 3* Copyright (C) 1996-2010, International Business Machines Corporation and * 4* others. All Rights Reserved. * 5****************************************************************************** 6*/ 7 8package com.ibm.icu.util; 9 10/** 11 * <p>Interface for enabling iteration over sets of <int, Object>, where 12 * int is the sorted integer index in ascending order, and Object its 13 * associated value.</p> 14 * <p>The ValueIterator allows iterations over integer indexes in the range 15 * of Integer.MIN_VALUE to Integer.MAX_VALUE inclusive. Implementations of 16 * ValueIterator should specify their own maximum subrange within the above 17 * range that is meaningful to its applications.</p> 18 * <p>Most implementations will be created by factory methods, such as the 19 * character name iterator in UCharacter.getNameIterator. See example below. 20 * </p> 21 * Example of use:<br> 22 * <pre> 23 * ValueIterator iterator = UCharacter.getNameIterator(); 24 * ValueIterator.Element result = new ValueIterator.Element(); 25 * iterator.setRange(UCharacter.MIN_VALUE, UCharacter.MAX_VALUE); 26 * while (iterator.next(result)) { 27 * System.out.println("Codepoint \\u" + 28 * Integer.toHexString(result.integer) + 29 * " has the character name " + (String)result.value); 30 * } 31 * </pre> 32 * @author synwee 33 * @stable ICU 2.6 34 */ 35public interface ValueIterator 36{ 37 // public inner class --------------------------------------------- 38 39 /** 40 * <p>The return result container of each iteration. Stores the next 41 * integer index and its associated value Object.</p> 42 * @stable ICU 2.6 43 */ 44 public static final class Element 45 { 46 // public data members ---------------------------------------- 47 48 /** 49 * Integer index of the current iteration 50 * @stable ICU 2.6 51 */ 52 public int integer; 53 /** 54 * Gets the Object value associated with the integer index. 55 * @stable ICU 2.6 56 */ 57 public Object value; 58 59 // public constructor ------------------------------------------ 60 61 /** 62 * Empty default constructor to make javadoc happy 63 * @stable ICU 2.4 64 */ 65 public Element() 66 { 67 } 68 } 69 70 // public methods ------------------------------------------------- 71 72 /** 73 * <p>Returns the next result for this iteration and returns 74 * true if we are not at the end of the iteration, false otherwise.</p> 75 * <p>If this returns a false, the contents of elements will not 76 * be updated.</p> 77 * @param element for storing the result index and value 78 * @return true if we are not at the end of the iteration, false otherwise. 79 * @see Element 80 * @stable ICU 2.6 81 */ 82 public boolean next(Element element); 83 84 /** 85 * <p>Resets the iterator to start iterating from the integer index 86 * Integer.MIN_VALUE or X if a setRange(X, Y) has been called previously. 87 * </p> 88 * @stable ICU 2.6 89 */ 90 public void reset(); 91 92 /** 93 * <p>Restricts the range of integers to iterate and resets the iteration 94 * to begin at the index argument start.</p> 95 * <p>If setRange(start, end) is not performed before next(element) is 96 * called, the iteration will start from the integer index 97 * Integer.MIN_VALUE and end at Integer.MAX_VALUE.</p> 98 * <p> 99 * If this range is set outside the meaningful range specified by the 100 * implementation, next(element) will always return false. 101 * </p> 102 * @param start first integer in the range to iterate 103 * @param limit one more than the last integer in the range 104 * @exception IllegalArgumentException thrown when attempting to set an 105 * illegal range. E.g limit <= start 106 * @stable ICU 2.6 107 */ 108 public void setRange(int start, int limit); 109} 110