libjava/java/util/StringTokenizer.java

   1 /* StringTokenizer -- breaks a String into tokens
   2    Copyright (C) 1998, 1999, 2001, 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.util;
  40
  41 /**
  42  * This class splits a string into tokens.  The caller can set on which
  43  * delimiters the string should be split and if the delimiters should be
  44  * returned. This is much simpler than {@link java.io.StreamTokenizer}.
  45  *
  46  * <p>You may change the delimiter set on the fly by calling
  47  * nextToken(String).  But the semantic is quite difficult; it even
  48  * depends on calling <code>hasMoreTokens()</code>.  You should call
  49  * <code>hasMoreTokens()</code> before, otherwise the old delimiters
  50  * after the last token are candidates for being returned.
  51  *
  52  * <p>If you want to get the delimiters, you have to use the three argument
  53  * constructor.  The delimiters are returned as token consisting of a
  54  * single character.
  55  *
  56  * @author Jochen Hoenicke
  57  * @author Warren Levy (warrenl@cygnus.com)
  58  * @see java.io.StreamTokenizer
  59  * @status updated to 1.4
  60  */
  61 public class StringTokenizer implements Enumeration
  62 {
  63   // WARNING: StringTokenizer is a CORE class in the bootstrap cycle. See the
  64   // comments in vm/reference/java/lang/Runtime for implications of this fact.
  65
  66   /**
  67    * The position in the str, where we currently are.
  68    */
  69   private int pos;
  70
  71   /**
  72    * The string that should be split into tokens.
  73    */
  74   private final String str;
  75
  76   /**
  77    * The length of the string.
  78    */
  79   private final int len;
  80
  81   /**
  82    * The string containing the delimiter characters.
  83    */
  84   private String delim;
  85
  86   /**
  87    * Tells, if we should return the delimiters.
  88    */
  89   private final boolean retDelims;
  90
  91   /**
  92    * Creates a new StringTokenizer for the string <code>str</code>,
  93    * that should split on the default delimiter set (space, tab,
  94    * newline, return and formfeed), and which doesn't return the
  95    * delimiters.
  96    *
  97    * @param str The string to split
  98    * @throws NullPointerException if str is null
  99    */
 100   public StringTokenizer(String str)
 101   {
 102     this(str, " \t\n\r\f", false);
 103   }
 104
 105   /**
 106    * Create a new StringTokenizer, that splits the given string on
 107    * the given delimiter characters.  It doesn't return the delimiter
 108    * characters.
 109    *
 110    * @param str the string to split
 111    * @param delim a string containing all delimiter characters
 112    * @throws NullPointerException if either argument is null
 113    */
 114   public StringTokenizer(String str, String delim)
 115   {
 116     this(str, delim, false);
 117   }
 118
 119   /**
 120    * Create a new StringTokenizer, that splits the given string on
 121    * the given delimiter characters.  If you set
 122    * <code>returnDelims</code> to <code>true</code>, the delimiter
 123    * characters are returned as tokens of their own.  The delimiter
 124    * tokens always consist of a single character.
 125    *
 126    * @param str the string to split
 127    * @param delim a string containing all delimiter characters
 128    * @param returnDelims tells, if you want to get the delimiters
 129    * @throws NullPointerException if str or delim is null
 130    */
 131   public StringTokenizer(String str, String delim, boolean returnDelims)
 132   {
 133     len = str.length();
 134     this.str = str;
 135     // The toString() hack causes the NullPointerException.
 136     this.delim = delim.toString();
 137     this.retDelims = returnDelims;
 138     this.pos = 0;
 139   }
 140
 141   /**
 142    * Tells if there are more tokens.
 143    *
 144    * @return true if the next call of nextToken() will succeed
 145    */
 146   public boolean hasMoreTokens()
 147   {
 148     if (! retDelims)
 149       {
 150         while (pos < len && delim.indexOf(str.charAt(pos)) >= 0)
 151           pos++;
 152       }
 153     return pos < len;
 154   }
 155
 156   /**
 157    * Returns the nextToken, changing the delimiter set to the given
 158    * <code>delim</code>.  The change of the delimiter set is
 159    * permanent, ie. the next call of nextToken(), uses the same
 160    * delimiter set.
 161    *
 162    * @param delim a string containing the new delimiter characters
 163    * @return the next token with respect to the new delimiter characters
 164    * @throws NoSuchElementException if there are no more tokens
 165    * @throws NullPointerException if delim is null
 166    */
 167   public String nextToken(String delim) throws NoSuchElementException
 168   {
 169     this.delim = delim;
 170     return nextToken();
 171   }
 172
 173   /**
 174    * Returns the nextToken of the string.
 175    *
 176    * @return the next token with respect to the current delimiter characters
 177    * @throws NoSuchElementException if there are no more tokens
 178    */
 179   public String nextToken() throws NoSuchElementException
 180   {
 181     if (pos < len && delim.indexOf(str.charAt(pos)) >= 0)
 182       {
 183         if (retDelims)
 184           return str.substring(pos, ++pos);
 185         while (++pos < len && delim.indexOf(str.charAt(pos)) >= 0);
 186       }
 187     if (pos < len)
 188       {
 189         int start = pos;
 190         while (++pos < len && delim.indexOf(str.charAt(pos)) < 0);
 191
 192         return str.substring(start, pos);
 193       }
 194     throw new NoSuchElementException();
 195   }
 196
 197   /**
 198    * This does the same as hasMoreTokens. This is the
 199    * <code>Enumeration</code> interface method.
 200    *
 201    * @return true, if the next call of nextElement() will succeed
 202    * @see #hasMoreTokens()
 203    */
 204   public boolean hasMoreElements()
 205   {
 206     return hasMoreTokens();
 207   }
 208
 209   /**
 210    * This does the same as nextTokens. This is the
 211    * <code>Enumeration</code> interface method.
 212    *
 213    * @return the next token with respect to the current delimiter characters
 214    * @throws NoSuchElementException if there are no more tokens
 215    * @see #nextToken()
 216    */
 217   public Object nextElement() throws NoSuchElementException
 218   {
 219     return nextToken();
 220   }
 221
 222   /**
 223    * This counts the number of remaining tokens in the string, with
 224    * respect to the current delimiter set.
 225    *
 226    * @return the number of times <code>nextTokens()</code> will succeed
 227    * @see #nextToken()
 228    */
 229   public int countTokens()
 230   {
 231     int count = 0;
 232     int delimiterCount = 0;
 233     boolean tokenFound = false; // Set when a non-delimiter is found
 234     int tmpPos = pos;
 235
 236     // Note for efficiency, we count up the delimiters rather than check
 237     // retDelims every time we encounter one.  That way, we can
 238     // just do the conditional once at the end of the method
 239     while (tmpPos < len)
 240       {
 241         if (delim.indexOf(str.charAt(tmpPos++)) >= 0)
 242           {
 243             if (tokenFound)
 244               {
 245                 // Got to the end of a token
 246                 count++;
 247                 tokenFound = false;
 248               }
 249             delimiterCount++; // Increment for this delimiter
 250           }
 251         else
 252           {
 253             tokenFound = true;
 254             // Get to the end of the token
 255             while (tmpPos < len
 256                    && delim.indexOf(str.charAt(tmpPos)) < 0)
 257               ++tmpPos;
 258           }
 259       }
 260
 261     // Make sure to count the last token
 262     if (tokenFound)
 263       count++;
 264
 265     // if counting delmiters add them into the token count
 266     return retDelims ? count + delimiterCount : count;
 267   }
 268 } // class StringTokenizer