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