JavaTM Platform
Standard Ed. 6

java.io
类 PrintWriter

java.lang.Object
  继承者 java.io.Writer
      继承者 java.io.PrintWriter
所有已实现的接口:
Closeable, Flushable, Appendable

public class PrintWriter
extends Writer

向文本输出流打印对象的格式化表示形式。此类实现在 PrintStream 中的所有 print 方法。它不包含用于写入原始字节的方法,对于这些字节,程序应该使用未编码的字节流进行写入。

PrintStream 类不同,如果启用了自动刷新,则只有在调用 printlnprintfformat 的其中一个方法时才可能完成此操作,而不是每当正好输出换行符时才完成。这些方法使用平台自有的行分隔符概念,而不是换行符。

此类中的方法不会抛出 I/O 异常,尽管其某些构造方法可能抛出异常。客户端可能会查询调用 checkError() 是否出现错误。

从以下版本开始:
JDK1.1

字段摘要
protected  Writer out
          此 PrintWriter 的底层字符输出流。
 
从类 java.io.Writer 继承的字段
lock
 
构造方法摘要
PrintWriter(File file)
          使用指定文件创建不具有自动行刷新的新 PrintWriter。
PrintWriter(File file, String csn)
          创建具有指定文件和字符集且不带自动刷行新的新 PrintWriter。
PrintWriter(OutputStream out)
          根据现有的 OutputStream 创建不带自动行刷新的新 PrintWriter。
PrintWriter(OutputStream out, boolean autoFlush)
          通过现有的 OutputStream 创建新的 PrintWriter。
PrintWriter(String fileName)
          创建具有指定文件名称且不带自动行刷新的新 PrintWriter。
PrintWriter(String fileName, String csn)
          创建具有指定文件名称和字符集且不带自动行刷新的新 PrintWriter。
PrintWriter(Writer out)
          创建不带自动行刷新的新 PrintWriter。
PrintWriter(Writer out, boolean autoFlush)
          创建新 PrintWriter。
 
方法摘要
 PrintWriter append(char c)
          将指定字符添加到此 writer。
 PrintWriter append(CharSequence csq)
          将指定的字符序列添加到此 writer。
 PrintWriter append(CharSequence csq, int start, int end)
          将指定字符序列的子序列添加到此 writer。
 boolean checkError()
          如果流没有关闭,则刷新流且检查其错误状态。
protected  void clearError()
          清除此流的错误状态。
 void close()
          关闭该流并释放与之关联的所有系统资源。
 void flush()
          刷新该流的缓冲。
 PrintWriter format(Locale l, String format, Object... args)
          使用指定格式字符串和参数将一个格式化字符串写入此 writer 中。
 PrintWriter format(String format, Object... args)
          使用指定格式字符串和参数将一个格式化字符串写入此 writer 中。
 void print(boolean b)
          打印 boolean 值。
 void print(char c)
          打印字符。
 void print(char[] s)
          打印字符数组。
 void print(double d)
          打印 double 精度浮点数。
 void print(float f)
          打印一个浮点数。
 void print(int i)
          打印整数。
 void print(long l)
          打印 long 整数。
 void print(Object obj)
          打印对象。
 void print(String s)
          打印字符串。
 PrintWriter printf(Locale l, String format, Object... args)
          使用指定格式字符串和参数将格式化的字符串写入此 writer 的便捷方法。
 PrintWriter printf(String format, Object... args)
          使用指定格式字符串和参数将格式化的字符串写入此 writer 的便捷方法。
 void println()
          通过写入行分隔符字符串终止当前行。
 void println(boolean x)
          打印 boolean 值,然后终止该行。
 void println(char x)
          打印字符,然后终止该行。
 void println(char[] x)
          打印字符数组,然后终止该行。
 void println(double x)
          打印双精度浮点数,然后终止该行。
 void println(float x)
          打印浮点数,然后终止该行。
 void println(int x)
          打印整数,然后终止该行。
 void println(long x)
          打印 long 整数,然后终止该行。
 void println(Object x)
          打印 Object,然后终止该行。
 void println(String x)
          打印 String,然后终止该行。
protected  void setError()
          指示已发生错误。
 void write(char[] buf)
          写入字符数组。
 void write(char[] buf, int off, int len)
          写入字符数组的某一部分。
 void write(int c)
          写入单个字符。
 void write(String s)
          写入字符串。
 void write(String s, int off, int len)
          写入字符串的某一部分。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

