Справочное руководство по Ada 2005

A.12.1 Пакет Streams.Stream_IO

Подпрограммы вложенного пакета Streams.Stream_IO обеспечивают управление файлами потоков. Доступ к файлу потока может быть последовательным, посредством вызова Read или Write для передачи массива элементов потока, или позиционным (если это поддерживается реализацией для данного файла), указанием относительного индекса элемента. Поскольку файл потока может быть преобразован в значение Stream_Access, вызов подпрограмм атрибутов, ориентированных на поток, различных типов элементов с тем же значением Stream_Access обеспечивает гетерогенный ввод-вывод. См. 13.13 для общего обсуждения потоков.

Статическая семантика

Элементы файла потока являются элементами потока. Если позиционирование поддерживается для указанного внешнего файла, для файла поддерживаются текущий индекс и текущий размер, как описано в A.8. Если позиционирование не поддерживается, текущий индекс не поддерживается, а текущий размер определяется реализацией.

Пакет библиотеки Streams.Stream_IO имеет следующее объявление:

with Ada.IO_Exceptions;
package Ada.Streams.Stream_IO is

type Stream_Access is access all Root_Stream_Type'Class;

type File_Type is limited private;

type File_Mode is (In_File, Out_File, Append_File);

type Count is range 0 .. определяемое реализацией;
subtype Positive_Count is Count range 1 .. Count'Last;
-- Индекс в файле, в элементах потока.

procedure Create (File : in out File_Type;
Mode : in File_Mode := Out_File;
Name : in String := "";
Form : in String := "");

procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in String;
Form : in String := "");

procedure Close (File : in out File_Type);
procedure Delete (File : in out File_Type);
procedure Reset (File : in out File_Type; Mode : in File_Mode);
procedure Reset (File : in out File_Type);

function Mode (File : in File_Type) return File_Mode;
function Name (File : in File_Type) return String;
function Form (File : in File_Type) return String;

function Is_Open (File : in File_Type) return Boolean;
function End_Of_File (File : in File_Type) return Boolean;

function Stream (File : in File_Type) return Stream_Access;
-- Возврат доступа к потоку для использования с T'Input и T'Output

Этот абзац был удалён.

-- Чтение массива элементов потока из файла
procedure Read (File : in File_Type;
Item : out Stream_Element_Array;
Last : out Stream_Element_Offset;
From : in Positive_Count);

procedure Read (File : in File_Type;
Item : out Stream_Element_Array;
Last : out Stream_Element_Offset);

Этот абзац был удалён.

-- Запись массива элементов потока в файл
procedure Write (File : in File_Type;
Item : in Stream_Element_Array;
To : in Positive_Count);

procedure Write (File : in File_Type;
Item : in Stream_Element_Array);

Этот абзац был удалён.

-- Операции с позицией внутри файла

procedure Set_Index(File : in File_Type; To : in Positive_Count);

function Index(File : in File_Type) return Positive_Count;
function Size (File : in File_Type) return Count;

procedure Set_Mode(File : in out File_Type; Mode : in File_Mode);

procedure Flush(File : in File_Type);

-- исключения
Status_Error : exception renames IO_Exceptions.Status_Error;
Mode_Error : exception renames IO_Exceptions.Mode_Error;
Name_Error : exception renames IO_Exceptions.Name_Error;
Use_Error : exception renames IO_Exceptions.Use_Error;
Device_Error : exception renames IO_Exceptions.Device_Error;
End_Error : exception renames IO_Exceptions.End_Error;
Data_Error : exception renames IO_Exceptions.Data_Error;

private
... -- не определено языком
end Ada.Streams.Stream_IO;

Тип File_Type требует финализации (см. 7.6).

Подпрограммы, указанные в подпункте A.8.2 для управления внешними файлами (Create, Open, Close, Delete, Reset, Mode, Name, Form и Is_Open) доступны для файлов потоков.

Функция End_Of_File:

Распространяет Mode_Error, если режим файла не In_File;

Если позиционирование поддерживается для данного внешнего файла, функция возвращает True, если текущий индекс превышает размер внешнего файла; в противном случае возвращает False;

Если позиционирование не поддерживается для данного внешнего файла, функция возвращает True, если больше нет элементов для чтения из данного файла; в противном случае возвращает False.

Процедура Set_Mode устанавливает режим файла. Если новый режим Append_File, файл позиционируется в конец; в противном случае позиция в файле не изменяется.

Процедура Flush синхронизирует внешний файл с внутренним файлом (путём сброса всех внутренних буферов) без закрытия файла или изменения позиции. Mode_Error распространяется, если режим файла In_File.

Функция Stream возвращает результат Stream_Access из объекта File_Type, что позволяет использовать атрибуты Read, Write, Input и Output, ориентированные на поток, для одного и того же файла для нескольких типов. Stream распространяет Status_Error, если File не открыт.

Процедуры Read и Write эквивалентны соответствующим операциям в пакете Streams. Read распространяет Mode_Error, если режим File не In_File. Write распространяет Mode_Error, если режим File не Out_File или Append_File. Процедура Read с параметром Positive_Count начинает чтение по указанному индексу. Процедура Write с параметром Positive_Count начинает запись по указанному индексу. Для файла, поддерживающего позиционирование, Read без параметра Positive_Count начинает чтение с текущего индекса, а Write без параметра Positive_Count начинает запись с текущего индекса.

Функция Size возвращает текущий размер файла.

Функция Index возвращает текущий индекс.

Процедура Set_Index устанавливает текущий индекс в указанное значение.

Если позиционирование поддерживается для внешнего файла, текущий индекс поддерживается следующим образом:

Для Open и Create, если параметр Mode равен Append_File, текущий индекс устанавливается в текущий размер файла плюс один; в противном случае текущий индекс устанавливается в один.

Для Reset, если параметр Mode равен Append_File или параметр Mode отсутствует и текущий режим Append_File, текущий индекс устанавливается в текущий размер файла плюс один; в противном случае текущий индекс устанавливается в один.

Для Set_Mode, если новый режим Append_File, текущий индекс устанавливается в текущий размер плюс один; в противном случае текущий индекс не изменяется.

Для Read и Write без параметра Positive_Count текущий индекс увеличивается на количество элементов потока, считанных или записанных.

Для Read и Write с параметром Positive_Count значение текущего индекса устанавливается в значение параметра Positive_Count плюс количество элементов потока, считанных или записанных.

Если позиционирование не поддерживается для данного файла, вызов Index или Set_Index распространяет Use_Error. Аналогично, вызов Read или Write с параметром Positive_Count распространяет Use_Error.

Абзацы с 34 по 36 были удалены.

Ошибка выполнения

Если объект File_Type, переданный в функцию Stream, позже закрывается или завершается, а атрибуты, ориентированные на поток, впоследствии вызываются (явным или неявным образом) на значении Stream_Access, возвращённом Stream, выполнение является ошибочным. Это правило действует даже если объект File_Type был открыт снова после закрытия.