Ada Programming/Libraries/Ada.Text_IO

Computing » Computer Science » Computer Programming » Ada Programming

---

This language feature is available from Ada 95 on.

Ada.Text_IO is a unit of the Predefined Language Environment since Ada 95.

Description

The package Text_IO is used for simple Input Output (I/O) in text format.

Tips and Tricks for Text_IO

Read a whole line from the console

Ada 2005 has a function Get_Line which returns a newly created string containing the whole line:

function Get_Line return String;

With older Ada generations, you need a little work to get the complete line with one call. The Get_Line procedure gets a line of text of as many characters the Item can hold or up to the new_line indicator, whichever comes first. (The new_line indicator's representation is implementation defined.) It has the following specification:

procedure Get_Line (Item: out String; Last: out Natural);

To be specific, consider an Item that can hold as much as 80 characters. Let's take two lines to read, one holding less that 80 characters, say 10, the other at least 80, perhaps more. Calling

Get_Line (Item, Last);

will read the first line up to the new_line indicator and consume them; Item's first 10 characters will be filled with the text read, the rest is junk; Last will hold the last filled index.

The next call will read the maximum Item can hold, i.e. 80 characters; the rest of the line (if any) and the new_line indicator remain unconsumed. Thus Last will be Item'First - 1 + 80. In order to consume the rest of the line, you have to call Get_Line again. The result will be like one of the two possibilities above, depending on the remaining line length. If no characters are read (i.e. when the new_line indicator is the only thing left unread), Last will hold value Item'First - 1.

The following example shows how the complete line could be read:

with Ada.Text_IO;
with Ada.Strings.Unbounded;

function Get_Line return String is

  package Ustr renames Ada.Strings.Unbounded;
  package T_IO renames Ada.Text_IO;

  Everything: Ustr.Unbounded_String := Ustr.Null_Unbounded_String;
  Item      : String (1 .. 80);
  Last      : Natural;

begin

  Get_Whole_Line:
  loop
    T_IO.Get_Line (Item, Last);                                        -- *
    Ustr.Append (Source => Everything, New_Item => Item (1 .. Last));  -- *
    exit Get_Whole_Line when Last < Item'Last;  -- **
  end loop Get_Whole_Line;

  return Ustr.To_String (Everything);

end Get_Line;

As an exercise, change the calls at (*) to

T_IO.Get_Line (Item (11 .. 20), Last);
Ustr.Append (Source => Everything, New_Item => Item (11 .. Last));

and see which values Item and Last will hold. Which criterium will you then need to exit the loop at (**)?

(This is of course not a very sensible idea to code like this, but as a learning instruction, it's fine.)

Read a whole line from a file

In principle it is the same as in console reading but you have to check for the end of file as well:

exit Get_Whole_Line when Last < Item'Last
                      or T_IO.End_Of_File (File);

End_of_File is always False for console input (except when you manage to enter the implementation defined end_of_file indicator). A well-formed text file (i.e. one created with Ada.Text_IO) will always hold an end_of_line (and an end_of_page) indicator before the end_of_file indicator (see procedure Close).

Generic nested packages

Ada.Text_IO has the following nested packages for input/output of scalar types. The only parameter is the involved type.

• Decimal_IO
• Enumeration_IO
• Fixed_IO
• Float_IO
• Integer_IO
• Modular_IO

Specification

--                     Standard Ada library specification
--   Copyright (c) 2003-2018 Maxim Reznik <reznikmm@gmail.com>
--   Copyright (c) 2004-2016 AXE Consultants
--   Copyright (c) 2004, 2005, 2006 Ada-Europe
--   Copyright (c) 2000 The MITRE Corporation, Inc.
--   Copyright (c) 1992, 1993, 1994, 1995 Intermetrics, Inc.
--   SPDX-License-Identifier: BSD-3-Clause and LicenseRef-AdaReferenceManual
-- -------------------------------------------------------------------------

with Ada.IO_Exceptions;

package Ada.Text_IO is

   type File_Type is limited private;

   type File_Mode is (In_File, Out_File, Append_File);

   type Count is range 0 .. implementation_defined;
   subtype Positive_Count is Count range 1 .. Count'Last;
   Unbounded : constant Count := 0; --  line and page length

   subtype Field       is Integer range 0 .. implementation_defined;
   subtype Number_Base is Integer range 2 .. 16;

   type Type_Set is (Lower_Case, Upper_Case);

   --  File Management

   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;

   --  Control of default input and output files

   procedure Set_Input (File : in File_Type);
   procedure Set_Output(File : in File_Type);
   procedure Set_Error (File : in File_Type);

   function Standard_Input  return File_Type;
   function Standard_Output return File_Type;
   function Standard_Error  return File_Type;

   function Current_Input   return File_Type;
   function Current_Output  return File_Type;
   function Current_Error   return File_Type;

   type File_Access is access constant File_Type;

   function Standard_Input  return File_Access;
   function Standard_Output return File_Access;
   function Standard_Error  return File_Access;

   function Current_Input   return File_Access;
   function Current_Output  return File_Access;
   function Current_Error   return File_Access;

   --   Buffer control
   procedure Flush (File : in out File_Type);
   procedure Flush;

   --  Specification of line and page lengths

   procedure Set_Line_Length (File : in File_Type; To : in Count);
   procedure Set_Line_Length (To   : in Count);

   procedure Set_Page_Length (File : in File_Type; To : in Count);
   procedure Set_Page_Length (To   : in Count);

   function  Line_Length (File : in File_Type) return Count;
   function  Line_Length return Count;

   function  Page_Length (File : in File_Type) return Count;
   function  Page_Length return Count;

   --  Column, Line, and Page Control

   procedure New_Line   (File    : in File_Type;
                         Spacing : in Positive_Count := 1);
   procedure New_Line   (Spacing : in Positive_Count := 1);

   procedure Skip_Line  (File    : in File_Type;
                         Spacing : in Positive_Count := 1);
   procedure Skip_Line  (Spacing : in Positive_Count := 1);

   function  End_Of_Line (File : in File_Type) return Boolean;
   function  End_Of_Line return Boolean;

   procedure New_Page   (File : in File_Type);
   procedure New_Page;

   procedure Skip_Page  (File : in File_Type);
   procedure Skip_Page;

   function  End_Of_Page (File : in File_Type) return Boolean;
   function  End_Of_Page return Boolean;

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

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

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

   function Col (File : in File_Type) return Positive_Count;
   function Col  return Positive_Count;

   function Line (File : in File_Type) return Positive_Count;
   function Line return Positive_Count;

   function Page (File : in File_Type) return Positive_Count;
   function Page return Positive_Count;

   --  Character Input-Output

   procedure Get (File : in  File_Type; Item : out Character);
   procedure Get (Item : out Character);

   procedure Put (File : in  File_Type; Item : in Character);
   procedure Put (Item : in  Character);

   procedure Look_Ahead (File        : in  File_Type;
                         Item        : out Character;
                         End_Of_Line : out Boolean);
   procedure Look_Ahead (Item        : out Character;
                         End_Of_Line : out Boolean);

   procedure Get_Immediate (File      : in  File_Type;
                            Item      : out Character);
   procedure Get_Immediate (Item      : out Character);

   procedure Get_Immediate (File      : in  File_Type;
                            Item      : out Character;
                            Available : out Boolean);
   procedure Get_Immediate (Item      : out Character;
                            Available : out Boolean);

   --  String Input-Output

   procedure Get (File : in  File_Type; Item : out String);
   procedure Get (Item : out String);

   procedure Put (File : in  File_Type; Item : in String);
   procedure Put (Item : in  String);

   procedure Get_Line (File : in  File_Type;
                       Item : out String;
                       Last : out Natural);
   procedure Get_Line (Item : out String; Last : out Natural);

   function Get_Line(File : in  File_Type) return String;

   function Get_Line return String;

   procedure Put_Line (File : in  File_Type; Item : in String);
   procedure Put_Line (Item : in  String);

   --  Generic packages for Input-Output of Integer Types

   generic
      type Num is range <>;
   package Integer_IO is

      Default_Width : Field := Num'Width;
      Default_Base  : Number_Base := 10;

      procedure Get (File  : in  File_Type;
                     Item  : out Num;
                     Width : in Field := 0);
      procedure Get (Item  : out Num;
                     Width : in  Field := 0);

      procedure Put (File  : in File_Type;
                     Item  : in Num;
                     Width : in Field := Default_Width;
                     Base  : in Number_Base := Default_Base);
      procedure Put (Item  : in Num;
                     Width : in Field := Default_Width;
                     Base  : in Number_Base := Default_Base);
      procedure Get (From : in  String;
                     Item : out Num;
                     Last : out Positive);
      procedure Put (To   : out String;
                     Item : in Num;
                     Base : in Number_Base := Default_Base);

   end Integer_IO;

   generic
      type Num is mod <>;
   package Modular_IO is

      Default_Width : Field := Num'Width;
      Default_Base  : Number_Base := 10;

      procedure Get (File  : in  File_Type;
                     Item  : out Num;
                     Width : in Field := 0);
      procedure Get (Item  : out Num;
                     Width : in  Field := 0);

      procedure Put (File  : in File_Type;
                     Item  : in Num;
                     Width : in Field := Default_Width;
                     Base  : in Number_Base := Default_Base);
      procedure Put (Item  : in Num;
                     Width : in Field := Default_Width;
                     Base  : in Number_Base := Default_Base);
      procedure Get (From : in  String;
                     Item : out Num;
                     Last : out Positive);
      procedure Put (To   : out String;
                     Item : in Num;
                     Base : in Number_Base := Default_Base);

   end Modular_IO;

   --  Generic packages for Input-Output of Real Types

   generic
      type Num is digits <>;
   package Float_IO is

      Default_Fore : Field := 2;
      Default_Aft  : Field := Num'Digits-1;
      Default_Exp  : Field := 3;

      procedure Get (File  : in  File_Type;
                     Item  : out Num;
                     Width : in  Field := 0);
      procedure Get (Item  : out Num;
                     Width : in  Field := 0);

      procedure Put (File : in File_Type;
                     Item : in Num;
                     Fore : in Field := Default_Fore;
                     Aft  : in Field := Default_Aft;
                     Exp  : in Field := Default_Exp);
      procedure Put (Item : in Num;
                     Fore : in Field := Default_Fore;
                     Aft  : in Field := Default_Aft;
                     Exp  : in Field := Default_Exp);

      procedure Get (From : in String;
                     Item : out Num;
                     Last : out Positive);
      procedure Put (To   : out String;
                     Item : in Num;
                     Aft  : in Field := Default_Aft;
                     Exp  : in Field := Default_Exp);
   end Float_IO;

   generic
      type Num is delta <>;
   package Fixed_IO is

      Default_Fore : Field := Num'Fore;
      Default_Aft  : Field := Num'Aft;
      Default_Exp  : Field := 0;

      procedure Get (File  : in  File_Type;
                     Item  : out Num;
                     Width : in  Field := 0);
      procedure Get (Item  : out Num;
                     Width : in  Field := 0);

      procedure Put (File : in File_Type;
                     Item : in Num;
                     Fore : in Field := Default_Fore;
                     Aft  : in Field := Default_Aft;
                     Exp  : in Field := Default_Exp);
      procedure Put (Item : in Num;
                     Fore : in Field := Default_Fore;
                     Aft  : in Field := Default_Aft;
                     Exp  : in Field := Default_Exp);

      procedure Get (From : in  String;
                     Item : out Num;
                     Last : out Positive);
      procedure Put (To   : out String;
                     Item : in Num;
                     Aft  : in Field := Default_Aft;
                     Exp  : in Field := Default_Exp);
   end Fixed_IO;

   generic
      type Num is delta <> digits <>;
   package Decimal_IO is

      Default_Fore : Field := Num'Fore;
      Default_Aft  : Field := Num'Aft;
      Default_Exp  : Field := 0;

      procedure Get (File  : in  File_Type;
                     Item  : out Num;
                     Width : in  Field := 0);
      procedure Get (Item  : out Num;
                     Width : in  Field := 0);

      procedure Put (File : in File_Type;
                     Item : in Num;
                     Fore : in Field := Default_Fore;
                     Aft  : in Field := Default_Aft;
                     Exp  : in Field := Default_Exp);
      procedure Put (Item : in Num;
                     Fore : in Field := Default_Fore;
                     Aft  : in Field := Default_Aft;
                     Exp  : in Field := Default_Exp);

      procedure Get (From : in  String;
                     Item : out Num;
                     Last : out Positive);
      procedure Put (To   : out String;
                     Item : in Num;
                     Aft  : in Field := Default_Aft;
                     Exp  : in Field := Default_Exp);
   end Decimal_IO;

   --  Generic package for Input-Output of Enumeration Types

   generic
      type Enum is (<>);
   package Enumeration_IO is

      Default_Width   : Field := 0;
      Default_Setting : Type_Set := Upper_Case;

      procedure Get (File : in  File_Type;
                     Item : out Enum);
      procedure Get (Item : out Enum);

      procedure Put (File  : in File_Type;
                     Item  : in Enum;
                     Width : in Field    := Default_Width;
                     Set   : in Type_Set := Default_Setting);
      procedure Put (Item  : in Enum;
                     Width : in Field    := Default_Width;
                     Set   : in Type_Set := Default_Setting);

      procedure Get (From : in  String;
                     Item : out Enum;
                     Last : out Positive);
      procedure Put (To   : out String;
                     Item : in  Enum;
                     Set  : in  Type_Set := Default_Setting);
   end Enumeration_IO;

   --  Exceptions

   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;
   Layout_Error : exception renames IO_Exceptions.Layout_Error;

private

   type File_Type is limited null record;

end Ada.Text_IO;

See also

Wikibook

• Ada Programming
• Ada Programming/Input Output
• Ada Programming/Libraries
• Ada Programming/Libraries/Ada
• Ada Programming/Libraries/Ada.Strings.Unbounded.Text_IO

External examples

• Search for examples of Ada.Text_IO in: Rosetta Code, GitHub (gists), any Alire crate or this Wikibook.
• Search for posts related to Ada.Text_IO in: Stack Overflow, comp.lang.ada or any Ada related page.

Ada Reference Manual

Ada 95

• A.10.1: The Package Text_IO ^[Annotated]

Ada 2005

• A.10.1: The Package Text_IO ^[Annotated]

Ada 2012

• A.10.1: The Package Text_IO ^[Annotated]

Ada Quality and Style Guide

• 7.7.5 Current Error Files

Open-Source Implementations

FSF GNAT

• Specification: a-textio.ads
• Body: a-textio.adb

drake

• Specification: streams/a-textio.ads
• Body: streams/a-textio.adb