8 Standard Library Routines

The Ada Reference Manual contains in Annex A a full description of an extensive set of standard library routines that can be used in any Ada program, and which must be provided by all Ada compilers. They are analogous to the standard C library used by C programs.

GNAT implements all of the facilities described in annex A, and for most purposes the description in the Ada Reference Manual, or appropriate Ada text book, will be sufficient for making use of these facilities.

In the case of the input-output facilities, See The Implementation of Standard I/O, gives details on exactly how GNAT interfaces to the file system. For the remaining packages, the Ada Reference Manual should be sufficient. The following is a list of the packages included, together with a brief description of the functionality that is provided.

For completeness, references are included to other predefined library routines defined in other sections of the Ada Reference Manual (these are cross-indexed from Annex A).

Ada (A.2)

This is a parent package for all the standard library packages. It is usually included implicitly in your program, and itself contains no useful data or routines.

Ada.Calendar (9.6)

Calendar provides time of day access, and routines for manipulating times and durations.

Ada.Characters (A.3.1)

This is a dummy parent package that contains no useful entities

Ada.Characters.Handling (A.3.2)

This package provides some basic character handling capabilities, including classification functions for classes of characters (e.g. test for letters, or digits).

Ada.Characters.Latin_1 (A.3.3)

This package includes a complete set of definitions of the characters that appear in type CHARACTER. It is useful for writing programs that will run in international environments. For example, if you want an upper case E with an acute accent in a string, it is often better to use the definition of UC_E_Acute in this package. Then your program will print in an understandable manner even if your environment does not support these extended characters.

Ada.Command_Line (A.15)

This package provides access to the command line parameters and the name of the current program (analogous to the use of argc and argv in C), and also allows the exit status for the program to be set in a system-independent manner.

Ada.Decimal (F.2)

This package provides constants describing the range of decimal numbers implemented, and also a decimal divide routine (analogous to the COBOL verb DIVIDE ... GIVING ... REMAINDER ...)

Ada.Direct_IO (A.8.4)

This package provides input-output using a model of a set of records of fixed-length, containing an arbitrary definite Ada type, indexed by an integer record number.

Ada.Dynamic_Priorities (D.5)

This package allows the priorities of a task to be adjusted dynamically as the task is running.

Ada.Exceptions (11.4.1)

This package provides additional information on exceptions, and also contains facilities for treating exceptions as data objects, and raising exceptions with associated messages.

Ada.Finalization (7.6)

This package contains the declarations and subprograms to support the use of controlled types, providing for automatic initialization and finalization (analogous to the constructors and destructors of C++)

Ada.Interrupts (C.3.2)

This package provides facilities for interfacing to interrupts, which includes the set of signals or conditions that can be raised and recognized as interrupts.

Ada.Interrupts.Names (C.3.2)

This package provides the set of interrupt names (actually signal or condition names) that can be handled by GNAT.

Ada.IO_Exceptions (A.13)

This package defines the set of exceptions that can be raised by use of the standard IO packages.

Ada.Numerics

This package contains some standard constants and exceptions used throughout the numerics packages. Note that the constants pi and e are defined here, and it is better to use these definitions than rolling your own.

Ada.Numerics.Complex_Elementary_Functions

Provides the implementation of standard elementary functions (such as log and trigonometric functions) operating on complex numbers using the standard Float and the Complex and Imaginary types created by the package Numerics.Complex_Types.

Ada.Numerics.Complex_Types

This is a predefined instantiation of Numerics.Generic_Complex_Types using Standard.Float to build the type Complex and Imaginary.

Ada.Numerics.Discrete_Random

This generic package provides a random number generator suitable for generating uniformly distributed values of a specified discrete subtype.

Ada.Numerics.Float_Random

This package provides a random number generator suitable for generating uniformly distributed floating point values in the unit interval.

Ada.Numerics.Generic_Complex_Elementary_Functions

This is a generic version of the package that provides the implementation of standard elementary functions (such as log and trigonometric functions) for an arbitrary complex type.

The following predefined instantiations of this package are provided:

Short_Float

