src/gnu/regexp/REMatchEnumeration.java

   1 /*
   2  *  gnu/regexp/REMatchEnumeration.java
   3  *  Copyright (C) 1998-2001 Wes Biggs
   4  *
   5  *  This library is free software; you can redistribute it and/or modify
   6  *  it under the terms of the GNU Lesser General Public License as published
   7  *  by the Free Software Foundation; either version 2.1 of the License, or
   8  *  (at your option) any later version.
   9  *
  10  *  This library is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  *  GNU Lesser General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU Lesser General Public License
  16  *  along with this program; if not, write to the Free Software
  17  *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18  */
  19 package gnu.regexp;
  20 import java.io.Serializable;
  21 import java.util.Enumeration;
  22 import java.util.NoSuchElementException;
  23
  24 /**
  25  * An REMatchEnumeration enumerates regular expression matches over a
  26  * given input text.  You obtain a reference to an enumeration using
  27  * the <code>getMatchEnumeration()</code> methods on an instance of
  28  * RE.
  29  *
  30  * <P>
  31  *
  32  * REMatchEnumeration does lazy computation; that is, it will not
  33  * search for a match until it needs to.  If you'd rather just get all
  34  * the matches at once in a big array, use the
  35  * <code>getAllMatches()</code> methods on RE.  However, using an
  36  * enumeration can help speed performance when the entire text does
  37  * not need to be searched immediately.
  38  *
  39  * <P>
  40  *
  41  * The enumerated type is especially useful when searching on a Reader
  42  * or InputStream, because the InputStream read position cannot be
  43  * guaranteed after calling <code>getMatch()</code> (see the
  44  * description of that method for an explanation of why).  Enumeration
  45  * also saves a lot of overhead required when calling
  46  * <code>getMatch()</code> multiple times.
  47  *
  48  * @author <A HREF="mailto:wes@cacas.org">Wes Biggs</A>
  49  */
  50 public class REMatchEnumeration implements Enumeration, Serializable {
  51   private static final int YES = 1;
  52   private static final int MAYBE = 0;
  53   private static final int NO = -1;
  54
  55   private int more;
  56   private REMatch match;
  57   private RE expr;
  58   private CharIndexed input;
  59   private int eflags;
  60     private int index;
  61
  62   // Package scope constructor is used by RE.getMatchEnumeration()
  63   REMatchEnumeration(RE expr, CharIndexed input, int index, int eflags) {
  64     more = MAYBE;
  65     this.expr = expr;
  66     this.input = input;
  67     this.index = index;
  68     this.eflags = eflags;
  69   }
  70
  71   /** Returns true if there are more matches in the input text. */
  72   public boolean hasMoreElements() {
  73     return hasMoreMatches(null);
  74   }
  75
  76   /** Returns true if there are more matches in the input text. */
  77   public boolean hasMoreMatches() {
  78     return hasMoreMatches(null);
  79   }
  80
  81   /** Returns true if there are more matches in the input text.
  82    * Saves the text leading up to the match (or to the end of the input)
  83    * in the specified buffer.
  84    */
  85   public boolean hasMoreMatches(StringBuffer buffer) {
  86     if (more == MAYBE) {
  87         match = expr.getMatchImpl(input,index,eflags,buffer);
  88         if (match != null) {
  89             input.move((match.end[0] > 0) ? match.end[0] : 1);
  90
  91             index = (match.end[0] > 0) ? match.end[0] + match.offset : index + 1;
  92             more = YES;
  93         } else more = NO;
  94     }
  95     return (more == YES);
  96   }
  97
  98   /** Returns the next match in the input text. */
  99   public Object nextElement() throws NoSuchElementException {
 100     return nextMatch();
 101   }
 102
 103   /**
 104    * Returns the next match in the input text. This method is provided
 105    * for convenience to avoid having to explicitly cast the return value
 106    * to class REMatch.
 107    */
 108   public REMatch nextMatch() throws NoSuchElementException {
 109     if (hasMoreElements()) {
 110         more = (input.isValid()) ? MAYBE : NO;
 111         return match;
 112     }
 113     throw new NoSuchElementException();
 114   }
 115 }
 116