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-2023, 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 --  In principle every node that is a component of a floating-point expression
  87 --  may have a dimension vector. However, the dimensionality checking is for
  88 --  the most part a bottom-up tree traversal, and the dimensions of operands
  89 --  become irrelevant once the dimensions of an operation have been computed.
  90 --  To minimize space use, the dimensions of operands are removed after the
  91 --  computation of the dimensions of the parent operation. This may complicate
  92 --  the analysis of nodes that have been constant-folded or otherwise rewritten
  93 --  when removing side effects. In such cases, the (sub)type of the expression
  94 --  is used to determine the applicable dimensions.
  95
  96 with Types; use Types;
  97
  98 package Sem_Dim is
  99
 100    procedure Analyze_Aspect_Dimension
 101      (N    : Node_Id;
 102       Id   : Entity_Id;
 103       Aggr : Node_Id);
 104    --  Analyze the contents of aspect Dimension. Associate the provided values
 105    --  and quantifiers with the related context N. Id is the corresponding
 106    --  Aspect_Id (Aspect_Dimension) Aggr is the corresponding expression for
 107    --  the aspect Dimension declared by the declaration of N.
 108
 109    procedure Analyze_Aspect_Dimension_System
 110      (N    : Node_Id;
 111       Id   : Entity_Id;
 112       Aggr : Node_Id);
 113    --  Analyze the contents of aspect Dimension_System. Extract the numerical
 114    --  type, unit name and corresponding symbol from each indivitual dimension.
 115    --  Id is the corresponding Aspect_Id (Aspect_Dimension_System). Aggr is
 116    --  the corresponding expression for the aspect Dimension_System from the
 117    --  declaration of N.
 118
 119    procedure Analyze_Dimension (N : Node_Id);
 120    --  N may denote any of the following contexts:
 121    --    * aggregate
 122    --    * assignment statement
 123    --    * attribute reference
 124    --    * binary operator
 125    --    * call
 126    --    * compontent declaration
 127    --    * extended return statement
 128    --    * expanded name
 129    --    * explicit dereference
 130    --    * identifier
 131    --    * indexed component
 132    --    * number declaration
 133    --    * object declaration
 134    --    * object renaming declaration
 135    --    * procedure call statement
 136    --    * qualified expression
 137    --    * selected component
 138    --    * simple return statement
 139    --    * slice
 140    --    * subtype declaration
 141    --    * type conversion
 142    --    * unary operator
 143    --    * unchecked type conversion
 144    --  Depending on the context, ensure that all expressions and entities
 145    --  involved do not violate the rules of a system.
 146
 147    procedure Analyze_Dimension_Array_Aggregate
 148      (N        : Node_Id;
 149       Comp_Typ : Entity_Id);
 150    --  Check, for each component of the array aggregate denoted by N, the
 151    --  dimensions of the component expression match the dimensions of the
 152    --  component type Comp_Typ.
 153
 154    procedure Analyze_Dimension_Call (N : Node_Id; Nam : Entity_Id);
 155    --  This routine is split in two steps. Note the second step applies only to
 156    --  function calls.
 157    --  Step 1. Dimension checking:
 158    --    * General case: check the dimensions of each actual parameter match
 159    --      the dimensions of the corresponding formal parameter.
 160    --    * Elementary function case: check each actual is dimensionless except
 161    --      for Sqrt call.
 162    --  Step 2. Dimension propagation (only for functions):
 163    --    * General case: propagate the dimensions from the returned type to the
 164    --      function call.
 165    --    * Sqrt case: the resulting dimensions equal to half the dimensions of
 166    --      the actual
 167
 168    procedure Analyze_Dimension_Extension_Or_Record_Aggregate (N : Node_Id);
 169    --  Check, for each component of the extension or record aggregate denoted
 170    --  by N, the dimensions of the component expression match the dimensions of
 171    --  the component type.
 172
 173    procedure Analyze_Dimension_Formals (N : Node_Id; Formals : List_Id);
 174    --  For sub spec N, issue a warning for each dimensioned formal with a
 175    --  literal default value in the list of formals Formals.
 176
 177    procedure Check_Expression_Dimensions
 178      (Expr : Node_Id;
 179       Typ  : Entity_Id);
 180    --  Compute dimensions of a floating-point expression and compare them with
 181    --  the dimensions of a the given type. Used to verify dimensions of the
 182    --  components of a multidimensional array type, for which components are
 183    --  typically themselves arrays. The resolution of such arrays delays the
 184    --  resolution of the ultimate components to a separate phase, which forces
 185    --  this separate dimension verification.
 186
 187    procedure Copy_Dimensions (From : Node_Id; To : Node_Id);
 188    --  Copy dimension vector of node From to node To. Note that To must be a
 189    --  node that is allowed to contain a dimension (see OK_For_Dimension in
 190    --  body of Sem_Dim).
 191
 192    procedure Copy_Dimensions_Of_Components (Rec : Entity_Id);
 193    --  Propagate the dimensions of the components of a record type T to the
 194    --  components of a record type derived from T. The derivation creates
 195    --  a full copy of the type declaration of the parent, and the dimension
 196    --  information of individual components must be transferred explicitly.
 197
 198    function Dimensions_Match (T1 : Entity_Id; T2 : Entity_Id) return Boolean;
 199    --  If the common base type has a dimension system, verify that two
 200    --  subtypes have the same dimensions. Used for conformance checking.
 201
 202    procedure Eval_Op_Expon_For_Dimensioned_Type
 203      (N    : Node_Id;
 204       Btyp : Entity_Id);
 205    --  Evaluate the Expon operator for dimensioned type with rational exponent.
 206    --  Indeed the regular Eval_Op_Expon routine (see package Sem_Eval) is
 207    --  restricted to Integer exponent. This routine deals only with rational
 208    --  exponent which is not an integer if Btyp is a dimensioned type.
 209
 210    procedure Expand_Put_Call_With_Symbol (N : Node_Id);
 211    --  Determine whether N denotes a subprogram call to one of the routines
 212    --  defined in System.Dim.Float_IO or System.Dim.Integer_IO and add an
 213    --  extra actual to the call to represent the symbolic representation of
 214    --  a dimension.
 215
 216    function Has_Dimension_System (Typ : Entity_Id) return Boolean;
 217    --  Return True if type Typ has aspect Dimension_System applied to it
 218
 219    function Is_Dim_IO_Package_Instantiation (N : Node_Id) return Boolean;
 220    --  Return True if N is a package instantiation of System.Dim.Integer_IO or
 221    --  of System.Dim.Float_IO.
 222
 223    function New_Copy_Tree_And_Copy_Dimensions
 224      (Source    : Node_Id;
 225       Map       : Elist_Id   := No_Elist;
 226       New_Sloc  : Source_Ptr := No_Location;
 227       New_Scope : Entity_Id  := Empty) return Node_Id;
 228    --  Same as New_Copy_Tree (defined in Sem_Util), except that this routine
 229    --  also copies the dimensions of Source to the returned node.
 230
 231    procedure Remove_Dimension_In_Statement (Stmt : Node_Id);
 232    --  Remove the dimensions associated with Stmt
 233
 234 end Sem_Dim;