2 Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
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)
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.
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
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
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. */
41 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
42 * "The Java Language Specification", ISBN 0-201-63451-1
43 * Status: Complete to version 1.1.
47 * This class allows data to be written to a byte array buffer and
48 * and then retrieved by an application. The internal byte array
49 * buffer is dynamically resized to hold all the data written. Please
50 * be aware that writing large amounts to data to this stream will
51 * cause large amounts of memory to be allocated.
53 * The size of the internal buffer defaults to 32 and it is resized
54 * by doubling the size of the buffer. This default size can be
55 * overridden by using the
56 * <code>gnu.java.io.ByteArrayOutputStream.initialBufferSize</code>
59 * There is a constructor that specified the initial buffer size and
60 * that is the preferred way to set that value because it it portable
61 * across all Java class library implementations.
63 * Note that this class also has methods that convert the byte array
64 * buffer to a <code>String</code> using either the system default or an
65 * application specified character encoding. Thus it can handle
66 * multibyte character encodings.
70 * @author Aaron M. Renn (arenn@urbanophile.com)
71 * @author Tom Tromey <tromey@cygnus.com>
72 * @date September 24, 1998
74 public class ByteArrayOutputStream
extends OutputStream
77 * This method initializes a new <code>ByteArrayOutputStream</code>
78 * with the default buffer size of 32 bytes. If a different initial
79 * buffer size is desired, see the constructor
80 * <code>ByteArrayOutputStream(int size)</code>. For applications
81 * where the source code is not available, the default buffer size
82 * can be set using the system property
83 * <code>gnu.java.io.ByteArrayOutputStream.initialBufferSize</code>
85 public ByteArrayOutputStream ()
87 this (initial_buffer_size
);
91 * This method initializes a new <code>ByteArrayOutputStream</code> with
92 * a specified initial buffer size.
94 * @param size The initial buffer size in bytes
96 public ByteArrayOutputStream (int size
)
103 * This method discards all of the bytes that have been written to
104 * the internal buffer so far by setting the <code>count</code>
105 * variable to 0. The internal buffer remains at its currently
108 public synchronized void reset ()
114 * This method returns the number of bytes that have been written to
115 * the buffer so far. This is the same as the value of the protected
116 * <code>count</code> variable. If the <code>reset</code> method is
117 * called, then this value is reset as well. Note that this method does
118 * not return the length of the internal buffer, but only the number
119 * of bytes that have been written to it.
121 * @return The number of bytes in the internal buffer
131 * This method returns a byte array containing the bytes that have been
132 * written to this stream so far. This array is a copy of the valid
133 * bytes in the internal buffer and its length is equal to the number of
134 * valid bytes, not necessarily to the the length of the current
135 * internal buffer. Note that since this method allocates a new array,
136 * it should be used with caution when the internal buffer is very large.
138 public synchronized byte[] toByteArray ()
140 byte[] ret
= new byte[count
];
141 System
.arraycopy(buf
, 0, ret
, 0, count
);
146 * Returns the bytes in the internal array as a <code>String</code>. The
147 * bytes in the buffer are converted to characters using the system default
148 * encoding. There is an overloaded <code>toString()</code> method that
149 * allows an application specified character encoding to be used.
151 * @return A <code>String</code> containing the data written to this
154 public String
toString ()
156 return new String (buf
, 0, count
);
160 * Returns the bytes in the internal array as a <code>String</code>. The
161 * bytes in the buffer are converted to characters using the specified
164 * @param enc The name of the character encoding to use
166 * @return A <code>String</code> containing the data written to this
169 * @exception UnsupportedEncodingException If the named encoding is
172 public String
toString (String enc
) throws UnsupportedEncodingException
174 return new String (buf
, 0, count
, enc
);
178 * This method returns the bytes in the internal array as a
179 * <code>String</code>. It uses each byte in the array as the low
180 * order eight bits of the Unicode character value and the passed in
181 * parameter as the high eight bits.
183 * This method does not convert bytes to characters in the proper way and
184 * so is deprecated in favor of the other overloaded <code>toString</code>
185 * methods which use a true character encoding.
187 * @param hibyte The high eight bits to use for each character in
188 * the <code>String</code>
190 * @return A <code>String</code> containing the data written to this
195 public String
toString (int hibyte
)
197 return new String (buf
, 0, count
, hibyte
);
200 // Resize buffer to accommodate new bytes.
201 private void resize (int add
)
203 if (count
+ add
>= buf
.length
)
205 int newlen
= buf
.length
* 2;
206 if (count
+ add
> newlen
)
207 newlen
= count
+ add
;
208 byte[] newbuf
= new byte[newlen
];
209 System
.arraycopy(buf
, 0, newbuf
, 0, count
);
215 * This method writes the writes the specified byte into the internal
218 * @param oneByte The byte to be read passed as an int
220 public synchronized void write (int oneByte
)
223 buf
[count
++] = (byte) oneByte
;
227 * This method writes <code>len</code> bytes from the passed in array
228 * <code>buf</code> starting at index <code>offset</code> into the
231 * @param buffer The byte array to write data from
232 * @param offset The index into the buffer to start writing data from
233 * @param add The number of bytes to write
235 public synchronized void write (byte[] buffer
, int offset
, int add
)
237 // If ADD < 0 then arraycopy will throw the appropriate error for
241 System
.arraycopy(buffer
, offset
, buf
, count
, add
);
246 * This method writes all the bytes that have been written to this stream
247 * from the internal buffer to the specified <code>OutputStream</code>.
249 * @param out The <code>OutputStream</code> to write to
251 * @exception IOException If an error occurs
253 public synchronized void writeTo (OutputStream out
) throws IOException
255 out
.write(buf
, 0, count
);
259 * The internal buffer where the data written is stored
261 protected byte[] buf
;
264 * The number of bytes that have been written to the buffer
269 * The default initial buffer size. Specified by the JCL.
271 private static final int DEFAULT_INITIAL_BUFFER_SIZE
= 32;
273 // The default buffer size which can be overridden by the user.
274 private static final int initial_buffer_size
;
279 = Integer
.getInteger ("gnu.java.io.ByteArrayOutputStream.initialBufferSize",
280 DEFAULT_INITIAL_BUFFER_SIZE
).intValue ();
282 r
= DEFAULT_INITIAL_BUFFER_SIZE
;
283 initial_buffer_size
= r
;