字段详细信息

out

protected Writer out
PrintWriter 的底层字符输出流。

从以下版本开始:
1.2
构造方法详细信息

PrintWriter

public PrintWriter(Writer out)
创建不带自动行刷新的新 PrintWriter。

参数:
out - 字符输出流

PrintWriter

public PrintWriter(Writer out,
                   boolean autoFlush)
创建新 PrintWriter。

参数:
out - 字符输出流
autoFlush - boolean 变量;如果为 true,则 printlnprintfformat 方法将刷新输出缓冲区

PrintWriter

public PrintWriter(OutputStream out)
根据现有的 OutputStream 创建不带自动行刷新的新 PrintWriter。此便捷构造方法创建必要的中间 OutputStreamWriter,后者使用默认字符编码将字符转换为字节。

参数:
out - 输出流
另请参见:
OutputStreamWriter.OutputStreamWriter(java.io.OutputStream)

PrintWriter

public PrintWriter(OutputStream out,
                   boolean autoFlush)
通过现有的 OutputStream 创建新的 PrintWriter。此便捷构造方法创建必要的中间 OutputStreamWriter,后者使用默认字符编码将字符转换为字节。

参数:
out - 输出流
autoFlush - boolean 变量;如果为 true,则 printlnprintfformat 方法将刷新输出缓冲区
另请参见:
OutputStreamWriter.OutputStreamWriter(java.io.OutputStream)

PrintWriter

public PrintWriter(String fileName)
            throws FileNotFoundException
创建具有指定文件名称且不带自动行刷新的新 PrintWriter。此便捷构造方法创建必要的中间 OutputStreamWriter,后者将使用此 Java 虚拟机实例的默认 charset 进行字符编码。

参数:
fileName - 用作此 writer 目标的文件名称。如果存在该文件,则将其大小截取为零;否则,创建一个新文件。将输出写入文件中,并对其进行缓冲处理。
抛出:
FileNotFoundException - 如果给定的字符串不表示现有的可写常规文件,并且无法创建该名称的新常规文件,或者在打开或创建文件时发生其他一些错误
SecurityException - 如果存在安全管理器,并且 checkWrite(fileName) 拒绝对文件进行写入访问。
从以下版本开始:
1.5

PrintWriter

public PrintWriter(String fileName,
                   String csn)
            throws FileNotFoundException,
                   UnsupportedEncodingException
创建具有指定文件名称和字符集且不带自动行刷新的新 PrintWriter。此便捷构造方法创建必要的中间 OutputStreamWriter,后者将使用提供的字符集进行字符编码。

参数:
fileName - 用作此 writer 目标的文件名称。如果存在该文件,则将其大小截取为零;否则,创建一个新文件。将输出写入文件中,并对其进行缓冲处理。
csn - 受支持的字符集的名称
抛出:
FileNotFoundException - 如果给定的字符串不表示现有的可写常规文件,并且无法创建该名称的新常规文件,或者在打开或创建文件时发生其他一些错误
SecurityException - 如果存在安全管理器,并且 checkWrite(fileName) 拒绝对文件进行写入访问。
UnsupportedEncodingException - 如果不支持指定字符集
从以下版本开始:
1.5

PrintWriter

public PrintWriter(File file)
            throws FileNotFoundException
使用指定文件创建不具有自动行刷新的新 PrintWriter。此便捷构造方法创建必要的中间 OutputStreamWriter,后者将使用此 Java 虚拟机实例的默认 charset 进行字符编码。

参数:
file - 作为此 writer 的目标使用的文件。如果存在该文件,则将其大小截取为零;否则,创建一个新文件。将输出写入文件中,并对其进行缓冲处理。
抛出:
FileNotFoundException - 如果给定的文件对象不表示现有的可写常规文件,并且无法创建该名称的新常规文件,或者在打开或创建文件时发生其他一些错误
SecurityException - 如果存在安全管理器,并且 checkWrite(file.getPath()) 拒绝对文件进行写入访问。
从以下版本开始:
1.5

PrintWriter

public PrintWriter(File file,
                   String csn)
            throws FileNotFoundException,
                   UnsupportedEncodingException
