Руководство по Ada (Ada 2022)

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
with Preelaborate, Global => in out synchronized is

type Stream_Access is access all Root_Stream_Type'Class;

type File_Type is limited private
with Preelaborable_Initialization;

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)
with Global => overriding in out File;

procedure Read (File : in File_Type;
Item : out Stream_Element_Array;
Last : out Stream_Element_Offset)
with Global => overriding in out File;

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

-- Запись массива потоковых элементов в файл
procedure Write (File : in File_Type;
Item : in Stream_Element_Array;
To : in Positive_Count)
with Global => overriding in out File;

procedure Write (File : in File_Type;
Item : in Stream_Element_Array)
with Global => overriding in out File;

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

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

procedure Set_Index(File : in File_Type; To : in Positive_Count)
with Global => overriding in out File;

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;

package Wide_File_Names is

-- Управление файлами

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

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

function Name (File : in File_Type) return Wide_String;

function Form (File : in File_Type) return Wide_String;

end Wide_File_Names;

package Wide_Wide_File_Names is

-- Управление файлами

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

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

function Name (File : in File_Type) return Wide_Wide_String;

function Form (File : in File_Type) return Wide_Wide_String;

end Wide_Wide_File_Names;

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

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

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

Функция End_Of_File:

Возвращает Mode_Error, если режим файла не In_File;

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

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

Процедура Set_Mode устанавливает режим файла. Если новый режим — Append_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 плюс количество прочитанных или записанных потоковых элементов.

END_OF_DOCUMENT_MARKER ```

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

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

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

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