View Javadoc
1   /*
2    * Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  /*
27   *******************************************************************************
28   * (C) Copyright IBM Corp. 1996-2005 - All Rights Reserved                     *
29   *                                                                             *
30   * The original version of this source code and documentation is copyrighted   *
31   * and owned by IBM, These materials are provided under terms of a License     *
32   * Agreement between IBM and Sun. This technology is protected by multiple     *
33   * US and International patents. This notice and attribution to IBM may not    *
34   * to removed.                                                                 *
35   *******************************************************************************
36   */
37  
38  package sun.text.normalizer;
39  
40  /**
41   * <p>Interface for enabling iteration over sets of <int index, int value>,
42   * where index is the sorted integer index in ascending order and value, its
43   * associated integer value.</p>
44   * <p>The result for each iteration is the consecutive range of
45   * <int index, int value> with the same value. Result is represented by
46   * <start, limit, value> where</p>
47   * <ul>
48   * <li> start is the starting integer of the result range
49   * <li> limit is 1 after the maximum integer that follows start, such that
50   *      all integers between start and (limit - 1), inclusive, have the same
51   *      associated integer value.
52   * <li> value is the integer value that all integers from start to (limit - 1)
53   *      share in common.
54   * </ul>
55   * <p>
56   * Hence value(start) = value(start + 1) = .... = value(start + n) = .... =
57   * value(limit - 1). However value(start -1) != value(start) and
58   * value(limit) != value(start).
59   * </p>
60   * <p>Most implementations will be created by factory methods, such as the
61   * character type iterator in UCharacter.getTypeIterator. See example below.
62   * </p>
63   * Example of use:<br>
64   * <pre>
65   * RangeValueIterator iterator = UCharacter.getTypeIterator();
66   * RangeValueIterator.Element result = new RangeValueIterator.Element();
67   * while (iterator.next(result)) {
68   *     System.out.println("Codepoint \\u" +
69   *                        Integer.toHexString(result.start) +
70   *                        " to codepoint \\u" +
71   *                        Integer.toHexString(result.limit - 1) +
72   *                        " has the character type " + result.value);
73   * }
74   * </pre>
75   * @author synwee
76   * @stable ICU 2.6
77   */
78  public interface RangeValueIterator
79  {
80      // public inner class ---------------------------------------------
81  
82      /**
83      * Return result wrapper for com.ibm.icu.util.RangeValueIterator.
84      * Stores the start and limit of the continous result range and the
85      * common value all integers between [start, limit - 1] has.
86      * @stable ICU 2.6
87      */
88      public class Element
89      {
90          // public data member ---------------------------------------------
91  
92          /**
93          * Starting integer of the continuous result range that has the same
94          * value
95          * @stable ICU 2.6
96          */
97          public int start;
98          /**
99          * (End + 1) integer of continuous result range that has the same
100         * value
101         * @stable ICU 2.6
102         */
103         public int limit;
104         /**
105         * Gets the common value of the continous result range
106         * @stable ICU 2.6
107         */
108         public int value;
109 
110         // public constructor --------------------------------------------
111 
112         /**
113          * Empty default constructor to make javadoc happy
114          * @stable ICU 2.4
115          */
116         public Element()
117         {
118         }
119     }
120 
121     // public methods -------------------------------------------------
122 
123     /**
124     * <p>Gets the next maximal result range with a common value and returns
125     * true if we are not at the end of the iteration, false otherwise.</p>
126     * <p>If the return boolean is a false, the contents of elements will not
127     * be updated.</p>
128     * @param element for storing the result range and value
129     * @return true if we are not at the end of the iteration, false otherwise.
130     * @see Element
131     * @stable ICU 2.6
132     */
133     public boolean next(Element element);
134 
135     /**
136     * Resets the iterator to the beginning of the iteration.
137     * @stable ICU 2.6
138     */
139     public void reset();
140 }