创建具有指定文件和字符集且不带自动刷行新的新 PrintWriter。此便捷构造方法创建必要的中间 OutputStreamWriter,后者将使用提供的字符集进行字符编码。

参数:
file - 作为此 writer 的目标使用的文件。如果存在该文件,则将其大小截取为零;否则,创建一个新文件。将输出写入文件中,并对其进行缓冲处理。
csn - 受支持的字符集的名称
抛出:
FileNotFoundException - 如果给定的文件对象不表示现有的可写常规文件,并且无法创建该名称的新常规文件,或者在打开或创建文件时发生其他一些错误
SecurityException - 如果存在安全管理器,并且 checkWrite(file.getPath()) 拒绝对文件进行写入访问。
UnsupportedEncodingException - 如果不支持指定字符集
从以下版本开始:
1.5
方法详细信息

flush

public void flush()
刷新该流的缓冲。

指定者:
接口 Flushable 中的 flush
指定者:
Writer 中的 flush
另请参见:
checkError()

close

public void close()
关闭该流并释放与之关联的所有系统资源。关闭以前关闭的流无效。

指定者:
接口 Closeable 中的 close
指定者:
Writer 中的 close
另请参见:
checkError()

checkError

public boolean checkError()
如果流没有关闭,则刷新流且检查其错误状态。

返回:
如果该打印流在底层输出流上或在格式转换过程中遇到错误,则返回 true

setError

protected void setError()
指示已发生错误。

在调用 clearError() 之前,此方法将导致 checkError() 的后续调用返回 true


clearError

protected void clearError()
清除此流的错误状态。

在另一个写入操作失败并调用 setError() 之前,此方法将导致 checkError() 的后续调用返回 false

从以下版本开始:
1.6

write

public void write(int c)
写入单个字符。

覆盖:
Writer 中的 write
参数:
c - 指定要写入的字符的 int。

write

public void write(char[] buf,
                  int off,
                  int len)
写入字符数组的某一部分。

指定者:
Writer 中的 write
参数:
buf - 字符数组
off - 以其处开始写入字符的偏移量
len - 要写入的字符数

write

public void write(char[] buf)
写入字符数组。此方法不能从 Writer 类继承,因为它必须取消 I/O 异常。

覆盖:
Writer 中的 write
参数:
buf - 要写入的字符数组

write

public void write(String s,
                  int off,
                  int len)
写入字符串的某一部分。

覆盖:
Writer 中的 write
参数:
s - 字符串
off - 以其处开始写入字符的偏移量
len - 要写入的字符数

write

public void write(String s)
写入字符串。此方法不能从 Writer 类继承,因为它必须取消 I/O 异常。

覆盖:
Writer 中的 write
参数:
s - 要写入的字符串

print

public void print(boolean b)
打印 boolean 值。按照平台的默认字符编码将 String.valueOf(boolean) 生成的字符串转换为字节,并完全以 write(int) 方法的方式写入这些字节。

参数:
b - 要打印的 boolean

print

public void print(char c)
打印字符。按照平台的默认字符编码将字符转换为一个或多个字节,并完全以 write(int) 方法的方式写入这些字节。

参数:
c - 要打印的 char

print

public void print(int i)
打印整数。按照平台的默认字节编码将 String.valueOf(int) 生成的字符串转换为字节,并完全以 write(int) 方法的方式写入这些字节。

参数:
i - 要打印的 int
另请参见:
Integer.toString(int)

print

public void print(long l)
打印 long 整数。按照平台的默认字符编码将 String.valueOf(long) 生成的字符串转换为字节,并完全以 write(int) 方法的方式写入这些字节。

参数:
l - 要打印的 long
另请参见:
Long.toString(long)

print

public void print(float f)
打印一个浮点数。按照平台的默认字符编码将 String.valueOf(float) 生成的字符串转换为字节,并完全以 write(int) 方法的方式写入这些字节。

参数:
f - 要打印的 float
另请参见:
Float.toString(float)

print

public void print(double d)
打印 double 精度浮点数。按照平台的默认字符编码将 String.valueOf(double) 生成的字符串转换为字节,并完全以 write(int) 方法的方式写入这些字节。

参数:
d - 要打印的 double
另请参见:
Double.toString(double)

print

public void print(char[] s)
打印字符数组。按照平台的默认字符编码将字符转换为字节,并完全以 write(int) 方法的方式写入这些字节。