Ada.Numerics.Short_Complex_Elementary_Functions

Float

Ada.Numerics.Complex_Elementary_Functions

Long_Float

Ada.Numerics.Long_Complex_Elementary_Functions

Ada.Numerics.Generic_Complex_Types

This is a generic package that allows the creation of complex types, with associated complex arithmetic operations.

The following predefined instantiations of this package exist

Short_Float

Ada.Numerics.Short_Complex_Complex_Types

Float

Ada.Numerics.Complex_Complex_Types

Long_Float

Ada.Numerics.Long_Complex_Complex_Types

Ada.Numerics.Generic_Elementary_Functions

This is a generic package that provides the implementation of standard elementary functions (such as log an trigonometric functions) for an arbitrary float type.

The following predefined instantiations of this package exist

Short_Float

Ada.Numerics.Short_Elementary_Functions

Float

Ada.Numerics.Elementary_Functions

Long_Float

Ada.Numerics.Long_Elementary_Functions

Ada.Real_Time (D.8)

This package provides facilities similar to those of Calendar, but operating with a finer clock suitable for real time control. Note that annex D requires that there be no backward clock jumps, and GNAT generally guarantees this behavior, but of course if the external clock on which the GNAT runtime depends is deliberately reset by some external event, then such a backward jump may occur.

Ada.Sequential_IO (A.8.1)

This package provides input-output facilities for sequential files, which can contain a sequence of values of a single type, which can be any Ada type, including indefinite (unconstrained) types.

Ada.Storage_IO (A.9)

This package provides a facility for mapping arbitrary Ada types to and from a storage buffer. It is primarily intended for the creation of new IO packages.

Ada.Streams (13.13.1)

This is a generic package that provides the basic support for the concept of streams as used by the stream attributes (Input, Output, Read and Write).

Ada.Streams.Stream_IO (A.12.1)

This package is a specialization of the type Streams defined in package Streams together with a set of operations providing Stream_IO capability. The Stream_IO model permits both random and sequential access to a file which can contain an arbitrary set of values of one or more Ada types.

Ada.Strings (A.4.1)

This package provides some basic constants used by the string handling packages.

Ada.Strings.Bounded (A.4.4)

This package provides facilities for handling variable length strings. The bounded model requires a maximum length. It is thus somewhat more limited than the unbounded model, but avoids the use of dynamic allocation or finalization.

Ada.Strings.Fixed (A.4.3)

This package provides facilities for handling fixed length strings.

Ada.Strings.Maps (A.4.2)

This package provides facilities for handling character mappings and arbitrarily defined subsets of characters. For instance it is useful in defining specialized translation tables.

Ada.Strings.Maps.Constants (A.4.6)

This package provides a standard set of predefined mappings and predefined character sets. For example, the standard upper to lower case conversion table is found in this package. Note that upper to lower case conversion is non-trivial if you want to take the entire set of characters, including extended characters like E with an acute accent, into account. You should use the mappings in this package (rather than adding 32 yourself) to do case mappings.

Ada.Strings.Unbounded (A.4.5)

This package provides facilities for handling variable length strings. The unbounded model allows arbitrary length strings, but requires the use of dynamic allocation and finalization.

Ada.Strings.Wide_Bounded (A.4.7)

Ada.Strings.Wide_Fixed (A.4.7)

Ada.Strings.Wide_Maps (A.4.7)

Ada.Strings.Wide_Maps.Constants (A.4.7)

Ada.Strings.Wide_Unbounded (A.4.7)

These packages provide analogous capabilities to the corresponding packages without ‘Wide_’ in the name, but operate with the types Wide_String and Wide_Character instead of String and Character.

Ada.Strings.Wide_Wide_Bounded (A.4.7)

Ada.Strings.Wide_Wide_Fixed (A.4.7)

Ada.Strings.Wide_Wide_Maps (A.4.7)

Ada.Strings.Wide_Wide_Maps.Constants (A.4.7)

Ada.Strings.Wide_Wide_Unbounded (A.4.7)

