gcc/ada/sem_dim.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                              S E M _ D I M                               --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 2011-2012, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  17 -- for  more details.  You should have  received  a copy of the GNU General --
  18 -- Public License  distributed with GNAT; see file COPYING3.  If not, go to --
  19 -- http://www.gnu.org/licenses for a complete copy of the license.          --
  20 --                                                                          --
  21 -- GNAT was originally developed  by the GNAT team at  New York University. --
  22 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  23 --                                                                          --
  24 ------------------------------------------------------------------------------
  25
  26 --  This package provides support for numerical systems with dimensions. A
  27 --  "dimension" is a compile-time property of a numerical type which represents
  28 --  a relation between various quantifiers such as length, velocity, etc.
  29
  30 --  Package System.Dim.Mks offers a ready-to-use system of SI base units. In
  31 --  addition, the implementation of this feature offers the ability to define
  32 --  an arbitrary system of units through the use of Ada 2012 aspects.
  33
  34 --  Dimensionality checking is part of type analysis performed by the compiler.
  35 --  It ensures that manipulation of quantified numeric values is sensible with
  36 --  respect to the system of units.
  37
  38 -----------------------------
  39 -- Aspect_Dimension_System --
  40 -----------------------------
  41
  42 --  In order to enable the user to create their own dimension system, a new
  43 --  aspect: Aspect_Dimension_System has been created.
  44
  45 --  Note that this aspect applies for type declaration of type derived from any
  46 --  numeric type.
  47
  48 --  It defines the names of each dimension
  49
  50 ----------------------
  51 -- Aspect_Dimension --
  52 ----------------------
  53
  54 --  This new aspect applies for subtype and object declarations in order to
  55 --  define new dimensions.
  56
  57 --  Using this aspect, the user is able to create new subtype/object with any
  58 --  dimension needed.
  59
  60 --  Note that the base type of the subtype/object must be the type that defines
  61 --  the corresponding dimension system.
  62
  63 --  The expression of this aspect is an aggregate of rational values for each
  64 --  dimension in the corresponding dimension system.
  65
  66 -------------------------------------------
  67 -- Dimensionality checking & propagation --
  68 -------------------------------------------
  69
  70 --  For each node (when needed), a dimension analysis (Analyze_Dimension) is
  71 --  performed as part of the Resolution routine or the Analysis routine if no
  72 --  Resolution.
  73
  74 --  The dimension analysis is divided into two phases:
  75
  76 --  Phase 1: dimension checking
  77
  78 --  Phase 2: propagation of dimensions
  79
  80 --  Depending on the node kind, either none, one phase or two phases are
  81 --  executed.
  82
  83 --  Phase 2 is called only when the node allows a dimension (see body of
  84 --  Sem_Dim to get the list of nodes that permit dimensions).
  85
  86 with Types; use Types;
  87
  88 package Sem_Dim is
  89
  90    procedure Analyze_Aspect_Dimension
  91      (N    : Node_Id;
  92       Id   : Entity_Id;
  93       Aggr : Node_Id);
  94    --  Analyze the contents of aspect Dimension. Associate the provided values
  95    --  and quantifiers with the related context N. Id is the corresponding
  96    --  Aspect_Id (Aspect_Dimension) Aggr is the corresponding expression for
  97    --  the aspect Dimension declared by the declaration of N.
  98
  99    procedure Analyze_Aspect_Dimension_System
 100      (N    : Node_Id;
 101       Id   : Entity_Id;
 102       Aggr : Node_Id);
 103    --  Analyze the contents of aspect Dimension_System. Extract the numerical
 104    --  type, unit name and corresponding symbol from each indivitual dimension.
 105    --  Id is the corresponding Aspect_Id (Aspect_Dimension_System)
 106    --  Aggr is the corresponding expression for the aspect Dimension_System
 107    --  declared by the declaration of N.
 108
 109    procedure Analyze_Dimension (N : Node_Id);
 110    --  N may denote any of the following contexts:
 111    --    * aggregate
 112    --    * assignment statement
 113    --    * attribute reference
 114    --    * binary operator
 115    --    * call
 116    --    * compontent declaration
 117    --    * extended return statement
 118    --    * expanded name
 119    --    * identifier
 120    --    * indexed component
 121    --    * object declaration
 122    --    * object renaming declaration
 123    --    * procedure call statement
 124    --    * qualified expression
 125    --    * selected component
 126    --    * simple return statement
 127    --    * slice
 128    --    * subtype declaration
 129    --    * type conversion
 130    --    * unary operator
 131    --    * unchecked type conversion
 132    --  Depending on the context, ensure that all expressions and entities
 133    --  involved do not violate the rules of a system.
 134
 135    procedure Analyze_Dimension_Array_Aggregate
 136      (N        : Node_Id;
 137       Comp_Typ : Entity_Id);
 138    --  Check, for each component of the array aggregate denoted by N, the
 139    --  dimensions of the component expression match the dimensions of the
 140    --  component type Comp_Typ.
 141
 142    procedure Analyze_Dimension_Call (N : Node_Id; Nam : Entity_Id);
 143    --  This routine is split in two steps. Note the second step applies only to
 144    --  function calls.
 145    --  Step 1. Dimension checking:
 146    --    * General case: check the dimensions of each actual parameter match
 147    --      the dimensions of the corresponding formal parameter.
 148    --    * Elementary function case: check each actual is dimensionless except
 149    --      for Sqrt call.
 150    --  Step 2. Dimension propagation (only for functions):
 151    --    * General case: propagate the dimensions from the returned type to the
 152    --      function call.
 153    --    * Sqrt case: the resulting dimensions equal to half the dimensions of
 154    --      the actual
 155
 156    procedure Analyze_Dimension_Extension_Or_Record_Aggregate (N : Node_Id);
 157    --  Check, for each component of the extension or record aggregate denoted
 158    --  by N, the dimensions of the component expression match the dimensions of
 159    --  the component type.
 160
 161    procedure Analyze_Dimension_Formals (N : Node_Id; Formals : List_Id);
 162    --  For sub spec N, issue a warning for each dimensioned formal with a
 163    --  literal default value in the list of formals Formals.
 164
 165    procedure Copy_Dimensions (From, To : Node_Id);
 166    --  Copy dimension vector of node From to node To. Note that To must be a
 167    --  node that is allowed to contain a dimension (see OK_For_Dimension in
 168    --  body of Sem_Dim).
 169
 170    procedure Eval_Op_Expon_For_Dimensioned_Type
 171      (N    : Node_Id;
 172       Btyp : Entity_Id);
 173    --  Evaluate the Expon operator for dimensioned type with rational exponent.
 174    --  Indeed the regular Eval_Op_Expon routine (see package Sem_Eval) is
 175    --  restricted to Integer exponent. This routine deals only with rational
 176    --  exponent which is not an integer if Btyp is a dimensioned type.
 177
 178    procedure Expand_Put_Call_With_Symbol (N : Node_Id);
 179    --  Determine whether N denotes a subprogram call to one of the routines
 180    --  defined in System.Dim.Float_IO or System.Dim.Integer_IO and add an
 181    --  extra actual to the call to represent the symbolic representation of
 182    --  a dimension.
 183
 184    function Has_Dimension_System (Typ : Entity_Id) return Boolean;
 185    --  Return True if type Typ has aspect Dimension_System applied to it
 186
 187    function Is_Dim_IO_Package_Instantiation (N : Node_Id) return Boolean;
 188    --  Return True if N is a package instantiation of System.Dim.Integer_IO or
 189    --  of System.Dim.Float_IO.
 190
 191    procedure Remove_Dimension_In_Statement (Stmt : Node_Id);
 192    --  Remove the dimensions associated with Stmt
 193
 194 end Sem_Dim;