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