17935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert/* 27935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert****************************************************************************** 3bee65486a185907111f3be60992433e133ec0e32Scott Russell* Copyright (C) 1996-2016, 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/** 11bee65486a185907111f3be60992433e133ec0e32Scott Russell * <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 13bee65486a185907111f3be60992433e133ec0e32Scott Russell * associated value. 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 17bee65486a185907111f3be60992433e133ec0e32Scott Russell * range that is meaningful to its applications. 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. 20bee65486a185907111f3be60992433e133ec0e32Scott Russell * 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 41bee65486a185907111f3be60992433e133ec0e32Scott Russell * integer index and its associated value Object. 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 74bee65486a185907111f3be60992433e133ec0e32Scott Russell * true if we are not at the end of the iteration, false otherwise. 757935b1839a081ed19ae0d33029ad3c09632a2caaFredrik Roubert * <p>If this returns a false, the contents of elements will not 76bee65486a185907111f3be60992433e133ec0e32Scott Russell * be updated. 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. 87bee65486a185907111f3be60992433e133ec0e32Scott Russell * 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 94bee65486a185907111f3be60992433e133ec0e32Scott Russell * to begin at the index argument start. 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 97bee65486a185907111f3be60992433e133ec0e32Scott Russell * Integer.MIN_VALUE and end at Integer.MAX_VALUE. 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. 101bee65486a185907111f3be60992433e133ec0e32Scott Russell * 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 105bee65486a185907111f3be60992433e133ec0e32Scott Russell * 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