LLDB  mainline
Mangled.h
Go to the documentation of this file.
1 //===-- Mangled.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 liblldb_Mangled_h_
10 #define liblldb_Mangled_h_
11 #if defined(__cplusplus)
12 
13 #include "lldb/lldb-enumerations.h"
14 #include "lldb/lldb-forward.h"
15 
17 
18 #include "llvm/ADT/StringRef.h"
19 
20 #include <memory>
21 #include <stddef.h>
22 
23 namespace lldb_private {
24 
25 /// \class Mangled Mangled.h "lldb/Core/Mangled.h"
26 /// A class that handles mangled names.
27 ///
28 /// Designed to handle mangled names. The demangled version of any names will
29 /// be computed when the demangled name is accessed through the Demangled()
30 /// acccessor. This class can also tokenize the demangled version of the name
31 /// for powerful searches. Functions and symbols could make instances of this
32 /// class for their mangled names. Uniqued string pools are used for the
33 /// mangled, demangled, and token string values to allow for faster
34 /// comparisons and for efficient memory use.
35 class Mangled {
36 public:
37  enum NamePreference {
38  ePreferMangled,
39  ePreferDemangled,
40  ePreferDemangledWithoutArguments
41  };
42 
43  enum ManglingScheme {
44  eManglingSchemeNone = 0,
45  eManglingSchemeMSVC,
46  eManglingSchemeItanium
47  };
48 
49  /// Default constructor.
50  ///
51  /// Initialize with both mangled and demangled names empty.
52  Mangled();
53 
54  /// Construct with name.
55  ///
56  /// Constructor with an optional string and a boolean indicating if it is
57  /// the mangled version.
58  ///
59  /// \param[in] name
60  /// The already const name to copy into this object.
61  ///
62  /// \param[in] is_mangled
63  /// If \b true then \a name is a mangled name, if \b false then
64  /// \a name is demangled.
65  Mangled(ConstString name, bool is_mangled);
66  Mangled(llvm::StringRef name, bool is_mangled);
67 
68  /// Construct with name.
69  ///
70  /// Constructor with an optional string and auto-detect if \a name is
71  /// mangled or not.
72  ///
73  /// \param[in] name
74  /// The already const name to copy into this object.
75  explicit Mangled(ConstString name);
76 
77  explicit Mangled(llvm::StringRef name);
78 
79  /// Destructor
80  ///
81  /// Releases its ref counts on the mangled and demangled strings that live
82  /// in the global string pool.
83  ~Mangled();
84 
85  /// Convert to pointer operator.
86  ///
87  /// This allows code to check a Mangled object to see if it contains a valid
88  /// mangled name using code such as:
89  ///
90  /// \code
91  /// Mangled mangled(...);
92  /// if (mangled)
93  /// { ...
94  /// \endcode
95  ///
96  /// \return
97  /// A pointer to this object if either the mangled or unmangled
98  /// name is set, NULL otherwise.
99  operator void *() const;
100 
101  /// Logical NOT operator.
102  ///
103  /// This allows code to check a Mangled object to see if it contains an
104  /// empty mangled name using code such as:
105  ///
106  /// \code
107  /// Mangled mangled(...);
108  /// if (!mangled)
109  /// { ...
110  /// \endcode
111  ///
112  /// \return
113  /// Returns \b true if the object has an empty mangled and
114  /// unmangled name, \b false otherwise.
115  bool operator!() const;
116 
117  /// Clear the mangled and demangled values.
118  void Clear();
119 
120  /// Compare the mangled string values
121  ///
122  /// Compares the Mangled::GetName() string in \a lhs and \a rhs.
123  ///
124  /// \param[in] lhs
125  /// A const reference to the Left Hand Side object to compare.
126  ///
127  /// \param[in] rhs
128  /// A const reference to the Right Hand Side object to compare.
129  ///
130  /// \return
131  /// \li -1 if \a lhs is less than \a rhs
132  /// \li 0 if \a lhs is equal to \a rhs
133  /// \li 1 if \a lhs is greater than \a rhs
134  static int Compare(const Mangled &lhs, const Mangled &rhs);
135 
136  /// Dump a description of this object to a Stream \a s.
137  ///
138  /// Dump a Mangled object to stream \a s. We don't force our demangled name
139  /// to be computed currently (we don't use the accessor).
140  ///
141  /// \param[in] s
142  /// The stream to which to dump the object description.
143  void Dump(Stream *s) const;
144 
145  /// Dump a debug description of this object to a Stream \a s.
146  ///
147  /// \param[in] s
148  /// The stream to which to dump the object description.
149  void DumpDebug(Stream *s) const;
150 
151  /// Demangled name get accessor.
152  ///
153  /// \return
154  /// A const reference to the demangled name string object.
155  ConstString GetDemangledName(lldb::LanguageType language) const;
156 
157  /// Display demangled name get accessor.
158  ///
159  /// \return
160  /// A const reference to the display demangled name string object.
161  ConstString GetDisplayDemangledName(lldb::LanguageType language) const;
162 
163  void SetDemangledName(ConstString name) { m_demangled = name; }
164 
165  void SetMangledName(ConstString name) { m_mangled = name; }
166 
167  /// Mangled name get accessor.
168  ///
169  /// \return
170  /// A reference to the mangled name string object.
171  ConstString &GetMangledName() { return m_mangled; }
172 
173  /// Mangled name get accessor.
174  ///
175  /// \return
176  /// A const reference to the mangled name string object.
177  ConstString GetMangledName() const { return m_mangled; }
178 
179  /// Best name get accessor.
180  ///
181  /// \param[in] preference
182  /// Which name would you prefer to get?
183  ///
184  /// \return
185  /// A const reference to the preferred name string object if this
186  /// object has a valid name of that kind, else a const reference to the
187  /// other name is returned.
188  ConstString GetName(lldb::LanguageType language,
189  NamePreference preference = ePreferDemangled) const;
190 
191  /// Check if "name" matches either the mangled or demangled name.
192  ///
193  /// \param[in] name
194  /// A name to match against both strings.
195  ///
196  /// \return
197  /// \b True if \a name matches either name, \b false otherwise.
198  bool NameMatches(ConstString name, lldb::LanguageType language) const {
199  if (m_mangled == name)
200  return true;
201  return GetDemangledName(language) == name;
202  }
203  bool NameMatches(const RegularExpression &regex,
204  lldb::LanguageType language) const;
205 
206  /// Get the memory cost of this object.
207  ///
208  /// Return the size in bytes that this object takes in memory. This returns
209  /// the size in bytes of this object, not any shared string values it may
210  /// refer to.
211  ///
212  /// \return
213  /// The number of bytes that this object occupies in memory.
214  ///
215  /// \see ConstString::StaticMemorySize ()
216  size_t MemorySize() const;
217 
218  /// Set the string value in this object.
219  ///
220  /// If \a is_mangled is \b true, then the mangled named is set to \a name,
221  /// else the demangled name is set to \a name.
222  ///
223  /// \param[in] name
224  /// The already const version of the name for this object.
225  ///
226  /// \param[in] is_mangled
227  /// If \b true then \a name is a mangled name, if \b false then
228  /// \a name is demangled.
229  void SetValue(ConstString name, bool is_mangled);
230 
231  /// Set the string value in this object.
232  ///
233  /// This version auto detects if the string is mangled by inspecting the
234  /// string value and looking for common mangling prefixes.
235  ///
236  /// \param[in] name
237  /// The already const version of the name for this object.
238  void SetValue(ConstString name);
239 
240  /// Try to guess the language from the mangling.
241  ///
242  /// For a mangled name to have a language it must have both a mangled and a
243  /// demangled name and it can be guessed from the mangling what the language
244  /// is. Note: this will return C++ for any language that uses Itanium ABI
245  /// mangling.
246  ///
247  /// Standard C function names will return eLanguageTypeUnknown because they
248  /// aren't mangled and it isn't clear what language the name represents
249  /// (there will be no mangled name).
250  ///
251  /// \return
252  /// The language for the mangled/demangled name, eLanguageTypeUnknown
253  /// if there is no mangled or demangled counterpart.
254  lldb::LanguageType GuessLanguage() const;
255 
256  /// Function signature for filtering mangled names.
257  using SkipMangledNameFn = bool(llvm::StringRef, ManglingScheme);
258 
259  /// Trigger explicit demangling to obtain rich mangling information. This is
260  /// optimized for batch processing while populating a name index. To get the
261  /// pure demangled name string for a single entity, use GetDemangledName()
262  /// instead.
263  ///
264  /// For names that match the Itanium mangling scheme, this uses LLVM's
265  /// ItaniumPartialDemangler. All other names fall back to LLDB's builtin
266  /// parser currently.
267  ///
268  /// This function is thread-safe when used with different \a context
269  /// instances in different threads.
270  ///
271  /// \param[in] context
272  /// The context for this function. A single instance can be stack-
273  /// allocated in the caller's frame and used for multiple calls.
274  ///
275  /// \param[in] skip_mangled_name
276  /// A filtering function for skipping entities based on name and mangling
277  /// scheme. This can be null if unused.
278  ///
279  /// \return
280  /// True on success, false otherwise.
281  bool DemangleWithRichManglingInfo(RichManglingContext &context,
282  SkipMangledNameFn *skip_mangled_name);
283 
284 private:
285  /// Mangled member variables.
286  ConstString m_mangled; ///< The mangled version of the name
287  mutable ConstString m_demangled; ///< Mutable so we can get it on demand with
288  ///a const version of this object
289 };
290 
291 Stream &operator<<(Stream &s, const Mangled &obj);
292 
293 } // namespace lldb_private
294 
295 #endif // #if defined(__cplusplus)
296 #endif // liblldb_Mangled_h_
bool NameMatches(llvm::StringRef name, NameMatch match_type, llvm::StringRef match)
Definition: NameMatches.cpp:15
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
LanguageType
Programming language type.
static bool Compare(BreakpointLocationSP lhs, lldb::break_id_t val)
Stream & operator<<(Stream &s, ConstString str)
Stream the string value str to the stream s.