17935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert/* 27935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert****************************************************************************** 37935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert* Copyright (C) 1996-2010, International Business Machines Corporation and * 47935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert* others. All Rights Reserved. * 57935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert****************************************************************************** 67935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert*/ 77935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert 87935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubertpackage com.ibm.icu.util; 97935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert 107935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert/** 117935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p>Interface for enabling iteration over sets of <int, Object>, where 127935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * int is the sorted integer index in ascending order, and Object its 137935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * associated value.</p> 147935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p>The ValueIterator allows iterations over integer indexes in the range 157935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * of Integer.MIN_VALUE to Integer.MAX_VALUE inclusive. Implementations of 167935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * ValueIterator should specify their own maximum subrange within the above 177935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * range that is meaningful to its applications.</p> 187935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p>Most implementations will be created by factory methods, such as the 197935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * character name iterator in UCharacter.getNameIterator. See example below. 207935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * </p> 217935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * Example of use:<br> 227935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <pre> 237935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * ValueIterator iterator = UCharacter.getNameIterator(); 247935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * ValueIterator.Element result = new ValueIterator.Element(); 257935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * iterator.setRange(UCharacter.MIN_VALUE, UCharacter.MAX_VALUE); 267935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * while (iterator.next(result)) { 277935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * System.out.println("Codepoint \\u" + 287935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * Integer.toHexString(result.integer) + 297935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * " has the character name " + (String)result.value); 307935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * } 317935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * </pre> 327935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @author synwee 337935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @stable ICU 2.6 347935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert */ 357935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubertpublic interface ValueIterator 367935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert{ 377935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert // public inner class --------------------------------------------- 387935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert 397935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert /** 407935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p>The return result container of each iteration. Stores the next 417935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * integer index and its associated value Object.</p> 427935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @stable ICU 2.6 437935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert */ 447935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert public static final class Element 457935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert { 467935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert // public data members ---------------------------------------- 477935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert 487935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert /** 497935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * Integer index of the current iteration 507935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @stable ICU 2.6 517935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert */ 527935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert public int integer; 537935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert /** 547935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * Gets the Object value associated with the integer index. 557935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @stable ICU 2.6 567935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert */ 577935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert public Object value; 587935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert 597935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert // public constructor ------------------------------------------ 607935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert 617935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert /** 627935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * Empty default constructor to make javadoc happy 637935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @stable ICU 2.4 647935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert */ 657935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert public Element() 667935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert { 677935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert } 687935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert } 697935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert 707935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert // public methods ------------------------------------------------- 717935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert 727935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert /** 737935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p>Returns the next result for this iteration and returns 747935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * true if we are not at the end of the iteration, false otherwise.</p> 757935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p>If this returns a false, the contents of elements will not 767935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * be updated.</p> 777935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @param element for storing the result index and value 787935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @return true if we are not at the end of the iteration, false otherwise. 797935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @see Element 807935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @stable ICU 2.6 817935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert */ 827935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert public boolean next(Element element); 837935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert 847935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert /** 857935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p>Resets the iterator to start iterating from the integer index 867935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * Integer.MIN_VALUE or X if a setRange(X, Y) has been called previously. 877935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * </p> 887935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @stable ICU 2.6 897935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert */ 907935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert public void reset(); 917935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert 927935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert /** 937935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p>Restricts the range of integers to iterate and resets the iteration 947935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * to begin at the index argument start.</p> 957935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p>If setRange(start, end) is not performed before next(element) is 967935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * called, the iteration will start from the integer index 977935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * Integer.MIN_VALUE and end at Integer.MAX_VALUE.</p> 987935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p> 997935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * If this range is set outside the meaningful range specified by the 1007935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * implementation, next(element) will always return false. 1017935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * </p> 1027935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @param start first integer in the range to iterate 1037935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @param limit one more than the last integer in the range 1047935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @exception IllegalArgumentException thrown when attempting to set an 1057935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * illegal range. E.g limit <= start 1067935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * @stable ICU 2.6 1077935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert */ 1087935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert public void setRange(int start, int limit); 1097935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert} 110