		       G N A T   E X A M P L E S
		       =========================


In order to compile the examples, make sure that the 'gnatmake' command is
in your path. 

Invocation
----------

In order to build the two executables provided in this example, you need to
use the "dimensioned_units.gpr" project file. On the command-line, do the following:

  $ gnatmake -Pdimensioned_units

Alternatively, in GPS, click on "Build", and then "Make", and then you can 
select which of the two example main programs will be built.

Features illustrated
---------------

* This example illustrates a numeric abstract data type in which both magnitude 
  and dimensionality are maintained across operations and assignments.  

  The approach is based on a design first illustrated in the original Red 
  language proposal and elaborated upon by both Paul Hilfinger [1] and Jean 
  Ichbiah [2].  The idea is to use discriminants to specify dimensionality and 
  to rely on language rules and overloaded operators to ensure that they remain 
  consistent.  

  In particular, we define the type to have a floating-point magnitude and 
  three integer discriminants: one each for the mass, distance, and time 
  dimensionality.  A "length" unit would have a distance discriminant value of 
  one, for example, with the time and mass discriminants set to zero.  An 
  "area" unit, on the other hand, would have a distance discriminant value of 
  two since it is a distance squared.  A dimensionless scalar value would have 
  all three discriminants set to zero.  

  Overloaded operator functions set the necessary discriminant values based on 
  the nature of the operation performed and perform any dimensionality 
  consistency checking required.  

  We rely on the fact that discriminants cannot be changed by assignment 
  statements (unless they have a default and take that default, which we do not 
  do).  Constraint_Error is raised if the discriminants of the left-hand side 
  differ from those on the right-hand side of the assignment statement.  

  The type is declared within a generic package, with the floating point type 
  for the magnitude as the sole generic formal parameter.  In addition, a child 
  package defines constants and subtypes for additional units, such as ergs or 
  speed, in terms of the metric system.  Other measurement systems could be 
  supported as well.  

  The enforcement of consistency checking incurs some run-time overhead that 
  might or might not be acceptable in a production program.  If not, a 
  different package can be instantiated to replace the ones providing the 
  dimensioned units and metric system constants.  This alternate generic 
  package provides the same names and operations as the one that enforces 
  dimensionality, along with the measurement system used.  As a result, the 
  client code need not be changed except for minor changes to the context 
  clauses.  Developers could use the dimension enforcing packages during 
  development and then replace those packages with this alternate package at 
  some point prior to the release, confident that their calculations are 
  dimensionally consistent.  
  
* Two main programs are provided: "demo_checked.adb" and "demo_unchecked.adb".  
  The first one uses the dimensioned units packages and the second one uses the 
  alternate package that incurs no checking overhead.  As you will see by 
  comparing them, the source code for the calculations are identical and they 
  will provide the same results when run.  The difference in checking overhead 
  can be seen by viewing the intermediate representation of the code, presented 
  by compiling with the "-gnatG" switch included on the command line.  
  
* The topic of dimensionality support in Ada has a long history, as the 
  references below will show.  For a more recent discussion, in the context of 
  Ada 2005, see "http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00324.TXT".
  Also of considerable interest is discussion available here:
  "http://www.christ-usch-grein.homepage.t-online.de/Ada/Universe.html" and
  "http://www.christ-usch-grein.homepage.t-online.de/Ada/Dimension.html".

* [1] P. Hilfinger, Abstraction Mechanisms and Language Design: MIT Press,
  1983.

  [2] J. Ichbiah, et al., Rationale for the Design of the Ada Programming
  Language, 1986.

