jars/icu4j-4_4_2-src/main/classes/core/src/com/ibm/icu/util/RangeValueIterator.java

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