001    /* StringBufferInputStream.java -- Read an String as a stream
002       Copyright (C) 1998, 1999, 2001, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010     
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.io;
040    
041    /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
042     * "The Java Language Specification", ISBN 0-201-63451-1
043     * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
044     * Status:  Believed complete and correct.  Deprecated in JDK 1.1.
045     */
046     
047    /**
048      * This class permits a <code>String</code> to be read as an input stream.
049      * The low eight bits of each character in the <code>String</code> are the
050      * bytes that are returned. The high eight bits of each character are
051      * discarded.
052      * <p>
053      * The mark/reset functionality in this class behaves differently than
054      * normal.  The <code>mark()</code> method is always ignored and the 
055      * <code>reset()</code> method always resets in stream to start reading from 
056      * position 0 in the String.  Note that since this method does not override 
057      * <code>markSupported()</code> in <code>InputStream</code>, calling that 
058      * method will return <code>false</code>.
059      * <p>
060      * Note that this class is deprecated because it does not properly handle
061      * 16-bit Java characters.  It is provided for backwards compatibility only
062      * and should not be used for new development.  The <code>StringReader</code>
063      * class should be used instead.
064      *
065      * @deprecated
066      *
067      * @author Aaron M. Renn (arenn@urbanophile.com)
068      * @author Warren Levy (warrenl@cygnus.com)
069      */
070    public class StringBufferInputStream extends InputStream
071    {
072      /** The String which is the input to this stream. */
073      protected String buffer;
074    
075      /** Position of the next byte in buffer to be read. */
076      protected int pos = 0;
077    
078      /** The length of the String buffer. */
079      protected int count;
080    
081     /**
082      * Create a new <code>StringBufferInputStream</code> that will read bytes
083      * from the passed in <code>String</code>.  This stream will read from the
084      * beginning to the end of the <code>String</code>.
085      *
086      * @param s The <code>String</code> this stream will read from.
087      */
088      public StringBufferInputStream(String s)
089      {
090        buffer = s;
091        count = s.length();
092      }
093    
094     /**
095      * This method returns the number of bytes available to be read from this
096      * stream.  The value returned will be equal to <code>count - pos</code>.
097      *
098      * @return The number of bytes that can be read from this stream before
099      * 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    }