接口 DataInput

java.io

接口 DataInput

所有已知子接口：

ImageInputStream, ImageOutputStream, ObjectInput

所有已知实现类：

DataInputStream, FileCacheImageInputStream, FileCacheImageOutputStream, FileImageInputStream, FileImageOutputStream, ImageInputStreamImpl, ImageOutputStreamImpl, MemoryCacheImageInputStream, MemoryCacheImageOutputStream, ObjectInputStream, RandomAccessFile

public interface DataInput

DataInput 接口用于从二进制流中读取字节，并根据所有 Java 基本类型数据进行重构。同时还提供根据 UTF-8 修改版格式的数据重构 String 的工具。

对于此接口中的所有数据读取例程来说，如果在读取所需字节数之前已经到达文件末尾 (end of file)，则将抛出 EOFException（IOException 的一种）。如果因为到达文件末尾以外的其他原因无法读取字节，则将抛出 IOException 而不是 EOFException。尤其是，在输入流已关闭的情况下，将抛出 IOException。

UTF-8 修改版

DataInput 和 DataOutput 接口的实现表示稍作改版的 UTF-8 格式的 Unicode 字符串。（关于标准 UTF-8 格式的信息，请参阅 The Unicode Standard, Version 4.0 的 3.9 Unicode Encoding Forms 节）。注意，在下表中，最高有效位显示在最左边的列中。

'\u0001' 到 '\u007F' 范围内的所有字符都是用单个字节表示的：

位值
字节 1
0 位 6-0

null 字符 '\u0000' 以及从 '\u0080' 到 '\u07FF' 的范围内的字符用两个字节表示：

位值
字节 1
1 1 0 位 10-6

字节 2
1 0 位 5-0

'\u0800' 到 '\uFFFF' 范围内的 char 值用三个字节表示：

位值
字节 1
1 1 1 0 位 15-12

字节 2
1 0 位 11-6

字节 3
1 0 位 5-0

这种格式与标准 UTF-8 格式之间的不同如下：

null 字节 '\u0000' 是用 2-byte 格式而不是 1-byte 格式编码的，因此已编码的字符串中决不会有嵌入的 null。
仅使用 1-byte、2-byte 和 3-byte 格式。
增补字符是以代理项对的形式表示的。

从以下版本开始：

JDK1.0

方法摘要
`boolean`	`readBoolean()` 读取一个输入字节，如果该字节不是零，则返回 `true`，如果是零，则返回 `false`。
`byte`	`readByte()` 读取并返回一个输入字节。
`char`	`readChar()` 读取两个输入字节并返回一个 `char` 值。
`double`	`readDouble()` 读取八个输入字节并返回一个 `double` 值。
`float`	`readFloat()` 读取四个输入字节并返回一个 `float` 值。
`void`	`readFully(byte[] b)` 从输入流中读取一些字节，并将它们存储在缓冲区数组 `b` 中。
`void`	`readFully(byte[] b, int off, int len)` 从输入流中读取 `len` 个字节。
`int`	`readInt()` 读取四个输入字节并返回一个 `int` 值。
`String`	`readLine()` 从输入流中读取下一文本行。
`long`	`readLong()` 读取八个输入字节并返回一个 `long` 值。
`short`	`readShort()` 读取两个输入字节并返回一个 `short` 值。
`int`	`readUnsignedByte()` 读取一个输入字节，将它左侧补零 (zero-extend) 转变为 `int` 类型，并返回结果，所以结果的范围是 `0` 到 `255`。
`int`	`readUnsignedShort()` 读取两个输入字节，并返回 `0` 到 `65535` 范围内的一个 `int` 值。
`String`	`readUTF()` 读入一个已使用 UTF-8 修改版格式编码的字符串。
`int`	`skipBytes(int n)` 试图在输入流中跳过数据的 `n` 个字节，并丢弃跳过的字节。

方法详细信息

readFully

void readFully(byte[] b)throws IOException

从输入流中读取一些字节，并将它们存储在缓冲区数组 b 中。读取的字节数等于 b 的长度。

在出现以下条件之一以前，此方法将一直阻塞：

输入数据的 b.length 个字节是可用的，在这种情况下，正常返回。
检测到文件末尾，在这种情况下，抛出 EOFException。
发生 I/O 错误，在这种情况下，将抛出 IOException，而不是 EOFException。

