Ada Runtime Library: Difference between revisions

=== Image attributes ===

Scalar types in Ada support the <tt>Image</tt> attribute. This attribute returns a string representation of a variable. This is of particular significance for operating-system development due to the need to ouput debugging information in string format to the console. The <tt>Image</tt> attribute is defined in [https://www.adaic.org/resources/add_content/standards/05rm/html/RM-K.html Annex K] of the Ada Language Reference Manual. Support for the image attributes of a particular scalar type is implemented in the run-time library.<br/>

For operating-system development, arguably the most important types to be able to print are unsigned integer types. By default, the GNAT compiler expects functionality for imaging unsigned integer types to be defined in the package <tt>s-imguns.ads</tt> and its associated package body. Provided below is an example implementation:

'''s-imguns.ads'''

<source lang="ada">

with System.Unsigned_Types;

-------------------------------------------------------------------------------

-- SYSTEM.IMG_UNS

--

-- Purpose:

-- This package provides an implementation of the Image attribute for

-- unsigned integer types.

-------------------------------------------------------------------------------

package System.Img_Uns is

pragma Pure;

----------------------------------------------------------------------------

-- Image_Unsigned

--

-- purpose:

-- Computes Unsigned'Image (V) and stores the result in S (1 .. P) \

-- setting the resulting value of P. The caller guarantees that S is

-- long enough to hold the result, and that S'First is 1.

----------------------------------------------------------------------------

procedure Image_Unsigned (

V : System.Unsigned_Types.Unsigned;

S : in out String;

P : out Natural

)

with Inline;

----------------------------------------------------------------------------

-- Set_Image_Unsigned

--

-- Purpose:

-- Stores the image of V in S starting at S (P + 1), P is updated to

-- point to the last character stored. The value stored is identical

-- to the value of Unsigned'Image (V) except that no leading space is

-- stored. The caller guarantees that S is long enough to hold the

-- result. S need not have a lower bound of 1.

----------------------------------------------------------------------------

procedure Set_Image_Unsigned (

V : System.Unsigned_Types.Unsigned;

S : in out String;

P : in out Natural

);

end System.Img_Uns;

</source>

'''s-imguns.adb'''

<source lang="ada">

with System.Unsigned_Types; use System.Unsigned_Types;

package body System.Img_Uns is

----------------------------------------------------------------------------

-- Image_Unsigned

----------------------------------------------------------------------------

procedure Image_Unsigned (

V : System.Unsigned_Types.Unsigned;

S : in out String;

P : out Natural

) is

pragma Assert (S'First = 1);

begin

S (1) := ' ';

P := 1;

Set_Image_Unsigned (V, S, P);

exception

when Constraint_Error =>

return;

end Image_Unsigned;

----------------------------------------------------------------------------

-- Set_Image_Unsigned

--

-- Implementation Notes:

-- - Refer to: http://www.nihamkin.com/2016/11/25/

-- writing-linux-modules-in-ada-part-3/

----------------------------------------------------------------------------

procedure Set_Image_Unsigned (

V : Unsigned;

S : in out String;

P : in out Natural

) is

-- The number of digits in the resulting string.

Digit_Count : Natural := 0;

begin

Get_Digit_Count :

declare

V2 : Unsigned := V;

begin

while V2 /= 0 loop

Digit_Count := Digit_Count + 1;

V2 := V2 / 10;

end loop;

exception

when Constraint_Error =>

Digit_Count := 0;

end Get_Digit_Count;

Write_To_String :

begin

if Digit_Count = 0 then

P := P + 1;

S (P) := '0';

else

for I in reverse 0 .. (Digit_Count - 1) loop

P := P + 1;

S (P) := Character'Val (48 + (V / 10 ** I) rem 10);

end loop;

end if;

exception

when Constraint_Error =>

return;

end Write_To_String;

end Set_Image_Unsigned;

end System.Img_Uns;

</source>

User-defined images for a given type can be implemented by overriding the default implementation of the <tt>Put_Image</tt> attribute.