KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ibm > icu > util > ValueIterator


1 /*
2 ******************************************************************************
3 * Copyright (C) 1996-2004, International Business Machines Corporation and *
4 * others. All Rights Reserved. *
5 ******************************************************************************
6 */
7
8 package 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  */
35 public 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 JavaDoc 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>Gets 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 the return boolean is 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
Popular Tags