java.io

Class PrintStream

java.lang.Object

java.io.OutputStream

java.io.FilterOutputStream

java.io.PrintStream

All Implemented Interfaces:

Closeable, Flushable, Appendable, AutoCloseable

public class PrintStream
extends FilterOutputStream
implements Appendable, Closeable

Wraps an existing OutputStream and provides convenience methods for writing common data types in a human readable format. This is not to be confused with DataOutputStream which is used for encoding common data types so that they can be read back in. No IOException is thrown by this class. Instead, callers should use checkError() to see if a problem has occurred in this stream.

Field Summary

Fields inherited from class java.io.FilterOutputStream

out

Constructor Summary

Constructors

Constructor and Description
PrintStream(File file) Creates a new print stream, without automatic line flushing, with the specified file.
PrintStream(File file, Charset charset) Creates a new print stream, without automatic line flushing, with the specified file and charset.
PrintStream(File file, String csn) Creates a new print stream, without automatic line flushing, with the specified file and charset.
PrintStream(OutputStream out) Creates a new print stream.
PrintStream(OutputStream out, boolean autoFlush) Creates a new print stream.
PrintStream(OutputStream out, boolean autoFlush, Charset charset) Creates a new print stream, with the specified OutputStream, automatic line flushing and charset.
PrintStream(OutputStream out, boolean autoFlush, String encoding) Creates a new print stream.
PrintStream(String fileName) Creates a new print stream, without automatic line flushing, with the specified file name.
PrintStream(String fileName, Charset charset) Creates a new print stream, without automatic line flushing, with the specified file name and charset.
PrintStream(String fileName, String csn) Creates a new print stream, without automatic line flushing, with the specified file name and charset.

Method Summary

Modifier and Type	Method and Description
PrintStream	append(char c) Appends the char c.
PrintStream	append(CharSequence charSequence) Appends the CharSequence charSequence, or "null".
PrintStream	append(CharSequence charSequence, int start, int end) Appends a subsequence of CharSequence charSequence, or "null".
boolean	checkError() Flushes this stream and returns the value of the error flag.
protected void	clearError() Sets the error state of the stream to false.
void	close() Closes this print stream.
void	flush() Ensures that all pending data is sent out to the target stream.
PrintStream	format(Locale l, String format, Object... args) Writes a string formatted by an intermediate Formatter to this stream using the specified locale, format string and arguments.
PrintStream	format(String format, Object... args) Formats args according to the format string format, and writes the result to this stream.
void	print(boolean b) Prints the string representation of the boolean b.
void	print(char c) Prints the string representation of the char c.
void	print(char[] chars) Prints the string representation of the character array chars.
void	print(double d) Prints the string representation of the double d.
void	print(float f) Prints the string representation of the float f.
void	print(int i) Prints the string representation of the int i.
void	print(long l) Prints the string representation of the long l.
void	print(Object o) Prints the string representation of the Object o, or "null".
void	print(String str) Prints a string to the target stream.
PrintStream	printf(Locale l, String format, Object... args) Prints a formatted string.
PrintStream	printf(String format, Object... args) Prints a formatted string.
void	println() Prints a newline.
void	println(boolean b) Prints the string representation of the boolean b followed by a newline.
void	println(char c) Prints the string representation of the char c followed by a newline.
void	println(char[] chars) Prints the string representation of the character array chars followed by a newline.
void	println(double d) Prints the string representation of the double d followed by a newline.
void	println(float f) Prints the string representation of the float f followed by a newline.
void	println(int i) Prints the string representation of the int i followed by a newline.
void	println(long l) Prints the string representation of the long l followed by a newline.
void	println(Object o) Prints the string representation of the Object o, or "null", followed by a newline.
void	println(String str) Prints a string followed by a newline.
protected void	setError() Sets the error flag of this print stream to true.
void	write(byte[] buffer, int offset, int length) Writes count bytes from buffer starting at offset to the target stream.
void	write(int oneByte) Writes one byte to the target stream.

