001/* PushbackReader.java -- An character stream that can unread chars
002   Copyright (C) 1998, 2000, 2001, 2003, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.io;
040
041/**
042 * This subclass of <code>FilterReader</code> provides the ability to
043 * unread data from a stream.  It maintains an internal buffer of unread
044 * data that is supplied to the next read operation.  This is conceptually
045 * similar to mark/reset functionality, except that in this case the
046 * position to reset the stream to does not need to be known in advance.
047 * <p>
048 * The default pushback buffer size one char, but this can be overridden
049 * by the creator of the stream.
050 *
051 * @author Aaron M. Renn (arenn@urbanophile.com)
052 * @author Warren Levy (warrenl@cygnus.com)
053 */
054public class PushbackReader extends FilterReader
055{
056  /**
057   * This is the default buffer size
058   */
059  private static final int DEFAULT_BUFFER_SIZE = 1;
060
061  /**
062   * This is the buffer that is used to store the pushed back data
063   */
064  private char[] buf;
065
066  /**
067   * This is the position in the buffer from which the next char will be
068   * read.  Bytes are stored in reverse order in the buffer, starting from
069   * <code>buf[buf.length - 1]</code> to <code>buf[0]</code>.  Thus when
070   * <code>pos</code> is 0 the buffer is full and <code>buf.length</code> when
071   * it is empty
072   */
073  private int pos;
074
075  /**
076   * This method initializes a <code>PushbackReader</code> to read from the
077   * specified subordinate <code>Reader</code> with a default pushback buffer
078   * size of 1.
079   *
080   * @param in The subordinate stream to read from
081   */
082  public PushbackReader(Reader in)
083  {
084    this(in, DEFAULT_BUFFER_SIZE);
085  }
086
087  /**
088   * This method initializes a <code>PushbackReader</code> to read from the
089   * specified subordinate <code>Reader</code> with the specified buffer
090   * size
091   *
092   * @param in The subordinate <code>Reader</code> to read from
093   * @param bufsize The pushback buffer size to use
094   */
095  public PushbackReader(Reader in, int bufsize)
096  {
097    super(in);
098
099    if (bufsize < 0)
100      throw new IllegalArgumentException("buffer size must be positive");
101
102    buf = new char[bufsize];
103    pos = bufsize;
104  }
105
106  /**
107   * This method closes the stream and frees any associated resources.
108   *
109   * @exception IOException If an error occurs.
110   */
111  public void close() throws IOException
112  {
113    synchronized (lock)
114      {
115        buf = null;
116        super.close();
117      }
118  }
119
120  /**
121   * This method throws an exception when called since this class does
122   * not support mark/reset.
123   *
124   * @param read_limit Not used.
125   *
126   * @exception IOException Always thrown to indicate mark/reset not supported.
127   */
128  public void mark(int read_limit) throws IOException
129  {
130    throw new IOException("mark not supported in this class");
131  }
132
133  /**
134   * This method returns <code>false</code> to indicate that it does not support
135   * mark/reset functionality.
136   *
137   * @return This method returns <code>false</code> to indicate that this
138   * class does not support mark/reset functionality
139   *
140   */
141  public boolean markSupported()
142  {
143    return(false);
144  }
145
146  /**
147   * This method always throws an IOException in this class because
148   * mark/reset functionality is not supported.
149   *
150   * @exception IOException Always thrown for this class
151   */
152  public void reset() throws IOException
153  {
154    throw new IOException("reset not supported in this class");
155  }
156
157  /**
158   * This method determines whether or not this stream is ready to be read.
159   * If it returns <code>false</code> to indicate that the stream is not
160   * ready, any attempt to read from the stream could (but is not
161   * guaranteed to) block.
162   * <p>
163   * This stream is ready to read if there are either chars waiting to be
164   * read in the pushback buffer or if the underlying stream is ready to
165   * be read.
166   *
167   * @return <code>true</code> if this stream is ready to be read,
168   * <code>false</code> otherwise
169   *
170   * @exception IOException If an error occurs
171   */
172  public boolean ready() throws IOException
173  {
174    synchronized (lock)
175      {
176        if (buf == null)
177          throw new IOException ("stream closed");
178
179        if (((buf.length - pos) > 0) || super.ready())
180          return(true);
181        else
182          return(false);
183      }
184  }
185
186  // Don't delete this method just because the spec says it shouldn't be there!
187  // See the CVS log for details.
188  /**
189    * This method skips the specified number of chars in the stream.  It
190    * returns the actual number of chars skipped, which may be less than the
191    * requested amount.
192    * <p>
193    * This method first discards chars from the buffer, then calls the
194    * <code>skip</code> method on the underlying <code>Reader</code> to
195    * skip additional chars if necessary.
196    *
197    * @param num_chars The requested number of chars to skip
198    *
199    * @return The actual number of chars skipped.
200    *
201    * @exception IOException If an error occurs
202    */
203  public long skip(long num_chars) throws IOException
204  {
205    synchronized (lock)
206      {
207        if (num_chars <= 0)
208          return(0);
209
210        if ((buf.length - pos) >= num_chars)
211          {
212            pos += num_chars;
213            return(num_chars);
214          }
215
216        int chars_discarded = buf.length - pos;
217        pos = buf.length;
218
219        long chars_skipped = in.skip(num_chars - chars_discarded);
220
221        return(chars_discarded + chars_skipped);
222      }
223  }
224
225  /**
226   * This method reads an unsigned char from the input stream and returns it
227   * as an int in the range of 0-65535.  This method also will return -1 if
228   * the end of the stream has been reached.  The char returned will be read
229   * from the pushback buffer, unless the buffer is empty, in which case
230   * the char will be read from the underlying stream.
231   * <p>
232   * This method will block until the char can be read.
233   *
234   * @return The char read or -1 if end of stream
235   *
236   * @exception IOException If an error occurs
237   */
238  public int read() throws IOException
239  {
240    synchronized (lock)
241      {
242        if (buf == null)
243          throw new IOException("stream closed");
244
245        if (pos == buf.length)
246          return(super.read());
247
248        ++pos;
249        return((buf[pos - 1] & 0xFFFF));
250      }
251  }
252
253  /**
254   * This method read chars from a stream and stores them into a caller
255   * supplied buffer.  It starts storing the data at index <code>offset</code>
256   * into
257   * the buffer and attempts to read <code>len</code> chars.  This method can
258   * return before reading the number of chars requested.  The actual number
259   * of chars read is returned as an int.  A -1 is returned to indicate the
260   * end of the stream.
261   *  <p>
262   * This method will block until some data can be read.
263   * <p>
264   * This method first reads chars from the pushback buffer in order to
265   * satisfy the read request.  If the pushback buffer cannot provide all
266   * of the chars requested, the remaining chars are read from the
267   * underlying stream.
268   *
269   * @param buffer The array into which the chars read should be stored
270   * @param offset The offset into the array to start storing chars
271   * @param length The requested number of chars to read
272   *
273   * @return The actual number of chars read, or -1 if end of stream.
274   *
275   * @exception IOException If an error occurs.
276   */
277  public synchronized int read(char[] buffer, int offset, int length)
278    throws IOException
279  {
280    synchronized (lock)
281      {
282        if (buf == null)
283          throw new IOException("stream closed");
284
285        if (offset < 0 || length < 0 || offset + length > buffer.length)
286          throw new ArrayIndexOutOfBoundsException();
287
288        int numBytes = Math.min(buf.length - pos, length);
289        if (numBytes > 0)
290          {
291            System.arraycopy (buf, pos, buffer, offset, numBytes);
292            pos += numBytes;
293            return numBytes;
294          }
295
296        return super.read(buffer, offset, length);
297      }
298  }
299
300  /**
301   * This method pushes a single char of data into the pushback buffer.
302   * The char pushed back is the one that will be returned as the first char
303   * of the next read.
304   * <p>
305   * If the pushback buffer is full, this method throws an exception.
306   * <p>
307   * The argument to this method is an <code>int</code>.  Only the low eight
308   * bits of this value are pushed back.
309   *
310   * @param b The char to be pushed back, passed as an int
311   *
312   * @exception IOException If the pushback buffer is full.
313   */
314  public void unread(int b) throws IOException
315  {
316    synchronized (lock)
317      {
318        if (buf == null)
319          throw new IOException("stream closed");
320        if (pos == 0)
321          throw new IOException("Pushback buffer is full");
322
323        --pos;
324        buf[pos] = (char)(b & 0xFFFF);
325      }
326  }
327
328  /**
329   * This method pushes all of the chars in the passed char array into
330   * the pushback buffer.  These chars are pushed in reverse order so that
331   * the next char read from the stream after this operation will be
332   * <code>buf[0]</code> followed by <code>buf[1]</code>, etc.
333   * <p>
334   * If the pushback buffer cannot hold all of the requested chars, an
335   * exception is thrown.
336   *
337   * @param buf The char array to be pushed back
338   *
339   * @exception IOException If the pushback buffer is full
340   */
341  public synchronized void unread(char[] buf) throws IOException
342  {
343    unread(buf, 0, buf.length);
344  }
345
346  /**
347   * This method pushed back chars from the passed in array into the pushback
348   * buffer.  The chars from <code>buf[offset]</code> to
349   * <code>buf[offset + len]</code>
350   * are pushed in reverse order so that the next char read from the stream
351   * after this operation will be <code>buf[offset]</code> followed by
352   * <code>buf[offset + 1]</code>, etc.
353   * <p>
354   * If the pushback buffer cannot hold all of the requested chars, an
355   * exception is thrown.
356   *
357   * @param buffer The char array to be pushed back
358   * @param offset The index into the array where the chars to be push start
359   * @param length The number of chars to be pushed.
360   *
361   * @exception IOException If the pushback buffer is full
362   */
363  public synchronized void unread(char[] buffer, int offset, int length)
364    throws IOException
365  {
366    synchronized (lock)
367      {
368        if (buf == null)
369          throw new IOException("stream closed");
370        if (pos < length)
371          throw new IOException("Pushback buffer is full");
372
373        // Note the order that these chars are being added is the opposite
374        // of what would be done if they were added to the buffer one at a time.
375        // See the Java Class Libraries book p. 1397.
376        System.arraycopy(buffer, offset, buf, pos - length, length);
377
378        // Don't put this into the arraycopy above, an exception might be thrown
379        // and in that case we don't want to modify pos.
380        pos -= length;
381      }
382  }
383}