libjava/java/util/StringTokenizer.java

   1 /* java.util.StringTokenizer
   2    Copyright (C) 1998, 1999, 2001 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 As a special exception, if you link this library with other files to
  22 produce an executable, this library does not by itself cause the
  23 resulting executable to be covered by the GNU General Public License.
  24 This exception does not however invalidate any other reasons why the
  25 executable file might be covered by the GNU General Public License. */
  26
  27
  28 package java.util;
  29
  30 /**
  31  * This class splits a string into tokens.  The caller can set on which
  32  * delimiters the string should be split and if the delimiters should be
  33  * returned.
  34  *
  35  * You may change the delimiter set on the fly by calling
  36  * nextToken(String).  But the semantic is quite difficult; it even
  37  * depends on calling <code>hasMoreTokens()</code>.  You should call
  38  * <code>hasMoreTokens()</code> before, otherwise the old delimiters
  39  * after the last token are returned.
  40  *
  41  * If you want to get the delimiters, you have to use the three argument
  42  * constructor.  The delimiters are returned as token consisting of a
  43  * single character.
  44  *
  45  * @author Jochen Hoenicke
  46  * @author Warren Levy <warrenl@cygnus.com>
  47  */
  48 public class StringTokenizer implements Enumeration
  49 {
  50   /**
  51    * The position in the str, where we currently are.
  52    */
  53   private int pos;
  54   /**
  55    * The string that should be split into tokens.
  56    */
  57   private String str;
  58   /**
  59    * The string containing the delimiter characters.
  60    */
  61   private String delim;
  62   /**
  63    * Tells, if we should return the delimiters.
  64    */
  65   private boolean retDelims;
  66
  67   /*{
  68      invariant {
  69      pos >= 0 :: "position is negative";
  70      pos <= str.length() :: "position is out of string";
  71      str != null :: "String is null";
  72      delim != null :: "Delimiters are null";
  73      }
  74      } */
  75
  76   /**
  77    * Creates a new StringTokenizer for the string <code>str</code>,
  78    * that should split on the default delimiter set (space, tap,
  79    * newline, return and formfeed), and which doesn't return the
  80    * delimiters.
  81    * @param str The string to split.
  82    */
  83   public StringTokenizer(String str)
  84     /*{ require { str != null :: "str must not be null"; } } */
  85   {
  86     this(str, " \t\n\r\f", false);
  87   }
  88
  89   /**
  90    * Create a new StringTokenizer, that splits the given string on
  91    * the given delimiter characters.  It doesn't return the delimiter
  92    * characters.
  93    *
  94    * @param str The string to split.
  95    * @param delim A string containing all delimiter characters.
  96    */
  97   public StringTokenizer(String str, String delim)
  98     /*{ require { str != null :: "str must not be null";
  99        delim != null :: "delim must not be null"; } } */
 100   {
 101     this(str, delim, false);
 102   }
 103
 104   /**
 105    * Create a new StringTokenizer, that splits the given string on
 106    * the given delimiter characters.  If you set
 107    * <code>returnDelims</code> to <code>true</code>, the delimiter
 108    * characters are returned as tokens of their own.  The delimiter
 109    * tokens always consist of a single character.
 110    *
 111    * @param str The string to split.
 112    * @param delim A string containing all delimiter characters.
 113    * @param returnDelims Tells, if you want to get the delimiters.
 114    */
 115   public StringTokenizer(String str, String delim, boolean returnDelims)
 116     /*{ require { str != null :: "str must not be null";
 117        delim != null :: "delim must not be null"; } } */
 118   {
 119     this.str = str;
 120     this.delim = delim;
 121     this.retDelims = returnDelims;
 122     this.pos = 0;
 123   }
 124
 125   /**
 126    * Tells if there are more tokens.
 127    * @return True, if the next call of nextToken() succeeds, false otherwise.
 128    */
 129   public boolean hasMoreTokens()
 130   {
 131     if (!retDelims)
 132       {
 133         while (pos < str.length() && delim.indexOf(str.charAt(pos)) > -1)
 134           {
 135             pos++;
 136           }
 137       }
 138     return pos < str.length();
 139   }
 140
 141   /**
 142    * Returns the nextToken, changing the delimiter set to the given
 143    * <code>delim</code>.  The change of the delimiter set is
 144    * permanent, ie. the next call of nextToken(), uses the same
 145    * delimiter set.
 146    * @param delim a string containing the new delimiter characters.
 147    * @return the next token with respect to the new delimiter characters.
 148    * @exception NoSuchElementException if there are no more tokens.
 149    */
 150   public String nextToken(String delim) throws NoSuchElementException
 151     /*{ require { hasMoreTokens() :: "no more Tokens available";
 152        ensure { $return != null && $return.length() > 0; } } */
 153   {
 154     this.delim = delim;
 155     return nextToken();
 156   }
 157
 158   /**
 159    * Returns the nextToken of the string.
 160    * @param delim a string containing the new delimiter characters.
 161    * @return the next token with respect to the new delimiter characters.
 162    * @exception NoSuchElementException if there are no more tokens.
 163    */
 164   public String nextToken() throws NoSuchElementException
 165     /*{ require { hasMoreTokens() :: "no more Tokens available";
 166        ensure { $return != null && $return.length() > 0; } } */
 167   {
 168     if (pos < str.length() && delim.indexOf(str.charAt(pos)) > -1)
 169       {
 170         if (retDelims)
 171           return str.substring(pos, ++pos);
 172
 173         while (++pos < str.length() && delim.indexOf(str.charAt(pos)) > -1)
 174           {
 175             /* empty */
 176           }
 177       }
 178     if (pos < str.length())
 179       {
 180         int start = pos;
 181         while (++pos < str.length() && delim.indexOf(str.charAt(pos)) == -1)
 182           {
 183             /* empty */
 184           }
 185         return str.substring(start, pos);
 186       }
 187     throw new NoSuchElementException();
 188   }
 189
 190   /**
 191    * This does the same as hasMoreTokens. This is the
 192    * <code>Enumeration</code interface method.
 193    * @return True, if the next call of nextElement() succeeds, false
 194    * otherwise.
 195    * @see #hasMoreTokens
 196    */
 197   public boolean hasMoreElements()
 198   {
 199     return hasMoreTokens();
 200   }
 201
 202   /**
 203    * This does the same as nextTokens. This is the
 204    * <code>Enumeration</code interface method.
 205    * @return the next token with respect to the new delimiter characters.
 206    * @exception NoSuchElementException if there are no more tokens.
 207    * @see #nextToken
 208    */
 209   public Object nextElement() throws NoSuchElementException
 210   {
 211     return nextToken();
 212   }
 213
 214   /**
 215    * This counts the number of remaining tokens in the string, with
 216    * respect to the current delimiter set.
 217    * @return the number of times <code>nextTokens()</code> will
 218    * succeed.
 219    * @see #nextToken
 220    */
 221   public int countTokens()
 222   {
 223     int count = 0;
 224     int delimiterCount = 0;
 225     boolean tokenFound = false;         // Set when a non-delimiter is found
 226     int tmpPos = pos;
 227
 228     // Note for efficiency, we count up the delimiters rather than check
 229     // retDelims every time we encounter one.  That way, we can
 230     // just do the conditional once at the end of the method
 231     while (tmpPos < str.length())
 232       {
 233         if (delim.indexOf(str.charAt(tmpPos++)) > -1)
 234           {
 235             if (tokenFound)
 236               {
 237                 // Got to the end of a token
 238                 count++;
 239                 tokenFound = false;
 240               }
 241
 242             delimiterCount++;           // Increment for this delimiter
 243           }
 244         else
 245           {
 246             tokenFound = true;
 247
 248             // Get to the end of the token
 249             while (tmpPos < str.length()
 250                    && delim.indexOf(str.charAt(tmpPos)) == -1)
 251               ++tmpPos;
 252           }
 253       }
 254
 255     // Make sure to count the last token
 256     if (tokenFound)
 257       count++;
 258
 259     // if counting delmiters add them into the token count
 260     return retDelims ? count + delimiterCount : count;
 261   }
 262 }