Skip to content

Minor improvements to subsection on machine representation #1316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gusthoff wants to merge 14 commits into
base: main
Choose a base branch
from
Open

Minor improvements to subsection on machine representation #1316

Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
c170d61
Adding integer type for overlay
gusthoff Feb 14, 2026
0cb2f62
Adding Gen_Show_Info procedure
gusthoff Feb 14, 2026
be2d8b2
Replace calls to `Put_Line` by `Show_Info`
gusthoff Feb 14, 2026
145a58a
Add headers to code example
gusthoff Feb 14, 2026
f67a67e
Adapting explanation after changes to code example
gusthoff Feb 14, 2026
b4749a4
Editorial change: Machine_Implementation => Machine_Representation
gusthoff Feb 14, 2026
33288a1
Editorial change: correcting typo
gusthoff Feb 16, 2026
51408c5
Editorial change: correct button in code example
gusthoff Feb 16, 2026
f9db140
Editorial change: adding empty line in code example
gusthoff Feb 16, 2026
14abe96
Mentioning generic procedure
gusthoff Feb 16, 2026
66f96d9
Editorial change: correcting typo
gusthoff Feb 16, 2026
acb85da
Editorial change: adding decimal non-exponential version of number
gusthoff Feb 16, 2026
781b78d
Editorial change: adding missing word
gusthoff Mar 13, 2026
e109cb7
Adding assert for overlay
gusthoff Mar 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 95 additions & 63 deletions content/courses/advanced-ada/parts/data_types/numerics.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3183,7 +3183,7 @@ rule that it must be smaller or equal to the *delta*. For example:
end Show_Fixed_Small_Delta;

In this example, the *delta* that we specifed for :ada:`Ordinary_Fixed_Point`
is 0.2, while the compiler-selected *small* is 2.0\ :sup:`-3`.
is 0.2, while the compiler-selected *small* is 0.125 (2.0\ :sup:`-3`).

.. admonition:: For further reading...

Expand Down Expand Up @@ -3374,10 +3374,10 @@ retrieve the actual integer representation, we can use
Machine representation of decimal types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Let's start with decimal fixed-ppint types. Consider the following types from
Let's start with decimal fixed-point types. Consider the following types from
the :ada:`Custom_Decimal_Types` package:

.. code:: ada compile_button project=Courses.Advanced_Ada.Data_Types.Numerics.Fixed_Point_Types.Machine_Implementation_Decimal_Types
.. code:: ada compile_button project=Courses.Advanced_Ada.Data_Types.Numerics.Fixed_Point_Types.Machine_Representation_Decimal_Types

package Custom_Decimal_Types is

