3fe3dc1843ec815d27be12619fe37458b64aa028
[lldb.git] / flang / include / flang / Evaluate / tools.h
1 //===-- include/flang/Evaluate/tools.h --------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8
9 #ifndef FORTRAN_EVALUATE_TOOLS_H_
10 #define FORTRAN_EVALUATE_TOOLS_H_
11
12 #include "traverse.h"
13 #include "flang/Common/idioms.h"
14 #include "flang/Common/template.h"
15 #include "flang/Common/unwrap.h"
16 #include "flang/Evaluate/constant.h"
17 #include "flang/Evaluate/expression.h"
18 #include "flang/Parser/message.h"
19 #include "flang/Semantics/attr.h"
20 #include "flang/Semantics/symbol.h"
21 #include <array>
22 #include <optional>
23 #include <set>
24 #include <type_traits>
25 #include <utility>
26
27 namespace Fortran::evaluate {
28
29 // Some expression predicates and extractors.
30
31 // Predicate: true when an expression is a variable reference, not an
32 // operation.  Be advised: a call to a function that returns an object
33 // pointer is a "variable" in Fortran (it can be the left-hand side of
34 // an assignment).
35 struct IsVariableHelper
36     : public AnyTraverse<IsVariableHelper, std::optional<bool>> {
37   using Result = std::optional<bool>; // effectively tri-state
38   using Base = AnyTraverse<IsVariableHelper, Result>;
39   IsVariableHelper() : Base{*this} {}
40   using Base::operator();
41   Result operator()(const StaticDataObject &) const { return false; }
42   Result operator()(const Symbol &) const;
43   Result operator()(const Component &) const;
44   Result operator()(const ArrayRef &) const;
45   Result operator()(const Substring &) const;
46   Result operator()(const CoarrayRef &) const { return true; }
47   Result operator()(const ComplexPart &) const { return true; }
48   Result operator()(const ProcedureDesignator &) const;
49   template <typename T> Result operator()(const Expr<T> &x) const {
50     if constexpr (common::HasMember<T, AllIntrinsicTypes> ||
51         std::is_same_v<T, SomeDerived>) {
52       // Expression with a specific type
53       if (std::holds_alternative<Designator<T>>(x.u) ||
54           std::holds_alternative<FunctionRef<T>>(x.u)) {
55         if (auto known{(*this)(x.u)}) {
56           return known;
57         }
58       }
59       return false;
60     } else {
61       return (*this)(x.u);
62     }
63   }
64 };
65
66 template <typename A> bool IsVariable(const A &x) {
67   if (auto known{IsVariableHelper{}(x)}) {
68     return *known;
69   } else {
70     return false;
71   }
72 }
73
74 // Predicate: true when an expression is assumed-rank
75 bool IsAssumedRank(const Symbol &);
76 bool IsAssumedRank(const ActualArgument &);
77 template <typename A> bool IsAssumedRank(const A &) { return false; }
78 template <typename A> bool IsAssumedRank(const Designator<A> &designator) {
79   if (const auto *symbol{std::get_if<SymbolRef>(&designator.u)}) {
80     return IsAssumedRank(symbol->get());
81   } else {
82     return false;
83   }
84 }
85 template <typename T> bool IsAssumedRank(const Expr<T> &expr) {
86   return std::visit([](const auto &x) { return IsAssumedRank(x); }, expr.u);
87 }
88 template <typename A> bool IsAssumedRank(const std::optional<A> &x) {
89   return x && IsAssumedRank(*x);
90 }
91
92 // Generalizing packagers: these take operations and expressions of more
93 // specific types and wrap them in Expr<> containers of more abstract types.
94
95 template <typename A> common::IfNoLvalue<Expr<ResultType<A>>, A> AsExpr(A &&x) {
96   return Expr<ResultType<A>>{std::move(x)};
97 }
98
99 template <typename T> Expr<T> AsExpr(Expr<T> &&x) {
100   static_assert(IsSpecificIntrinsicType<T>);
101   return std::move(x);
102 }
103
104 template <TypeCategory CATEGORY>
105 Expr<SomeKind<CATEGORY>> AsCategoryExpr(Expr<SomeKind<CATEGORY>> &&x) {
106   return std::move(x);
107 }
108
109 template <typename A>
110 common::IfNoLvalue<Expr<SomeType>, A> AsGenericExpr(A &&x) {
111   if constexpr (common::HasMember<A, TypelessExpression>) {
112     return Expr<SomeType>{std::move(x)};
113   } else {
114     return Expr<SomeType>{AsCategoryExpr(std::move(x))};
115   }
116 }
117
118 template <typename A>
119 common::IfNoLvalue<Expr<SomeKind<ResultType<A>::category>>, A> AsCategoryExpr(
120     A &&x) {
121   return Expr<SomeKind<ResultType<A>::category>>{AsExpr(std::move(x))};
122 }
123
124 inline Expr<SomeType> AsGenericExpr(Expr<SomeType> &&x) { return std::move(x); }
125
126 Expr<SomeType> Parenthesize(Expr<SomeType> &&);
127
128 Expr<SomeReal> GetComplexPart(
129     const Expr<SomeComplex> &, bool isImaginary = false);
130
131 template <int KIND>
132 Expr<SomeComplex> MakeComplex(Expr<Type<TypeCategory::Real, KIND>> &&re,
133     Expr<Type<TypeCategory::Real, KIND>> &&im) {
134   return AsCategoryExpr(ComplexConstructor<KIND>{std::move(re), std::move(im)});
135 }
136
137 template <typename A> constexpr bool IsNumericCategoryExpr() {
138   if constexpr (common::HasMember<A, TypelessExpression>) {
139     return false;
140   } else {
141     return common::HasMember<ResultType<A>, NumericCategoryTypes>;
142   }
143 }
144
145 // Specializing extractor.  If an Expr wraps some type of object, perhaps
146 // in several layers, return a pointer to it; otherwise null.  Also works
147 // with expressions contained in ActualArgument.
148 template <typename A, typename B>
149 auto UnwrapExpr(B &x) -> common::Constify<A, B> * {
150   using Ty = std::decay_t<B>;
151   if constexpr (std::is_same_v<A, Ty>) {
152     return &x;
153   } else if constexpr (std::is_same_v<Ty, ActualArgument>) {
154     if (auto *expr{x.UnwrapExpr()}) {
155       return UnwrapExpr<A>(*expr);
156     }
157   } else if constexpr (std::is_same_v<Ty, Expr<SomeType>>) {
158     return std::visit([](auto &x) { return UnwrapExpr<A>(x); }, x.u);
159   } else if constexpr (!common::HasMember<A, TypelessExpression>) {
160     if constexpr (std::is_same_v<Ty, Expr<ResultType<A>>> ||
161         std::is_same_v<Ty, Expr<SomeKind<ResultType<A>::category>>>) {
162       return std::visit([](auto &x) { return UnwrapExpr<A>(x); }, x.u);
163     }
164   }
165   return nullptr;
166 }
167
168 template <typename A, typename B>
169 const A *UnwrapExpr(const std::optional<B> &x) {
170   if (x) {
171     return UnwrapExpr<A>(*x);
172   } else {
173     return nullptr;
174   }
175 }
176
177 template <typename A, typename B> A *UnwrapExpr(std::optional<B> &x) {
178   if (x) {
179     return UnwrapExpr<A>(*x);
180   } else {
181     return nullptr;
182   }
183 }
184
185 // If an expression simply wraps a DataRef, extract and return it.
186 // The Boolean argument controls the handling of Substring
187 // references: when true (not default), it extracts the base DataRef
188 // of a substring, if it has one.
189 template <typename A>
190 common::IfNoLvalue<std::optional<DataRef>, A> ExtractDataRef(
191     const A &, bool intoSubstring) {
192   return std::nullopt; // default base case
193 }
194 template <typename T>
195 std::optional<DataRef> ExtractDataRef(
196     const Designator<T> &d, bool intoSubstring = false) {
197   return std::visit(
198       [=](const auto &x) -> std::optional<DataRef> {
199         if constexpr (common::HasMember<decltype(x), decltype(DataRef::u)>) {
200           return DataRef{x};
201         }
202         if constexpr (std::is_same_v<std::decay_t<decltype(x)>, Substring>) {
203           if (intoSubstring) {
204             return ExtractSubstringBase(x);
205           }
206         }
207         return std::nullopt; // w/o "else" to dodge bogus g++ 8.1 warning
208       },
209       d.u);
210 }
211 template <typename T>
212 std::optional<DataRef> ExtractDataRef(
213     const Expr<T> &expr, bool intoSubstring = false) {
214   return std::visit(
215       [=](const auto &x) { return ExtractDataRef(x, intoSubstring); }, expr.u);
216 }
217 template <typename A>
218 std::optional<DataRef> ExtractDataRef(
219     const std::optional<A> &x, bool intoSubstring = false) {
220   if (x) {
221     return ExtractDataRef(*x, intoSubstring);
222   } else {
223     return std::nullopt;
224   }
225 }
226 template <typename A>
227 std::optional<DataRef> ExtractDataRef(const A *p, bool intoSubstring = false) {
228   if (p) {
229     return ExtractDataRef(*p, intoSubstring);
230   } else {
231     return std::nullopt;
232   }
233 }
234 std::optional<DataRef> ExtractSubstringBase(const Substring &);
235
236 // Predicate: is an expression is an array element reference?
237 template <typename T>
238 bool IsArrayElement(const Expr<T> &expr, bool intoSubstring = false) {
239   if (auto dataRef{ExtractDataRef(expr, intoSubstring)}) {
240     const DataRef *ref{&*dataRef};
241     while (const Component * component{std::get_if<Component>(&ref->u)}) {
242       ref = &component->base();
243     }
244     if (const auto *coarrayRef{std::get_if<CoarrayRef>(&ref->u)}) {
245       return !coarrayRef->subscript().empty();
246     } else {
247       return std::holds_alternative<ArrayRef>(ref->u);
248     }
249   } else {
250     return false;
251   }
252 }
253
254 template <typename A>
255 std::optional<NamedEntity> ExtractNamedEntity(const A &x) {
256   if (auto dataRef{ExtractDataRef(x, true)}) {
257     return std::visit(
258         common::visitors{
259             [](SymbolRef &&symbol) -> std::optional<NamedEntity> {
260               return NamedEntity{symbol};
261             },
262             [](Component &&component) -> std::optional<NamedEntity> {
263               return NamedEntity{std::move(component)};
264             },
265             [](CoarrayRef &&co) -> std::optional<NamedEntity> {
266               return co.GetBase();
267             },
268             [](auto &&) { return std::optional<NamedEntity>{}; },
269         },
270         std::move(dataRef->u));
271   } else {
272     return std::nullopt;
273   }
274 }
275
276 struct ExtractCoindexedObjectHelper {
277   template <typename A> std::optional<CoarrayRef> operator()(const A &) const {
278     return std::nullopt;
279   }
280   std::optional<CoarrayRef> operator()(const CoarrayRef &x) const { return x; }
281   template <typename A>
282   std::optional<CoarrayRef> operator()(const Expr<A> &expr) const {
283     return std::visit(*this, expr.u);
284   }
285   std::optional<CoarrayRef> operator()(const DataRef &dataRef) const {
286     return std::visit(*this, dataRef.u);
287   }
288   std::optional<CoarrayRef> operator()(const NamedEntity &named) const {
289     if (const Component * component{named.UnwrapComponent()}) {
290       return (*this)(*component);
291     } else {
292       return std::nullopt;
293     }
294   }
295   std::optional<CoarrayRef> operator()(const ProcedureDesignator &des) const {
296     if (const auto *component{
297             std::get_if<common::CopyableIndirection<Component>>(&des.u)}) {
298       return (*this)(component->value());
299     } else {
300       return std::nullopt;
301     }
302   }
303   std::optional<CoarrayRef> operator()(const Component &component) const {
304     return (*this)(component.base());
305   }
306   std::optional<CoarrayRef> operator()(const ArrayRef &arrayRef) const {
307     return (*this)(arrayRef.base());
308   }
309 };
310
311 template <typename A> std::optional<CoarrayRef> ExtractCoarrayRef(const A &x) {
312   if (auto dataRef{ExtractDataRef(x, true)}) {
313     return ExtractCoindexedObjectHelper{}(*dataRef);
314   } else {
315     return ExtractCoindexedObjectHelper{}(x);
316   }
317 }
318
319 // If an expression is simply a whole symbol data designator,
320 // extract and return that symbol, else null.
321 template <typename A> const Symbol *UnwrapWholeSymbolDataRef(const A &x) {
322   if (auto dataRef{ExtractDataRef(x)}) {
323     if (const SymbolRef * p{std::get_if<SymbolRef>(&dataRef->u)}) {
324       return &p->get();
325     }
326   }
327   return nullptr;
328 }
329
330 // GetFirstSymbol(A%B%C[I]%D) -> A
331 template <typename A> const Symbol *GetFirstSymbol(const A &x) {
332   if (auto dataRef{ExtractDataRef(x, true)}) {
333     return &dataRef->GetFirstSymbol();
334   } else {
335     return nullptr;
336   }
337 }
338
339 // GetLastPointerSymbol(A%PTR1%B%PTR2%C) -> PTR2
340 const Symbol *GetLastPointerSymbol(const evaluate::DataRef &);
341
342 // Creation of conversion expressions can be done to either a known
343 // specific intrinsic type with ConvertToType<T>(x) or by converting
344 // one arbitrary expression to the type of another with ConvertTo(to, from).
345
346 template <typename TO, TypeCategory FROMCAT>
347 Expr<TO> ConvertToType(Expr<SomeKind<FROMCAT>> &&x) {
348   static_assert(IsSpecificIntrinsicType<TO>);
349   if constexpr (FROMCAT == TO::category) {
350     if (auto *already{std::get_if<Expr<TO>>(&x.u)}) {
351       return std::move(*already);
352     } else {
353       return Expr<TO>{Convert<TO, FROMCAT>{std::move(x)}};
354     }
355   } else if constexpr (TO::category == TypeCategory::Complex) {
356     using Part = typename TO::Part;
357     Scalar<Part> zero;
358     return Expr<TO>{ComplexConstructor<TO::kind>{
359         ConvertToType<Part>(std::move(x)), Expr<Part>{Constant<Part>{zero}}}};
360   } else if constexpr (FROMCAT == TypeCategory::Complex) {
361     // Extract and convert the real component of a complex value
362     return std::visit(
363         [&](auto &&z) {
364           using ZType = ResultType<decltype(z)>;
365           using Part = typename ZType::Part;
366           return ConvertToType<TO, TypeCategory::Real>(Expr<SomeReal>{
367               Expr<Part>{ComplexComponent<Part::kind>{false, std::move(z)}}});
368         },
369         std::move(x.u));
370   } else {
371     return Expr<TO>{Convert<TO, FROMCAT>{std::move(x)}};
372   }
373 }
374
375 template <typename TO, TypeCategory FROMCAT, int FROMKIND>
376 Expr<TO> ConvertToType(Expr<Type<FROMCAT, FROMKIND>> &&x) {
377   return ConvertToType<TO, FROMCAT>(Expr<SomeKind<FROMCAT>>{std::move(x)});
378 }
379
380 template <typename TO> Expr<TO> ConvertToType(BOZLiteralConstant &&x) {
381   static_assert(IsSpecificIntrinsicType<TO>);
382   if constexpr (TO::category == TypeCategory::Integer) {
383     return Expr<TO>{
384         Constant<TO>{Scalar<TO>::ConvertUnsigned(std::move(x)).value}};
385   } else {
386     static_assert(TO::category == TypeCategory::Real);
387     using Word = typename Scalar<TO>::Word;
388     return Expr<TO>{
389         Constant<TO>{Scalar<TO>{Word::ConvertUnsigned(std::move(x)).value}}};
390   }
391 }
392
393 // Conversions to dynamic types
394 std::optional<Expr<SomeType>> ConvertToType(
395     const DynamicType &, Expr<SomeType> &&);
396 std::optional<Expr<SomeType>> ConvertToType(
397     const DynamicType &, std::optional<Expr<SomeType>> &&);
398 std::optional<Expr<SomeType>> ConvertToType(const Symbol &, Expr<SomeType> &&);
399 std::optional<Expr<SomeType>> ConvertToType(
400     const Symbol &, std::optional<Expr<SomeType>> &&);
401
402 // Conversions to the type of another expression
403 template <TypeCategory TC, int TK, typename FROM>
404 common::IfNoLvalue<Expr<Type<TC, TK>>, FROM> ConvertTo(
405     const Expr<Type<TC, TK>> &, FROM &&x) {
406   return ConvertToType<Type<TC, TK>>(std::move(x));
407 }
408
409 template <TypeCategory TC, typename FROM>
410 common::IfNoLvalue<Expr<SomeKind<TC>>, FROM> ConvertTo(
411     const Expr<SomeKind<TC>> &to, FROM &&from) {
412   return std::visit(
413       [&](const auto &toKindExpr) {
414         using KindExpr = std::decay_t<decltype(toKindExpr)>;
415         return AsCategoryExpr(
416             ConvertToType<ResultType<KindExpr>>(std::move(from)));
417       },
418       to.u);
419 }
420
421 template <typename FROM>
422 common::IfNoLvalue<Expr<SomeType>, FROM> ConvertTo(
423     const Expr<SomeType> &to, FROM &&from) {
424   return std::visit(
425       [&](const auto &toCatExpr) {
426         return AsGenericExpr(ConvertTo(toCatExpr, std::move(from)));
427       },
428       to.u);
429 }
430
431 // Convert an expression of some known category to a dynamically chosen
432 // kind of some category (usually but not necessarily distinct).
433 template <TypeCategory TOCAT, typename VALUE> struct ConvertToKindHelper {
434   using Result = std::optional<Expr<SomeKind<TOCAT>>>;
435   using Types = CategoryTypes<TOCAT>;
436   ConvertToKindHelper(int k, VALUE &&x) : kind{k}, value{std::move(x)} {}
437   template <typename T> Result Test() {
438     if (kind == T::kind) {
439       return std::make_optional(
440           AsCategoryExpr(ConvertToType<T>(std::move(value))));
441     }
442     return std::nullopt;
443   }
444   int kind;
445   VALUE value;
446 };
447
448 template <TypeCategory TOCAT, typename VALUE>
449 common::IfNoLvalue<Expr<SomeKind<TOCAT>>, VALUE> ConvertToKind(
450     int kind, VALUE &&x) {
451   return common::SearchTypes(
452       ConvertToKindHelper<TOCAT, VALUE>{kind, std::move(x)})
453       .value();
454 }
455
456 // Given a type category CAT, SameKindExprs<CAT, N> is a variant that
457 // holds an arrays of expressions of the same supported kind in that
458 // category.
459 template <typename A, int N = 2> using SameExprs = std::array<Expr<A>, N>;
460 template <int N = 2> struct SameKindExprsHelper {
461   template <typename A> using SameExprs = std::array<Expr<A>, N>;
462 };
463 template <TypeCategory CAT, int N = 2>
464 using SameKindExprs =
465     common::MapTemplate<SameKindExprsHelper<N>::template SameExprs,
466         CategoryTypes<CAT>>;
467
468 // Given references to two expressions of arbitrary kind in the same type
469 // category, convert one to the kind of the other when it has the smaller kind,
470 // then return them in a type-safe package.
471 template <TypeCategory CAT>
472 SameKindExprs<CAT, 2> AsSameKindExprs(
473     Expr<SomeKind<CAT>> &&x, Expr<SomeKind<CAT>> &&y) {
474   return std::visit(
475       [&](auto &&kx, auto &&ky) -> SameKindExprs<CAT, 2> {
476         using XTy = ResultType<decltype(kx)>;
477         using YTy = ResultType<decltype(ky)>;
478         if constexpr (std::is_same_v<XTy, YTy>) {
479           return {SameExprs<XTy>{std::move(kx), std::move(ky)}};
480         } else if constexpr (XTy::kind < YTy::kind) {
481           return {SameExprs<YTy>{ConvertTo(ky, std::move(kx)), std::move(ky)}};
482         } else {
483           return {SameExprs<XTy>{std::move(kx), ConvertTo(kx, std::move(ky))}};
484         }
485 #if !__clang__ && 100 * __GNUC__ + __GNUC_MINOR__ == 801
486         // Silence a bogus warning about a missing return with G++ 8.1.0.
487         // Doesn't execute, but must be correctly typed.
488         CHECK(!"can't happen");
489         return {SameExprs<XTy>{std::move(kx), std::move(kx)}};
490 #endif
491       },
492       std::move(x.u), std::move(y.u));
493 }
494
495 // Ensure that both operands of an intrinsic REAL operation (or CMPLX()
496 // constructor) are INTEGER or REAL, then convert them as necessary to the
497 // same kind of REAL.
498 using ConvertRealOperandsResult =
499     std::optional<SameKindExprs<TypeCategory::Real, 2>>;
500 ConvertRealOperandsResult ConvertRealOperands(parser::ContextualMessages &,
501     Expr<SomeType> &&, Expr<SomeType> &&, int defaultRealKind);
502
503 // Per F'2018 R718, if both components are INTEGER, they are both converted
504 // to default REAL and the result is default COMPLEX.  Otherwise, the
505 // kind of the result is the kind of most precise REAL component, and the other
506 // component is converted if necessary to its type.
507 std::optional<Expr<SomeComplex>> ConstructComplex(parser::ContextualMessages &,
508     Expr<SomeType> &&, Expr<SomeType> &&, int defaultRealKind);
509 std::optional<Expr<SomeComplex>> ConstructComplex(parser::ContextualMessages &,
510     std::optional<Expr<SomeType>> &&, std::optional<Expr<SomeType>> &&,
511     int defaultRealKind);
512
513 template <typename A> Expr<TypeOf<A>> ScalarConstantToExpr(const A &x) {
514   using Ty = TypeOf<A>;
515   static_assert(
516       std::is_same_v<Scalar<Ty>, std::decay_t<A>>, "TypeOf<> is broken");
517   return Expr<TypeOf<A>>{Constant<Ty>{x}};
518 }
519
520 // Combine two expressions of the same specific numeric type with an operation
521 // to produce a new expression.
522 template <template <typename> class OPR, typename SPECIFIC>
523 Expr<SPECIFIC> Combine(Expr<SPECIFIC> &&x, Expr<SPECIFIC> &&y) {
524   static_assert(IsSpecificIntrinsicType<SPECIFIC>);
525   return AsExpr(OPR<SPECIFIC>{std::move(x), std::move(y)});
526 }
527
528 // Given two expressions of arbitrary kind in the same intrinsic type
529 // category, convert one of them if necessary to the larger kind of the
530 // other, then combine the resulting homogenized operands with a given
531 // operation, returning a new expression in the same type category.
532 template <template <typename> class OPR, TypeCategory CAT>
533 Expr<SomeKind<CAT>> PromoteAndCombine(
534     Expr<SomeKind<CAT>> &&x, Expr<SomeKind<CAT>> &&y) {
535   return std::visit(
536       [](auto &&xy) {
537         using Ty = ResultType<decltype(xy[0])>;
538         return AsCategoryExpr(
539             Combine<OPR, Ty>(std::move(xy[0]), std::move(xy[1])));
540       },
541       AsSameKindExprs(std::move(x), std::move(y)));
542 }
543
544 // Given two expressions of arbitrary type, try to combine them with a
545 // binary numeric operation (e.g., Add), possibly with data type conversion of
546 // one of the operands to the type of the other.  Handles special cases with
547 // typeless literal operands and with REAL/COMPLEX exponentiation to INTEGER
548 // powers.
549 template <template <typename> class OPR>
550 std::optional<Expr<SomeType>> NumericOperation(parser::ContextualMessages &,
551     Expr<SomeType> &&, Expr<SomeType> &&, int defaultRealKind);
552
553 extern template std::optional<Expr<SomeType>> NumericOperation<Power>(
554     parser::ContextualMessages &, Expr<SomeType> &&, Expr<SomeType> &&,
555     int defaultRealKind);
556 extern template std::optional<Expr<SomeType>> NumericOperation<Multiply>(
557     parser::ContextualMessages &, Expr<SomeType> &&, Expr<SomeType> &&,
558     int defaultRealKind);
559 extern template std::optional<Expr<SomeType>> NumericOperation<Divide>(
560     parser::ContextualMessages &, Expr<SomeType> &&, Expr<SomeType> &&,
561     int defaultRealKind);
562 extern template std::optional<Expr<SomeType>> NumericOperation<Add>(
563     parser::ContextualMessages &, Expr<SomeType> &&, Expr<SomeType> &&,
564     int defaultRealKind);
565 extern template std::optional<Expr<SomeType>> NumericOperation<Subtract>(
566     parser::ContextualMessages &, Expr<SomeType> &&, Expr<SomeType> &&,
567     int defaultRealKind);
568
569 std::optional<Expr<SomeType>> Negation(
570     parser::ContextualMessages &, Expr<SomeType> &&);
571
572 // Given two expressions of arbitrary type, try to combine them with a
573 // relational operator (e.g., .LT.), possibly with data type conversion.
574 std::optional<Expr<LogicalResult>> Relate(parser::ContextualMessages &,
575     RelationalOperator, Expr<SomeType> &&, Expr<SomeType> &&);
576
577 template <int K>
578 Expr<Type<TypeCategory::Logical, K>> LogicalNegation(
579     Expr<Type<TypeCategory::Logical, K>> &&x) {
580   return AsExpr(Not<K>{std::move(x)});
581 }
582
583 Expr<SomeLogical> LogicalNegation(Expr<SomeLogical> &&);
584
585 template <int K>
586 Expr<Type<TypeCategory::Logical, K>> BinaryLogicalOperation(LogicalOperator opr,
587     Expr<Type<TypeCategory::Logical, K>> &&x,
588     Expr<Type<TypeCategory::Logical, K>> &&y) {
589   return AsExpr(LogicalOperation<K>{opr, std::move(x), std::move(y)});
590 }
591
592 Expr<SomeLogical> BinaryLogicalOperation(
593     LogicalOperator, Expr<SomeLogical> &&, Expr<SomeLogical> &&);
594
595 // Convenience functions and operator overloadings for expression construction.
596 // These interfaces are defined only for those situations that can never
597 // emit any message.  Use the more general templates (above) in other
598 // situations.
599
600 template <TypeCategory C, int K>
601 Expr<Type<C, K>> operator-(Expr<Type<C, K>> &&x) {
602   return AsExpr(Negate<Type<C, K>>{std::move(x)});
603 }
604
605 template <TypeCategory C, int K>
606 Expr<Type<C, K>> operator+(Expr<Type<C, K>> &&x, Expr<Type<C, K>> &&y) {
607   return AsExpr(Combine<Add, Type<C, K>>(std::move(x), std::move(y)));
608 }
609
610 template <TypeCategory C, int K>
611 Expr<Type<C, K>> operator-(Expr<Type<C, K>> &&x, Expr<Type<C, K>> &&y) {
612   return AsExpr(Combine<Subtract, Type<C, K>>(std::move(x), std::move(y)));
613 }
614
615 template <TypeCategory C, int K>
616 Expr<Type<C, K>> operator*(Expr<Type<C, K>> &&x, Expr<Type<C, K>> &&y) {
617   return AsExpr(Combine<Multiply, Type<C, K>>(std::move(x), std::move(y)));
618 }
619
620 template <TypeCategory C, int K>
621 Expr<Type<C, K>> operator/(Expr<Type<C, K>> &&x, Expr<Type<C, K>> &&y) {
622   return AsExpr(Combine<Divide, Type<C, K>>(std::move(x), std::move(y)));
623 }
624
625 template <TypeCategory C> Expr<SomeKind<C>> operator-(Expr<SomeKind<C>> &&x) {
626   return std::visit(
627       [](auto &xk) { return Expr<SomeKind<C>>{-std::move(xk)}; }, x.u);
628 }
629
630 template <TypeCategory CAT>
631 Expr<SomeKind<CAT>> operator+(
632     Expr<SomeKind<CAT>> &&x, Expr<SomeKind<CAT>> &&y) {
633   return PromoteAndCombine<Add, CAT>(std::move(x), std::move(y));
634 }
635
636 template <TypeCategory CAT>
637 Expr<SomeKind<CAT>> operator-(
638     Expr<SomeKind<CAT>> &&x, Expr<SomeKind<CAT>> &&y) {
639   return PromoteAndCombine<Subtract, CAT>(std::move(x), std::move(y));
640 }
641
642 template <TypeCategory CAT>
643 Expr<SomeKind<CAT>> operator*(
644     Expr<SomeKind<CAT>> &&x, Expr<SomeKind<CAT>> &&y) {
645   return PromoteAndCombine<Multiply, CAT>(std::move(x), std::move(y));
646 }
647
648 template <TypeCategory CAT>
649 Expr<SomeKind<CAT>> operator/(
650     Expr<SomeKind<CAT>> &&x, Expr<SomeKind<CAT>> &&y) {
651   return PromoteAndCombine<Divide, CAT>(std::move(x), std::move(y));
652 }
653
654 // A utility for use with common::SearchTypes to create generic expressions
655 // when an intrinsic type category for (say) a variable is known
656 // but the kind parameter value is not.
657 template <TypeCategory CAT, template <typename> class TEMPLATE, typename VALUE>
658 struct TypeKindVisitor {
659   using Result = std::optional<Expr<SomeType>>;
660   using Types = CategoryTypes<CAT>;
661
662   TypeKindVisitor(int k, VALUE &&x) : kind{k}, value{std::move(x)} {}
663   TypeKindVisitor(int k, const VALUE &x) : kind{k}, value{x} {}
664
665   template <typename T> Result Test() {
666     if (kind == T::kind) {
667       return AsGenericExpr(TEMPLATE<T>{std::move(value)});
668     }
669     return std::nullopt;
670   }
671
672   int kind;
673   VALUE value;
674 };
675
676 // TypedWrapper() wraps a object in an explicitly typed representation
677 // (e.g., Designator<> or FunctionRef<>) that has been instantiated on
678 // a dynamically chosen Fortran type.
679 template <TypeCategory CATEGORY, template <typename> typename WRAPPER,
680     typename WRAPPED>
681 common::IfNoLvalue<std::optional<Expr<SomeType>>, WRAPPED> WrapperHelper(
682     int kind, WRAPPED &&x) {
683   return common::SearchTypes(
684       TypeKindVisitor<CATEGORY, WRAPPER, WRAPPED>{kind, std::move(x)});
685 }
686
687 template <template <typename> typename WRAPPER, typename WRAPPED>
688 common::IfNoLvalue<std::optional<Expr<SomeType>>, WRAPPED> TypedWrapper(
689     const DynamicType &dyType, WRAPPED &&x) {
690   switch (dyType.category()) {
691     SWITCH_COVERS_ALL_CASES
692   case TypeCategory::Integer:
693     return WrapperHelper<TypeCategory::Integer, WRAPPER, WRAPPED>(
694         dyType.kind(), std::move(x));
695   case TypeCategory::Real:
696     return WrapperHelper<TypeCategory::Real, WRAPPER, WRAPPED>(
697         dyType.kind(), std::move(x));
698   case TypeCategory::Complex:
699     return WrapperHelper<TypeCategory::Complex, WRAPPER, WRAPPED>(
700         dyType.kind(), std::move(x));
701   case TypeCategory::Character:
702     return WrapperHelper<TypeCategory::Character, WRAPPER, WRAPPED>(
703         dyType.kind(), std::move(x));
704   case TypeCategory::Logical:
705     return WrapperHelper<TypeCategory::Logical, WRAPPER, WRAPPED>(
706         dyType.kind(), std::move(x));
707   case TypeCategory::Derived:
708     return AsGenericExpr(Expr<SomeDerived>{WRAPPER<SomeDerived>{std::move(x)}});
709   }
710 }
711
712 // GetLastSymbol() returns the rightmost symbol in an object or procedure
713 // designator (which has perhaps been wrapped in an Expr<>), or a null pointer
714 // when none is found.
715 struct GetLastSymbolHelper
716     : public AnyTraverse<GetLastSymbolHelper, std::optional<const Symbol *>> {
717   using Result = std::optional<const Symbol *>;
718   using Base = AnyTraverse<GetLastSymbolHelper, Result>;
719   GetLastSymbolHelper() : Base{*this} {}
720   using Base::operator();
721   Result operator()(const Symbol &x) const { return &x; }
722   Result operator()(const Component &x) const { return &x.GetLastSymbol(); }
723   Result operator()(const NamedEntity &x) const { return &x.GetLastSymbol(); }
724   Result operator()(const ProcedureDesignator &x) const {
725     return x.GetSymbol();
726   }
727   template <typename T> Result operator()(const Expr<T> &x) const {
728     if constexpr (common::HasMember<T, AllIntrinsicTypes> ||
729         std::is_same_v<T, SomeDerived>) {
730       if (const auto *designator{std::get_if<Designator<T>>(&x.u)}) {
731         if (auto known{(*this)(*designator)}) {
732           return known;
733         }
734       }
735       return nullptr;
736     } else {
737       return (*this)(x.u);
738     }
739   }
740 };
741
742 template <typename A> const Symbol *GetLastSymbol(const A &x) {
743   if (auto known{GetLastSymbolHelper{}(x)}) {
744     return *known;
745   } else {
746     return nullptr;
747   }
748 }
749
750 // Convenience: If GetLastSymbol() succeeds on the argument, return its
751 // set of attributes, otherwise the empty set.
752 template <typename A> semantics::Attrs GetAttrs(const A &x) {
753   if (const Symbol * symbol{GetLastSymbol(x)}) {
754     return symbol->attrs();
755   } else {
756     return {};
757   }
758 }
759
760 // GetBaseObject()
761 template <typename A> std::optional<BaseObject> GetBaseObject(const A &) {
762   return std::nullopt;
763 }
764 template <typename T>
765 std::optional<BaseObject> GetBaseObject(const Designator<T> &x) {
766   return x.GetBaseObject();
767 }
768 template <typename T>
769 std::optional<BaseObject> GetBaseObject(const Expr<T> &x) {
770   return std::visit([](const auto &y) { return GetBaseObject(y); }, x.u);
771 }
772 template <typename A>
773 std::optional<BaseObject> GetBaseObject(const std::optional<A> &x) {
774   if (x) {
775     return GetBaseObject(*x);
776   } else {
777     return std::nullopt;
778   }
779 }
780
781 // Predicate: IsAllocatableOrPointer()
782 template <typename A> bool IsAllocatableOrPointer(const A &x) {
783   return GetAttrs(x).HasAny(
784       semantics::Attrs{semantics::Attr::POINTER, semantics::Attr::ALLOCATABLE});
785 }
786
787 // Procedure and pointer detection predicates
788 bool IsProcedure(const Expr<SomeType> &);
789 bool IsFunction(const Expr<SomeType> &);
790 bool IsProcedurePointer(const Expr<SomeType> &);
791 bool IsNullPointer(const Expr<SomeType> &);
792
793 // Extracts the chain of symbols from a designator, which has perhaps been
794 // wrapped in an Expr<>, removing all of the (co)subscripts.  The
795 // base object will be the first symbol in the result vector.
796 struct GetSymbolVectorHelper
797     : public Traverse<GetSymbolVectorHelper, SymbolVector> {
798   using Result = SymbolVector;
799   using Base = Traverse<GetSymbolVectorHelper, Result>;
800   using Base::operator();
801   GetSymbolVectorHelper() : Base{*this} {}
802   Result Default() { return {}; }
803   Result Combine(Result &&a, Result &&b) {
804     a.insert(a.end(), b.begin(), b.end());
805     return std::move(a);
806   }
807   Result operator()(const Symbol &) const;
808   Result operator()(const Component &) const;
809   Result operator()(const ArrayRef &) const;
810   Result operator()(const CoarrayRef &) const;
811 };
812 template <typename A> SymbolVector GetSymbolVector(const A &x) {
813   return GetSymbolVectorHelper{}(x);
814 }
815
816 // GetLastTarget() returns the rightmost symbol in an object designator's
817 // SymbolVector that has the POINTER or TARGET attribute, or a null pointer
818 // when none is found.
819 const Symbol *GetLastTarget(const SymbolVector &);
820
821 // Collects all of the Symbols in an expression
822 template <typename A> semantics::SymbolSet CollectSymbols(const A &);
823 extern template semantics::SymbolSet CollectSymbols(const Expr<SomeType> &);
824 extern template semantics::SymbolSet CollectSymbols(const Expr<SomeInteger> &);
825 extern template semantics::SymbolSet CollectSymbols(
826     const Expr<SubscriptInteger> &);
827
828 // Predicate: does a variable contain a vector-valued subscript (not a triplet)?
829 bool HasVectorSubscript(const Expr<SomeType> &);
830
831 // Utilities for attaching the location of the declaration of a symbol
832 // of interest to a message, if both pointers are non-null.  Handles
833 // the case of USE association gracefully.
834 parser::Message *AttachDeclaration(parser::Message &, const Symbol &);
835 parser::Message *AttachDeclaration(parser::Message *, const Symbol &);
836 template <typename MESSAGES, typename... A>
837 parser::Message *SayWithDeclaration(
838     MESSAGES &messages, const Symbol &symbol, A &&...x) {
839   return AttachDeclaration(messages.Say(std::forward<A>(x)...), symbol);
840 }
841
842 // Check for references to impure procedures; returns the name
843 // of one to complain about, if any exist.
844 std::optional<std::string> FindImpureCall(
845     FoldingContext &, const Expr<SomeType> &);
846 std::optional<std::string> FindImpureCall(
847     FoldingContext &, const ProcedureRef &);
848
849 // Predicate: is a scalar expression suitable for naive scalar expansion
850 // in the flattening of an array expression?
851 // TODO: capture such scalar expansions in temporaries, flatten everything
852 struct UnexpandabilityFindingVisitor
853     : public AnyTraverse<UnexpandabilityFindingVisitor> {
854   using Base = AnyTraverse<UnexpandabilityFindingVisitor>;
855   using Base::operator();
856   UnexpandabilityFindingVisitor() : Base{*this} {}
857   template <typename T> bool operator()(const FunctionRef<T> &) { return true; }
858   bool operator()(const CoarrayRef &) { return true; }
859 };
860
861 template <typename T> bool IsExpandableScalar(const Expr<T> &expr) {
862   return !UnexpandabilityFindingVisitor{}(expr);
863 }
864
865 // Common handling for procedure pointer compatibility of left- and right-hand
866 // sides.  Returns nullopt if they're compatible.  Otherwise, it returns a
867 // message that needs to be augmented by the names of the left and right sides
868 std::optional<parser::MessageFixedText> CheckProcCompatibility(bool isCall,
869     const std::optional<characteristics::Procedure> &lhsProcedure,
870     const characteristics::Procedure *rhsProcedure);
871
872 // Scalar constant expansion
873 class ScalarConstantExpander {
874 public:
875   explicit ScalarConstantExpander(ConstantSubscripts &&extents)
876       : extents_{std::move(extents)} {}
877   ScalarConstantExpander(
878       ConstantSubscripts &&extents, std::optional<ConstantSubscripts> &&lbounds)
879       : extents_{std::move(extents)}, lbounds_{std::move(lbounds)} {}
880   ScalarConstantExpander(
881       ConstantSubscripts &&extents, ConstantSubscripts &&lbounds)
882       : extents_{std::move(extents)}, lbounds_{std::move(lbounds)} {}
883
884   template <typename A> A Expand(A &&x) const {
885     return std::move(x); // default case
886   }
887   template <typename T> Constant<T> Expand(Constant<T> &&x) {
888     auto expanded{x.Reshape(std::move(extents_))};
889     if (lbounds_) {
890       expanded.set_lbounds(std::move(*lbounds_));
891     }
892     return expanded;
893   }
894   template <typename T> Constant<T> Expand(Parentheses<T> &&x) {
895     return Expand(std::move(x)); // Constant<> can be parenthesized
896   }
897   template <typename T> Expr<T> Expand(Expr<T> &&x) {
898     return std::visit([&](auto &&x) { return Expr<T>{Expand(std::move(x))}; },
899         std::move(x.u));
900   }
901
902 private:
903   ConstantSubscripts extents_;
904   std::optional<ConstantSubscripts> lbounds_;
905 };
906
907 } // namespace Fortran::evaluate
908
909 namespace Fortran::semantics {
910
911 class Scope;
912
913 // These functions are used in Evaluate so they are defined here rather than in
914 // Semantics to avoid a link-time dependency on Semantics.
915 // All of these apply GetUltimate() or ResolveAssociations() to their arguments.
916
917 bool IsVariableName(const Symbol &);
918 bool IsPureProcedure(const Symbol &);
919 bool IsPureProcedure(const Scope &);
920 bool IsFunction(const Symbol &);
921 bool IsProcedure(const Symbol &);
922 bool IsProcedurePointer(const Symbol &);
923 bool IsSaved(const Symbol &); // saved implicitly or explicitly
924 bool IsDummy(const Symbol &);
925 bool IsFunctionResult(const Symbol &);
926 bool IsKindTypeParameter(const Symbol &);
927 bool IsLenTypeParameter(const Symbol &);
928
929 // ResolveAssociations() traverses use associations and host associations
930 // like GetUltimate(), but also resolves through whole variable associations
931 // with ASSOCIATE(x => y) and related constructs.  GetAssociationRoot()
932 // applies ResolveAssociations() and then, in the case of resolution to
933 // a construct association with part of a variable that does not involve a
934 // vector subscript, returns the first symbol of that variable instead
935 // of the construct entity.
936 // (E.g., for ASSOCIATE(x => y%z), ResolveAssociations(x) returns x,
937 // while GetAssociationRoot(x) returns y.)
938 const Symbol &ResolveAssociations(const Symbol &);
939 const Symbol &GetAssociationRoot(const Symbol &);
940
941 const Symbol *FindCommonBlockContaining(const Symbol &);
942 int CountLenParameters(const DerivedTypeSpec &);
943 int CountNonConstantLenParameters(const DerivedTypeSpec &);
944 const Symbol &GetUsedModule(const UseDetails &);
945
946 } // namespace Fortran::semantics
947
948 #endif // FORTRAN_EVALUATE_TOOLS_H_