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