libjava/java/io/StringBufferInputStream.java

   1 /* StringBufferInputStream.java -- Read an String as a stream
   2    Copyright (C) 1998, 1999, 2001, 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.io;
  40
  41 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  42  * "The Java Language Specification", ISBN 0-201-63451-1
  43  * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
  44  * Status:  Believed complete and correct.  Deprecated in JDK 1.1.
  45  */
  46
  47 /**
  48   * This class permits a <code>String</code> to be read as an input stream.
  49   * The low eight bits of each character in the <code>String</code> are the
  50   * bytes that are returned. The high eight bits of each character are
  51   * discarded.
  52   * <p>
  53   * The mark/reset functionality in this class behaves differently than
  54   * normal.  The <code>mark()</code> method is always ignored and the
  55   * <code>reset()</code> method always resets in stream to start reading from
  56   * position 0 in the String.  Note that since this method does not override
  57   * <code>markSupported()</code> in <code>InputStream</code>, calling that
  58   * method will return <code>false</code>.
  59   * <p>
  60   * Note that this class is deprecated because it does not properly handle
  61   * 16-bit Java characters.  It is provided for backwards compatibility only
  62   * and should not be used for new development.  The <code>StringReader</code>
  63   * class should be used instead.
  64   *
  65   * @deprecated
  66   *
  67   * @author Aaron M. Renn (arenn@urbanophile.com)
  68   * @author Warren Levy (warrenl@cygnus.com)
  69   */
  70 public class StringBufferInputStream extends InputStream
  71 {
  72   /** The String which is the input to this stream. */
  73   protected String buffer;
  74
  75   /** Position of the next byte in buffer to be read. */
  76   protected int pos = 0;
  77
  78   /** The length of the String buffer. */
  79   protected int count;
  80
  81  /**
  82   * Create a new <code>StringBufferInputStream</code> that will read bytes
  83   * from the passed in <code>String</code>.  This stream will read from the
  84   * beginning to the end of the <code>String</code>.
  85   *
  86   * @param s The <code>String</code> this stream will read from.
  87   */
  88   public StringBufferInputStream(String s)
  89   {
  90     buffer = s;
  91     count = s.length();
  92   }
  93
  94  /**
  95   * This method returns the number of bytes available to be read from this
  96   * stream.  The value returned will be equal to <code>count - pos</code>.
  97   *
  98   * @return The number of bytes that can be read from this stream before
  99   * blocking, which is all of them
 100   */
 101   public int available()
 102   {
 103     return count - pos;
 104   }
 105
 106  /**
 107   * This method reads one byte from the stream.  The <code>pos</code> counter
 108   * is advanced to the next byte to be read.  The byte read is returned as
 109   * an int in the range of 0-255.  If the stream position is already at the
 110   * end of the buffer, no byte is read and a -1 is returned in order to
 111   * indicate the end of the stream.
 112   *
 113   * @return The byte read, or -1 if end of stream
 114   */
 115   public int read()
 116   {
 117     if (pos >= count)
 118       return -1;        // EOF
 119
 120     return ((int) buffer.charAt(pos++)) & 0xFF;
 121   }
 122
 123 /**
 124   * This method reads bytes from the stream and stores them into a caller
 125   * supplied buffer.  It starts storing the data at index <code>offset</code>
 126   * into the buffer and attempts to read <code>len</code> bytes.  This method
 127   * can return before reading the number of bytes requested if the end of the
 128   * stream is encountered first.  The actual number of bytes read is
 129   * returned.  If no bytes can be read because the stream is already at
 130   * the end of stream position, a -1 is returned.
 131   * <p>
 132   * This method does not block.
 133   *
 134   * @param b The array into which the bytes read should be stored.
 135   * @param off The offset into the array to start storing bytes
 136   * @param len The requested number of bytes to read
 137   *
 138   * @return The actual number of bytes read, or -1 if end of stream.
 139   */
 140   public int read(byte[] b, int off, int len)
 141   {
 142     if (off < 0 || len < 0 || off + len > b.length)
 143       throw new ArrayIndexOutOfBoundsException();
 144
 145     if (pos >= count)
 146       return -1;        // EOF
 147
 148     int numRead = Math.min(len, count - pos);
 149     if (numRead < 0)
 150       return 0;
 151
 152     buffer.getBytes(pos, pos + numRead, b, off);
 153     pos += numRead;
 154     return numRead;
 155   }
 156
 157  /**
 158   * This method sets the read position in the stream to the beginning
 159   * setting the <code>pos</code> variable equal to 0.  Note that this differs
 160   * from the common implementation of the <code>reset()</code> method.
 161   */
 162   public void reset()
 163   {
 164     pos = 0;
 165   }
 166
 167  /**
 168   * This method attempts to skip the requested number of bytes in the
 169   * input stream.  It does this by advancing the <code>pos</code> value by the
 170   * specified number of bytes.  It this would exceed the length of the
 171   * buffer, then only enough bytes are skipped to position the stream at
 172   * the end of the buffer.  The actual number of bytes skipped is returned.
 173   *
 174   * @param n The requested number of bytes to skip
 175   *
 176   * @return The actual number of bytes skipped.
 177   */
 178   public long skip(long n)
 179   {
 180     if (n < 0)
 181       return 0L;
 182
 183     long actualSkip = Math.min(n, count - pos);
 184     pos += actualSkip;
 185     return actualSkip;
 186   }
 187 }