contrib/llvm-project/clang/include/clang/AST/TemplateName.h

   1 //===- TemplateName.h - C++ Template Name Representation --------*- 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 //  This file defines the TemplateName interface and subclasses.
  10 //
  11 //===----------------------------------------------------------------------===//
  12
  13 #ifndef LLVM_CLANG_AST_TEMPLATENAME_H
  14 #define LLVM_CLANG_AST_TEMPLATENAME_H
  15
  16 #include "clang/AST/NestedNameSpecifier.h"
  17 #include "clang/Basic/LLVM.h"
  18 #include "llvm/ADT/FoldingSet.h"
  19 #include "llvm/ADT/PointerIntPair.h"
  20 #include "llvm/ADT/PointerUnion.h"
  21 #include "llvm/Support/PointerLikeTypeTraits.h"
  22 #include <cassert>
  23
  24 namespace clang {
  25
  26 class ASTContext;
  27 class DependentTemplateName;
  28 class DiagnosticBuilder;
  29 class IdentifierInfo;
  30 class NamedDecl;
  31 class NestedNameSpecifier;
  32 enum OverloadedOperatorKind : int;
  33 class OverloadedTemplateStorage;
  34 class AssumedTemplateStorage;
  35 class PartialDiagnostic;
  36 struct PrintingPolicy;
  37 class QualifiedTemplateName;
  38 class SubstTemplateTemplateParmPackStorage;
  39 class SubstTemplateTemplateParmStorage;
  40 class TemplateArgument;
  41 class TemplateDecl;
  42 class TemplateTemplateParmDecl;
  43
  44 /// Implementation class used to describe either a set of overloaded
  45 /// template names or an already-substituted template template parameter pack.
  46 class UncommonTemplateNameStorage {
  47 protected:
  48   enum Kind {
  49     Overloaded,
  50     Assumed, // defined in DeclarationName.h
  51     SubstTemplateTemplateParm,
  52     SubstTemplateTemplateParmPack
  53   };
  54
  55   struct BitsTag {
  56     /// A Kind.
  57     unsigned Kind : 2;
  58
  59     /// The number of stored templates or template arguments,
  60     /// depending on which subclass we have.
  61     unsigned Size : 30;
  62   };
  63
  64   union {
  65     struct BitsTag Bits;
  66     void *PointerAlignment;
  67   };
  68
  69   UncommonTemplateNameStorage(Kind kind, unsigned size) {
  70     Bits.Kind = kind;
  71     Bits.Size = size;
  72   }
  73
  74 public:
  75   unsigned size() const { return Bits.Size; }
  76
  77   OverloadedTemplateStorage *getAsOverloadedStorage()  {
  78     return Bits.Kind == Overloaded
  79              ? reinterpret_cast<OverloadedTemplateStorage *>(this)
  80              : nullptr;
  81   }
  82
  83   AssumedTemplateStorage *getAsAssumedTemplateName()  {
  84     return Bits.Kind == Assumed
  85              ? reinterpret_cast<AssumedTemplateStorage *>(this)
  86              : nullptr;
  87   }
  88
  89   SubstTemplateTemplateParmStorage *getAsSubstTemplateTemplateParm() {
  90     return Bits.Kind == SubstTemplateTemplateParm
  91              ? reinterpret_cast<SubstTemplateTemplateParmStorage *>(this)
  92              : nullptr;
  93   }
  94
  95   SubstTemplateTemplateParmPackStorage *getAsSubstTemplateTemplateParmPack() {
  96     return Bits.Kind == SubstTemplateTemplateParmPack
  97              ? reinterpret_cast<SubstTemplateTemplateParmPackStorage *>(this)
  98              : nullptr;
  99   }
 100 };
 101
 102 /// A structure for storing the information associated with an
 103 /// overloaded template name.
 104 class OverloadedTemplateStorage : public UncommonTemplateNameStorage {
 105   friend class ASTContext;
 106
 107   OverloadedTemplateStorage(unsigned size)
 108       : UncommonTemplateNameStorage(Overloaded, size) {}
 109
 110   NamedDecl **getStorage() {
 111     return reinterpret_cast<NamedDecl **>(this + 1);
 112   }
 113   NamedDecl * const *getStorage() const {
 114     return reinterpret_cast<NamedDecl *const *>(this + 1);
 115   }
 116
 117 public:
 118   using iterator = NamedDecl *const *;
 119
 120   iterator begin() const { return getStorage(); }
 121   iterator end() const { return getStorage() + size(); }
 122 };
 123
 124 /// A structure for storing an already-substituted template template
 125 /// parameter pack.
 126 ///
 127 /// This kind of template names occurs when the parameter pack has been
 128 /// provided with a template template argument pack in a context where its
 129 /// enclosing pack expansion could not be fully expanded.
 130 class SubstTemplateTemplateParmPackStorage
 131   : public UncommonTemplateNameStorage, public llvm::FoldingSetNode
 132 {
 133   TemplateTemplateParmDecl *Parameter;
 134   const TemplateArgument *Arguments;
 135
 136 public:
 137   SubstTemplateTemplateParmPackStorage(TemplateTemplateParmDecl *Parameter,
 138                                        unsigned Size,
 139                                        const TemplateArgument *Arguments)
 140       : UncommonTemplateNameStorage(SubstTemplateTemplateParmPack, Size),
 141         Parameter(Parameter), Arguments(Arguments) {}
 142
 143   /// Retrieve the template template parameter pack being substituted.
 144   TemplateTemplateParmDecl *getParameterPack() const {
 145     return Parameter;
 146   }
 147
 148   /// Retrieve the template template argument pack with which this
 149   /// parameter was substituted.
 150   TemplateArgument getArgumentPack() const;
 151
 152   void Profile(llvm::FoldingSetNodeID &ID, ASTContext &Context);
 153
 154   static void Profile(llvm::FoldingSetNodeID &ID,
 155                       ASTContext &Context,
 156                       TemplateTemplateParmDecl *Parameter,
 157                       const TemplateArgument &ArgPack);
 158 };
 159
 160 /// Represents a C++ template name within the type system.
 161 ///
 162 /// A C++ template name refers to a template within the C++ type
 163 /// system. In most cases, a template name is simply a reference to a
 164 /// class template, e.g.
 165 ///
 166 /// \code
 167 /// template<typename T> class X { };
 168 ///
 169 /// X<int> xi;
 170 /// \endcode
 171 ///
 172 /// Here, the 'X' in \c X<int> is a template name that refers to the
 173 /// declaration of the class template X, above. Template names can
 174 /// also refer to function templates, C++0x template aliases, etc.
 175 ///
 176 /// Some template names are dependent. For example, consider:
 177 ///
 178 /// \code
 179 /// template<typename MetaFun, typename T1, typename T2> struct apply2 {
 180 ///   typedef typename MetaFun::template apply<T1, T2>::type type;
 181 /// };
 182 /// \endcode
 183 ///
 184 /// Here, "apply" is treated as a template name within the typename
 185 /// specifier in the typedef. "apply" is a nested template, and can
 186 /// only be understood in the context of
 187 class TemplateName {
 188   using StorageType =
 189       llvm::PointerUnion4<TemplateDecl *, UncommonTemplateNameStorage *,
 190                           QualifiedTemplateName *, DependentTemplateName *>;
 191
 192   StorageType Storage;
 193
 194   explicit TemplateName(void *Ptr);
 195
 196 public:
 197   // Kind of name that is actually stored.
 198   enum NameKind {
 199     /// A single template declaration.
 200     Template,
 201
 202     /// A set of overloaded template declarations.
 203     OverloadedTemplate,
 204
 205     /// An unqualified-id that has been assumed to name a function template
 206     /// that will be found by ADL.
 207     AssumedTemplate,
 208
 209     /// A qualified template name, where the qualification is kept
 210     /// to describe the source code as written.
 211     QualifiedTemplate,
 212
 213     /// A dependent template name that has not been resolved to a
 214     /// template (or set of templates).
 215     DependentTemplate,
 216
 217     /// A template template parameter that has been substituted
 218     /// for some other template name.
 219     SubstTemplateTemplateParm,
 220
 221     /// A template template parameter pack that has been substituted for
 222     /// a template template argument pack, but has not yet been expanded into
 223     /// individual arguments.
 224     SubstTemplateTemplateParmPack
 225   };
 226
 227   TemplateName() = default;
 228   explicit TemplateName(TemplateDecl *Template);
 229   explicit TemplateName(OverloadedTemplateStorage *Storage);
 230   explicit TemplateName(AssumedTemplateStorage *Storage);
 231   explicit TemplateName(SubstTemplateTemplateParmStorage *Storage);
 232   explicit TemplateName(SubstTemplateTemplateParmPackStorage *Storage);
 233   explicit TemplateName(QualifiedTemplateName *Qual);
 234   explicit TemplateName(DependentTemplateName *Dep);
 235
 236   /// Determine whether this template name is NULL.
 237   bool isNull() const;
 238
 239   // Get the kind of name that is actually stored.
 240   NameKind getKind() const;
 241
 242   /// Retrieve the underlying template declaration that
 243   /// this template name refers to, if known.
 244   ///
 245   /// \returns The template declaration that this template name refers
 246   /// to, if any. If the template name does not refer to a specific
 247   /// declaration because it is a dependent name, or if it refers to a
 248   /// set of function templates, returns NULL.
 249   TemplateDecl *getAsTemplateDecl() const;
 250
 251   /// Retrieve the underlying, overloaded function template
 252   /// declarations that this template name refers to, if known.
 253   ///
 254   /// \returns The set of overloaded function templates that this template
 255   /// name refers to, if known. If the template name does not refer to a
 256   /// specific set of function templates because it is a dependent name or
 257   /// refers to a single template, returns NULL.
 258   OverloadedTemplateStorage *getAsOverloadedTemplate() const;
 259
 260   /// Retrieve information on a name that has been assumed to be a
 261   /// template-name in order to permit a call via ADL.
 262   AssumedTemplateStorage *getAsAssumedTemplateName() const;
 263
 264   /// Retrieve the substituted template template parameter, if
 265   /// known.
 266   ///
 267   /// \returns The storage for the substituted template template parameter,
 268   /// if known. Otherwise, returns NULL.
 269   SubstTemplateTemplateParmStorage *getAsSubstTemplateTemplateParm() const;
 270
 271   /// Retrieve the substituted template template parameter pack, if
 272   /// known.
 273   ///
 274   /// \returns The storage for the substituted template template parameter pack,
 275   /// if known. Otherwise, returns NULL.
 276   SubstTemplateTemplateParmPackStorage *
 277   getAsSubstTemplateTemplateParmPack() const;
 278
 279   /// Retrieve the underlying qualified template name
 280   /// structure, if any.
 281   QualifiedTemplateName *getAsQualifiedTemplateName() const;
 282
 283   /// Retrieve the underlying dependent template name
 284   /// structure, if any.
 285   DependentTemplateName *getAsDependentTemplateName() const;
 286
 287   TemplateName getUnderlying() const;
 288
 289   /// Get the template name to substitute when this template name is used as a
 290   /// template template argument. This refers to the most recent declaration of
 291   /// the template, including any default template arguments.
 292   TemplateName getNameToSubstitute() const;
 293
 294   /// Determines whether this is a dependent template name.
 295   bool isDependent() const;
 296
 297   /// Determines whether this is a template name that somehow
 298   /// depends on a template parameter.
 299   bool isInstantiationDependent() const;
 300
 301   /// Determines whether this template name contains an
 302   /// unexpanded parameter pack (for C++0x variadic templates).
 303   bool containsUnexpandedParameterPack() const;
 304
 305   /// Print the template name.
 306   ///
 307   /// \param OS the output stream to which the template name will be
 308   /// printed.
 309   ///
 310   /// \param SuppressNNS if true, don't print the
 311   /// nested-name-specifier that precedes the template name (if it has
 312   /// one).
 313   void print(raw_ostream &OS, const PrintingPolicy &Policy,
 314              bool SuppressNNS = false) const;
 315
 316   /// Debugging aid that dumps the template name.
 317   void dump(raw_ostream &OS) const;
 318
 319   /// Debugging aid that dumps the template name to standard
 320   /// error.
 321   void dump() const;
 322
 323   void Profile(llvm::FoldingSetNodeID &ID) {
 324     ID.AddPointer(Storage.getOpaqueValue());
 325   }
 326
 327   /// Retrieve the template name as a void pointer.
 328   void *getAsVoidPointer() const { return Storage.getOpaqueValue(); }
 329
 330   /// Build a template name from a void pointer.
 331   static TemplateName getFromVoidPointer(void *Ptr) {
 332     return TemplateName(Ptr);
 333   }
 334 };
 335
 336 /// Insertion operator for diagnostics.  This allows sending TemplateName's
 337 /// into a diagnostic with <<.
 338 const DiagnosticBuilder &operator<<(const DiagnosticBuilder &DB,
 339                                     TemplateName N);
 340 const PartialDiagnostic &operator<<(const PartialDiagnostic &PD,
 341                                     TemplateName N);
 342
 343 /// A structure for storing the information associated with a
 344 /// substituted template template parameter.
 345 class SubstTemplateTemplateParmStorage
 346   : public UncommonTemplateNameStorage, public llvm::FoldingSetNode {
 347   friend class ASTContext;
 348
 349   TemplateTemplateParmDecl *Parameter;
 350   TemplateName Replacement;
 351
 352   SubstTemplateTemplateParmStorage(TemplateTemplateParmDecl *parameter,
 353                                    TemplateName replacement)
 354       : UncommonTemplateNameStorage(SubstTemplateTemplateParm, 0),
 355         Parameter(parameter), Replacement(replacement) {}
 356
 357 public:
 358   TemplateTemplateParmDecl *getParameter() const { return Parameter; }
 359   TemplateName getReplacement() const { return Replacement; }
 360
 361   void Profile(llvm::FoldingSetNodeID &ID);
 362
 363   static void Profile(llvm::FoldingSetNodeID &ID,
 364                       TemplateTemplateParmDecl *parameter,
 365                       TemplateName replacement);
 366 };
 367
 368 inline TemplateName TemplateName::getUnderlying() const {
 369   if (SubstTemplateTemplateParmStorage *subst
 370         = getAsSubstTemplateTemplateParm())
 371     return subst->getReplacement().getUnderlying();
 372   return *this;
 373 }
 374
 375 /// Represents a template name that was expressed as a
 376 /// qualified name.
 377 ///
 378 /// This kind of template name refers to a template name that was
 379 /// preceded by a nested name specifier, e.g., \c std::vector. Here,
 380 /// the nested name specifier is "std::" and the template name is the
 381 /// declaration for "vector". The QualifiedTemplateName class is only
 382 /// used to provide "sugar" for template names that were expressed
 383 /// with a qualified name, and has no semantic meaning. In this
 384 /// manner, it is to TemplateName what ElaboratedType is to Type,
 385 /// providing extra syntactic sugar for downstream clients.
 386 class QualifiedTemplateName : public llvm::FoldingSetNode {
 387   friend class ASTContext;
 388
 389   /// The nested name specifier that qualifies the template name.
 390   ///
 391   /// The bit is used to indicate whether the "template" keyword was
 392   /// present before the template name itself. Note that the
 393   /// "template" keyword is always redundant in this case (otherwise,
 394   /// the template name would be a dependent name and we would express
 395   /// this name with DependentTemplateName).
 396   llvm::PointerIntPair<NestedNameSpecifier *, 1> Qualifier;
 397
 398   /// The template declaration or set of overloaded function templates
 399   /// that this qualified name refers to.
 400   TemplateDecl *Template;
 401
 402   QualifiedTemplateName(NestedNameSpecifier *NNS, bool TemplateKeyword,
 403                         TemplateDecl *Template)
 404       : Qualifier(NNS, TemplateKeyword? 1 : 0), Template(Template) {}
 405
 406 public:
 407   /// Return the nested name specifier that qualifies this name.
 408   NestedNameSpecifier *getQualifier() const { return Qualifier.getPointer(); }
 409
 410   /// Whether the template name was prefixed by the "template"
 411   /// keyword.
 412   bool hasTemplateKeyword() const { return Qualifier.getInt(); }
 413
 414   /// The template declaration that this qualified name refers
 415   /// to.
 416   TemplateDecl *getDecl() const { return Template; }
 417
 418   /// The template declaration to which this qualified name
 419   /// refers.
 420   TemplateDecl *getTemplateDecl() const { return Template; }
 421
 422   void Profile(llvm::FoldingSetNodeID &ID) {
 423     Profile(ID, getQualifier(), hasTemplateKeyword(), getTemplateDecl());
 424   }
 425
 426   static void Profile(llvm::FoldingSetNodeID &ID, NestedNameSpecifier *NNS,
 427                       bool TemplateKeyword, TemplateDecl *Template) {
 428     ID.AddPointer(NNS);
 429     ID.AddBoolean(TemplateKeyword);
 430     ID.AddPointer(Template);
 431   }
 432 };
 433
 434 /// Represents a dependent template name that cannot be
 435 /// resolved prior to template instantiation.
 436 ///
 437 /// This kind of template name refers to a dependent template name,
 438 /// including its nested name specifier (if any). For example,
 439 /// DependentTemplateName can refer to "MetaFun::template apply",
 440 /// where "MetaFun::" is the nested name specifier and "apply" is the
 441 /// template name referenced. The "template" keyword is implied.
 442 class DependentTemplateName : public llvm::FoldingSetNode {
 443   friend class ASTContext;
 444
 445   /// The nested name specifier that qualifies the template
 446   /// name.
 447   ///
 448   /// The bit stored in this qualifier describes whether the \c Name field
 449   /// is interpreted as an IdentifierInfo pointer (when clear) or as an
 450   /// overloaded operator kind (when set).
 451   llvm::PointerIntPair<NestedNameSpecifier *, 1, bool> Qualifier;
 452
 453   /// The dependent template name.
 454   union {
 455     /// The identifier template name.
 456     ///
 457     /// Only valid when the bit on \c Qualifier is clear.
 458     const IdentifierInfo *Identifier;
 459
 460     /// The overloaded operator name.
 461     ///
 462     /// Only valid when the bit on \c Qualifier is set.
 463     OverloadedOperatorKind Operator;
 464   };
 465
 466   /// The canonical template name to which this dependent
 467   /// template name refers.
 468   ///
 469   /// The canonical template name for a dependent template name is
 470   /// another dependent template name whose nested name specifier is
 471   /// canonical.
 472   TemplateName CanonicalTemplateName;
 473
 474   DependentTemplateName(NestedNameSpecifier *Qualifier,
 475                         const IdentifierInfo *Identifier)
 476       : Qualifier(Qualifier, false), Identifier(Identifier),
 477         CanonicalTemplateName(this) {}
 478
 479   DependentTemplateName(NestedNameSpecifier *Qualifier,
 480                         const IdentifierInfo *Identifier,
 481                         TemplateName Canon)
 482       : Qualifier(Qualifier, false), Identifier(Identifier),
 483         CanonicalTemplateName(Canon) {}
 484
 485   DependentTemplateName(NestedNameSpecifier *Qualifier,
 486                         OverloadedOperatorKind Operator)
 487       : Qualifier(Qualifier, true), Operator(Operator),
 488         CanonicalTemplateName(this) {}
 489
 490   DependentTemplateName(NestedNameSpecifier *Qualifier,
 491                         OverloadedOperatorKind Operator,
 492                         TemplateName Canon)
 493        : Qualifier(Qualifier, true), Operator(Operator),
 494          CanonicalTemplateName(Canon) {}
 495
 496 public:
 497   /// Return the nested name specifier that qualifies this name.
 498   NestedNameSpecifier *getQualifier() const { return Qualifier.getPointer(); }
 499
 500   /// Determine whether this template name refers to an identifier.
 501   bool isIdentifier() const { return !Qualifier.getInt(); }
 502
 503   /// Returns the identifier to which this template name refers.
 504   const IdentifierInfo *getIdentifier() const {
 505     assert(isIdentifier() && "Template name isn't an identifier?");
 506     return Identifier;
 507   }
 508
 509   /// Determine whether this template name refers to an overloaded
 510   /// operator.
 511   bool isOverloadedOperator() const { return Qualifier.getInt(); }
 512
 513   /// Return the overloaded operator to which this template name refers.
 514   OverloadedOperatorKind getOperator() const {
 515     assert(isOverloadedOperator() &&
 516            "Template name isn't an overloaded operator?");
 517     return Operator;
 518   }
 519
 520   void Profile(llvm::FoldingSetNodeID &ID) {
 521     if (isIdentifier())
 522       Profile(ID, getQualifier(), getIdentifier());
 523     else
 524       Profile(ID, getQualifier(), getOperator());
 525   }
 526
 527   static void Profile(llvm::FoldingSetNodeID &ID, NestedNameSpecifier *NNS,
 528                       const IdentifierInfo *Identifier) {
 529     ID.AddPointer(NNS);
 530     ID.AddBoolean(false);
 531     ID.AddPointer(Identifier);
 532   }
 533
 534   static void Profile(llvm::FoldingSetNodeID &ID, NestedNameSpecifier *NNS,
 535                       OverloadedOperatorKind Operator) {
 536     ID.AddPointer(NNS);
 537     ID.AddBoolean(true);
 538     ID.AddInteger(Operator);
 539   }
 540 };
 541
 542 } // namespace clang.
 543
 544 namespace llvm {
 545
 546 /// The clang::TemplateName class is effectively a pointer.
 547 template<>
 548 struct PointerLikeTypeTraits<clang::TemplateName> {
 549   static inline void *getAsVoidPointer(clang::TemplateName TN) {
 550     return TN.getAsVoidPointer();
 551   }
 552
 553   static inline clang::TemplateName getFromVoidPointer(void *Ptr) {
 554     return clang::TemplateName::getFromVoidPointer(Ptr);
 555   }
 556
 557   // No bits are available!
 558   enum { NumLowBitsAvailable = 0 };
 559 };
 560
 561 } // namespace llvm.
 562
 563 #endif // LLVM_CLANG_AST_TEMPLATENAME_H