1 //===-- ConstString.h -------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_ConstString_h_
11 #define liblldb_ConstString_h_
13 #include "llvm/ADT/StringRef.h"
14 #include "llvm/Support/FormatVariadic.h" // for format_provider
16 #include <stddef.h> // for size_t
18 namespace lldb_private {
25 namespace lldb_private {
27 //----------------------------------------------------------------------
28 /// @class ConstString ConstString.h "lldb/Utility/ConstString.h"
29 /// @brief A uniqued constant string class.
31 /// Provides an efficient way to store strings as uniqued strings. After
32 /// the strings are uniqued, finding strings that are equal to one
33 /// another is very fast as just the pointers need to be compared. It
34 /// also allows for many common strings from many different sources to
35 /// be shared to keep the memory footprint low.
37 /// No reference counting is done on strings that are added to the
38 /// string pool, once strings are added they are in the string pool for
39 /// the life of the program.
40 //----------------------------------------------------------------------
43 //------------------------------------------------------------------
44 /// Default constructor
46 /// Initializes the string to an empty string.
47 //------------------------------------------------------------------
48 ConstString() : m_string(nullptr) {}
50 //------------------------------------------------------------------
53 /// Copies the string value in \a rhs into this object.
56 /// Another string object to copy.
57 //------------------------------------------------------------------
58 ConstString(const ConstString &rhs) : m_string(rhs.m_string) {}
60 explicit ConstString(const llvm::StringRef &s);
62 //------------------------------------------------------------------
63 /// Construct with C String value
65 /// Constructs this object with a C string by looking to see if the
66 /// C string already exists in the global string pool. If it doesn't
67 /// exist, it is added to the string pool.
70 /// A NULL terminated C string to add to the string pool.
71 //------------------------------------------------------------------
72 explicit ConstString(const char *cstr);
74 //------------------------------------------------------------------
75 /// Construct with C String value with max length
77 /// Constructs this object with a C string with a length. If
78 /// \a max_cstr_len is greater than the actual length of the string,
79 /// the string length will be truncated. This allows substrings to
80 /// be created without the need to NULL terminate the string as it
81 /// is passed into this function.
84 /// A pointer to the first character in the C string. The C
85 /// string can be NULL terminated in a buffer that contains
86 /// more characters than the length of the string, or the
87 /// string can be part of another string and a new substring
90 /// @param[in] max_cstr_len
91 /// The max length of \a cstr. If the string length of \a cstr
92 /// is less than \a max_cstr_len, then the string will be
93 /// truncated. If the string length of \a cstr is greater than
94 /// \a max_cstr_len, then only max_cstr_len bytes will be used
96 //------------------------------------------------------------------
97 explicit ConstString(const char *cstr, size_t max_cstr_len);
99 //------------------------------------------------------------------
102 /// Since constant string values are currently not reference counted,
103 /// there isn't much to do here.
104 //------------------------------------------------------------------
105 ~ConstString() = default;
107 //----------------------------------------------------------------------
108 /// C string equality binary predicate function object for ConstString
110 //----------------------------------------------------------------------
111 struct StringIsEqual {
112 //--------------------------------------------------------------
115 /// Two C strings are equal when they are contained in ConstString
116 /// objects when their pointer values are equal to each other.
119 /// Returns \b true if the C string in \a lhs is equal to
120 /// the C string value in \a rhs, \b false otherwise.
121 //--------------------------------------------------------------
122 bool operator()(const char *lhs, const char *rhs) const {
127 //------------------------------------------------------------------
128 /// Convert to bool operator.
130 /// This allows code to check a ConstString object to see if it
131 /// contains a valid string using code such as:
134 /// ConstString str(...);
140 /// /b True this object contains a valid non-empty C string, \b
142 //------------------------------------------------------------------
143 explicit operator bool() const { return m_string && m_string[0]; }
145 //------------------------------------------------------------------
146 /// Assignment operator
148 /// Assigns the string in this object with the value from \a rhs.
151 /// Another string object to copy into this object.
154 /// A const reference to this object.
155 //------------------------------------------------------------------
156 const ConstString &operator=(const ConstString &rhs) {
157 m_string = rhs.m_string;
161 //------------------------------------------------------------------
162 /// Equal to operator
164 /// Returns true if this string is equal to the string in \a rhs.
165 /// This operation is very fast as it results in a pointer
166 /// comparison since all strings are in a uniqued in a global string
170 /// Another string object to compare this object to.
173 /// @li \b true if this object is equal to \a rhs.
174 /// @li \b false if this object is not equal to \a rhs.
175 //------------------------------------------------------------------
176 bool operator==(const ConstString &rhs) const {
177 // We can do a pointer compare to compare these strings since they
178 // must come from the same pool in order to be equal.
179 return m_string == rhs.m_string;
182 //------------------------------------------------------------------
183 /// Not equal to operator
185 /// Returns true if this string is not equal to the string in \a rhs.
186 /// This operation is very fast as it results in a pointer
187 /// comparison since all strings are in a uniqued in a global string
191 /// Another string object to compare this object to.
194 /// @li \b true if this object is not equal to \a rhs.
195 /// @li \b false if this object is equal to \a rhs.
196 //------------------------------------------------------------------
197 bool operator!=(const ConstString &rhs) const {
198 return m_string != rhs.m_string;
201 bool operator<(const ConstString &rhs) const;
203 //------------------------------------------------------------------
204 /// Get the string value as a C string.
206 /// Get the value of the contained string as a NULL terminated C
209 /// If \a value_if_empty is nullptr, then nullptr will be returned.
212 /// Returns \a value_if_empty if the string is empty, otherwise
213 /// the C string value contained in this object.
214 //------------------------------------------------------------------
215 const char *AsCString(const char *value_if_empty = nullptr) const {
216 return (IsEmpty() ? value_if_empty : m_string);
219 //------------------------------------------------------------------
220 /// Get the string value as a llvm::StringRef
223 /// Returns a new llvm::StringRef object filled in with the
225 //------------------------------------------------------------------
226 llvm::StringRef GetStringRef() const {
227 return llvm::StringRef(m_string, GetLength());
230 //------------------------------------------------------------------
231 /// Get the string value as a C string.
233 /// Get the value of the contained string as a NULL terminated C
234 /// string value. Similar to the ConstString::AsCString() function,
235 /// yet this function will always return nullptr if the string is not
236 /// valid. So this function is a direct accessor to the string
240 /// Returns nullptr the string is invalid, otherwise the C string
241 /// value contained in this object.
242 //------------------------------------------------------------------
243 const char *GetCString() const { return m_string; }
245 //------------------------------------------------------------------
246 /// Get the length in bytes of string value.
248 /// The string pool stores the length of the string, so we can avoid
249 /// calling strlen() on the pointer value with this function.
252 /// Returns the number of bytes that this string occupies in
253 /// memory, not including the NULL termination byte.
254 //------------------------------------------------------------------
255 size_t GetLength() const;
257 //------------------------------------------------------------------
258 /// Clear this object's state.
260 /// Clear any contained string and reset the value to the an empty
262 //------------------------------------------------------------------
263 void Clear() { m_string = nullptr; }
265 //------------------------------------------------------------------
266 /// Equal to operator
268 /// Returns true if this string is equal to the string in \a rhs.
269 /// If case sensitive equality is tested, this operation is very
270 /// fast as it results in a pointer comparison since all strings
271 /// are in a uniqued in a global string pool.
274 /// The Left Hand Side const ConstString object reference.
277 /// The Right Hand Side const ConstString object reference.
279 /// @param[in] case_sensitive
280 /// Case sensitivity. If true, case sensitive equality
281 /// will be tested, otherwise character case will be ignored
284 /// @li \b true if this object is equal to \a rhs.
285 /// @li \b false if this object is not equal to \a rhs.
286 //------------------------------------------------------------------
287 static bool Equals(const ConstString &lhs, const ConstString &rhs,
288 const bool case_sensitive = true);
290 //------------------------------------------------------------------
291 /// Compare two string objects.
293 /// Compares the C string values contained in \a lhs and \a rhs and
294 /// returns an integer result.
296 /// NOTE: only call this function when you want a true string
297 /// comparison. If you want string equality use the, use the ==
298 /// operator as it is much more efficient. Also if you want string
299 /// inequality, use the != operator for the same reasons.
302 /// The Left Hand Side const ConstString object reference.
305 /// The Right Hand Side const ConstString object reference.
307 /// @param[in] case_sensitive
308 /// Case sensitivity of compare. If true, case sensitive compare
309 /// will be performed, otherwise character case will be ignored
312 /// @li -1 if lhs < rhs
313 /// @li 0 if lhs == rhs
314 /// @li 1 if lhs > rhs
315 //------------------------------------------------------------------
316 static int Compare(const ConstString &lhs, const ConstString &rhs,
317 const bool case_sensitive = true);
319 //------------------------------------------------------------------
320 /// Dump the object description to a stream.
322 /// Dump the string value to the stream \a s. If the contained string
323 /// is empty, print \a value_if_empty to the stream instead. If
324 /// \a value_if_empty is nullptr, then nothing will be dumped to the
328 /// The stream that will be used to dump the object description.
330 /// @param[in] value_if_empty
331 /// The value to dump if the string is empty. If nullptr, nothing
332 /// will be output to the stream.
333 //------------------------------------------------------------------
334 void Dump(Stream *s, const char *value_if_empty = nullptr) const;
336 //------------------------------------------------------------------
337 /// Dump the object debug description to a stream.
340 /// The stream that will be used to dump the object description.
341 //------------------------------------------------------------------
342 void DumpDebug(Stream *s) const;
344 //------------------------------------------------------------------
345 /// Test for empty string.
348 /// @li \b true if the contained string is empty.
349 /// @li \b false if the contained string is not empty.
350 //------------------------------------------------------------------
351 bool IsEmpty() const { return m_string == nullptr || m_string[0] == '\0'; }
353 //------------------------------------------------------------------
354 /// Set the C string value.
356 /// Set the string value in the object by uniquing the \a cstr
357 /// string value in our global string pool.
359 /// If the C string already exists in the global string pool, it
360 /// finds the current entry and returns the existing value. If it
361 /// doesn't exist, it is added to the string pool.
364 /// A NULL terminated C string to add to the string pool.
365 //------------------------------------------------------------------
366 void SetCString(const char *cstr);
368 void SetString(const llvm::StringRef &s);
370 //------------------------------------------------------------------
371 /// Set the C string value and its mangled counterpart.
373 /// Object files and debug symbols often use mangled string to
374 /// represent the linkage name for a symbol, function or global.
375 /// The string pool can efficiently store these values and their
376 /// counterparts so when we run into another instance of a mangled
377 /// name, we can avoid calling the name demangler over and over on
378 /// the same strings and then trying to unique them.
380 /// @param[in] demangled
381 /// The demangled C string to correlate with the \a mangled
384 /// @param[in] mangled
385 /// The already uniqued mangled ConstString to correlate the
386 /// soon to be uniqued version of \a demangled.
387 //------------------------------------------------------------------
388 void SetCStringWithMangledCounterpart(const char *demangled,
389 const ConstString &mangled);
391 //------------------------------------------------------------------
392 /// Retrieve the mangled or demangled counterpart for a mangled
393 /// or demangled ConstString.
395 /// Object files and debug symbols often use mangled string to
396 /// represent the linkage name for a symbol, function or global.
397 /// The string pool can efficiently store these values and their
398 /// counterparts so when we run into another instance of a mangled
399 /// name, we can avoid calling the name demangler over and over on
400 /// the same strings and then trying to unique them.
402 /// @param[in] counterpart
403 /// A reference to a ConstString object that might get filled in
404 /// with the demangled/mangled counterpart.
407 /// /b True if \a counterpart was filled in with the counterpart
408 /// /b false otherwise.
409 //------------------------------------------------------------------
410 bool GetMangledCounterpart(ConstString &counterpart) const;
412 //------------------------------------------------------------------
413 /// Set the C string value with length.
415 /// Set the string value in the object by uniquing \a cstr_len bytes
416 /// starting at the \a cstr string value in our global string pool.
417 /// If trim is true, then \a cstr_len indicates a maximum length of
418 /// the CString and if the actual length of the string is less, then
419 /// it will be trimmed.
421 /// If the C string already exists in the global string pool, it
422 /// finds the current entry and returns the existing value. If it
423 /// doesn't exist, it is added to the string pool.
426 /// A NULL terminated C string to add to the string pool.
428 /// @param[in] cstr_len
429 /// The maximum length of the C string.
430 //------------------------------------------------------------------
431 void SetCStringWithLength(const char *cstr, size_t cstr_len);
433 //------------------------------------------------------------------
434 /// Set the C string value with the minimum length between
435 /// \a fixed_cstr_len and the actual length of the C string. This
436 /// can be used for data structures that have a fixed length to
437 /// store a C string where the string might not be NULL terminated
438 /// if the string takes the entire buffer.
439 //------------------------------------------------------------------
440 void SetTrimmedCStringWithLength(const char *cstr, size_t fixed_cstr_len);
442 //------------------------------------------------------------------
443 /// Get the memory cost of this object.
445 /// Return the size in bytes that this object takes in memory. This
446 /// returns the size in bytes of this object, which does not include
447 /// any the shared string values it may refer to.
450 /// The number of bytes that this object occupies in memory.
452 /// @see ConstString::StaticMemorySize ()
453 //------------------------------------------------------------------
454 size_t MemorySize() const { return sizeof(ConstString); }
456 //------------------------------------------------------------------
457 /// Get the size in bytes of the current global string pool.
459 /// Reports the size in bytes of all shared C string values,
460 /// containers and any other values as a byte size for the
461 /// entire string pool.
464 /// The number of bytes that the global string pool occupies
466 //------------------------------------------------------------------
467 static size_t StaticMemorySize();
470 //------------------------------------------------------------------
472 //------------------------------------------------------------------
473 const char *m_string;
476 //------------------------------------------------------------------
477 /// Stream the string value \a str to the stream \a s
478 //------------------------------------------------------------------
479 Stream &operator<<(Stream &s, const ConstString &str);
481 } // namespace lldb_private
484 template <> struct format_provider<lldb_private::ConstString> {
485 static void format(const lldb_private::ConstString &CS, llvm::raw_ostream &OS,
486 llvm::StringRef Options);
490 #endif // liblldb_ConstString_h_