These packages provide analogous capabilities to the corresponding packages without ‘Wide_’ in the name, but operate with the types Wide_Wide_String and Wide_Wide_Character instead of String and Character.

Ada.Synchronous_Task_Control (D.10)

This package provides some standard facilities for controlling task communication in a synchronous manner.

Ada.Tags

This package contains definitions for manipulation of the tags of tagged values.

Ada.Task_Attributes

This package provides the capability of associating arbitrary task-specific data with separate tasks.

Ada.Text_IO

This package provides basic text input-output capabilities for character, string and numeric data. The subpackages of this package are listed next.

Ada.Text_IO.Decimal_IO

Provides input-output facilities for decimal fixed-point types

Ada.Text_IO.Enumeration_IO

Provides input-output facilities for enumeration types.

Ada.Text_IO.Fixed_IO

Provides input-output facilities for ordinary fixed-point types.

Ada.Text_IO.Float_IO

Provides input-output facilities for float types. The following predefined instantiations of this generic package are available:

Short_Float

Short_Float_Text_IO

Float

Float_Text_IO

Long_Float

Long_Float_Text_IO

Ada.Text_IO.Integer_IO

Provides input-output facilities for integer types. The following predefined instantiations of this generic package are available:

Short_Short_Integer

Ada.Short_Short_Integer_Text_IO

Short_Integer

Ada.Short_Integer_Text_IO

Integer

Ada.Integer_Text_IO

Long_Integer

Ada.Long_Integer_Text_IO

Long_Long_Integer

Ada.Long_Long_Integer_Text_IO

Ada.Text_IO.Modular_IO

Provides input-output facilities for modular (unsigned) types

Ada.Text_IO.Complex_IO (G.1.3)

This package provides basic text input-output capabilities for complex data.

Ada.Text_IO.Editing (F.3.3)

This package contains routines for edited output, analogous to the use of pictures in COBOL. The picture formats used by this package are a close copy of the facility in COBOL.

Ada.Text_IO.Text_Streams (A.12.2)

This package provides a facility that allows Text_IO files to be treated as streams, so that the stream attributes can be used for writing arbitrary data, including binary data, to Text_IO files.

Ada.Unchecked_Conversion (13.9)

This generic package allows arbitrary conversion from one type to another of the same size, providing for breaking the type safety in special circumstances.

If the types have the same Size (more accurately the same Value_Size), then the effect is simply to transfer the bits from the source to the target type without any modification. This usage is well defined, and for simple types whose representation is typically the same across all implementations, gives a portable method of performing such conversions.

If the types do not have the same size, then the result is implementation defined, and thus may be non-portable. The following describes how GNAT handles such unchecked conversion cases.

If the types are of different sizes, and are both discrete types, then the effect is of a normal type conversion without any constraint checking. In particular if the result type has a larger size, the result will be zero or sign extended. If the result type has a smaller size, the result will be truncated by ignoring high order bits.

If the types are of different sizes, and are not both discrete types, then the conversion works as though pointers were created to the source and target, and the pointer value is converted. The effect is that bits are copied from successive low order storage units and bits of the source up to the length of the target type.

A warning is issued if the lengths differ, since the effect in this case is implementation dependent, and the above behavior may not match that of some other compiler.

A pointer to one type may be converted to a pointer to another type using unchecked conversion. The only case in which the effect is undefined is when one or both pointers are pointers to unconstrained array types. In this case, the bounds information may get incorrectly transferred, and in particular, GNAT uses double size pointers for such types, and it is meaningless to convert between such pointer types. GNAT will issue a warning if the alignment of the target designated type is more strict than the alignment of the source designated type (since the result may be unaligned in this case).

A pointer other than a pointer to an unconstrained array type may be converted to and from System.Address. Such usage is common in Ada 83 programs, but note that Ada.Address_To_Access_Conversions is the preferred method of performing such conversions in Ada 95 and Ada 2005. Neither unchecked conversion nor Ada.Address_To_Access_Conversions should be used in conjunction with pointers to unconstrained objects, since the bounds information cannot be handled correctly in this case.

Ada.Unchecked_Deallocation (13.11.2)

