jars/icu4j-52_1/main/classes/core/src/com/ibm/icu/util/RangeValueIterator.java

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