jars/icu4j-52_1/main/classes/core/src/com/ibm/icu/impl/StringUCharacterIterator.java

   1 /*
   2  *******************************************************************************
   3  * Copyright (C) 1996-2006, International Business Machines Corporation and    *
   4  * others. All Rights Reserved.                                                *
   5  *******************************************************************************
   6  */
   7 package com.ibm.icu.impl;
   8
   9 import com.ibm.icu.text.UCharacterIterator;
  10
  11 /**
  12  * Used by Collation. UCharacterIterator on Strings. Can't use
  13  * ReplaceableUCharacterIterator because it is not easy to do a fast setText.
  14  * @author synwee
  15  */
  16 // TODO: Investivate if setText is a feature required by users so that we can
  17 // move this method to the base class!
  18 public final class StringUCharacterIterator extends UCharacterIterator
  19 {
  20
  21     // public constructor ------------------------------------------------------
  22
  23     /**
  24      * Public constructor
  25      * @param str text which the iterator will be based on
  26      */
  27     public StringUCharacterIterator(String str)
  28     {
  29         if (str == null) {
  30             throw new IllegalArgumentException();
  31         }
  32         m_text_ = str;
  33         m_currentIndex_ = 0;
  34     }
  35
  36     /**
  37      * Public default constructor
  38      */
  39     public StringUCharacterIterator()
  40     {
  41         m_text_ = "";
  42         m_currentIndex_ = 0;
  43     }
  44
  45     // public methods ----------------------------------------------------------
  46
  47     /**
  48      * Creates a copy of this iterator, does not clone the underlying
  49      * <code>String</code>object
  50      * @return copy of this iterator
  51      */
  52     ///CLOVER:OFF
  53     public Object clone()
  54     {
  55         try {
  56             return super.clone();
  57         } catch (CloneNotSupportedException e) {
  58             return null; // never invoked
  59         }
  60     }
  61     ///CLOVER:ON
  62     /**
  63      * Returns the current UTF16 character.
  64      * @return current UTF16 character
  65      */
  66     public int current()
  67     {
  68         if (m_currentIndex_ < m_text_.length()) {
  69             return m_text_.charAt(m_currentIndex_);
  70         }
  71         return DONE;
  72     }
  73
  74
  75     /**
  76      * Returns the length of the text
  77      * @return length of the text
  78      */
  79     public int getLength()
  80     {
  81         return m_text_.length();
  82     }
  83
  84     /**
  85      * Gets the current currentIndex in text.
  86      * @return current currentIndex in text.
  87      */
  88     public int getIndex()
  89     {
  90         return m_currentIndex_;
  91     }
  92
  93     /**
  94      * Returns next UTF16 character and increments the iterator's currentIndex
  95      * by 1.
  96      * If the resulting currentIndex is greater or equal to the text length,
  97      * the currentIndex is reset to the text length and a value of DONE is
  98      * returned.
  99      * @return next UTF16 character in text or DONE if the new currentIndex is
 100      *         off the end of the text range.
 101      */
 102     public int next()
 103     {
 104         if (m_currentIndex_ < m_text_.length())
 105         {
 106             return m_text_.charAt(m_currentIndex_ ++);
 107         }
 108         return DONE;
 109     }
 110
 111
 112     /**
 113      * Returns previous UTF16 character and decrements the iterator's
 114      * currentIndex by 1.
 115      * If the resulting currentIndex is less than 0, the currentIndex is reset
 116      * to 0 and a value of DONE is returned.
 117      * @return next UTF16 character in text or DONE if the new currentIndex is
 118      *         off the start of the text range.
 119      */
 120     public int previous()
 121     {
 122         if (m_currentIndex_ > 0) {
 123             return m_text_.charAt(-- m_currentIndex_);
 124         }
 125         return DONE;
 126     }
 127
 128     /**
 129      * <p>Sets the currentIndex to the specified currentIndex in the text and
 130      * returns that single UTF16 character at currentIndex.
 131      * This assumes the text is stored as 16-bit code units.</p>
 132      * @param currentIndex the currentIndex within the text.
 133      * @exception IndexOutOfBoundsException is thrown if an invalid currentIndex
 134      *            is supplied. i.e. currentIndex is out of bounds.
 135      */
 136     public void setIndex(int currentIndex) throws IndexOutOfBoundsException
 137     {
 138         if (currentIndex < 0 || currentIndex > m_text_.length()) {
 139             throw new IndexOutOfBoundsException();
 140         }
 141         m_currentIndex_ = currentIndex;
 142     }
 143
 144     /**
 145      * Fills the buffer with the underlying text storage of the iterator
 146      * If the buffer capacity is not enough a exception is thrown. The capacity
 147      * of the fill in buffer should at least be equal to length of text in the
 148      * iterator obtained by calling <code>getLength()</code).
 149      * <b>Usage:</b>
 150      *
 151      * <code>
 152      * <pre>
 153      *         UChacterIterator iter = new UCharacterIterator.getInstance(text);
 154      *         char[] buf = new char[iter.getLength()];
 155      *         iter.getText(buf);
 156      *
 157      *         OR
 158      *         char[] buf= new char[1];
 159      *         int len = 0;
 160      *         for(;;){
 161      *             try{
 162      *                 len = iter.getText(buf);
 163      *                 break;
 164      *             }catch(IndexOutOfBoundsException e){
 165      *                 buf = new char[iter.getLength()];
 166      *             }
 167      *         }
 168      * </pre>
 169      * </code>
 170      *
 171      * @param fillIn an array of chars to fill with the underlying UTF-16 code
 172      *         units.
 173      * @param offset the position within the array to start putting the data.
 174      * @return the number of code units added to fillIn, as a convenience
 175      * @exception IndexOutOfBoundsException exception if there is not enough
 176      *            room after offset in the array, or if offset &lt; 0.
 177      */
 178     ///CLOVER:OFF
 179     public int getText(char[] fillIn, int offset)
 180     {
 181         int length = m_text_.length();
 182         if (offset < 0 || offset + length > fillIn.length) {
 183             throw new IndexOutOfBoundsException(Integer.toString(length));
 184         }
 185         m_text_.getChars(0, length, fillIn, offset);
 186         return length;
 187     }
 188     ///CLOVER:ON
 189     /**
 190      * Convenience method for returning the underlying text storage as as
 191      * string
 192      * @return the underlying text storage in the iterator as a string
 193      */
 194     public String getText()
 195     {
 196         return m_text_;
 197     }
 198
 199     /**
 200      * Reset this iterator to point to a new string. This method is used by
 201      * other classes that want to avoid allocating new
 202      * ReplaceableCharacterIterator objects every time their setText method
 203      * is called.
 204      * @param text The String to be iterated over
 205      */
 206     public void setText(String text)
 207     {
 208         if (text == null) {
 209             throw new NullPointerException();
 210         }
 211         m_text_ = text;
 212         m_currentIndex_ = 0;
 213     }
 214
 215     // private data members ----------------------------------------------------
 216
 217     /**
 218      * Text string object
 219      */
 220     private String m_text_;
 221     /**
 222      * Current currentIndex
 223      */
 224     private int m_currentIndex_;
 225
 226 }