This generic package allows explicit freeing of storage previously allocated by use of an allocator.

Ada.Wide_Text_IO (A.11)

This package is similar to Ada.Text_IO, except that the external file supports wide character representations, and the internal types are Wide_Character and Wide_String instead of Character and String. It contains generic subpackages listed next.

Ada.Wide_Text_IO.Decimal_IO

Provides input-output facilities for decimal fixed-point types

Ada.Wide_Text_IO.Enumeration_IO

Provides input-output facilities for enumeration types.

Ada.Wide_Text_IO.Fixed_IO

Provides input-output facilities for ordinary fixed-point types.

Ada.Wide_Text_IO.Float_IO

Provides input-output facilities for float types. The following predefined instantiations of this generic package are available:

Short_Float

Short_Float_Wide_Text_IO

Float

Float_Wide_Text_IO

Long_Float

Long_Float_Wide_Text_IO

Ada.Wide_Text_IO.Integer_IO

Provides input-output facilities for integer types. The following predefined instantiations of this generic package are available:

Short_Short_Integer

Ada.Short_Short_Integer_Wide_Text_IO

Short_Integer

Ada.Short_Integer_Wide_Text_IO

Integer

Ada.Integer_Wide_Text_IO

Long_Integer

Ada.Long_Integer_Wide_Text_IO

Long_Long_Integer

Ada.Long_Long_Integer_Wide_Text_IO

Ada.Wide_Text_IO.Modular_IO

Provides input-output facilities for modular (unsigned) types

Ada.Wide_Text_IO.Complex_IO (G.1.3)

This package is similar to Ada.Text_IO.Complex_IO, except that the external file supports wide character representations.

Ada.Wide_Text_IO.Editing (F.3.4)

This package is similar to Ada.Text_IO.Editing, except that the types are Wide_Character and Wide_String instead of Character and String.

Ada.Wide_Text_IO.Streams (A.12.3)

This package is similar to Ada.Text_IO.Streams, except that the types are Wide_Character and Wide_String instead of Character and String.

Ada.Wide_Wide_Text_IO (A.11)

This package is similar to Ada.Text_IO, except that the external file supports wide character representations, and the internal types are Wide_Character and Wide_String instead of Character and String. It contains generic subpackages listed next.

Ada.Wide_Wide_Text_IO.Decimal_IO

Provides input-output facilities for decimal fixed-point types

Ada.Wide_Wide_Text_IO.Enumeration_IO

Provides input-output facilities for enumeration types.

Ada.Wide_Wide_Text_IO.Fixed_IO

Provides input-output facilities for ordinary fixed-point types.

Ada.Wide_Wide_Text_IO.Float_IO

Provides input-output facilities for float types. The following predefined instantiations of this generic package are available:

Short_Float

Short_Float_Wide_Wide_Text_IO

Float

Float_Wide_Wide_Text_IO

Long_Float

Long_Float_Wide_Wide_Text_IO

Ada.Wide_Wide_Text_IO.Integer_IO

Provides input-output facilities for integer types. The following predefined instantiations of this generic package are available:

Short_Short_Integer

Ada.Short_Short_Integer_Wide_Wide_Text_IO

Short_Integer

Ada.Short_Integer_Wide_Wide_Text_IO

Integer

Ada.Integer_Wide_Wide_Text_IO

Long_Integer

Ada.Long_Integer_Wide_Wide_Text_IO

Long_Long_Integer

Ada.Long_Long_Integer_Wide_Wide_Text_IO

Ada.Wide_Wide_Text_IO.Modular_IO

Provides input-output facilities for modular (unsigned) types

Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3)

This package is similar to Ada.Text_IO.Complex_IO, except that the external file supports wide character representations.

Ada.Wide_Wide_Text_IO.Editing (F.3.4)

This package is similar to Ada.Text_IO.Editing, except that the types are Wide_Character and Wide_String instead of Character and String.

Ada.Wide_Wide_Text_IO.Streams (A.12.3)

This package is similar to Ada.Text_IO.Streams, except that the types are Wide_Character and Wide_String instead of Character and String.