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
10package com.ibm.icu.util;
11
12/**
13 * <p>Interface for enabling iteration over sets of &lt;int, Object&gt;, 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 */
37public 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 &lt;= start
108     * @stable ICU 2.6
109     */
110    public void setRange(int start, int limit);
111}
112