jars/icu4j-4_4_2-src/main/classes/core/src/com/ibm/icu/util/ValueIterator.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, Object>, where\r
  12  * int is the sorted integer index in ascending order, and Object its\r
  13  * associated value.</p>\r
  14  * <p>The ValueIterator allows iterations over integer indexes in the range\r
  15  * of Integer.MIN_VALUE to Integer.MAX_VALUE inclusive. Implementations of\r
  16  * ValueIterator should specify their own maximum subrange within the above\r
  17  * range that is meaningful to its applications.</p>\r
  18  * <p>Most implementations will be created by factory methods, such as the\r
  19  * character name iterator in UCharacter.getNameIterator. See example below.\r
  20  * </p>\r
  21  * Example of use:<br>\r
  22  * <pre>\r
  23  * ValueIterator iterator = UCharacter.getNameIterator();\r
  24  * ValueIterator.Element result = new ValueIterator.Element();\r
  25  * iterator.setRange(UCharacter.MIN_VALUE, UCharacter.MAX_VALUE);\r
  26  * while (iterator.next(result)) {\r
  27  *     System.out.println("Codepoint \\u" +\r
  28  *                        Integer.toHexString(result.integer) +\r
  29  *                        " has the character name " + (String)result.value);\r
  30  * }\r
  31  * </pre>\r
  32  * @author synwee\r
  33  * @stable ICU 2.6\r
  34  */\r
  35 public interface ValueIterator\r
  36 {\r
  37     // public inner class ---------------------------------------------\r
  38 \r
  39     /**\r
  40     * <p>The return result container of each iteration. Stores the next\r
  41     * integer index and its associated value Object.</p>\r
  42     * @stable ICU 2.6\r
  43     */\r
  44     public static final class Element\r
  45     {\r
  46         // public data members ----------------------------------------\r
  47 \r
  48         /**\r
  49         * Integer index of the current iteration\r
  50         * @stable ICU 2.6\r
  51         */\r
  52         public int integer;\r
  53         /**\r
  54         * Gets the Object value associated with the integer index.\r
  55         * @stable ICU 2.6\r
  56         */\r
  57         public Object value;\r
  58 \r
  59         // public constructor ------------------------------------------\r
  60 \r
  61         /**\r
  62          * Empty default constructor to make javadoc happy\r
  63          * @stable ICU 2.4\r
  64          */\r
  65         public Element()\r
  66         {\r
  67         }\r
  68     }\r
  69 \r
  70     // public methods -------------------------------------------------\r
  71 \r
  72     /**\r
  73     * <p>Returns the next result for this iteration and returns\r
  74     * true if we are not at the end of the iteration, false otherwise.</p>\r
  75     * <p>If this returns a false, the contents of elements will not\r
  76     * be updated.</p>\r
  77     * @param element for storing the result index and value\r
  78     * @return true if we are not at the end of the iteration, false otherwise.\r
  79     * @see Element\r
  80     * @stable ICU 2.6\r
  81     */\r
  82     public boolean next(Element element);\r
  83 \r
  84     /**\r
  85     * <p>Resets the iterator to start iterating from the integer index\r
  86     * Integer.MIN_VALUE or X if a setRange(X, Y) has been called previously.\r
  87     * </p>\r
  88     * @stable ICU 2.6\r
  89     */\r
  90     public void reset();\r
  91 \r
  92     /**\r
  93      * <p>Restricts the range of integers to iterate and resets the iteration\r
  94      * to begin at the index argument start.</p>\r
  95      * <p>If setRange(start, end) is not performed before next(element) is\r
  96      * called, the iteration will start from the integer index\r
  97      * Integer.MIN_VALUE and end at Integer.MAX_VALUE.</p>\r
  98      * <p>\r
  99      * If this range is set outside the meaningful range specified by the\r
 100      * implementation, next(element) will always return false.\r
 101      * </p>\r
 102      * @param start first integer in the range to iterate\r
 103      * @param limit one more than the last integer in the range\r
 104      * @exception IllegalArgumentException thrown when attempting to set an\r
 105      *            illegal range. E.g limit <= start\r
 106      * @stable ICU 2.6\r
 107      */\r
 108     public void setRange(int start, int limit);\r
 109 }\r