# Ada Programming/Input Output
## Overview

The standard Ada libraries provide several Input/Output facilities, each one adapted to specific needs. Namely, the language defines the following dedicated packages:
* Text_IO
* Sequential_IO
* Direct_IO
* Stream_IO
The programmer must choose the adequate package depending on the application needs. For example, the following properties of the data handled by the application should be considered:
* Data contents: plain text, or binary data?
* Accessing the data: random access, or sequential access?
* Medium: data file, console, network/data-bus?
* Data structure: homogeneous file (sequence of the same data field), heterogeneous file (different data fields)?
* Data format: adherence to an existing data format, or the application can freely choose a new one?
For example, Stream_IO is very powerful and can handle complex data structures but can be heavier than other packages; Sequential_IO is lean and easy to use but cannot be used by applications requiring random data access; Text_IO can handle just textual data, but it is enough for handling the command-line console.
The following table gives some advices for choosing the more adequate one:
Simple heuristics for choosing an I/O package :
| Data access | Plain text | Binary data | Binary data |
| Data access | Plain text | Homogeneous | Heterogeneous |
| Sequential | Text_IO | Sequential_IO | Stream_IO |
| Random | Stream_IO | Direct_IO | Stream_IO |
So the most important lesson to learn is choosing the right one. This chapter will describe more in detail these standard packages, explaining how to use them effectively. Besides these Ada-defined packages for general I/O operations each Ada compiler usually has other implementation-defined Input-Output facilities, and there are also other external libraries for specialized I/O needs like XML processing or interfacing with databases.

## Text I/O

Text I/O is probably the most used Input/Output package. All data inside the file are represented by human readable text. Text I/O provides support for line and page layout but the standard is free form text.
This example copies text from standard input to standard output when all lines are shorter than 80 characters, the string length. See package Text I/O how to deal with longer lines.
The package also contains several generic packages for converting numeric and enumeration types to character strings; there are child packages for handling Bounded and Unbounded strings, allowing the programmer to read and write different data types in the same file easily (there are ready-to-use instantiations of these generic packages for the Integer, Float, and Complex types). Finally, the same family of Ada.Text_IO packages (including the several children and instantiation packages) for the type Wide_Character and Wide_Wide_Character.
It is worth noting that the family of Text_IO packages provide some automatic text processing. For example, the Get procedures for numeric and enumeration types ignore white space at the beginning of a line (Get_Line for String does not present this behavior), or adding line and page terminators when closing the file. This is thus adequate for applications handling simple textual data, but users requiring direct management of text (e.g. raw access to the character encoding) must consider other packages like Sequential_IO.
See this tutorial for a longer example of using text I/O in Ada.

## Direct I/O

Direct I/O is used for random access files which contain only elements of one specific type. With Direct_IO you can position the file pointer to any element of that type (random access), however you can't freely choose the element type, the element type needs to be a definite subtype.

## Sequential I/O

Direct I/O is used for random access files which contain only elements of one specific type. With Sequential_IO it is the other way round: you can choose between definite and indefinite element types but you have to read and write the elements one after the other.

## Stream I/O

Stream I/O is the most powerful input/output package which Ada provides. Stream I/O allows you to mix objects from different element types in one sequential file. In order to read/write from/to a stream each type provides a 'Read and 'Write attribute as well as an 'Input and 'Output attribute. These attributes are automatically generated for each type you declare.
The 'Read and 'Write attributes treat the elements as raw data. They are suitable for low level input/output as well as interfacing with other programming languages.
The 'Input and 'Output attributes add additional control information to the file, like for example the 'First and 'Last attributes for an array.
In object orientated programming you can also use the 'Class'Input and 'Class'Output attributes - they will store and recover the actual object type as well.
Stream I/O is also the most flexible input/output package. All I/O attributes can be replaced with user defined functions or procedures using representation clauses and you can provide your own Stream I/O types using flexible object-oriented techniques.
The following example, defines a Create_File program which creates a "test.data" file with heterogeneous data. It stores -100 Integer, 55.1 Float, and 10 user-defined Halfbyte_Type values in binary. Supposing that your system architecture is little endian, and Integer size is 4 bytes, the file will contain the following binary data (in hexadecimal): 9cff ffff 6666 5c42 0a.

## See also
### Wikibook

* Ada Programming
* Ada Programming/Libraries/Ada.Direct_IO
* Ada Programming/Libraries/Ada.Sequential_IO
* Ada Programming/Libraries/Ada.Streams
** Ada Programming/Libraries/Ada.Streams.Stream_IO
** Ada Programming/Libraries/Ada.Text_IO.Text_Streams
* Ada Programming/Libraries/Ada.Text_IO
** Ada Programming/Libraries/Ada.Text_IO.Enumeration_IO (nested package)
** Ada Programming/Libraries/Ada.Text_IO.Integer_IO (nested package)
** Ada Programming/Libraries/Ada.Text_IO.Modular_IO (nested package)
** Ada Programming/Libraries/Ada.Text_IO.Float_IO (nested package)
** Ada Programming/Libraries/Ada.Text_IO.Fixed_IO (nested package)
** Ada Programming/Libraries/Ada.Text_IO.Decimal_IO (nested package)
** Ada Programming/Libraries/Ada.Text_IO.Bounded_IO
** Ada Programming/Libraries/Ada.Text_IO.Unbounded_IO
** Ada Programming/Libraries/Ada.Text_IO.Complex_IO (specialized needs annex)
** Ada Programming/Libraries/Ada.Text_IO.Editing (specialized needs annex)
* Ada Programming/Libraries/Ada.Integer_Text_IO
* Ada Programming/Libraries/Ada.Float_Text_IO
* Ada Programming/Libraries/Ada.Complex_Text_IO (specialized needs annex)
* Ada Programming/Libraries/Ada.Storage_IO (not a general-purpose I/O package)
* Ada Programming/Libraries/Ada.IO_Exceptions
* Ada Programming/Libraries/Ada.Command_Line
* Ada Programming/Libraries/Ada.Directories
* Ada Programming/Libraries/Ada.Environment_Variables
* Ada Programming/Libraries/GNAT.IO (implementation defined)
* Ada Programming/Libraries/GNAT.IO_Aux (implementation defined)
* Ada Programming/Libraries/GNAT.Calendar.Time_IO (implementation defined)
* Ada Programming/Libraries/System.IO (implementation defined)
* Ada Programming/Libraries
** Ada Programming/Libraries/GUI
** Ada Programming/Libraries/Web
** Ada Programming/Libraries/Database
* Ada Programming/Platform
* Ada Programming/Platform/Linux
* Ada Programming/Platform/Windows

### Ada Reference Manual

* A.6 Input-Output (Annotated)
* A.7 External Files and File Objects (Annotated)
* A.8 Sequential and Direct Files (Annotated)
* A.10 Text Input-Output (Annotated)
* A.11 Wide Text Input-Output and Wide Wide Text Input-Output (Annotated)
* A.12 Stream Input-Output (Annotated)
* A.13 Exceptions in Input-Output (Annotated)
* A.14 File Sharing (Annotated)

### Ada 95 Quality and Style Guide

* 7.7 Input/Output
** 7.7.1 Name and Form Parameters
** 7.7.2 File Closing
** 7.7.3 Input/Output on Access Types
** 7.7.4 Package Ada.Streams.Stream_IO
** 7.7.5 Current Error Files