Methods inherited from class java.io.OutputStream

nullOutputStream, write

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PrintStream

public PrintStream(OutputStream out)

Creates a new print stream. This stream will not flush automatically.

Parameters:

out - The output stream to which values and objects will be printed

See Also:

PrintWriter(java.io.OutputStream)

PrintStream

public PrintStream(OutputStream out,
                   boolean autoFlush)

Creates a new print stream.

Parameters:

out - The output stream to which values and objects will be printed

autoFlush - A boolean; if true, the output buffer will be flushed whenever a byte array is written, one of the println methods is invoked, or a newline character or byte ('\n') is written

See Also:

PrintWriter(java.io.OutputStream, boolean)

PrintStream

public PrintStream(OutputStream out,
                   boolean autoFlush,
                   String encoding)
            throws UnsupportedEncodingException

Creates a new print stream.

Parameters:

out - The output stream to which values and objects will be printed

autoFlush - A boolean; if true, the output buffer will be flushed whenever a byte array is written, one of the println methods is invoked, or a newline character or byte ('\n') is written

encoding - The name of a supported character encoding

Throws:

UnsupportedEncodingException - If the named encoding is not supported

Since:

1.4

PrintStream

public PrintStream(OutputStream out,
                   boolean autoFlush,
                   Charset charset)

Creates a new print stream, with the specified OutputStream, automatic line flushing and charset. This convenience constructor creates the necessary intermediate OutputStreamWriter, which will encode characters using the provided charset.

Parameters:

out - The output stream to which values and objects will be printed

autoFlush - A boolean; if true, the output buffer will be flushed whenever a byte array is written, one of the println methods is invoked, or a newline character or byte ('\n') is written

charset - A charset

Since:

10

PrintStream

public PrintStream(String fileName)
            throws FileNotFoundException

Creates a new print stream, without automatic line flushing, with the specified file name. This convenience constructor creates the necessary intermediate OutputStreamWriter, which will encode characters using the default charset for this instance of the Java virtual machine.

Parameters:

fileName - The name of the file to use as the destination of this print stream. If the file exists, then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

Throws:

FileNotFoundException - If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

SecurityException - If a security manager is present and checkWrite(fileName) denies write access to the file

Since:

1.5

PrintStream

public PrintStream(String fileName,
                   String csn)
            throws FileNotFoundException,
                   UnsupportedEncodingException

Creates a new print stream, without automatic line flushing, with the specified file name and charset. This convenience constructor creates the necessary intermediate OutputStreamWriter, which will encode characters using the provided charset.

Parameters:

fileName - The name of the file to use as the destination of this print stream. If the file exists, then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

csn - The name of a supported charset

Throws:

FileNotFoundException - If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

SecurityException - If a security manager is present and checkWrite(fileName) denies write access to the file

UnsupportedEncodingException - If the named charset is not supported

Since:

1.5

PrintStream

public PrintStream(String fileName,
                   Charset charset)
            throws IOException

Creates a new print stream, without automatic line flushing, with the specified file name and charset. This convenience constructor creates the necessary intermediate OutputStreamWriter, which will encode characters using the provided charset.

Parameters:

fileName - The name of the file to use as the destination of this print stream. If the file exists, then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

charset - A charset

Throws:

IOException - if an I/O error occurs while opening or creating the file

SecurityException - If a security manager is present and checkWrite(fileName) denies write access to the file

Since:

10

PrintStream

public PrintStream(File file)
            throws FileNotFoundException

Creates a new print stream, without automatic line flushing, with the specified file. This convenience constructor creates the necessary intermediate OutputStreamWriter, which will encode characters using the default charset for this instance of the Java virtual machine.

Parameters:

file - The file to use as the destination of this print stream. If the file exists, then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

Throws:

FileNotFoundException - If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

SecurityException - If a security manager is present and checkWrite(file.getPath()) denies write access to the file

Since:

1.5

PrintStream

