LLDB mainline
ConstString.h
Go to the documentation of this file.
1//===-- ConstString.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 LLDB_UTILITY_CONSTSTRING_H
10#define LLDB_UTILITY_CONSTSTRING_H
11
12#include "llvm/ADT/DenseMapInfo.h"
13#include "llvm/ADT/StringRef.h"
14#include "llvm/Support/FormatVariadic.h"
15
16#include <cstddef>
17#include <string_view>
18
19namespace lldb_private {
20class Stream;
21}
22namespace llvm {
23class raw_ostream;
24}
25
26namespace lldb_private {
27
28/// \class ConstString ConstString.h "lldb/Utility/ConstString.h"
29/// A uniqued constant string class.
30///
31/// Provides an efficient way to store strings as uniqued strings. After the
32/// strings are uniqued, finding strings that are equal to one another is very
33/// fast as just the pointers need to be compared. It also allows for many
34/// common strings from many different sources to be shared to keep the memory
35/// footprint low.
36///
37/// No reference counting is done on strings that are added to the string
38/// pool, once strings are added they are in the string pool for the life of
39/// the program.
41public:
42 /// Default constructor
43 ///
44 /// Initializes the string to an empty string.
45 ConstString() = default;
46
47 explicit ConstString(llvm::StringRef s);
48
49 /// Construct with C String value
50 ///
51 /// Constructs this object with a C string by looking to see if the
52 /// C string already exists in the global string pool. If it doesn't
53 /// exist, it is added to the string pool.
54 ///
55 /// \param[in] cstr
56 /// A NULL terminated C string to add to the string pool.
57 explicit ConstString(const char *cstr);
58
59 /// Construct with C String value with max length
60 ///
61 /// Constructs this object with a C string with a length. If \a max_cstr_len
62 /// is greater than the actual length of the string, the string length will
63 /// be truncated. This allows substrings to be created without the need to
64 /// NULL terminate the string as it is passed into this function.
65 ///
66 /// \param[in] cstr
67 /// A pointer to the first character in the C string. The C
68 /// string can be NULL terminated in a buffer that contains
69 /// more characters than the length of the string, or the
70 /// string can be part of another string and a new substring
71 /// can be created.
72 ///
73 /// \param[in] max_cstr_len
74 /// The max length of \a cstr. If the string length of \a cstr
75 /// is less than \a max_cstr_len, then the string will be
76 /// truncated. If the string length of \a cstr is greater than
77 /// \a max_cstr_len, then only max_cstr_len bytes will be used
78 /// from \a cstr.
79 explicit ConstString(const char *cstr, size_t max_cstr_len);
80
81 /// Convert to bool operator.
82 ///
83 /// This allows code to check a ConstString object to see if it contains a
84 /// valid string using code such as:
85 ///
86 /// \code
87 /// ConstString str(...);
88 /// if (str)
89 /// { ...
90 /// \endcode
91 ///
92 /// \return
93 /// /b True this object contains a valid non-empty C string, \b
94 /// false otherwise.
95 explicit operator bool() const { return !IsEmpty(); }
96
97 /// Equal to operator
98 ///
99 /// Returns true if this string is equal to the string in \a rhs. This
100 /// operation is very fast as it results in a pointer comparison since all
101 /// strings are in a uniqued in a global string pool.
102 ///
103 /// \param[in] rhs
104 /// Another string object to compare this object to.
105 ///
106 /// \return
107 /// true if this object is equal to \a rhs.
108 /// false if this object is not equal to \a rhs.
109 bool operator==(ConstString rhs) const {
110 // We can do a pointer compare to compare these strings since they must
111 // come from the same pool in order to be equal.
112 return m_string == rhs.m_string;
113 }
114
115 /// Equal to operator against a non-ConstString value.
116 ///
117 /// Returns true if this string is equal to the string in \a rhs. This
118 /// overload is usually slower than comparing against a ConstString value.
119 /// However, if the rhs string not already a ConstString and it is impractical
120 /// to turn it into a non-temporary variable, then this overload is faster.
121 ///
122 /// \param[in] rhs
123 /// Another string object to compare this object to.
124 ///
125 /// \return
126 /// \b true if this object is equal to \a rhs.
127 /// \b false if this object is not equal to \a rhs.
128 bool operator==(const char *rhs) const {
129 // ConstString differentiates between empty strings and nullptr strings, but
130 // StringRef doesn't. Therefore we have to do this check manually now.
131 if (m_string == nullptr && rhs != nullptr)
132 return false;
133 if (m_string != nullptr && rhs == nullptr)
134 return false;
135
136 return GetStringRef() == rhs;
137 }
138
139 /// Not equal to operator
140 ///
141 /// Returns true if this string is not equal to the string in \a rhs. This
142 /// operation is very fast as it results in a pointer comparison since all
143 /// strings are in a uniqued in a global string pool.
144 ///
145 /// \param[in] rhs
146 /// Another string object to compare this object to.
147 ///
148 /// \return
149 /// \b true if this object is not equal to \a rhs.
150 /// \b false if this object is equal to \a rhs.
151 bool operator!=(ConstString rhs) const { return m_string != rhs.m_string; }
152
153 /// Not equal to operator against a non-ConstString value.
154 ///
155 /// Returns true if this string is not equal to the string in \a rhs. This
156 /// overload is usually slower than comparing against a ConstString value.
157 /// However, if the rhs string not already a ConstString and it is impractical
158 /// to turn it into a non-temporary variable, then this overload is faster.
159 ///
160 /// \param[in] rhs
161 /// Another string object to compare this object to.
162 ///
163 /// \return \b true if this object is not equal to \a rhs, false otherwise.
164 bool operator!=(const char *rhs) const { return !(*this == rhs); }
165
166 bool operator<(ConstString rhs) const;
167
168 // Implicitly convert \class ConstString instances to \class StringRef.
169 operator llvm::StringRef() const { return GetStringRef(); }
170 // Implicitly convert \class ConstString instances to \calss std::string_view.
171 operator std::string_view() const { return std::string_view(m_string, GetLength()); }
172
173 /// Get the string value as a C string.
174 ///
175 /// Get the value of the contained string as a NULL terminated C string
176 /// value.
177 ///
178 /// If \a value_if_empty is nullptr, then nullptr will be returned.
179 ///
180 /// \return Returns \a value_if_empty if the string is empty, otherwise
181 /// the C string value contained in this object.
182 const char *AsCString(const char *value_if_empty = nullptr) const {
183 return (IsEmpty() ? value_if_empty : m_string);
184 }
185
186 /// Get the string value as a llvm::StringRef
187 ///
188 /// \return
189 /// Returns a new llvm::StringRef object filled in with the
190 /// needed data.
191 llvm::StringRef GetStringRef() const {
192 return llvm::StringRef(m_string, GetLength());
193 }
194
195 /// Get the string value as a C string.
196 ///
197 /// Get the value of the contained string as a NULL terminated C string
198 /// value. Similar to the ConstString::AsCString() function, yet this
199 /// function will always return nullptr if the string is not valid. So this
200 /// function is a direct accessor to the string pointer value.
201 ///
202 /// \return
203 /// Returns nullptr the string is invalid, otherwise the C string
204 /// value contained in this object.
205 const char *GetCString() const { return m_string; }
206
207 /// Get the length in bytes of string value.
208 ///
209 /// The string pool stores the length of the string, so we can avoid calling
210 /// strlen() on the pointer value with this function.
211 ///
212 /// \return
213 /// Returns the number of bytes that this string occupies in
214 /// memory, not including the NULL termination byte.
215 size_t GetLength() const;
216
217 /// Clear this object's state.
218 ///
219 /// Clear any contained string and reset the value to the empty string
220 /// value.
221 void Clear() { m_string = nullptr; }
222
223 /// Equal to operator
224 ///
225 /// Returns true if this string is equal to the string in \a rhs. If case
226 /// sensitive equality is tested, this operation is very fast as it results
227 /// in a pointer comparison since all strings are in a uniqued in a global
228 /// string pool.
229 ///
230 /// \param[in] lhs
231 /// The Left Hand Side const ConstString object reference.
232 ///
233 /// \param[in] rhs
234 /// The Right Hand Side const ConstString object reference.
235 ///
236 /// \param[in] case_sensitive
237 /// Case sensitivity. If true, case sensitive equality
238 /// will be tested, otherwise character case will be ignored
239 ///
240 /// \return \b true if this object is equal to \a rhs, \b false otherwise.
241 static bool Equals(ConstString lhs, ConstString rhs,
242 const bool case_sensitive = true);
243
244 /// Compare two string objects.
245 ///
246 /// Compares the C string values contained in \a lhs and \a rhs and returns
247 /// an integer result.
248 ///
249 /// NOTE: only call this function when you want a true string
250 /// comparison. If you want string equality use the, use the == operator as
251 /// it is much more efficient. Also if you want string inequality, use the
252 /// != operator for the same reasons.
253 ///
254 /// \param[in] lhs
255 /// The Left Hand Side const ConstString object reference.
256 ///
257 /// \param[in] rhs
258 /// The Right Hand Side const ConstString object reference.
259 ///
260 /// \param[in] case_sensitive
261 /// Case sensitivity of compare. If true, case sensitive compare
262 /// will be performed, otherwise character case will be ignored
263 ///
264 /// \return -1 if lhs < rhs, 0 if lhs == rhs, 1 if lhs > rhs
265 static int Compare(ConstString lhs, ConstString rhs,
266 const bool case_sensitive = true);
267
268 /// Dump the object description to a stream.
269 ///
270 /// Dump the string value to the stream \a s. If the contained string is
271 /// empty, print \a value_if_empty to the stream instead. If \a
272 /// value_if_empty is nullptr, then nothing will be dumped to the stream.
273 ///
274 /// \param[in] s
275 /// The stream that will be used to dump the object description.
276 ///
277 /// \param[in] value_if_empty
278 /// The value to dump if the string is empty. If nullptr, nothing
279 /// will be output to the stream.
280 void Dump(Stream *s, const char *value_if_empty = nullptr) const;
281
282 /// Dump the object debug description to a stream.
283 ///
284 /// \param[in] s
285 /// The stream that will be used to dump the object description.
286 void DumpDebug(Stream *s) const;
287
288 /// Test for empty string.
289 ///
290 /// \return
291 /// \b true if the contained string is empty.
292 /// \b false if the contained string is not empty.
293 bool IsEmpty() const { return m_string == nullptr || m_string[0] == '\0'; }
294
295 /// Test for null string.
296 ///
297 /// \return
298 /// \b true if there is no string associated with this instance.
299 /// \b false if there is a string associated with this instance.
300 bool IsNull() const { return m_string == nullptr; }
301
302 /// Set the C string value.
303 ///
304 /// Set the string value in the object by uniquing the \a cstr string value
305 /// in our global string pool.
306 ///
307 /// If the C string already exists in the global string pool, it finds the
308 /// current entry and returns the existing value. If it doesn't exist, it is
309 /// added to the string pool.
310 ///
311 /// \param[in] cstr
312 /// A NULL terminated C string to add to the string pool.
313 void SetCString(const char *cstr);
314
315 void SetString(llvm::StringRef s);
316
317 /// Set the C string value and its mangled counterpart.
318 ///
319 /// Object files and debug symbols often use mangled string to represent the
320 /// linkage name for a symbol, function or global. The string pool can
321 /// efficiently store these values and their counterparts so when we run
322 /// into another instance of a mangled name, we can avoid calling the name
323 /// demangler over and over on the same strings and then trying to unique
324 /// them.
325 ///
326 /// \param[in] demangled
327 /// The demangled string to correlate with the \a mangled name.
328 ///
329 /// \param[in] mangled
330 /// The already uniqued mangled ConstString to correlate the
331 /// soon to be uniqued version of \a demangled.
332 void SetStringWithMangledCounterpart(llvm::StringRef demangled,
333 ConstString mangled);
334
335 /// Retrieve the mangled or demangled counterpart for a mangled or demangled
336 /// ConstString.
337 ///
338 /// Object files and debug symbols often use mangled string to represent the
339 /// linkage name for a symbol, function or global. The string pool can
340 /// efficiently store these values and their counterparts so when we run
341 /// into another instance of a mangled name, we can avoid calling the name
342 /// demangler over and over on the same strings and then trying to unique
343 /// them.
344 ///
345 /// \param[in] counterpart
346 /// A reference to a ConstString object that might get filled in
347 /// with the demangled/mangled counterpart.
348 ///
349 /// \return
350 /// /b True if \a counterpart was filled in with the counterpart
351 /// /b false otherwise.
352 bool GetMangledCounterpart(ConstString &counterpart) const;
353
354 /// Set the C string value with length.
355 ///
356 /// Set the string value in the object by uniquing \a cstr_len bytes
357 /// starting at the \a cstr string value in our global string pool. If trim
358 /// is true, then \a cstr_len indicates a maximum length of the CString and
359 /// if the actual length of the string is less, then it will be trimmed.
360 ///
361 /// If the C string already exists in the global string pool, it finds the
362 /// current entry and returns the existing value. If it doesn't exist, it is
363 /// added to the string pool.
364 ///
365 /// \param[in] cstr
366 /// A NULL terminated C string to add to the string pool.
367 ///
368 /// \param[in] cstr_len
369 /// The maximum length of the C string.
370 void SetCStringWithLength(const char *cstr, size_t cstr_len);
371
372 /// Set the C string value with the minimum length between \a fixed_cstr_len
373 /// and the actual length of the C string. This can be used for data
374 /// structures that have a fixed length to store a C string where the string
375 /// might not be NULL terminated if the string takes the entire buffer.
376 void SetTrimmedCStringWithLength(const char *cstr, size_t fixed_cstr_len);
377
378 /// Get the memory cost of this object.
379 ///
380 /// Return the size in bytes that this object takes in memory. This returns
381 /// the size in bytes of this object, which does not include any the shared
382 /// string values it may refer to.
383 ///
384 /// \return
385 /// The number of bytes that this object occupies in memory.
386 size_t MemorySize() const { return sizeof(ConstString); }
387
388 struct MemoryStats {
389 size_t GetBytesTotal() const { return bytes_total; }
390 size_t GetBytesUsed() const { return bytes_used; }
391 size_t GetBytesUnused() const { return bytes_total - bytes_used; }
392 size_t bytes_total = 0;
393 size_t bytes_used = 0;
394 };
395
397
398protected:
399 template <typename T, typename Enable> friend struct ::llvm::DenseMapInfo;
400 /// Only used by DenseMapInfo.
401 static ConstString FromStringPoolPointer(const char *ptr) {
402 ConstString s;
403 s.m_string = ptr;
404 return s;
405 };
406
407 const char *m_string = nullptr;
408};
409
410/// Stream the string value \a str to the stream \a s
412
413} // namespace lldb_private
414
415namespace llvm {
416template <> struct format_provider<lldb_private::ConstString> {
417 static void format(const lldb_private::ConstString &CS, llvm::raw_ostream &OS,
418 llvm::StringRef Options);
419};
420
421/// DenseMapInfo implementation.
422/// \{
423template <> struct DenseMapInfo<lldb_private::ConstString> {
426 DenseMapInfo<const char *>::getEmptyKey());
427 }
430 DenseMapInfo<const char *>::getTombstoneKey());
431 }
433 return DenseMapInfo<const char *>::getHashValue(val.m_string);
434 }
437 return LHS == RHS;
438 }
439};
440/// \}
441
442inline raw_ostream &operator<<(raw_ostream &os, lldb_private::ConstString s) {
443 os << s.GetStringRef();
444 return os;
445}
446} // namespace llvm
447
448#endif // LLDB_UTILITY_CONSTSTRING_H
A uniqued constant string class.
Definition: ConstString.h:40
bool GetMangledCounterpart(ConstString &counterpart) const
Retrieve the mangled or demangled counterpart for a mangled or demangled ConstString.
size_t MemorySize() const
Get the memory cost of this object.
Definition: ConstString.h:386
static MemoryStats GetMemoryStats()
bool IsNull() const
Test for null string.
Definition: ConstString.h:300
void SetCStringWithLength(const char *cstr, size_t cstr_len)
Set the C string value with length.
void SetCString(const char *cstr)
Set the C string value.
static int Compare(ConstString lhs, ConstString rhs, const bool case_sensitive=true)
Compare two string objects.
ConstString()=default
Default constructor.
const char * AsCString(const char *value_if_empty=nullptr) const
Get the string value as a C string.
Definition: ConstString.h:182
void Dump(Stream *s, const char *value_if_empty=nullptr) const
Dump the object description to a stream.
void DumpDebug(Stream *s) const
Dump the object debug description to a stream.
bool IsEmpty() const
Test for empty string.
Definition: ConstString.h:293
void SetTrimmedCStringWithLength(const char *cstr, size_t fixed_cstr_len)
Set the C string value with the minimum length between fixed_cstr_len and the actual length of the C ...
bool operator==(const char *rhs) const
Equal to operator against a non-ConstString value.
Definition: ConstString.h:128
bool operator==(ConstString rhs) const
Equal to operator.
Definition: ConstString.h:109
size_t GetLength() const
Get the length in bytes of string value.
llvm::StringRef GetStringRef() const
Get the string value as a llvm::StringRef.
Definition: ConstString.h:191
void SetString(llvm::StringRef s)
void Clear()
Clear this object's state.
Definition: ConstString.h:221
bool operator!=(ConstString rhs) const
Not equal to operator.
Definition: ConstString.h:151
bool operator<(ConstString rhs) const
static ConstString FromStringPoolPointer(const char *ptr)
Only used by DenseMapInfo.
Definition: ConstString.h:401
const char * GetCString() const
Get the string value as a C string.
Definition: ConstString.h:205
bool operator!=(const char *rhs) const
Not equal to operator against a non-ConstString value.
Definition: ConstString.h:164
void SetStringWithMangledCounterpart(llvm::StringRef demangled, ConstString mangled)
Set the C string value and its mangled counterpart.
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
A class that represents a running process on the host machine.
Definition: SBAttachInfo.h:14
Stream & operator<<(Stream &s, const Mangled &obj)
Definition: Debugger.h:53
raw_ostream & operator<<(raw_ostream &os, lldb_private::ConstString s)
Definition: ConstString.h:442
static lldb_private::ConstString getEmptyKey()
Definition: ConstString.h:424
static unsigned getHashValue(lldb_private::ConstString val)
Definition: ConstString.h:432
static lldb_private::ConstString getTombstoneKey()
Definition: ConstString.h:428
static bool isEqual(lldb_private::ConstString LHS, lldb_private::ConstString RHS)
Definition: ConstString.h:435
static void format(const lldb_private::ConstString &CS, llvm::raw_ostream &OS, llvm::StringRef Options)