参数:
s - 要打印的字符数组
抛出:
NullPointerException - 如果 snull

print

public void print(String s)
打印字符串。如果参数为 null,则打印字符串 "null"。否则,按照平台的默认字符编码将字符串的字符转换为字节,并完全以 write(int) 方法的方式写入这些字节。

参数:
s - 要打印的 String

print

public void print(Object obj)
打印对象。按照平台的默认字符串编码将 String.valueOf(Object) 方法生成的字符串转换为字节,并完全以 write(int) 方法的方式写入这些字节。

参数:
obj - 要打印的 Object
另请参见:
Object.toString()

println

public void println()
通过写入行分隔符字符串终止当前行。行分隔符字符串由系统属性 line.separator 定义,不一定是单个换行符 ('\n')。


println

public void println(boolean x)
打印 boolean 值,然后终止该行。此方法的行为就像先调用 print(boolean) 然后调用 println() 一样。

参数:
x - 要打印的 boolean

println

public void println(char x)
打印字符,然后终止该行。此方法的行为就像先调用 print(char) 然后调用 println() 一样。

参数:
x - 要打印的 char

println

public void println(int x)
打印整数,然后终止该行。此方法的行为就像先调用 print(int) 然后调用 println() 一样。

参数:
x - 要打印的 int

println

public void println(long x)
打印 long 整数,然后终止该行。此方法的行为就像先调用 print(long) 然后调用 println() 一样。

参数:
x - 要打印的 long

println

public void println(float x)
打印浮点数,然后终止该行。此方法的行为就像先调用 print(float) 然后调用 println() 一样。

参数:
x - 要打印的 float

println

public void println(double x)
打印双精度浮点数,然后终止该行。此方法的行为就像先调用 print(double) 然后调用 println() 一样。

参数:
x - 要打印的 double

println

public void println(char[] x)
打印字符数组,然后终止该行。此方法的行为就像先调用 print(char[]) 然后调用 println() 一样。

参数:
x - 要打印的 char 值的数组

println

public void println(String x)
打印 String,然后终止该行。此方法的行为就像先调用 print(String) 然后调用 println() 一样。

参数:
x - 要打印的 String

println

public void println(Object x)
打印 Object,然后终止该行。此方法首先调用 String.valueOf(x) 以获取打印对象的字符串值,行为就像先调用 print(String) 然后调用 println() 一样。

参数:
x - 要打印的 Object

printf

public PrintWriter printf(String format,
                          Object... args)
使用指定格式字符串和参数将格式化的字符串写入此 writer 的便捷方法。如果启用自动刷新,则调用此方法将刷新输出缓冲区。

调用此方法的 out.printf(format, args) 形式,行为与以下调用完全相同:

     out.format(format, args) 

参数:
format - 在格式字符串的语法中描述的格式字符串。
args - 格式字符串中的格式说明符引用的参数。如果参数多于格式说明符,则忽略额外的参数。参数的数量是可变的,并且可以为零。参数的最大数量受到 Java Virtual Machine Specification 定义的 Java 数组的最大维数的限制。针对 null 参数的行为依赖于转换
返回:
此 writer
抛出:
IllegalFormatException - 如果格式字符串包含非法语法、与给定参数不兼容的格式说明符、对给定格式字符串而言不够充足的参数或其他非法条件。有关所有可能的格式错误的规范,请参阅 formatter 类规范的详细信息部分。
NullPointerException - 如果 formatnull
从以下版本开始:
1.5

printf

public PrintWriter printf(Locale l,
                          String format,
                          Object... args)
使用指定格式字符串和参数将格式化的字符串写入此 writer 的便捷方法。如果启用自动刷新,则调用此方法将刷新输出缓冲区。

调用此方法的 out.printf(l, format, args) 形式,行为与以下调用完全相同:

     out.format(l, format, args) 

参数:
l - 格式化过程中应用的 locale。如果 lnull,则不应用本地化。
format - 在格式字符串的语法中描述的格式字符串。
args - 格式字符串中的格式说明符引用的参数。如果参数多于格式说明符,则忽略额外的参数。参数的数量是可变的,并且可以为零。参数的最大数量受到 Java Virtual Machine Specification 定义的 Java 数组的最大维数的限制。针对 null 参数的行为依赖于转换
返回:
此 writer
抛出:
IllegalFormatException - 如果格式字符串包含非法语法、与给定参数不兼容的格式说明符、对给定格式字符串而言不够充足的参数或其他非法条件。有关所有可能的格式错误的规范,请参阅 formatter 类规范的详细信息部分。
NullPointerException - 如果 formatnull
从以下版本开始:
1.5