public PrintStream(File file,
                   String csn)
            throws FileNotFoundException,
                   UnsupportedEncodingException

Creates a new print stream, without automatic line flushing, with the specified file and charset. This convenience constructor creates the necessary intermediate OutputStreamWriter, which will encode characters using the provided charset.

Parameters:

file - The file to use as the destination of this print stream. If the file exists, then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

csn - The name of a supported charset

Throws:

FileNotFoundException - If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

SecurityException - If a security manager is present and checkWrite(file.getPath()) denies write access to the file

UnsupportedEncodingException - If the named charset is not supported

Since:

1.5

PrintStream

public PrintStream(File file,
                   Charset charset)
            throws IOException

Creates a new print stream, without automatic line flushing, with the specified file and charset. This convenience constructor creates the necessary intermediate OutputStreamWriter, which will encode characters using the provided charset.

Parameters:

file - The file to use as the destination of this print stream. If the file exists, then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

charset - A charset

Throws:

IOException - if an I/O error occurs while opening or creating the file

SecurityException - If a security manager is present and checkWrite(file.getPath()) denies write access to the file

Since:

10

Method Detail

checkError

public boolean checkError()

Flushes this stream and returns the value of the error flag.

Returns:

true if either an IOException has been thrown previously or if setError() has been called; false otherwise.

See Also:

setError()

clearError

protected void clearError()

Sets the error state of the stream to false.

Since:

1.6

close

public void close()

Closes this print stream. Flushes this stream and then closes the target stream. If an I/O error occurs, this stream's error state is set to true.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class FilterOutputStream

flush

public void flush()

Ensures that all pending data is sent out to the target stream. It also flushes the target stream. If an I/O error occurs, this stream's error state is set to true.

Specified by:

flush in interface Flushable

Overrides:

flush in class FilterOutputStream

format

public PrintStream format(String format,
                          Object... args)

Formats args according to the format string format, and writes the result to this stream. This method uses the user's default locale. See "Be wary of the default locale".

Parameters:

format - the format string (see Formatter.format(java.lang.String, java.lang.Object...))

args - the list of arguments passed to the formatter. If there are more arguments than required by format, additional arguments are ignored.

Returns:

this stream.

Throws:

IllegalFormatException - if the format string is illegal or incompatible with the arguments, if there are not enough arguments or if any other error regarding the format string or arguments is detected.

NullPointerException - if format == null

format

public PrintStream format(Locale l,
                          String format,
                          Object... args)

Writes a string formatted by an intermediate Formatter to this stream using the specified locale, format string and arguments.

Parameters:

l - the locale used in the method. No localization will be applied if l is null.

format - the format string (see Formatter.format(java.lang.String, java.lang.Object...))

args - the list of arguments passed to the formatter. If there are more arguments than required by format, additional arguments are ignored.

Returns:

this stream.

Throws:

IllegalFormatException - if the format string is illegal or incompatible with the arguments, if there are not enough arguments or if any other error regarding the format string or arguments is detected.

NullPointerException - if format == null

printf

public PrintStream printf(String format,
                          Object... args)

Prints a formatted string. The behavior of this method is the same as this stream's #format(String, Object...) method.

The Locale used is the user's default locale. See "Be wary of the default locale".

Parameters:

format - the format string (see Formatter.format(java.lang.String, java.lang.Object...))

args - the list of arguments passed to the formatter. If there are more arguments than required by format, additional arguments are ignored.

Returns:

this stream.

Throws:

IllegalFormatException - if the format string is illegal or incompatible with the arguments, if there are not enough arguments or if any other error regarding the format string or arguments is detected.

NullPointerException - if format == null

printf

public PrintStream printf(Locale l,
                          String format,
                          Object... args)

Prints a formatted string. The behavior of this method is the same as this stream's #format(Locale, String, Object...) method.

Parameters:

l - the locale used in the method. No localization will be applied if l is null.

format - the format string (see Formatter.format(java.lang.String, java.lang.Object...))

