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 &lt;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