format

public PrintWriter format(String format,
                          Object... args)
使用指定格式字符串和参数将一个格式化字符串写入此 writer 中。如果启用自动刷新,则调用此方法将刷新输出缓冲区。

始终使用的语言环境是由 Locale.getDefault() 返回的语言环境,不管以前在此对象上调用了其他什么样的格式化方法。

参数:
format - 在格式字符串的语法中描述的格式字符串。
args - 格式字符串中的格式说明符引用的参数。如果参数多于格式说明符,则忽略额外的参数。参数的数量是可变的,并且可以为零。参数的最大数量受到 Java Virtual Machine Specification 定义的 Java 数组的最大维数的限制。针对 null 参数的行为依赖于 conversion
返回:
此 writer
抛出:
IllegalFormatException - 如果格式字符串包含非法语法、与给定参数不兼容的格式说明符、对给定格式字符串而言不够充足的参数或其他非法条件。有关所有可能的格式错误的规范,请参阅 formatter 类规范的详细信息部分。
NullPointerException - 如果 formatnull
从以下版本开始:
1.5

format

public PrintWriter format(Locale l,
                          String format,
                          Object... args)
使用指定格式字符串和参数将一个格式化字符串写入此 writer 中。如果启用自动刷新,则调用此方法将刷新输出缓冲区。

参数:
l - 格式化过程中应用的 locale。如果 lnull,则不应用本地化。
format - 在格式字符串的语法中描述的格式字符串。
args - 格式字符串中的格式说明符引用的参数。如果参数多于格式说明符,则忽略额外的参数。参数的数量是可变的,并且可以为零。参数的最大数量受到 Java Virtual Machine Specification 定义的 Java 数组的最大维数的限制。针对 null 参数的行为依赖于 conversion
返回:
此 writer
抛出:
IllegalFormatException - 如果格式字符串包含非法语法、与给定参数不兼容的格式说明符、对给定格式字符串而言不够充足的参数或其他非法条件。有关所有可能的格式错误的规范,请参阅 formatter 类规范的详细信息部分。
NullPointerException - 如果 formatnull
从以下版本开始:
1.5

append

public PrintWriter append(CharSequence csq)
将指定的字符序列添加到此 writer。

此方法调用 out.append(csq) 的行为与调用下列方法完全相同:

     out.write(csq.toString()) 

可能不添加整个序列,也可能添加,具体取决于字符序列 csqtoString 指定。例如,调用一个字符缓冲区的 toString 方法将返回一个子序列,其内容取决于缓冲区的位置和限制。

指定者:
接口 Appendable 中的 append
覆盖:
Writer 中的 append
参数:
csq - 要添加的字符串序列。如果 csqnull,则向此 writer 添加四个字符 "null"
返回:
此 writer
从以下版本开始:
1.5

append

public PrintWriter append(CharSequence csq,
                          int start,
                          int end)
将指定字符序列的子序列添加到此 writer。

csq 不为 null 时,调用该方法的 out.append(csq、 start、 end) 形式,行为与以下调用完全相同:

     out.write(csq.subSequence(start, end).toString()) 

指定者:
接口 Appendable 中的 append
覆盖:
Writer 中的 append
参数:
csq - 要添加子序列的字符序列。如果 csqnull,则添加四个字符 "null",就好像 csq 包含这些字符一样。
start - 子序列中第一个字符的索引
end - 子序列中最后一个字符后面的字符的索引
返回:
此 writer
抛出:
IndexOutOfBoundsException - 如果 startend 为负,而 start 大于 end 或者 end 大于 csq.length()
从以下版本开始:
1.5

append

public PrintWriter append(char c)
将指定字符添加到此 writer。

调用此方法的 out.append(c) 形式,行为与以下调用完全相同:

     out.write(c) 

指定者:
接口 Appendable 中的 append
覆盖:
Writer 中的 append
参数:
c - 要添加的 16 位字符
返回:
此 writer
从以下版本开始:
1.5

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策