args - the list of arguments passed to the formatter. If there are more arguments than required by format, additional arguments are ignored.

Returns:

this stream.

Throws:

IllegalFormatException - if the format string is illegal or incompatible with the arguments, if there are not enough arguments or if any other error regarding the format string or arguments is detected.

NullPointerException - if format == null.

print

public void print(char[] chars)

Prints the string representation of the character array chars.

print

public void print(char c)

Prints the string representation of the char c.

print

public void print(double d)

Prints the string representation of the double d.

print

public void print(float f)

Prints the string representation of the float f.

print

public void print(int i)

Prints the string representation of the int i.

print

public void print(long l)

Prints the string representation of the long l.

print

public void print(Object o)

Prints the string representation of the Object o, or "null".

print

public void print(String str)

Prints a string to the target stream. The string is converted to an array of bytes using the encoding chosen during the construction of this stream. The bytes are then written to the target stream with write(int).

If an I/O error occurs, this stream's error state is set to true.

Parameters:

str - the string to print to the target stream.

See Also:

write(int)

print

public void print(boolean b)

Prints the string representation of the boolean b.

println

public void println()

Prints a newline.

println

public void println(char[] chars)

Prints the string representation of the character array chars followed by a newline.

println

public void println(char c)

Prints the string representation of the char c followed by a newline.

println

public void println(double d)

Prints the string representation of the double d followed by a newline.

println

public void println(float f)

Prints the string representation of the float f followed by a newline.

println

public void println(int i)

Prints the string representation of the int i followed by a newline.

println

public void println(long l)

Prints the string representation of the long l followed by a newline.

println

public void println(Object o)

Prints the string representation of the Object o, or "null", followed by a newline.

println

public void println(String str)

Prints a string followed by a newline. The string is converted to an array of bytes using the encoding chosen during the construction of this stream. The bytes are then written to the target stream with write(int).

If an I/O error occurs, this stream's error state is set to true.

Parameters:

str - the string to print to the target stream.

See Also:

write(int)

println

public void println(boolean b)

Prints the string representation of the boolean b followed by a newline.

setError

protected void setError()

Sets the error flag of this print stream to true.

write

public void write(byte[] buffer,
                  int offset,
                  int length)

Writes count bytes from buffer starting at offset to the target stream. If autoFlush is set, this stream gets flushed after writing the buffer.

This stream's error flag is set to true if this stream is closed or an I/O error occurs.

Overrides:

write in class FilterOutputStream

Parameters:

buffer - the buffer to be written.

offset - the index of the first byte in buffer to write.

length - the number of bytes in buffer to write.

Throws:

IndexOutOfBoundsException - if offset < 0 or count < 0, or if offset + count is bigger than the length of buffer.

See Also:

flush()

write

public void write(int oneByte)

Writes one byte to the target stream. Only the least significant byte of the integer oneByte is written. This stream is flushed if oneByte is equal to the character '\n' and this stream is set to autoFlush.

This stream's error flag is set to true if it is closed or an I/O error occurs.

Overrides:

write in class FilterOutputStream

Parameters:

oneByte - the byte to be written

append

public PrintStream append(char c)

Appends the char c.

Specified by:

append in interface Appendable

Parameters:

c - the character to append.

Returns:

this stream.

append

public PrintStream append(CharSequence charSequence)

Appends the CharSequence charSequence, or "null".

Specified by:

append in interface Appendable

Parameters:

charSequence - the character sequence to append.

Returns:

this stream.

append

public PrintStream append(CharSequence charSequence,
                          int start,
                          int end)

Appends a subsequence of CharSequence charSequence, or "null".

Specified by:

append in interface Appendable

Parameters:

charSequence - the character sequence appended to the target stream.

start - the index of the first char in the character sequence appended to the target stream.

end - the index of the character following the last character of the subsequence appended to the target stream.

Returns:

this stream.

Throws:

IndexOutOfBoundsException - if start > end, start < 0, end < 0 or either start or end are greater or equal than the length of charSequence.