如果 b 为 null，则抛出 NullPointerException。如果 b.length 为零，则不读取字节。否则，将读取的第一个字节存储到元素 b[0] 中，下一个字节存储到 b[1] 中，依此类推。如果此方法抛出异常，则可能是因为已经用输入流中的数据更新了 b 的某些（但非全部）字节。

参数：

b - 存储读取数据的缓冲区。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readFully

void readFully(byte[] b, int off, int len)  throws IOException

从输入流中读取 len 个字节。

在出现以下条件之一以前，此方法将一直阻塞：

输入数据的 len 个字节是可用的，在这种情况下，正常返回。
检测到文件末尾，在这种情况下，抛出 EOFException。
如果发生 I/O 错误，在这种情况下，将抛出 IOException，而不是 EOFException。

如果 b 为 null，则抛出 NullPointerException。如果 off 为负，或 len 为负，或者 off+len 大于数组 b 的长度，则抛出 IndexOutOfBoundsException。如果 len 为零，则不读取字节。否则，将读取的第一个字节存储到元素 b[off] 中，下一个字节存储到 b[off+1] 中，依此类推。读取的字节数至多等于 b[0]。

参数：

b - 存储读取数据的缓冲区。

off - 指定数据中的偏移量的 int 值。

len - 指定读取的字节数的 int 值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

skipBytes

int skipBytes(int n) throws IOException

试图在输入流中跳过数据的 n 个字节，并丢弃跳过的字节。不过，可以跳过更少的字节数，该字节数甚至可以为零。这可能由很多情况引起；在已经跳过 n 个字节前到达文件末尾只是其中的一种可能。此方法从不抛出 EOFException。返回实际跳过的字节数。

参数：

n - 要跳过的字节数。

返回：

实际跳过的字节数。

抛出：

IOException - 如果发生 I/O 错误。

readBoolean

boolean readBoolean() throws IOException

读取一个输入字节，如果该字节不是零，则返回 true，如果是零，则返回 false。此方法适用于读取用接口 DataOutput 的 writeBoolean 方法写入的字节。

返回：

读取的 boolean 值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readByte

byte readByte() throws IOException

读取并返回一个输入字节。该字节被看作是 -128 到 127（包含）范围内的一个有符号值。此方法适用于读取用接口 DataOutput 的 writeByte 方法写入的字节。

返回：

读取的 8 位值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readUnsignedByte

int readUnsignedByte() throws IOException

读取一个输入字节，将它左侧补零 (zero-extend) 转变为 int 类型，并返回结果，所以结果的范围是 0 到 255。如果接口 DataOutput 的 writeByte 方法的参数是 0 到 255 之间的值，则此方法适用于读取用 writeByte 写入的字节。

返回：

读取的无符号 8 位值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readShort

short readShort() throws IOException

读取两个输入字节并返回一个 short 值。设 a 为第一个读取字节，b 为第二个读取字节。返回的值是：

(short)((a << 8) | (b & 0xff))

此方法适用于读取用接口 DataOutput 的 writeShort 方法写入的字节。

返回：

读取的 16 位值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readUnsignedShort

int readUnsignedShort() throws IOException

读取两个输入字节，并返回 0 到 65535 范围内的一个 int 值。设 a 为第一个读取字节，b 为第二个读取字节。返回的值是：

(((a & 0xff) << 8) | (b & 0xff))

如果接口 DataOutput 的 writeShort 方法的参数是 0 到 65535 范围内的值，则此方法适用于读取用 writeShort 写入的字节。

返回：

读取的无符号 16 位值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readChar

char readChar() throws IOException

读取两个输入字节并返回一个 char 值。设 a 为第一个读取字节，b 为第二个读取字节。返回的值是：

(char)((a << 8) | (b & 0xff))

此方法适用于读取用接口 DataOutput 的 writeChar 方法写入的字节。

返回：

读取的 char 值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readInt

int readInt()  throws IOException

读取四个输入字节并返回一个 int 值。设 a-d 为四个读取字节中的第一个字节。返回的值是：

 (((a & 0xff) << 24) | ((b & 0xff) << 16) |((c & 0xff) << 8) | (d & 0xff))

此方法适用于读取用接口 DataOutput 的 writeInt 方法写入的字节。

返回：

读取的 int 值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readLong

long readLong() throws IOException

读取八个输入字节并返回一个 long 值。设 a-h 为八个读取字节中的第一个字节。返回的值是：

 (((long)(a & 0xff) << 56) |((long)(b & 0xff) << 48) |((long)(c & 0xff) << 40) |((long)(d & 0xff) << 32) |((long)(e & 0xff) << 24) |((long)(f & 0xff) << 16) |((long)(g & 0xff) <<  8) |((long)(h & 0xff)))

