StringUCharacterIterator


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 }
227
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags