home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / util / StringTokenizer.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  9.0 KB  |  272 lines
  1. /*
  2.  * @(#)StringTokenizer.java    1.19 98/03/18
  3.  *
  4.  * Copyright 1994-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.util;
  16.  
  17. import java.lang.*;
  18.  
  19. /**
  20.  * The string tokenizer class allows an application to break a 
  21.  * string into tokens. The tokenization method is much simpler than 
  22.  * the one used by the <code>StreamTokenizer</code> class. The 
  23.  * <code>StringTokenizer</code> methods do not distinguish among 
  24.  * identifiers, numbers, and quoted strings, nor do they recognize 
  25.  * and skip comments. 
  26.  * <p>
  27.  * The set of delimiters (the characters that separate tokens) may 
  28.  * be specified either at creation time or on a per-token basis. 
  29.  * <p>
  30.  * An instance of <code>StringTokenizer</code> behaves in one of two 
  31.  * ways, depending on whether it was created with the 
  32.  * <code>returnTokens</code> flag having the value <code>true</code> 
  33.  * or <code>false</code>: 
  34.  * <ul>
  35.  * <li>If the flag is <code>false</code>, delimiter characters serve to 
  36.  *     separate tokens. A token is a maximal sequence of consecutive 
  37.  *     characters that are not delimiters. 
  38.  * <li>If the flag is <code>true</code>, delimiter characters are themselves 
  39.  *     considered to be tokens. A token is thus either one delimiter 
  40.  *     character, or a maximal sequence of consecutive characters that are 
  41.  *     not delimiters.
  42.  * </ul><p>
  43.  * A <tt>StringTokenizer</tt> object internally maintains a current 
  44.  * position within the string to be tokenized. Some operations advance this 
  45.  * current position past the characters processed.<p>
  46.  * A token is returned by taking a substring of the string that was used to 
  47.  * create the <tt>StringTokenizer</tt> object.
  48.  * <p>
  49.  * The following is one example of the use of the tokenizer. The code:
  50.  * <blockquote><pre>
  51.  *     StringTokenizer st = new StringTokenizer("this is a test");
  52.  *     while (st.hasMoreTokens()) {
  53.  *         println(st.nextToken());
  54.  *     }
  55.  * </pre></blockquote>
  56.  * <p>
  57.  * prints the following output:
  58.  * <blockquote><pre>
  59.  *     this
  60.  *     is
  61.  *     a
  62.  *     test
  63.  * </pre></blockquote>
  64.  *
  65.  * @author  unascribed
  66.  * @version 1.19, 03/18/98
  67.  * @see     java.io.StreamTokenizer
  68.  * @since   JDK1.0
  69.  */
  70. public
  71. class StringTokenizer implements Enumeration {
  72.     private int currentPosition;
  73.     private int maxPosition;
  74.     private String str;
  75.     private String delimiters;
  76.     private boolean retTokens;
  77.  
  78.     /**
  79.      * Constructs a string tokenizer for the specified string. All  
  80.      * characters in the <code>delim</code> argument are the delimiters 
  81.      * for separating tokens. 
  82.      * <p>
  83.      * If the <code>returnTokens</code> flag is <code>true</code>, then 
  84.      * the delimiter characters are also returned as tokens. Each 
  85.      * delimiter is returned as a string of length one. If the flag is 
  86.      * <code>false</code>, the delimiter characters are skipped and only 
  87.      * serve as separators between tokens. 
  88.      *
  89.      * @param   str            a string to be parsed.
  90.      * @param   delim          the delimiters.
  91.      * @param   returnTokens   flag indicating whether to return the delimiters
  92.      *                         as tokens.
  93.      */
  94.     public StringTokenizer(String str, String delim, boolean returnTokens) {
  95.     currentPosition = 0;
  96.     this.str = str;
  97.     maxPosition = str.length();
  98.     delimiters = delim;
  99.     retTokens = returnTokens;
  100.     }
  101.  
  102.     /**
  103.      * Constructs a string tokenizer for the specified string. The 
  104.      * characters in the <code>delim</code> argument are the delimiters 
  105.      * for separating tokens. Delimiter characters themselves will not 
  106.      * be treated as tokens.
  107.      *
  108.      * @param   str     a string to be parsed.
  109.      * @param   delim   the delimiters.
  110.      */
  111.     public StringTokenizer(String str, String delim) {
  112.     this(str, delim, false);
  113.     }
  114.  
  115.     /**
  116.      * Constructs a string tokenizer for the specified string. The 
  117.      * tokenizer uses the default delimiter set, which is 
  118.      * <code>"\t\n\r\f"</code>: the space character, the tab
  119.      * character, the newline character, the carriage-return character,
  120.      * and the form-feed character. Delimiter characters themselves will 
  121.      * not be treated as tokens.
  122.      *
  123.      * @param   str   a string to be parsed.
  124.      */
  125.     public StringTokenizer(String str) {
  126.     this(str, " \t\n\r\f", false);
  127.     }
  128.  
  129.     /**
  130.      * Skips delimiters.
  131.      */
  132.     private void skipDelimiters() {
  133.     while (!retTokens &&
  134.            (currentPosition < maxPosition) &&
  135.            (delimiters.indexOf(str.charAt(currentPosition)) >= 0)) {
  136.         currentPosition++;
  137.     }
  138.     }
  139.  
  140.     /**
  141.      * Tests if there are more tokens available from this tokenizer's string. 
  142.      * If this method returns <tt>true</tt>, then a subsequent call to 
  143.      * <tt>nextToken</tt> with no argument will successfully return a token.
  144.      *
  145.      * @return  <code>true</code> if and only if there is at least one token 
  146.      *          in the string after the current position; <code>false</code> 
  147.      *          otherwise.
  148.      */
  149.     public boolean hasMoreTokens() {
  150.     skipDelimiters();
  151.     return (currentPosition < maxPosition);
  152.     }
  153.  
  154.     /**
  155.      * Returns the next token from this string tokenizer.
  156.      *
  157.      * @return     the next token from this string tokenizer.
  158.      * @exception  NoSuchElementException  if there are no more tokens in this
  159.      *               tokenizer's string.
  160.      */
  161.     public String nextToken() {
  162.     skipDelimiters();
  163.  
  164.     if (currentPosition >= maxPosition) {
  165.         throw new NoSuchElementException();
  166.     }
  167.  
  168.     int start = currentPosition;
  169.     while ((currentPosition < maxPosition) && 
  170.            (delimiters.indexOf(str.charAt(currentPosition)) < 0)) {
  171.         currentPosition++;
  172.     }
  173.     if (retTokens && (start == currentPosition) &&
  174.         (delimiters.indexOf(str.charAt(currentPosition)) >= 0)) {
  175.         currentPosition++;
  176.     }
  177.     return str.substring(start, currentPosition);
  178.     }
  179.  
  180.     /**
  181.      * Returns the next token in this string tokenizer's string. First, 
  182.      * the set of characters considered to be delimiters by this 
  183.      * <tt>StringTokenizer</tt> object is changed to be the characters in 
  184.      * the string <tt>delim</tt>. Then the next token in the string
  185.      * after the current position is returned. The current position is 
  186.      * advanced beyond the recognized token.  The new delimiter set 
  187.      * remains the default after this call. 
  188.      *
  189.      * @param      delim   the new delimiters.
  190.      * @return     the next token, after switching to the new delimiter set.
  191.      * @exception  NoSuchElementException  if there are no more tokens in this
  192.      *               tokenizer's string.
  193.      */
  194.     public String nextToken(String delim) {
  195.     delimiters = delim;
  196.     return nextToken();
  197.     }
  198.  
  199.     /**
  200.      * Returns the same value as the <code>hasMoreTokens</code>
  201.      * method. It exists so that this class can implement the
  202.      * <code>Enumeration</code> interface. 
  203.      *
  204.      * @return  <code>true</code> if there are more tokens;
  205.      *          <code>false</code> otherwise.
  206.      * @see     java.util.Enumeration
  207.      * @see     java.util.StringTokenizer#hasMoreTokens()
  208.      */
  209.     public boolean hasMoreElements() {
  210.     return hasMoreTokens();
  211.     }
  212.  
  213.     /**
  214.      * Returns the same value as the <code>nextToken</code> method,
  215.      * except that its declared return value is <code>Object</code> rather than
  216.      * <code>String</code>. It exists so that this class can implement the
  217.      * <code>Enumeration</code> interface. 
  218.      *
  219.      * @return     the next token in the string.
  220.      * @exception  NoSuchElementException  if there are no more tokens in this
  221.      *               tokenizer's string.
  222.      * @see        java.util.Enumeration
  223.      * @see        java.util.StringTokenizer#nextToken()
  224.      */
  225.     public Object nextElement() {
  226.     return nextToken();
  227.     }
  228.  
  229.     /**
  230.      * Calculates the number of times that this tokenizer's 
  231.      * <code>nextToken</code> method can be called before it generates an 
  232.      * exception. The current position is not advanced.
  233.      *
  234.      * @return  the number of tokens remaining in the string using the current
  235.      *          delimiter set.
  236.      * @see     java.util.StringTokenizer#nextToken()
  237.      */
  238.     public int countTokens() {
  239.     int count = 0;
  240.     int currpos = currentPosition;
  241.  
  242.     while (currpos < maxPosition) {
  243.         /*
  244.          * This is just skipDelimiters(); but it does not affect
  245.          * currentPosition.
  246.          */
  247.         while (!retTokens &&
  248.            (currpos < maxPosition) &&
  249.            (delimiters.indexOf(str.charAt(currpos)) >= 0)) {
  250.         currpos++;
  251.         }
  252.  
  253.         if (currpos >= maxPosition) {
  254.         break;
  255.         }
  256.  
  257.         int start = currpos;
  258.         while ((currpos < maxPosition) && 
  259.            (delimiters.indexOf(str.charAt(currpos)) < 0)) {
  260.         currpos++;
  261.         }
  262.         if (retTokens && (start == currpos) &&
  263.         (delimiters.indexOf(str.charAt(currpos)) >= 0)) {
  264.         currpos++;
  265.         }
  266.         count++;
  267.  
  268.     }
  269.     return count;
  270.     }
  271. }
  272.