FileDocCategorySizeDatePackage
PrintWriter.javaAPI DocAndroid 1.5 API30420Wed May 06 22:41:04 BST 2009java.io

PrintWriter

public class PrintWriter extends Writer
Wraps either an existing {@link OutputStream} or an existing {@link Writer} and provides convenience methods for printing common data types in a human readable format. No {@code IOException} is thrown by this class. Instead, callers should use {@link #checkError()} to see if a problem has occurred in this writer.
since
Android 1.0

Fields Summary
protected Writer
out
The writer to print data to.
private boolean
ioError
Indicates whether this PrintWriter is in an error state.
private boolean
autoflush
Indicates whether or not this PrintWriter should flush its contents after printing a new line.
private final String
lineSeparator
Constructors Summary
public PrintWriter(OutputStream out)
Constructs a new {@code PrintWriter} with {@code out} as its target stream. By default, the new print writer does not automatically flush its contents to the target stream when a newline is encountered.

param
out the target output stream.
throws
NullPointerException if {@code out} is {@code null}.
since
Android 1.0

 //$NON-NLS-1$

                                                                                   
       
        this(new OutputStreamWriter(out), false);
    
public PrintWriter(OutputStream out, boolean autoflush)
Constructs a new {@code PrintWriter} with {@code out} as its target stream. The parameter {@code autoflush} determines if the print writer automatically flushes its contents to the target stream when a newline is encountered.

param
out the target output stream.
param
autoflush indicates whether contents are flushed upon encountering a newline sequence.
throws
NullPointerException if {@code out} is {@code null}.
since
Android 1.0

        this(new OutputStreamWriter(out), autoflush);
    
public PrintWriter(Writer wr)
Constructs a new {@code PrintWriter} with {@code wr} as its target writer. By default, the new print writer does not automatically flush its contents to the target writer when a newline is encountered.

param
wr the target writer.
throws
NullPointerException if {@code wr} is {@code null}.
since
Android 1.0

        this(wr, false);
    
public PrintWriter(Writer wr, boolean autoflush)
Constructs a new {@code PrintWriter} with {@code out} as its target writer. The parameter {@code autoflush} determines if the print writer automatically flushes its contents to the target writer when a newline is encountered.

param
wr the target writer.
param
autoflush indicates whether to flush contents upon encountering a newline sequence.
throws
NullPointerException if {@code out} is {@code null}.
since
Android 1.0

        super(wr);
        this.autoflush = autoflush;
        out = wr;
    
public PrintWriter(File file)
Constructs a new {@code PrintWriter} with {@code file} as its target. The virtual machine's default character set is used for character encoding. The print writer does not automatically flush its contents to the target file when a newline is encountered. The output to the file is buffered.

param
file the target file. If the file already exists, its contents are removed, otherwise a new file is created.
throws
FileNotFoundException if an error occurs while opening or creating the target file.
throws
SecurityException if a security manager exists and it denies writing to the target file.
since
Android 1.0

        // BEGIN android-modified
        this(new OutputStreamWriter(
                     new BufferedOutputStream(
                             new FileOutputStream(file), 8192)),
                false);
        // END android-modified
    
public PrintWriter(File file, String csn)
Constructs a new {@code PrintWriter} with {@code file} as its target. The character set named {@code csn} is used for character encoding. The print writer does not automatically flush its contents to the target file when a newline is encountered. The output to the file is buffered.

param
file the target file. If the file already exists, its contents are removed, otherwise a new file is created.
param
csn the name of the character set used for character encoding.
throws
FileNotFoundException if an error occurs while opening or creating the target file.
throws
NullPointerException if {@code csn} is {@code null}.
throws
SecurityException if a security manager exists and it denies writing to the target file.
throws
UnsupportedEncodingException if the encoding specified by {@code csn} is not supported.
since
Android 1.0

        // BEGIN android-modified
        this(new OutputStreamWriter(
                     new BufferedOutputStream(
                             new FileOutputStream(file), 8192), csn),
                false);
        // END android-modified
    
public PrintWriter(String fileName)
Constructs a new {@code PrintWriter} with the file identified by {@code fileName} as its target. The virtual machine's default character set is used for character encoding. The print writer does not automatically flush its contents to the target file when a newline is encountered. The output to the file is buffered.

param
fileName the target file's name. If the file already exists, its contents are removed, otherwise a new file is created.
throws
FileNotFoundException if an error occurs while opening or creating the target file.
throws
SecurityException if a security manager exists and it denies writing to the target file.
since
Android 1.0

        // BEGIN android-modified
        this(new OutputStreamWriter(
                     new BufferedOutputStream(
                             new FileOutputStream(fileName), 8192)),
                false);
        // END android-modified
    
public PrintWriter(String fileName, String csn)
Constructs a new {@code PrintWriter} with the file identified by {@code fileName} as its target. The character set named {@code csn} is used for character encoding. The print writer does not automatically flush its contents to the target file when a newline is encountered. The output to the file is buffered.

param
fileName the target file's name. If the file already exists, its contents are removed, otherwise a new file is created.
param
csn the name of the character set used for character encoding.
throws
FileNotFoundException if an error occurs while opening or creating the target file.
throws
NullPointerException if {@code csn} is {@code null}.
throws
SecurityException if a security manager exists and it denies writing to the target file.
throws
UnsupportedEncodingException if the encoding specified by {@code csn} is not supported.
since
Android 1.0

        // BEGIN android-modified
        this(new OutputStreamWriter(
                     new BufferedOutputStream(
                             new FileOutputStream(fileName), 8192), csn),
                false);
        // END android-modified
    
Methods Summary
public java.io.PrintWriterappend(char c)
Appends the character {@code c} to the target.

param
c the character to append to the target.
return
this writer.
since
Android 1.0

        write(c);
        return this;
    
public java.io.PrintWriterappend(java.lang.CharSequence csq)
Appends the character sequence {@code csq} to the target. This method works the same way as {@code PrintWriter.print(csq.toString())}. If {@code csq} is {@code null}, then the string "null" is written to the target.

param
csq the character sequence appended to the target.
return
this writer.
since
Android 1.0

        if (null == csq) {
            append(TOKEN_NULL, 0, TOKEN_NULL.length());
        } else {
            append(csq, 0, csq.length());
        }
        return this;
    
public java.io.PrintWriterappend(java.lang.CharSequence csq, int start, int end)
Appends a subsequence of the character sequence {@code csq} to the target. This method works the same way as {@code PrintWriter.print(csq.subsequence(start, end).toString())}. If {@code csq} is {@code null}, then the specified subsequence of the string "null" will be written to the target.

param
csq the character sequence appended to the target.
param
start the index of the first char in the character sequence appended to the target.
param
end the index of the character following the last character of the subsequence appended to the target.
return
this writer.
throws
StringIndexOutOfBoundsException if {@code start > end}, {@code start < 0}, {@code end < 0} or either {@code start} or {@code end} are greater or equal than the length of {@code csq}.
since
Android 1.0

        if (null == csq) {
            csq = TOKEN_NULL;
        }
        String output = csq.subSequence(start, end).toString();
        write(output, 0, output.length());
        return this;
    
public booleancheckError()
Flushes this writer and returns the value of the error flag.

return
{@code true} if either an {@code IOException} has been thrown previously or if {@code setError()} has been called; {@code false} otherwise.
see
#setError()
since
Android 1.0

        if (out != null) {
            flush();
        }
        return ioError;
    
public voidclose()
Closes this print writer. Flushes this writer and then closes the target. If an I/O error occurs, this writer's error flag is set to {@code true}.

since
Android 1.0

        synchronized (lock) {
            if (out != null) {
                try {
                    out.close();
                } catch (IOException e) {
                    setError();
                }
                out = null;
            }
        }
    
private final voiddoWrite(char[] buf, int offset, int count)

        // BEGIN android-note
        // changed array notation to be consistent with the rest of harmony
        // END android-note
        synchronized (lock) {
            if (out != null) {
                try {
                    out.write(buf, offset, count);
                } catch (IOException e) {
                    setError();
                }
            } else {
                setError();
            }
        }
    
public voidflush()
Ensures that all pending data is sent out to the target. It also flushes the target. If an I/O error occurs, this writer's error state is set to {@code true}.

since
Android 1.0

        synchronized (lock) {
            if (out != null) {
                try {
                    out.flush();
                } catch (IOException e) {
                    setError();
                }
            } else {
                setError();
            }
        }
    
public java.io.PrintWriterformat(java.lang.String format, java.lang.Object args)
Writes a string formatted by an intermediate {@code Formatter} to the target using the specified format string and arguments. For the locale, the default value of the current virtual machine instance is used. If automatic flushing is enabled then the buffer is flushed as well.

param
format the format string used for {@link java.util.Formatter#format}.
param
args the list of arguments passed to the formatter. If there are more arguments than required by the {@code format} string, then the additional arguments are ignored.
return
this writer.
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.
throws
NullPointerException if {@code format} is {@code null}.
since
Android 1.0

        return format(Locale.getDefault(), format, args);
    
public java.io.PrintWriterformat(java.util.Locale l, java.lang.String format, java.lang.Object args)
Writes a string formatted by an intermediate {@code Formatter} to the target using the specified locale, format string and arguments. If automatic flushing is enabled then this writer is flushed.

param
l the locale used in the method. No localization will be applied if {@code l} is {@code null}.
param
format the format string used for {@link java.util.Formatter#format}.
param
args the list of arguments passed to the formatter. If there are more arguments than required by the {@code format} string, then the additional arguments are ignored.
return
this writer.
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.
throws
NullPointerException if {@code format} is {@code null}.
since
Android 1.0

        if (format == null) {
            throw new NullPointerException(Msg.getString("K0351")); //$NON-NLS-1$
        }
        new Formatter(this, l).format(format, args);
        if (autoflush) {
            flush();
        }
        return this;
    
private voidnewline()
Print a new line String onto the writer, flushing if autoflush enabled.

        print(lineSeparator);
        if (autoflush) {
            flush();
        }
    
public voidprint(char[] charArray)
Prints the string representation of the specified character array to the target.

param
charArray the character array to print to the target.
see
#print(String)
since
Android 1.0

        print(new String(charArray, 0, charArray.length));
    
public voidprint(char ch)
Prints the string representation of the specified character to the target.

param
ch the character to print to the target.
see
#print(String)
since
Android 1.0

        print(String.valueOf(ch));
    
public voidprint(double dnum)
Prints the string representation of the specified double to the target.

param
dnum the double value to print to the target.
see
#print(String)
since
Android 1.0

        print(String.valueOf(dnum));
    
public voidprint(float fnum)
Prints the string representation of the specified float to the target.

param
fnum the float value to print to the target.
see
#print(String)
since
Android 1.0

        print(String.valueOf(fnum));
    
public voidprint(int inum)
Prints the string representation of the specified integer to the target.

param
inum the integer value to print to the target.
see
#print(String)
since
Android 1.0

        print(String.valueOf(inum));
    
public voidprint(long lnum)
Prints the string representation of the specified long to the target.

param
lnum the long value to print to the target.
see
#print(String)
since
Android 1.0

        print(String.valueOf(lnum));
    
public voidprint(java.lang.Object obj)
Prints the string representation of the specified object to the target.

param
obj the object to print to the target.
see
#print(String)
since
Android 1.0

        print(String.valueOf(obj));
    
public voidprint(java.lang.String str)
Prints a string to the target. The string is converted to an array of bytes using the encoding chosen during the construction of this writer. The bytes are then written to the target with {@code write(int)}.

If an I/O error occurs, this writer's error flag is set to {@code true}.

param
str the string to print to the target.
see
#write(int)
since
Android 1.0

        write(str != null ? str : String.valueOf((Object) null));
    
public voidprint(boolean bool)
Prints the string representation of the specified boolean to the target.

param
bool the boolean value to print the target.
see
#print(String)
since
Android 1.0

        print(String.valueOf(bool));
    
public java.io.PrintWriterprintf(java.lang.String format, java.lang.Object args)
Prints a formatted string. The behavior of this method is the same as this writer's {@code #format(String, Object...)} method. For the locale, the default value of the current virtual machine instance is used.

param
format the format string used for {@link java.util.Formatter#format}.
param
args the list of arguments passed to the formatter. If there are more arguments than required by the {@code format} string, then the additional arguments are ignored.
return
this writer.
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.
throws
NullPointerException if {@code format} is {@code null}.
since
Android 1.0

        return format(format, args);
    
public java.io.PrintWriterprintf(java.util.Locale l, java.lang.String format, java.lang.Object args)
Prints a formatted string. The behavior of this method is the same as this writer's {@code #format(Locale, String, Object...)} method.

param
l the locale used in the method. No localization will be applied if {@code l} is {@code null}.
param
format the format string used for {@link java.util.Formatter#format}.
param
args the list of arguments passed to the formatter. If there are more arguments than required by the {@code format} string, then the additional arguments are ignored.
return
this writer.
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.
throws
NullPointerException if {@code format} is {@code null}.
since
Android 1.0

        return format(l, format, args);
    
public voidprintln()
Prints the string representation of the system property {@code "line.separator"} to the target. Flushes this writer if the autoflush flag is set to {@code true}.

since
Android 1.0

        synchronized (lock) {
            newline();
        }
    
public voidprintln(char[] charArray)
Prints the string representation of the specified character array followed by the system property {@code "line.separator"} to the target. Flushes this writer if the autoflush flag is set to {@code true}.

param
charArray the character array to print to the target.
see
#print(String)
since
Android 1.0

        println(new String(charArray, 0, charArray.length));
    
public voidprintln(char ch)
Prints the string representation of the specified character followed by the system property {@code "line.separator"} to the target. Flushes this writer if the autoflush flag is set to {@code true}.

param
ch the character to print to the target.
see
#print(String)
since
Android 1.0

        println(String.valueOf(ch));
    
public voidprintln(double dnum)
Prints the string representation of the specified double followed by the system property {@code "line.separator"} to the target. Flushes this writer if the autoflush flag is set to {@code true}.

param
dnum the double value to print to the target.
see
#print(String)
since
Android 1.0

        println(String.valueOf(dnum));
    
public voidprintln(float fnum)
Prints the string representation of the specified float followed by the system property {@code "line.separator"} to the target. Flushes this writer if the autoflush flag is set to {@code true}.

param
fnum the float value to print to the target.
see
#print(String)
since
Android 1.0

        println(String.valueOf(fnum));
    
public voidprintln(int inum)
Prints the string representation of the specified integer followed by the system property {@code "line.separator"} to the target. Flushes this writer if the autoflush flag is set to {@code true}.

param
inum the integer value to print to the target.
see
#print(String)
since
Android 1.0

        println(String.valueOf(inum));
    
public voidprintln(long lnum)
Prints the string representation of the specified long followed by the system property {@code "line.separator"} to the target. Flushes this writer if the autoflush flag is set to {@code true}.

param
lnum the long value to print to the target.
see
#print(String)
since
Android 1.0

        println(String.valueOf(lnum));
    
public voidprintln(java.lang.Object obj)
Prints the string representation of the specified object followed by the system property {@code "line.separator"} to the target. Flushes this writer if the autoflush flag is set to {@code true}.

param
obj the object to print to the target.
see
#print(String)
since
Android 1.0

        println(String.valueOf(obj));
    
public voidprintln(java.lang.String str)
Prints a string followed by the system property {@code "line.separator"} to the target. The string is converted to an array of bytes using the encoding chosen during the construction of this writer. The bytes are then written to the target with {@code write(int)}. Finally, this writer is flushed if the autoflush flag is set to {@code true}.

If an I/O error occurs, this writer's error flag is set to {@code true}.

param
str the string to print to the target.
see
#write(int)
since
Android 1.0

        synchronized (lock) {
            print(str);
            newline();
        }
    
public voidprintln(boolean bool)
Prints the string representation of the specified boolean followed by the system property {@code "line.separator"} to the target. Flushes this writer if the autoflush flag is set to {@code true}.

param
bool the boolean value to print to the target.
see
#print(String)
since
Android 1.0

        println(String.valueOf(bool));
    
protected voidsetError()
Sets the error flag of this writer to {@code true}.

since
Android 1.0

        synchronized (lock) {
            ioError = true;
        }
    
public voidwrite(char[] buf)
Writes the character buffer {@code buf} to the target.

param
buf the non-null array containing characters to write.
since
Android 1.0

        // BEGIN android-note
        // changed array notation to be consistent with the rest of harmony
        // END android-note
        write(buf, 0, buf.length);
    
public voidwrite(char[] buf, int offset, int count)
Writes {@code count} characters from {@code buffer} starting at {@code offset} to the target.

This writer's error flag is set to {@code true} if this writer is closed or an I/O error occurs.

param
buf the buffer to write to the target.
param
offset the index of the first character in {@code buffer} to write.
param
count the number of characters in {@code buffer} to write.
throws
IndexOutOfBoundsException if {@code offset < 0} or {@code count < 0}, or if {@code offset + count} is greater than the length of {@code buf}.
since
Android 1.0

        // BEGIN android-note
        // changed array notation to be consistent with the rest of harmony
        // END android-note
        doWrite(buf, offset, count);
    
public voidwrite(int oneChar)
Writes one character to the target. Only the two least significant bytes of the integer {@code oneChar} are written.

This writer's error flag is set to {@code true} if this writer is closed or an I/O error occurs.

param
oneChar the character to write to the target.
since
Android 1.0

        doWrite(new char[] { (char) oneChar }, 0, 1);
    
public voidwrite(java.lang.String str)
Writes the characters from the specified string to the target.

param
str the non-null string containing the characters to write.
since
Android 1.0

        write(str.toCharArray());
    
public voidwrite(java.lang.String str, int offset, int count)
Writes {@code count} characters from {@code str} starting at {@code offset} to the target.

param
str the non-null string containing the characters to write.
param
offset the index of the first character in {@code str} to write.
param
count the number of characters from {@code str} to write.
throws
IndexOutOfBoundsException if {@code offset < 0} or {@code count < 0}, or if {@code offset + count} is greater than the length of {@code str}.
since
Android 1.0

        write(str.substring(offset, offset + count).toCharArray());