此方法适用于读取用接口 DataOutput 的 writeLong 方法写入的字节。

返回：

读取的 long 值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readFloat

float readFloat() throws IOException

读取四个输入字节并返回一个 float 值。实现这一点的方法是：先使用与 readInt 方法完全相同的方式构造一个 int 值，然后使用与 Float.intBitsToFloat 方法完全相同的方式将此 int 值转换成一个 float 值。此方法适用于读取用接口 DataOutput 的 writeFloat 方法写入的字节。

返回：

读取的 float 值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readDouble

double readDouble() throws IOException

读取八个输入字节并返回一个 double 值。实现这一点的方法是：先使用与 readlong 方法完全相同的方式构造一个 long 值，然后使用与 Double.longBitsToDouble 方法完全相同的方式将此 long 值转换成一个 double 值。此方法适用于读取用接口 DataOutput 的 writeDouble 方法写入的字节。

返回：

读取的 double 值。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

readLine

String readLine() throws IOException

从输入流中读取下一文本行。该方法读取连续的字节，将每个字节分别转换成一个字符，直到遇到行结尾符或到达末尾；然后以 String 形式返回读取的字符。注意，因为此方法用于处理字符，所以它不支持整个 Unicode 字符集的输入。

如果在一个字节都没有读取的时候就到达文件末尾，则返回 null。否则，通过左侧补零将读取的每个字节转换成 char 类型的值。如果遇到字符 '\n'，则丢弃它并且停止读取。如果遇到字符 '\r' 则丢弃它，如果后续字节转变成字符 '\n'，则同样丢弃它并停止读取。如果在遇到字符 '\n' 和 '\r' 之一前到达文件末尾，则停止读取。一旦已停止读取，则返回一个 String，它按顺序包含所有已读取且未丢弃的字符。注意，此字符串中的每个字符的值都将小于 \u0100（即 (char)256）的值。

返回：

输入流中文本的下一行，如果还没有读取一个字节就到达文件末尾，则返回 null。

抛出：

IOException - 如果发生 I/O 错误。

readUTF

String readUTF() throws IOException

读入一个已使用 UTF-8 修改版格式编码的字符串。readUTF 的常规协定是：该方法读取使用 UTF-8 修改版格式编码的 Unicode 字符串的表示形式；然后以 String 的形式返回此字符串。

首先读取两个字节，并使用它们构造一个无符号 16 位整数，构造方式与 readUnsignedShort 方法的方式完全相同。该整数值被称为 UTF 长度，它指定要读取的额外字节数。然后成组地将这些字节转换为字符。每组的长度根据该组第一个字节的值计算。紧跟在某个组后面的字节（如果有）是下一组的第一个字节。

如果组的第一个字节与位模式 0xxxxxxx（其中 x 表示“可能为 0 或 1”）匹配，则该组只有这一个字节。该字节被左侧补零，转换成一个字符。

如果组的第一个字节与位模式 110xxxxx 匹配，则该组只由字节 a 和另一个字节 b 组成。如果没有字节 b（因为字节 a 是要读取的最后一个字节），或者字节 b 与位模式 10xxxxxx 不匹配，则抛出 UTFDataFormatException。否则，将该组转换成字符：

(char)(((a& 0x1F) << 6) | (b & 0x3F))

如果组的第一个字节与位模式 1110xxxx 匹配，则该组由字节 a 和另外两个字节 b 和 c 组成。如果没有字节 c（因为字节 a 是要读取的最后两个字节之一），或者字节 b 或字节 c 与位模式 10xxxxxx 不匹配，则抛出 UTFDataFormatException。否则，将该组转换成字符：

 (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))

如果组的第一个字节与模式 1111xxxx 或模式 10xxxxxx 匹配，则抛出 UTFDataFormatException。

如果在执行整个过程中的任意时间到达文件末尾，则抛出 EOFException。

在通过此过程将每个组转换成字符后，按照从输入流中读取相应组的顺序，将这些字符收集在一起，形成一个 String，然后该字符串将被返回。

可以使用 DataOutput 接口的 writeUTF 方法写入适合此方法读取的数据。

返回：

一个 Unicode 字符串。

抛出：

EOFException - 如果此流在读取所有字节之前到达末尾。

IOException - 如果发生 I/O 错误。

UTFDataFormatException - 如果这些字节不表示一个有效的、UTF-8 修改版编码的字符串。