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 index, int value&gt;,
14 * where index is the sorted integer index in ascending order and value, its
15 * associated integer value.
16 * <p>The result for each iteration is the consecutive range of
17 * &lt;int index, int value&gt; with the same value. Result is represented by
18 * &lt;start, limit, value&gt; where
19 * <ul>
20 * <li> start is the starting integer of the result range
21 * <li> limit is 1 after the maximum integer that follows start, such that
22 *      all integers between start and (limit - 1), inclusive, have the same
23 *      associated integer value.
24 * <li> value is the integer value that all integers from start to (limit - 1)
25 *      share in common.
26 * </ul>
27 * <p>
28 * Hence value(start) = value(start + 1) = .... = value(start + n) = .... =
29 * value(limit - 1). However value(start -1) != value(start) and
30 * value(limit) != value(start).
31 *
32 * <p>Most implementations will be created by factory methods, such as the
33 * character type iterator in UCharacter.getTypeIterator. See example below.
34 *
35 * <p>Example of use:<br>
36 * <pre>
37 * RangeValueIterator iterator = UCharacter.getTypeIterator();
38 * RangeValueIterator.Element result = new RangeValueIterator.Element();
39 * while (iterator.next(result)) {
40 *     System.out.println("Codepoint \\u" +
41 *                        Integer.toHexString(result.start) +
42 *                        " to codepoint \\u" +
43 *                        Integer.toHexString(result.limit - 1) +
44 *                        " has the character type " + result.value);
45 * }
46 * </pre>
47 * @author synwee
48 * @stable ICU 2.6
49 */
50public interface RangeValueIterator
51{
52    // public inner class ---------------------------------------------
53
54    /**
55    * Return result wrapper for com.ibm.icu.util.RangeValueIterator.
56    * Stores the start and limit of the continous result range and the
57    * common value all integers between [start, limit - 1] has.
58    * @stable ICU 2.6
59    */
60    public class Element
61    {
62        // public data member ---------------------------------------------
63
64        /**
65        * Starting integer of the continuous result range that has the same
66        * value
67        * @stable ICU 2.6
68        */
69        public int start;
70        /**
71        * (End + 1) integer of continuous result range that has the same
72        * value
73        * @stable ICU 2.6
74        */
75        public int limit;
76        /**
77        * Gets the common value of the continous result range
78        * @stable ICU 2.6
79        */
80        public int value;
81
82        // public constructor --------------------------------------------
83
84        /**
85         * Empty default constructor to make javadoc happy
86         * @stable ICU 2.4
87         */
88        public Element()
89        {
90        }
91    }
92
93    // public methods -------------------------------------------------
94
95    /**
96    * <p>Returns the next maximal result range with a common value and returns
97    * true if we are not at the end of the iteration, false otherwise.
98    * <p>If this returns a false, the contents of elements will not
99    * be updated.
100    * @param element for storing the result range and value
101    * @return true if we are not at the end of the iteration, false otherwise.
102    * @see Element
103    * @stable ICU 2.6
104    */
105    public boolean next(Element element);
106
107    /**
108    * Resets the iterator to the beginning of the iteration.
109    * @stable ICU 2.6
110    */
111    public void reset();
112}
113