Интерфейс 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 в The Unicode Standard, Version 4.0)

Символы в диапазоне '\u0001' по '\u007F' представлены одним байтом.
Нулевой символ '\u0000' и символы в диапазоне '\u0080' по '\u07FF' представлены парой байтов.
Символы в диапазоне '\u0800' по '\uFFFF' представлены тремя байтами.

Значение	Байт	Значения битов
Значение	Байт	7	6	5	4	3	2	1	0
`\u0001` по `\u007F`	1	0	биты 6-0
`\u0000`, `\u0080` по `\u07FF`	1	1	1	0	биты 10-6
`\u0000`, `\u0080` по `\u07FF`	2	1	0	биты 5-0
`\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-байтовый форматы.
Дополнительные символы представлены в виде пар суррогатов.

С:: 1.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 - буфер, в который считываются данные.
Исключения:: NullPointerException - если b равно null.; 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 - целое число, задающее смещение в массиве данных b.; len - целое число, задающее количество байтов для чтения.
Исключения:: NullPointerException - если b равно null.; IndexOutOfBoundsException - если off отрицательное, len отрицательное или len больше b.length - off.; 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. Обратите внимание, что поскольку этот метод обрабатывает байты, он не поддерживает ввод полного набора символов Юникод.

Если конец файла обнаружен до того, как будет прочитан хотя бы один байт, то возвращается 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.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/DataInput.html