Expand All @@ -3394,78 +3394,110 @@ the :ada:`Custom_Decimal_Types` package:
type Int_T2_D6 is
range -2 ** (T2_D6'Size - 1) ..
2 ** (T2_D6'Size - 1) - 1;
type Int_T2_D12 is
range -2 ** (T2_D12'Size - 1) ..
2 ** (T2_D12'Size - 1) - 1;

end Custom_Decimal_Types;

We can use an overlay to uncover the actual integer values stored on the
machine when assigning values to objects of decimal type. For example:
We can use an overlay in the body of the generic :ada:`Gen_Show_Info` procedure
to uncover the actual integer values stored on the machine for objects of a
decimal type. For example:

.. code:: ada no_button project=Courses.Advanced_Ada.Data_Types.Numerics.Fixed_Point_Types.Machine_Implementation_Decimal_Types
.. code:: ada no_button project=Courses.Advanced_Ada.Data_Types.Numerics.Fixed_Point_Types.Machine_Representation_Decimal_Types

generic
type T_Decimal is delta <> digits <>;
type T_Int_Decimal is range <>;
procedure Gen_Show_Info (V : T_Decimal;
V_Str : String);

with Ada.Text_IO; use Ada.Text_IO;

procedure Gen_Show_Info (V : T_Decimal;
V_Str : String)
is
V_Int_Overlay : T_Int_Decimal
Copy link

@swbaird swbaird Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps add an assertion that T_Decimal'Size = T_Int_Decimal'Size?
No warning will be generated for a size mismatch if we use an overlay instead of an Unchecked_Conversion instance.

Copy link
Collaborator Author

@gusthoff gusthoff Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's a very good addition, thanks!

A question, though: should this pragma be rather placed in the package specification, as T_Int_Decimal is always going to be used to create overlays?

Also, would you say that such a pragma should always be used for overlays? If so, I should be mentioning that in the section about overlays, as well as adding a pragma to other code examples in this course that use overlays.

Copy link

@swbaird swbaird Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like your idea of putting the assertion in the spec; the assertion documents a requirement that the client needs to be aware of.

For overlays in general, the sizes don't necessarily have to match , but you have to be careful to avoid a situation where you use an overlay to obtain a view of an object that is larger than the object really is (so you could be accessing whatever memory happens to follow the object).

For example, C might call Ada and on the Ada side it appears that we have a parameter of an enormous constrained array type and a second parameter specifying the actual length of the array. One might want to declare a subtype with the right bounds and then use an overlay to get a view of the array parameter that has the correct bounds. The two array subtypes would not be of the same size; that's the whole point.

Alignment is also an important consideration to be aware of. It is often a good idea to somehow ensure (perhaps via an assertion) that the address specified in an overlay satisfies the alignment requirements of the type in question.

Copy link

@swbaird swbaird Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you can mostly ignore what I said about adding an assertion to ensure correct alignment; when an object is declared with a specified address (as for an overlay), the compiler generates a run-time check that the address is properly aligned. But one still ought to take steps to ensure that this check won't fail.

Copy link

@swbaird swbaird Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bob reminds me that the compiler only emits the alignment check on machines that trap unaligned accesses (so not on x86). In the case where no check is performed, the user would have to decide whether they want to perform the check themselves (presumably via an assertion).

with Address => V'Address,
Import, Volatile;

pragma Assert
(T_Decimal'Size = T_Int_Decimal'Size);

V_Real : Float;
begin
V_Real := Float (V_Int_Overlay) *
T_Decimal'Small;

Put_Line (V_Str
& " (fixed-point) : "
& V'Image);
Put_Line (V_Str
& " (integer) : "
& V_Int_Overlay'Image);
Put_Line (V_Str
& " (floating-p.) : "
& V_Real'Image);
Put_Line ("----------");
end Gen_Show_Info;

with Gen_Show_Info;

package Custom_Decimal_Types.Show_Info_Procs is

procedure Show_Info is new
Gen_Show_Info (T_Decimal => T0_D4,
T_Int_Decimal => Int_T0_D4);
procedure Show_Info is new
Gen_Show_Info (T_Decimal => T2_D6,
T_Int_Decimal => Int_T2_D6);
procedure Show_Info is new
Gen_Show_Info (T_Decimal => T2_D12,
T_Int_Decimal => Int_T2_D12);

end Custom_Decimal_Types.Show_Info_Procs;

In this example, we use the overlays :ada:`V_Int_Overlay` in the generic
procedure :ada:`Gen_Show_Info`. This allows us to retrieve the integer
representation of the decimal input variable :ada:`V`. We instantiate this
generic procedure for the :ada:`T0_D4` and :ada:`T2_D6` types (see
:ada:`Show_Info` procedures).

We can then call :ada:`Show_Info` for a few values. By doing so, we see
the machine representation of those decimal values. For example:

.. code:: ada no_button project=Courses.Advanced_Ada.Data_Types.Numerics.Fixed_Point_Types.Machine_Representation_Decimal_Types
:class: ada-run

with Ada.Text_IO; use Ada.Text_IO;

with Custom_Decimal_Types;
use Custom_Decimal_Types;

procedure Show_Machine_Implementation is
V_T0_D4 : T0_D4;
V_Int_T0_D4 : Int_T0_D4
with Address => V_T0_D4'Address,
Import, Volatile;
with Custom_Decimal_Types.Show_Info_Procs;
use Custom_Decimal_Types.Show_Info_Procs;

V_T2_D6 : T2_D6;
V_Int_T2_D6 : Int_T2_D6
with Address => V_T2_D6'Address,
Import, Volatile;
procedure Show_Machine_Representation is
begin
V_T0_D4 := 1.0;
Put_Line ("1.0 (T0_D4) : "
& V_T0_D4'Image);
Put_Line ("1.0 (Int_T0_D4) : "
& V_Int_T0_D4'Image);

V_T2_D6 := 1.55;
V_T0_D4 := T0_D4 (V_T2_D6);
Put_Line ("1.55 (T0_D4) : "
& V_T0_D4'Image);
Put_Line ("1.55 (Int_T0_D4) : "
& V_Int_T0_D4'Image);

V_T0_D4 := 2.0;
Put_Line ("2.0 (T0_D4) : "
& V_T0_D4'Image);
Put_Line ("2.0 (Int_T0_D4) : "
& V_Int_T0_D4'Image);

Put_Line ("-----------------------------");

V_T2_D6 := 1.0;
Put_Line ("1.00 (T2_D6) : "
& V_T2_D6'Image);
Put_Line ("1.00 (Int_T2_D6) : "
& V_Int_T2_D6'Image);

V_T2_D6 := 1.55;
Put_Line ("1.55 (T2_D6) : "
& V_T2_D6'Image);
Put_Line ("1.55 (Int_T2_D6) : "
& V_Int_T2_D6'Image);

V_T2_D6 := 2.0;
Put_Line ("2.00 (T2_D6) : "
& V_T2_D6'Image);
Put_Line ("2.00 (Int_T2_D6) : "
& V_Int_T2_D6'Image);

Put_Line ("-----------------------------");
end Show_Machine_Implementation;

In this example, we use the overlays :ada:`V_Int_T0_D4` and :ada:`V_Int_T2_D6`
to retrieve the integer representation of the decimal variables :ada:`V_T0_D4`
and :ada:`V_T2_D6`. By doing this, we retrieve the machine representation of
the real values for the :ada:`T0_D4` and :ada:`T2_D6` types. The table shows
the values that we get by running the test application:
Put_Line ("=============================");
Put_Line ("T0_D4");
Put_Line ("=============================");

Show_Info (T0_D4'(1.0), "1.0 ");
Show_Info (T0_D4 (T2_D6'(1.55)),
"1.55 ");
Show_Info (T0_D4'(2.0), "2.0 ");

Put_Line ("=============================");
Put_Line ("T2_D6");
Put_Line ("=============================");

Show_Info (T2_D6'(1.0), "1.0 ");
Show_Info (T2_D6'(1.55), "1.55 ");
Show_Info (T2_D6'(2.0), "2.0 ");
end Show_Machine_Representation;

The table shows the values that we get by running the test application:

+-------------+-----------------------------+
| Real value | Integer representation |
Expand All @@ -3492,7 +3524,7 @@ which, as we've seen before, is equal to the *delta* for decimal fixed-point
types. (Later on, we see that this *detail* makes a difference for ordinary
fixed-point types.)

For example, if we multiple the integer representation of the real value by the
For example, if we multiply the integer representation of the real value by the
*small*, we get the real value:

+-------------+-------------------------------+
Expand Down
Loading