include/clang/AST/TemplateName.h

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