OpenJDK 1.22 · java.io.BufferedWriter · APIdia, the JavaDoc alternative

Writes text to a character-output stream, buffering characters so as to provide for the efficient writing of single characters, arrays, and strings.

The buffer size may be specified, or the default size may be accepted. The default is large enough for most purposes.

A newLine() method is provided, which uses the platform's own notion of line separator as defined by the system property line.separator. Not all platforms use the newline character ('\n') to terminate lines. Calling this method to terminate each output line is therefore preferred to writing a newline character directly.

In general, a Writer sends its output immediately to the underlying character or byte stream. Unless prompt output is required, it is advisable to wrap a BufferedWriter around any Writer whose write() operations may be costly, such as FileWriters and OutputStreamWriters. For example,

PrintWriter out = new PrintWriter(new BufferedWriter(new FileWriter("foo.out")));

will buffer the PrintWriter's output to the file. Without buffering, each invocation of a print() method would cause characters to be converted into bytes that would then be written immediately to the file, which can be very inefficient.

Field Summary

Modifier and Type	Field and Description
private char[]	cb
private static final int	DEFAULT_INITIAL_BUFFER_SIZE
private static final int	DEFAULT_MAX_BUFFER_SIZE
private final int	maxChars
private int	nChars
private int	nextChar
private Writer	out

Inherited from java.io.Writer:: lock

Constructor Summary

Access	Constructor and Description
private	BufferedWriter(Writer out, int initialSize, int maxSize) Creates a buffered character-output stream.
public	BufferedWriter(Writer A Writer out) Creates a buffered character-output stream that uses a default-sized output buffer.
public	BufferedWriter(Writer A Writer out, int Output-buffer size, a positive integer sz) Creates a new buffered character-output stream that uses an output buffer of the given size.

Method Summary

Modifier and Type	Method and Description
public void	close() Implements abstract java.io.Writer.close. Implements java.io.Closeable.close. Closes the stream, flushing it first.
private void	ensureOpen() Checks to make sure that the stream has not been closed
public void	flush() Implements abstract java.io.Writer.flush. Implements java.io.Flushable.flush. Flushes the stream.
pack-priv void	flushBuffer() Flushes the output buffer to the underlying character stream, without flushing the stream itself.
private void	growIfNeeded(int len) Grow char array to fit an additional len characters if needed.
private void	implClose()
private void	implFlush()
private void	implFlushBuffer()
private void	implWrite(int c) Hides java.io.Writer.implWrite.
private void	implWrite(char[] cbuf, int off, int len)
private void	implWrite(String s, int off, int len) Hides java.io.Writer.implWrite.
private static int	initialBufferSize() Returns the buffer size to use when no output buffer size specified
private int	min(int a, int b) Our own little min method, to avoid loading java.lang.Math if we've run out of file descriptors and we're trying to print a stack trace.
public void	newLine() Writes a line separator.
public void	write(int int specifying a character to be written c) Overrides java.io.Writer.write. Writes a single character.
public void	write(char[] A character array cbuf, int Offset from which to start reading characters off, int Number of characters to write len) Implements abstract java.io.Writer.write. Writes a portion of an array of characters.
public void	write(String String to be written s, int Offset from which to start reading characters off, int Number of characters to be written len) Overrides java.io.Writer.write. Writes a portion of a String.

Inherited from java.io.Writer:: append append append nullWriter write write

Field Detail

cb	back to summary
private char[] cb

DEFAULT_INITIAL_BUFFER_SIZE	back to summary
private static final int DEFAULT_INITIAL_BUFFER_SIZE

DEFAULT_MAX_BUFFER_SIZE	back to summary
private static final int DEFAULT_MAX_BUFFER_SIZE

maxChars	back to summary
private final int maxChars

nChars	back to summary
private int nChars

nextChar	back to summary
private int nextChar

out	back to summary
private Writer out

Constructor Detail

BufferedWriter	back to summary
private BufferedWriter(Writer out, int initialSize, int maxSize) Creates a buffered character-output stream.

BufferedWriter	back to summary
public BufferedWriter(Writer out) Creates a buffered character-output stream that uses a default-sized output buffer. Parameters out:Writer A Writer

BufferedWriter

back to summary

public BufferedWriter(Writer out)

Creates a buffered character-output stream that uses a default-sized output buffer.

Parameters

out:Writer: A Writer

BufferedWriter back to summary

BufferedWriter	back to summary
public BufferedWriter(Writer out, int sz) Creates a new buffered character-output stream that uses an output buffer of the given size. Parameters out:Writer A Writer sz:int Output-buffer size, a positive integer Exceptions IllegalArgumentException: If `sz <= 0`

public BufferedWriter(Writer out, int sz)

Creates a new buffered character-output stream that uses an output buffer of the given size.

Parameters

out:Writer: A Writer
sz:int: Output-buffer size, a positive integer

Exceptions

IllegalArgumentException:: If sz <= 0

Method Detail

close	back to summary
public void close() throws IOException Implements abstract java.io.Writer.close. Implements java.io.Closeable.close. Doc from java.io.Writer.close. Closes the stream, flushing it first. Once the stream has been closed, further write() or flush() invocations will cause an IOException to be thrown. Closing a previously closed stream has no effect. Exceptions IOException: If an I/O error occurs

back to summary

public void close() throws IOException

Implements abstract java.io.Writer.close.

Implements java.io.Closeable.close.

Doc from java.io.Writer.close.

