Интерфейс DataInput

Все известные подинтерфейсы:: ImageInputStream, ImageOutputStream, ObjectInput

Все известные реализующие классы:: DataInputStream, FileCacheImageInputStream, FileCacheImageOutputStream, FileImageInputStream, FileImageOutputStream, ImageInputStreamImpl, ImageOutputStreamImpl, MemoryCacheImageInputStream, MemoryCacheImageOutputStream, ObjectInputStream, RandomAccessFile

public interface DataInput

Интерфейс DataInput предоставляет возможность чтения байтов из двоичного потока и восстановления из них данных в любом из типов Java примитивных типов. Также есть возможность восстановления String из данных в формате изменённого UTF-8.

Вообще, для всех процедур чтения в этом интерфейсе справедливо, что если конец файла достигнут до того, как необходимое количество байтов было прочитано, то будет брошено исключение EOFException (которое является типом IOException). Если какой-либо байт не может быть прочитан по какой-либо причине, кроме конца файла, то будет брошено исключение IOException, отличное от EOFException. В частности, может быть брошено исключение IOException, если входной поток был закрыт.

Изменённый UTF-8

Реализации интерфейсов DataInput и DataOutput представляют строки Unicode в формате, который является небольшим изменением UTF-8. (Для информации о стандартном формате UTF-8 см. раздел 3.9 Unicode Encoding Forms в The Unicode Standard, Version 4.0). Обратите внимание, что в следующей таблице старший бит находится в крайнем левом столбце.

Все символы в диапазоне `'\u0001'` до `'\u007F'` представлены одним байтом:
	Значения битов
Байт 1	0	биты 6-0
Символ нуль `'\u0000'` и символы в диапазоне `'\u0080'` до `'\u07FF'` представлены парой байтов:
	Значения битов
Байт 1	1	1	0	биты 10-6
Байт 2	1	0	биты 5-0
Значения `char` в диапазоне `'\u0800'` до `'\uFFFF'` представлены тремя байтами:
	Значения битов
Байт 1	1	1	1	0	биты 15-12
Байт 2	1	0	биты 11-6
Байт 3	1	0	биты 5-0

Различия между этим форматом и стандартным форматом UTF-8 следующие:

Байт нуль '\u0000' кодируется в формате из 2 байтов, а не из 1 байта, чтобы закодированные строки никогда не имели вложенных нулей.
Используются только форматы из 1, 2 и 3 байтов.
Дополнительные символы представляются в виде пар суррогатов.

С:: JDK1.0
См. также:: DataInputStream, DataOutput

Методы

Модификатор и тип	Метод и описание
`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()` Читает один байт входного потока, расширяет его с нулями до типа `int` и возвращает результат, который, следовательно, находится в диапазоне от `0` до `255`.
`int`	`readUnsignedShort()` Читает два байта входного потока и возвращает значение типа `int` в диапазоне от `0` до `65535`.
`String`	`readUTF()` Читает строку, закодированную в формате изменённого UTF-8.
`int`	`skipBytes(int n)` Попытка пропустить `n` байтов данных из входного потока, отбрасывая пропущенные байты.

Методы

readFully

void readFully(byte[] b)
        throws IOException

Считывает несколько байтов из потока ввода и сохраняет их в массив буфера b. Количество считанных байтов равно длине b.

Этот метод блокируется до тех пор, пока не выполнится одно из следующих условий:

b.length байтов входных данных становятся доступны, в этом случае выполняется нормальный возврат.
Обнаружен конец файла, в этом случае выбрасывается EOFException.
Возникает ошибка ввода-вывода, в этом случае выбрасывается IOException ошибка, отличная от EOFException.

Если b равно null, выбрасывается NullPointerException. Если b.length равно нулю, байты не считываются. В противном случае первый считанный байт сохраняется в элемент b[0], следующий - в b[1] и так далее. Если из этого метода выбрасывается исключение, то возможно, что некоторые, но не все байты b были обновлены данными из входного потока.

Параметры:: b - буфер, в который считываются данные.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

readFully

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

Считывает len байтов из входного потока.

Этот метод блокируется до тех пор, пока не выполнится одно из следующих условий:

len байтов входных данных становятся доступны, в этом случае выполняется нормальный возврат.
Обнаружен конец файла, в этом случае выбрасывается EOFException.
Возникает ошибка ввода-вывода, в этом случае выбрасывается IOException ошибка, отличная от EOFException.

Если b равно null, выбрасывается NullPointerException. Если off отрицательно, или len отрицательно, или off+len больше длины массива b, выбрасывается IndexOutOfBoundsException. Если len равно нулю, байты не считываются. В противном случае первый считанный байт сохраняется в элемент b[off], следующий - в b[off+1], и так далее. Количество считанных байтов не превышает len.

Параметры:: b - буфер, в который считываются данные.; off - целочисленное значение, определяющее смещение в данных.; len - целочисленное значение, определяющее количество байтов для чтения.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

skipBytes

int skipBytes(int n)
       throws IOException

Попытка пропустить n байтов данных из входного потока, удалив пропущенные байты. Однако, он может пропустить меньшее количество байтов, возможно, ноль. Это может быть результатом различных условий; достижение конца файла до пропуска n байтов является лишь одним из возможных случаев. Этот метод никогда не выбрасывает EOFException. Возвращается фактическое количество пропущенных байтов.

Параметры:: n - количество байтов для пропуска.
Возвращаемое значение:: количество фактически пропущенных байтов.
Исключения:: IOException - если возникает ошибка ввода-вывода.

readBoolean

boolean readBoolean()
             throws IOException

