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