jars/icu4j-4_4_2-src/main/classes/core/src/com/ibm/icu/impl/StringUCharacterIterator.java

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