Считывает один байт входных данных и возвращает true, если этот байт не равен нулю, false, если этот байт равен нулю. Этот метод подходит для чтения байта, записанного методом writeBoolean интерфейса DataOutput.

Возвращаемое значение:: считанное значение boolean.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

readByte

byte readByte()
       throws IOException

Считывает и возвращает один байт входных данных. Байта обрабатывается как целое со знаком в диапазоне -128 по 127 включительно. Этот метод подходит для чтения байта, записанного методом writeByte интерфейса DataOutput.

Возвращаемое значение:: считанное значение с 8 битами.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

readUnsignedByte

int readUnsignedByte()
              throws IOException

Считывает один входной байт, беззнаково расширяет его до типа int и возвращает результат, который, следовательно, находится в диапазоне 0 по 255. Этот метод подходит для чтения байта, записанного методом writeByte интерфейса DataOutput, если аргумент для writeByte предназначался для значения в диапазоне 0 по 255.

Возвращаемое значение:: считанное беззнаковое 8-битное значение.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

readShort

short readShort()
         throws IOException

Считывает два входных байта и возвращает значение типа short. Пусть a - первый считанный байт, а b - второй. Возвращаемое значение равно:

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

. Этот метод подходит для чтения байтов, записанных методом writeShort интерфейса DataOutput.

Возвращаемое значение:: считанное 16-битное значение.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

readUnsignedShort

int readUnsignedShort()
               throws IOException

Считывает два входных байта и возвращает значение типа int в диапазоне 0 по 65535. Пусть a - первый считанный байт, а b - второй. Возвращаемое значение равно:

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

. Этот метод подходит для чтения байтов, записанных методом writeShort интерфейса DataOutput, если аргумент для writeShort предназначался для значения в диапазоне 0 по 65535.

Возвращаемое значение:: считанное беззнаковое 16-битное значение.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

readChar

char readChar()
       throws IOException

Считывает два входных байта и возвращает значение типа char. Пусть a - первый считанный байт, а b - второй. Возвращаемое значение равно:

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

. Этот метод подходит для чтения байтов, записанных методом writeChar интерфейса DataOutput.

Возвращаемое значение:: считанное значение char.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

readInt

int readInt()
     throws IOException

Считывает четыре входных байта и возвращает значение типа int. Пусть a-d - первый, второй, третий и четвёртый считанные байты. Возвращаемое значение равно:

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

. Этот метод подходит для чтения байтов, записанных методом writeInt интерфейса DataOutput.

Возвращаемое значение:: считанное значение int.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

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)))

Этот метод подходит для чтения байтов, записанных методом writeLong интерфейса DataOutput.

Возвращаемое значение:: считанное значение long.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

readFloat

float readFloat()
         throws IOException

Считывает четыре входных байта и возвращает значение типа float. Сначала он создаёт значение типа int точно так же, как метод readInt, а затем преобразует это значение типа int в float точно так же, как метод Float.intBitsToFloat. Этот метод подходит для чтения байтов, записанных методом writeFloat интерфейса DataOutput.

Возвращаемое значение:: считанное значение float.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

readDouble

double readDouble()
           throws IOException

Считывает восемь входных байтов и возвращает значение типа double. Сначала он создаёт значение типа long точно так же, как метод readLong, а затем преобразует это значение типа long в double точно так же, как метод Double.longBitsToDouble. Этот метод подходит для чтения байтов, записанных методом writeDouble интерфейса DataOutput.

Возвращаемое значение:: считанное значение double.
Исключения:: EOFException - если этот поток достигает конца до чтения всех байтов.; IOException - если возникает ошибка ввода-вывода.

readLine

String readLine()
         throws IOException

Читает следующую строку текста из входного потока. Она считывает последовательные байты, преобразуя каждый байт по отдельности в символ, до тех пор, пока не встретит символ окончания строки или конец файла; прочитанные символы затем возвращаются как String. Обратите внимание, что поскольку этот метод обрабатывает байты, он не поддерживает ввод полного набора символов Unicode.

Если конец файла встречается до того, как можно прочитать хотя бы один байт, то возвращается null. В противном случае каждый считанный байт преобразуется в тип char путем расширения нулями. Если встречается символ '\n', он отбрасывается, и чтение прекращается. Если встречается символ '\r', он отбрасывается, и если следующий байт преобразуется в символ '\n', то и он отбрасывается; чтение затем прекращается. Если конец файла встречается до того, как встретятся любой из символов '\n' и '\r', чтение прекращается. После прекращения чтения возвращается String, содержащий все прочитанные и не отброшенные символы в порядке их чтения. Обратите внимание, что значение каждого символа в этой строке будет меньше \u0100, то есть (char)256.

Возвращает:: следующую строку текста из входного потока или null, если конец файла встречается до того, как можно прочитать байт.
Выбрасывает:: IOException - если произошла ошибка ввода-вывода.

readUTF

String readUTF()
        throws IOException

Читает строку, закодированную в формате изменённого UTF-8. Общее соглашение для readUTF заключается в том, что она читает представление строки символов Юникод, закодированной в формате изменённого UTF-8; эта строка символов затем возвращается как 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, который и возвращается.

Метод writeUTF интерфейса DataOutput может быть использован для записи данных, пригодных для чтения этим методом.

Возвращает:: строку Юникод.
Выбрасывает:: EOFException - если поток достигает конца, прежде чем прочитаны все байты.; IOException - если произошла ошибка ввода-вывода.; UTFDataFormatException - если байты не представляют собой допустимого кодирования строки в формате изменённого UTF-8.

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.