Closes the stream, flushing it first. Once the stream has been closed, further write() or flush() invocations will cause an IOException to be thrown. Closing a previously closed stream has no effect.

Exceptions

IOException:: If an I/O error occurs

ensureOpen	back to summary
private void ensureOpen() throws IOException Checks to make sure that the stream has not been closed

flush	back to summary
public void flush() throws IOException Implements abstract java.io.Writer.flush. Implements java.io.Flushable.flush. Flushes the stream. Exceptions IOException: If an I/O error occurs

flush

back to summary

public void flush() throws IOException

Implements abstract java.io.Writer.flush.

Implements java.io.Flushable.flush.

Flushes the stream.

Exceptions

IOException:: If an I/O error occurs

flushBuffer	back to summary
pack-priv void flushBuffer() throws IOException Flushes the output buffer to the underlying character stream, without flushing the stream itself. This method is non-private only so that it may be invoked by PrintStream.

growIfNeeded	back to summary
private void growIfNeeded(int len) Grow char array to fit an additional len characters if needed. If possible, it grows by len+1 to avoid flushing when len chars are added. This method should only be called while holding the lock.

implClose	back to summary
private void implClose() throws IOException Annotations @SuppressWarnings:try

implFlush	back to summary
private void implFlush() throws IOException

implFlushBuffer	back to summary
private void implFlushBuffer() throws IOException

implWrite	back to summary
private void implWrite(int c) throws IOException Hides java.io.Writer.implWrite.

implWrite	back to summary
private void implWrite(char[] cbuf, int off, int len) throws IOException

implWrite	back to summary
private void implWrite(String s, int off, int len) throws IOException Hides java.io.Writer.implWrite.

initialBufferSize	back to summary
private static int initialBufferSize() Returns the buffer size to use when no output buffer size specified

min	back to summary
private int min(int a, int b) Our own little min method, to avoid loading java.lang.Math if we've run out of file descriptors and we're trying to print a stack trace.

newLine back to summary

newLine	back to summary
public void newLine() throws IOException Writes a line separator. The line separator string is defined by the system property `line.separator`, and is not necessarily a single newline ('\n') character. Exceptions IOException: If an I/O error occurs

public void newLine() throws IOException

Writes a line separator. The line separator string is defined by the system property line.separator, and is not necessarily a single newline ('\n') character.

Exceptions

IOException:: If an I/O error occurs

write	back to summary
public void write(int c) throws IOException Overrides java.io.Writer.write. Writes a single character. Parameters c:int Doc from java.io.Writer.write. int specifying a character to be written Exceptions IOException: If an I/O error occurs

write

back to summary

public void write(int c) throws IOException

Overrides java.io.Writer.write.

Writes a single character.

Parameters

c:int

Doc from java.io.Writer.write.

int specifying a character to be written

Exceptions

IOException:: If an I/O error occurs

write back to summary

write	back to summary
public void write(char[] cbuf, int off, int len) throws IOException Implements abstract java.io.Writer.write. Writes a portion of an array of characters. Ordinarily this method stores characters from the given array into this stream's buffer, flushing the buffer to the underlying stream as needed. If the requested length is at least as large as the buffer, however, then this method will flush the buffer and write the characters directly to the underlying stream. Thus redundant `BufferedWriter`s will not copy data unnecessarily. Parameters cbuf:char[] A character array off:int Offset from which to start reading characters len:int Number of characters to write Exceptions IOException: If an I/O error occurs IndexOutOfBoundsException: If `off` is negative, or `len` is negative, or `off + len` is negative or greater than the length of the given array

public void write(char[] cbuf, int off, int len) throws IOException

Implements abstract java.io.Writer.write.

Writes a portion of an array of characters.

Ordinarily this method stores characters from the given array into this stream's buffer, flushing the buffer to the underlying stream as needed. If the requested length is at least as large as the buffer, however, then this method will flush the buffer and write the characters directly to the underlying stream. Thus redundant BufferedWriters will not copy data unnecessarily.

Parameters

cbuf:char[]: A character array
off:int: Offset from which to start reading characters
len:int: Number of characters to write

Exceptions

IOException:: If an I/O error occurs
IndexOutOfBoundsException:: If off is negative, or len is negative, or off + len is negative or greater than the length of the given array

write back to summary

write	back to summary
public void write(String s, int off, int len) throws IOException Overrides java.io.Writer.write. Writes a portion of a String. Implementation Specification While the specification of this method in the superclass recommends that an `IndexOutOfBoundsException` be thrown if `len` is negative or `off + len` is negative, the implementation in this class does not throw such an exception in these cases but instead simply writes no characters. Parameters s:String String to be written off:int Offset from which to start reading characters len:int Number of characters to be written Exceptions IOException: If an I/O error occurs IndexOutOfBoundsException: If `off` is negative, or `off + len` is greater than the length of the given string

public void write(String s, int off, int len) throws IOException

Overrides java.io.Writer.write.

Writes a portion of a String.

Implementation Specification

While the specification of this method in the superclass recommends that an IndexOutOfBoundsException be thrown if len is negative or off + len is negative, the implementation in this class does not throw such an exception in these cases but instead simply writes no characters.

Parameters

s:String: String to be written
off:int: Offset from which to start reading characters
len:int: Number of characters to be written

Exceptions

IOException:: If an I/O error occurs
IndexOutOfBoundsException:: If off is negative, or off + len is greater than the length of the given string

public Class BufferedWriter

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail