gcc/ada/sem_eval.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                             S E M _ E V A L                              --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2008, 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 contains various subprograms involved in compile time
  27 --  evaluation of expressions and checks for staticness of expressions and
  28 --  types. It also contains the circuitry for checking for violations of pure
  29 --  and preelaborated conditions (this naturally goes here, since these rules
  30 --  involve consideration of staticness).
  31
  32 --  Note: the static evaluation for attributes is found in Sem_Attr even though
  33 --  logically it belongs here. We have done this so that it is easier to add
  34 --  new attributes to GNAT.
  35
  36 with Types;  use Types;
  37 with Uintp;  use Uintp;
  38 with Urealp; use Urealp;
  39
  40 package Sem_Eval is
  41
  42    ------------------------------------
  43    -- Handling of Static Expressions --
  44    ------------------------------------
  45
  46    --  This package contains a set of routine that process individual
  47    --  subexpression nodes with the objective of folding (precomputing) the
  48    --  value of static expressions that are known at compile time and properly
  49    --  computing the setting of two flags that appear in every subexpression
  50    --  node:
  51
  52    --    Is_Static_Expression
  53
  54    --      This flag is set on any expression that is static according to the
  55    --      rules in (RM 4.9(3-32)).
  56
  57    --    Raises_Constraint_Error
  58
  59    --      This flag indicates that it is known at compile time that the
  60    --      evaluation of an expression raises constraint error. If the
  61    --      expression is static, and this flag is off, then it is also known at
  62    --      compile time that the expression does not raise constraint error
  63    --      (i.e. the flag is accurate for static expressions, and conservative
  64    --      for non-static expressions.
  65
  66    --  If a static expression does not raise constraint error, then the
  67    --  Raises_Constraint_Error flag is off, and the expression must be computed
  68    --  at compile time, which means that it has the form of either a literal,
  69    --  or a constant that is itself (recursively) either a literal or a
  70    --  constant.
  71
  72    --  The above rules must be followed exactly in order for legality checks to
  73    --  be accurate. For subexpressions that are not static according to the RM
  74    --  definition, they are sometimes folded anyway, but of course in this case
  75    --  Is_Static_Expression is not set.
  76
  77    -------------------------------
  78    -- Compile-Time Known Values --
  79    -------------------------------
  80
  81    --  For most legality checking purposes the flag Is_Static_Expression
  82    --  defined in Sinfo should be used. This package also provides a routine
  83    --  called Is_OK_Static_Expression which in addition of checking that an
  84    --  expression is static in the RM 4.9 sense, it checks that the expression
  85    --  does not raise constraint error. In fact for certain legality checks not
  86    --  only do we need to ascertain that the expression is static, but we must
  87    --  also ensure that it does not raise constraint error.
  88    --
  89    --  Neither of Is_Static_Expression and Is_OK_Static_Expression should be
  90    --  used for compile time evaluation purposes. In fact certain expression
  91    --  whose value is known at compile time are not static in the RM 4.9 sense.
  92    --  A typical example is:
  93    --
  94    --     C : constant Integer := Record_Type'Size;
  95    --
  96    --  The expression 'C' is not static in the technical RM sense, but for many
  97    --  simple record types, the size is in fact known at compile time. When we
  98    --  are trying to perform compile time constant folding (for instance for
  99    --  expressions like C + 1, Is_Static_Expression or Is_OK_Static_Expression
 100    --  are not the right functions to test if folding is possible. Instead, we
 101    --  use Compile_Time_Known_Value. All static expressions that do not raise
 102    --  constraint error (i.e. those for which Is_OK_Static_Expression is true)
 103    --  are known at compile time, but as shown by the above example, there are
 104    --  cases of non-static expressions which are known at compile time.
 105
 106    -----------------
 107    -- Subprograms --
 108    -----------------
 109
 110    procedure Check_Non_Static_Context (N : Node_Id);
 111    --  Deals with the special check required for a static expression that
 112    --  appears in a non-static context, i.e. is not part of a larger static
 113    --  expression (see RM 4.9(35)), i.e. the value of the expression must be
 114    --  within the base range of the base type of its expected type. A check is
 115    --  also made for expressions that are inside the base range, but outside
 116    --  the range of the expected subtype (this is a warning message rather than
 117    --  an illegality).
 118    --
 119    --  Note: most cases of non-static context checks are handled within
 120    --  Sem_Eval itself, including all cases of expressions at the outer level
 121    --  (i.e. those that are not a subexpression). Currently the only outside
 122    --  customer for this procedure is Sem_Attr (because Eval_Attribute is
 123    --  there). There is also one special case arising from ranges (see body of
 124    --  Resolve_Range).
 125
 126    procedure Check_String_Literal_Length (N : Node_Id; Ttype : Entity_Id);
 127    --  N is either a string literal, or a constraint error node. In the latter
 128    --  case, the situation is already dealt with, and the call has no effect.
 129    --  In the former case, if the target type, Ttyp is constrained, then a
 130    --  check is made to see if the string literal is of appropriate length.
 131
 132    type Compare_Result is (LT, LE, EQ, GT, GE, NE, Unknown);
 133    subtype Compare_GE is Compare_Result range EQ .. GE;
 134    subtype Compare_LE is Compare_Result range LT .. EQ;
 135    function Compile_Time_Compare
 136      (L, R : Node_Id;
 137       Rec  : Boolean := False) return Compare_Result;
 138    --  Given two expression nodes, finds out whether it can be determined at
 139    --  compile time how the runtime values will compare. An Unknown result
 140    --  means that the result of a comparison cannot be determined at compile
 141    --  time, otherwise the returned result indicates the known result of the
 142    --  comparison, given as tightly as possible (i.e. EQ or LT is preferred
 143    --  returned value to LE). Rec is a parameter that is set True for a
 144    --  recursive call from within Compile_Time_Compare to avoid some infinite
 145    --  recursion cases. It should never be set by a client.
 146
 147    procedure Flag_Non_Static_Expr (Msg : String; Expr : Node_Id);
 148    --  This procedure is called after it has been determined that Expr is not
 149    --  static when it is required to be. Msg is the text of a message that
 150    --  explains the error. This procedure checks if an error is already posted
 151    --  on Expr, if so, it does nothing unless All_Errors_Mode is set in which
 152    --  case this flag is ignored. Otherwise the given message is posted using
 153    --  Error_Msg_F, and then Why_Not_Static is called on Expr to generate
 154    --  additional messages. The string given as Msg should end with ! to make
 155    --  it an unconditional message, to ensure that if it is posted, the entire
 156    --  set of messages is all posted.
 157
 158    function Is_OK_Static_Expression (N : Node_Id) return Boolean;
 159    --  An OK static expression is one that is static in the RM definition sense
 160    --  and which does not raise constraint error. For most legality checking
 161    --  purposes you should use Is_Static_Expression. For those legality checks
 162    --  where the expression N should not raise constraint error use this
 163    --  routine. This routine is *not* to be used in contexts where the test is
 164    --  for compile time evaluation purposes. Use Compile_Time_Known_Value
 165    --  instead (see section on "Compile-Time Known Values" above).
 166
 167    function Is_Static_Range (N : Node_Id) return Boolean;
 168    --  Determine if range is static, as defined in RM 4.9(26). The only allowed
 169    --  argument is an N_Range node (but note that the semantic analysis of
 170    --  equivalent range attribute references already turned them into the
 171    --  equivalent range).
 172
 173    function Is_OK_Static_Range (N : Node_Id) return Boolean;
 174    --  Like Is_Static_Range, but also makes sure that the bounds of the range
 175    --  are compile-time evaluable (i.e. do not raise constraint error). A
 176    --  result of true means that the bounds are compile time evaluable. A
 177    --  result of false means they are not (either because the range is not
 178    --  static, or because one or the other bound raises CE).
 179
 180    function Is_Static_Subtype (Typ : Entity_Id) return Boolean;
 181    --  Determines whether a subtype fits the definition of an Ada static
 182    --  subtype as given in (RM 4.9(26)).
 183
 184    function Is_OK_Static_Subtype (Typ : Entity_Id) return Boolean;
 185    --  Like Is_Static_Subtype but also makes sure that the bounds of the
 186    --  subtype are compile-time evaluable (i.e. do not raise constraint error).
 187    --  A result of true means that the bounds are compile time evaluable. A
 188    --  result of false means they are not (either because the range is not
 189    --  static, or because one or the other bound raises CE).
 190
 191    function Subtypes_Statically_Compatible
 192      (T1 : Entity_Id;
 193       T2 : Entity_Id) return Boolean;
 194    --  Returns true if the subtypes are unconstrained or the constraint on
 195    --  on T1 is statically compatible with T2 (as defined by 4.9.1(4)).
 196    --  Otherwise returns false.
 197
 198    function Subtypes_Statically_Match (T1, T2 : Entity_Id) return Boolean;
 199    --  Determine whether two types T1, T2, which have the same base type,
 200    --  are statically matching subtypes (RM 4.9.1(1-2)).
 201
 202    function Compile_Time_Known_Value (Op : Node_Id) return Boolean;
 203    --  Returns true if Op is an expression not raising constraint error whose
 204    --  value is known at compile time. This is true if Op is a static
 205    --  expression, but can also be true for expressions which are technically
 206    --  non-static but which are in fact known at compile time, such as the
 207    --  static lower bound of a non-static range or the value of a constant
 208    --  object whose initial value is static. Note that this routine is defended
 209    --  against unanalyzed expressions. Such expressions will not cause a
 210    --  blowup, they may cause pessimistic (i.e. False) results to be returned.
 211
 212    function Compile_Time_Known_Value_Or_Aggr (Op : Node_Id) return Boolean;
 213    --  Similar to Compile_Time_Known_Value, but also returns True if the value
 214    --  is a compile time known aggregate, i.e. an aggregate all of whose
 215    --  constituent expressions are either compile time known values or compile
 216    --  time known aggregates.
 217
 218    function Compile_Time_Known_Bounds (T : Entity_Id) return Boolean;
 219    --  If T is an array whose index bounds are all known at compile time, then
 220    --  True is returned, if T is not an array, or one or more of its index
 221    --  bounds is not known at compile time, then False is returned.
 222
 223    function Expr_Value (N : Node_Id) return Uint;
 224    --  Returns the folded value of the expression N. This function is called in
 225    --  instances where it has already been determined that the expression is
 226    --  static or its value is compile time known (Compile_Time_Known_Value (N)
 227    --  returns True). This version is used for integer values, and enumeration
 228    --  or character literals. In the latter two cases, the value returned is
 229    --  the Pos value in the relevant enumeration type. It can also be used for
 230    --  fixed-point values, in which case it returns the corresponding integer
 231    --  value. It cannot be used for floating-point values.
 232
 233    function Expr_Value_E (N : Node_Id) return Entity_Id;
 234    --  Returns the folded value of the expression. This function is called in
 235    --  instances where it has already been determined that the expression is
 236    --  static or its value known at compile time. This version is used for
 237    --  enumeration types and returns the corresponding enumeration literal.
 238
 239    function Expr_Value_R (N : Node_Id) return Ureal;
 240    --  Returns the folded value of the expression. This function is called in
 241    --  instances where it has already been determined that the expression is
 242    --  static or its value known at compile time. This version is used for real
 243    --  values (including both the floating-point and fixed-point cases). In the
 244    --  case of a fixed-point type, the real value is returned (cf above version
 245    --  returning Uint).
 246
 247    function Expr_Value_S (N : Node_Id) return Node_Id;
 248    --  Returns the folded value of the expression. This function is called
 249    --  in instances where it has already been determined that the expression
 250    --  is static or its value is known at compile time. This version is used
 251    --  for string types and returns the corresponding N_String_Literal node.
 252
 253    function Expr_Rep_Value (N : Node_Id) return Uint;
 254    --  This is identical to Expr_Value, except in the case of enumeration
 255    --  literals of types for which an enumeration representation clause has
 256    --  been given, in which case it returns the representation value rather
 257    --  than the pos value. This is the value that is needed for generating code
 258    --  sequences, while the Expr_Value value is appropriate for compile time
 259    --  constraint errors or getting the logical value. Note that this function
 260    --  does NOT concern itself with biased values, if the caller needs a
 261    --  properly biased value, the subtraction of the bias must be handled
 262    --  explicitly.
 263
 264    procedure Eval_Actual                 (N : Node_Id);
 265    procedure Eval_Allocator              (N : Node_Id);
 266    procedure Eval_Arithmetic_Op          (N : Node_Id);
 267    procedure Eval_Call                   (N : Node_Id);
 268    procedure Eval_Character_Literal      (N : Node_Id);
 269    procedure Eval_Concatenation          (N : Node_Id);
 270    procedure Eval_Conditional_Expression (N : Node_Id);
 271    procedure Eval_Entity_Name            (N : Node_Id);
 272    procedure Eval_Indexed_Component      (N : Node_Id);
 273    procedure Eval_Integer_Literal        (N : Node_Id);
 274    procedure Eval_Logical_Op             (N : Node_Id);
 275    procedure Eval_Membership_Op          (N : Node_Id);
 276    procedure Eval_Named_Integer          (N : Node_Id);
 277    procedure Eval_Named_Real             (N : Node_Id);
 278    procedure Eval_Op_Expon               (N : Node_Id);
 279    procedure Eval_Op_Not                 (N : Node_Id);
 280    procedure Eval_Real_Literal           (N : Node_Id);
 281    procedure Eval_Relational_Op          (N : Node_Id);
 282    procedure Eval_Shift                  (N : Node_Id);
 283    procedure Eval_Short_Circuit          (N : Node_Id);
 284    procedure Eval_Slice                  (N : Node_Id);
 285    procedure Eval_String_Literal         (N : Node_Id);
 286    procedure Eval_Qualified_Expression   (N : Node_Id);
 287    procedure Eval_Type_Conversion        (N : Node_Id);
 288    procedure Eval_Unary_Op               (N : Node_Id);
 289    procedure Eval_Unchecked_Conversion   (N : Node_Id);
 290
 291    procedure Fold_Str (N : Node_Id; Val : String_Id; Static : Boolean);
 292    --  Rewrite N with a new N_String_Literal node as the result of the compile
 293    --  time evaluation of the node N. Val is the resulting string value from
 294    --  the folding operation. The Is_Static_Expression flag is set in the
 295    --  result node. The result is fully analyzed and resolved. Static indicates
 296    --  whether the result should be considered static or not (True = consider
 297    --  static). The point here is that normally all string literals are static,
 298    --  but if this was the result of some sequence of evaluation where values
 299    --  were known at compile time but not static, then the result is not
 300    --  static.
 301
 302    procedure Fold_Uint (N : Node_Id; Val : Uint; Static : Boolean);
 303    --  Rewrite N with a (N_Integer_Literal, N_Identifier, N_Character_Literal)
 304    --  node as the result of the compile time evaluation of the node N. Val is
 305    --  the result in the integer case and is the position of the literal in the
 306    --  literals list for the enumeration case. Is_Static_Expression is set True
 307    --  in the result node. The result is fully analyzed/resolved. Static
 308    --  indicates whether the result should be considered static or not (True =
 309    --  consider static). The point here is that normally all string literals
 310    --  are static, but if this was the result of some sequence of evaluation
 311    --  where values were known at compile time but not static, then the result
 312    --  is not static.
 313
 314    procedure Fold_Ureal (N : Node_Id; Val : Ureal; Static : Boolean);
 315    --  Rewrite N with a new N_Real_Literal node as the result of the compile
 316    --  time evaluation of the node N. Val is the resulting real value from the
 317    --  folding operation. The Is_Static_Expression flag is set in the result
 318    --  node. The result is fully analyzed and result. Static indicates whether
 319    --  the result should be considered static or not (True = consider static).
 320    --  The point here is that normally all string literals are static, but if
 321    --  this was the result of some sequence of evaluation where values were
 322    --  known at compile time but not static, then the result is not static.
 323
 324    function Is_In_Range
 325      (N         : Node_Id;
 326       Typ       : Entity_Id;
 327       Fixed_Int : Boolean := False;
 328       Int_Real  : Boolean := False) return Boolean;
 329    --  Returns True if it can be guaranteed at compile time that expression is
 330    --  known to be in range of the subtype Typ. If the values of N or of either
 331    --  bounds of Type are unknown at compile time, False will always be
 332    --  returned. A result of False does not mean that the expression is out of
 333    --  range, merely that it cannot be determined at compile time that it is in
 334    --  range. If Typ is a floating point type or Int_Real is set, any integer
 335    --  value is treated as though it was a real value (i.e. the underlying real
 336    --  value is used). In this case we use the corresponding real value, both
 337    --  for the bounds of Typ, and for the value of the expression N. If Typ is
 338    --  a fixed type or a discrete type and Int_Real is False but flag Fixed_Int
 339    --  is True then any fixed-point value is treated as though it was discrete
 340    --  value (i.e. the underlying integer value is used). In this case we use
 341    --  the corresponding integer value, both for the bounds of Typ, and for the
 342    --  value of the expression N. If Typ is a discrete type and Fixed_Int as
 343    --  well as Int_Real are false, integer values are used throughout.
 344
 345    function Is_Out_Of_Range
 346      (N         : Node_Id;
 347       Typ       : Entity_Id;
 348       Fixed_Int : Boolean := False;
 349       Int_Real  : Boolean := False) return Boolean;
 350    --  Returns True if it can be guaranteed at compile time that expression is
 351    --  known to be out of range of the subtype Typ. True is returned if Typ is
 352    --  a scalar type, at least one of whose bounds is known at compile time,
 353    --  and N is a compile time known expression which can be determined to be
 354    --  outside a compile_time known bound of Typ. A result of False does not
 355    --  mean that the expression is in range, but rather merely that it cannot
 356    --  be determined at compile time that it is out of range. Flags Int_Real
 357    --  and Fixed_Int are used as in routine Is_In_Range above.
 358
 359    function In_Subrange_Of
 360      (T1        : Entity_Id;
 361       T2        : Entity_Id;
 362       Fixed_Int : Boolean := False) return Boolean;
 363    --  Returns True if it can be guaranteed at compile time that the range of
 364    --  values for scalar type T1 are always in the range of scalar type T2. A
 365    --  result of False does not mean that T1 is not in T2's subrange, only that
 366    --  it cannot be determined at compile time. Flag Fixed_Int is used as in
 367    --  routine Is_In_Range above.
 368
 369    function Is_Null_Range (Lo : Node_Id; Hi : Node_Id) return Boolean;
 370    --  Returns True if it can guarantee that Lo .. Hi is a null range. If it
 371    --  cannot (because the value of Lo or Hi is not known at compile time) then
 372    --  it returns False.
 373
 374    function Not_Null_Range (Lo : Node_Id; Hi : Node_Id) return Boolean;
 375    --  Returns True if it can guarantee that Lo .. Hi is not a null range. If
 376    --  it cannot (because the value of Lo or Hi is not known at compile time)
 377    --  then it returns False.
 378
 379    procedure Why_Not_Static (Expr : Node_Id);
 380    --  This procedure may be called after generating an error message that
 381    --  complains that something is non-static. If it finds good reasons, it
 382    --  generates one or more error messages pointing the appropriate offending
 383    --  component of the expression. If no good reasons can be figured out, then
 384    --  no messages are generated. The expectation here is that the caller has
 385    --  already issued a message complaining that the expression is non-static.
 386    --  Note that this message should be placed using Error_Msg_F or
 387    --  Error_Msg_FE, so that it will sort before any messages placed by this
 388    --  call. Note that it is fine to call Why_Not_Static with something that is
 389    --  not an expression, and usually this has no effect, but in some cases
 390    --  (N_Parameter_Association or N_Range), it makes sense for the internal
 391    --  recursive calls.
 392
 393    procedure Initialize;
 394    --  Initializes the internal data structures. Must be called before each
 395    --  separate main program unit (e.g. in a GNSA/ASIS context).
 396
 397 private
 398    --  The Eval routines are all marked inline, since they are called once
 399
 400    pragma Inline (Eval_Actual);
 401    pragma Inline (Eval_Allocator);
 402    pragma Inline (Eval_Character_Literal);
 403    pragma Inline (Eval_Conditional_Expression);
 404    pragma Inline (Eval_Indexed_Component);
 405    pragma Inline (Eval_Named_Integer);
 406    pragma Inline (Eval_Named_Real);
 407    pragma Inline (Eval_Real_Literal);
 408    pragma Inline (Eval_Shift);
 409    pragma Inline (Eval_Slice);
 410    pragma Inline (Eval_String_Literal);
 411    pragma Inline (Eval_Unchecked_Conversion);
 412
 413    pragma Inline (Is_OK_Static_Expression);
 414
 415 end Sem_Eval;