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 /// A uniqued constant string class.
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
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
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 \a max_cstr_len
78 /// is greater than the actual length of the string, the string length will
79 /// be truncated. This allows substrings to be created without the need to
80 /// NULL terminate the string as it is passed into this function.
83 /// A pointer to the first character in the C string. The C
84 /// string can be NULL terminated in a buffer that contains
85 /// more characters than the length of the string, or the
86 /// string can be part of another string and a new substring
89 /// @param[in] max_cstr_len
90 /// The max length of \a cstr. If the string length of \a cstr
91 /// is less than \a max_cstr_len, then the string will be
92 /// truncated. If the string length of \a cstr is greater than
93 /// \a max_cstr_len, then only max_cstr_len bytes will be used
95 //------------------------------------------------------------------
96 explicit ConstString(const char *cstr, size_t max_cstr_len);
98 //------------------------------------------------------------------
101 /// Since constant string values are currently not reference counted, there
102 /// isn't much to do here.
103 //------------------------------------------------------------------
104 ~ConstString() = default;
106 //----------------------------------------------------------------------
107 /// C string equality binary predicate function object for ConstString
109 //----------------------------------------------------------------------
110 struct StringIsEqual {
111 //--------------------------------------------------------------
114 /// Two C strings are equal when they are contained in ConstString objects
115 /// when their pointer values are equal to each other.
118 /// Returns \b true if the C string in \a lhs is equal to
119 /// the C string value in \a rhs, \b false otherwise.
120 //--------------------------------------------------------------
121 bool operator()(const char *lhs, const char *rhs) const {
126 //------------------------------------------------------------------
127 /// Convert to bool operator.
129 /// This allows code to check a ConstString object to see if it contains a
130 /// valid string using code such as:
133 /// ConstString str(...);
139 /// /b True this object contains a valid non-empty C string, \b
141 //------------------------------------------------------------------
142 explicit operator bool() const { return !IsEmpty(); }
144 //------------------------------------------------------------------
145 /// Assignment operator
147 /// Assigns the string in this object with the value from \a rhs.
150 /// Another string object to copy into this object.
153 /// A const reference to this object.
154 //------------------------------------------------------------------
155 const ConstString &operator=(const ConstString &rhs) {
156 m_string = rhs.m_string;
160 //------------------------------------------------------------------
161 /// Equal to operator
163 /// Returns true if this string is equal to the string in \a rhs. This
164 /// operation is very fast as it results in a pointer comparison since all
165 /// strings are in a uniqued in a global string pool.
168 /// Another string object to compare this object to.
171 /// @li \b true if this object is equal to \a rhs.
172 /// @li \b false if this object is not equal to \a rhs.
173 //------------------------------------------------------------------
174 bool operator==(const ConstString &rhs) const {
175 // We can do a pointer compare to compare these strings since they must
176 // come from the same pool in order to be equal.
177 return m_string == rhs.m_string;
180 //------------------------------------------------------------------
181 /// Not equal to operator
183 /// Returns true if this string is not equal to the string in \a rhs. This
184 /// operation is very fast as it results in a pointer comparison since all
185 /// strings are in a uniqued in a global string pool.
188 /// Another string object to compare this object to.
191 /// @li \b true if this object is not equal to \a rhs.
192 /// @li \b false if this object is equal to \a rhs.
193 //------------------------------------------------------------------
194 bool operator!=(const ConstString &rhs) const {
195 return m_string != rhs.m_string;
198 bool operator<(const ConstString &rhs) const;
200 //------------------------------------------------------------------
201 /// Get the string value as a C string.
203 /// Get the value of the contained string as a NULL terminated C string
206 /// If \a value_if_empty is nullptr, then nullptr will be returned.
209 /// Returns \a value_if_empty if the string is empty, otherwise
210 /// the C string value contained in this object.
211 //------------------------------------------------------------------
212 const char *AsCString(const char *value_if_empty = nullptr) const {
213 return (IsEmpty() ? value_if_empty : m_string);
216 //------------------------------------------------------------------
217 /// Get the string value as a llvm::StringRef
220 /// Returns a new llvm::StringRef object filled in with the
222 //------------------------------------------------------------------
223 llvm::StringRef GetStringRef() const {
224 return llvm::StringRef(m_string, GetLength());
227 //------------------------------------------------------------------
228 /// Get the string value as a C string.
230 /// Get the value of the contained string as a NULL terminated C string
231 /// value. Similar to the ConstString::AsCString() function, yet this
232 /// function will always return nullptr if the string is not valid. So this
233 /// function is a direct accessor to the string pointer value.
236 /// Returns nullptr the string is invalid, otherwise the C string
237 /// value contained in this object.
238 //------------------------------------------------------------------
239 const char *GetCString() const { return m_string; }
241 //------------------------------------------------------------------
242 /// Get the length in bytes of string value.
244 /// The string pool stores the length of the string, so we can avoid calling
245 /// strlen() on the pointer value with this function.
248 /// Returns the number of bytes that this string occupies in
249 /// memory, not including the NULL termination byte.
250 //------------------------------------------------------------------
251 size_t GetLength() const;
253 //------------------------------------------------------------------
254 /// Clear this object's state.
256 /// Clear any contained string and reset the value to the an empty string
258 //------------------------------------------------------------------
259 void Clear() { m_string = nullptr; }
261 //------------------------------------------------------------------
262 /// Equal to operator
264 /// Returns true if this string is equal to the string in \a rhs. If case
265 /// sensitive equality is tested, this operation is very fast as it results
266 /// in a pointer comparison since all strings are in a uniqued in a global
270 /// The Left Hand Side const ConstString object reference.
273 /// The Right Hand Side const ConstString object reference.
275 /// @param[in] case_sensitive
276 /// Case sensitivity. If true, case sensitive equality
277 /// will be tested, otherwise character case will be ignored
280 /// @li \b true if this object is equal to \a rhs.
281 /// @li \b false if this object is not equal to \a rhs.
282 //------------------------------------------------------------------
283 static bool Equals(const ConstString &lhs, const ConstString &rhs,
284 const bool case_sensitive = true);
286 //------------------------------------------------------------------
287 /// Compare two string objects.
289 /// Compares the C string values contained in \a lhs and \a rhs and returns
290 /// an integer result.
292 /// NOTE: only call this function when you want a true string
293 /// comparison. If you want string equality use the, use the == operator as
294 /// it is much more efficient. Also if you want string inequality, use the
295 /// != operator for the same reasons.
298 /// The Left Hand Side const ConstString object reference.
301 /// The Right Hand Side const ConstString object reference.
303 /// @param[in] case_sensitive
304 /// Case sensitivity of compare. If true, case sensitive compare
305 /// will be performed, otherwise character case will be ignored
308 /// @li -1 if lhs < rhs
309 /// @li 0 if lhs == rhs
310 /// @li 1 if lhs > rhs
311 //------------------------------------------------------------------
312 static int Compare(const ConstString &lhs, const ConstString &rhs,
313 const bool case_sensitive = true);
315 //------------------------------------------------------------------
316 /// Dump the object description to a stream.
318 /// Dump the string value to the stream \a s. If the contained string is
319 /// empty, print \a value_if_empty to the stream instead. If \a
320 /// value_if_empty is nullptr, then nothing will be dumped to the stream.
323 /// The stream that will be used to dump the object description.
325 /// @param[in] value_if_empty
326 /// The value to dump if the string is empty. If nullptr, nothing
327 /// will be output to the stream.
328 //------------------------------------------------------------------
329 void Dump(Stream *s, const char *value_if_empty = nullptr) const;
331 //------------------------------------------------------------------
332 /// Dump the object debug description to a stream.
335 /// The stream that will be used to dump the object description.
336 //------------------------------------------------------------------
337 void DumpDebug(Stream *s) const;
339 //------------------------------------------------------------------
340 /// Test for empty string.
343 /// @li \b true if the contained string is empty.
344 /// @li \b false if the contained string is not empty.
345 //------------------------------------------------------------------
346 bool IsEmpty() const { return m_string == nullptr || m_string[0] == '\0'; }
348 //------------------------------------------------------------------
349 /// Set the C string value.
351 /// Set the string value in the object by uniquing the \a cstr string value
352 /// in our global string pool.
354 /// If the C string already exists in the global string pool, it finds the
355 /// current entry and returns the existing value. If it doesn't exist, it is
356 /// added to the string pool.
359 /// A NULL terminated C string to add to the string pool.
360 //------------------------------------------------------------------
361 void SetCString(const char *cstr);
363 void SetString(const llvm::StringRef &s);
365 //------------------------------------------------------------------
366 /// Set the C string value and its mangled counterpart.
368 /// Object files and debug symbols often use mangled string to represent the
369 /// linkage name for a symbol, function or global. The string pool can
370 /// efficiently store these values and their counterparts so when we run
371 /// into another instance of a mangled name, we can avoid calling the name
372 /// demangler over and over on the same strings and then trying to unique
375 /// @param[in] demangled
376 /// The demangled C string to correlate with the \a mangled
379 /// @param[in] mangled
380 /// The already uniqued mangled ConstString to correlate the
381 /// soon to be uniqued version of \a demangled.
382 //------------------------------------------------------------------
383 void SetCStringWithMangledCounterpart(const char *demangled,
384 const ConstString &mangled);
386 //------------------------------------------------------------------
387 /// Retrieve the mangled or demangled counterpart for a mangled or demangled
390 /// Object files and debug symbols often use mangled string to represent the
391 /// linkage name for a symbol, function or global. The string pool can
392 /// efficiently store these values and their counterparts so when we run
393 /// into another instance of a mangled name, we can avoid calling the name
394 /// demangler over and over on the same strings and then trying to unique
397 /// @param[in] counterpart
398 /// A reference to a ConstString object that might get filled in
399 /// with the demangled/mangled counterpart.
402 /// /b True if \a counterpart was filled in with the counterpart
403 /// /b false otherwise.
404 //------------------------------------------------------------------
405 bool GetMangledCounterpart(ConstString &counterpart) const;
407 //------------------------------------------------------------------
408 /// Set the C string value with length.
410 /// Set the string value in the object by uniquing \a cstr_len bytes
411 /// starting at the \a cstr string value in our global string pool. If trim
412 /// is true, then \a cstr_len indicates a maximum length of the CString and
413 /// if the actual length of the string is less, then it will be trimmed.
415 /// If the C string already exists in the global string pool, it finds the
416 /// current entry and returns the existing value. If it doesn't exist, it is
417 /// added to the string pool.
420 /// A NULL terminated C string to add to the string pool.
422 /// @param[in] cstr_len
423 /// The maximum length of the C string.
424 //------------------------------------------------------------------
425 void SetCStringWithLength(const char *cstr, size_t cstr_len);
427 //------------------------------------------------------------------
428 /// Set the C string value with the minimum length between \a fixed_cstr_len
429 /// and the actual length of the C string. This can be used for data
430 /// structures that have a fixed length to store a C string where the string
431 /// might not be NULL terminated if the string takes the entire buffer.
432 //------------------------------------------------------------------
433 void SetTrimmedCStringWithLength(const char *cstr, size_t fixed_cstr_len);
435 //------------------------------------------------------------------
436 /// Get the memory cost of this object.
438 /// Return the size in bytes that this object takes in memory. This returns
439 /// the size in bytes of this object, which does not include any the shared
440 /// string values it may refer to.
443 /// The number of bytes that this object occupies in memory.
445 /// @see ConstString::StaticMemorySize ()
446 //------------------------------------------------------------------
447 size_t MemorySize() const { return sizeof(ConstString); }
449 //------------------------------------------------------------------
450 /// Get the size in bytes of the current global string pool.
452 /// Reports the size in bytes of all shared C string values, containers and
453 /// any other values as a byte size for the entire string pool.
456 /// The number of bytes that the global string pool occupies
458 //------------------------------------------------------------------
459 static size_t StaticMemorySize();
462 //------------------------------------------------------------------
464 //------------------------------------------------------------------
465 const char *m_string;
468 //------------------------------------------------------------------
469 /// Stream the string value \a str to the stream \a s
470 //------------------------------------------------------------------
471 Stream &operator<<(Stream &s, const ConstString &str);
473 } // namespace lldb_private
476 template <> struct format_provider<lldb_private::ConstString> {
477 static void format(const lldb_private::ConstString &CS, llvm::raw_ostream &OS,
478 llvm::StringRef Options);
482 #endif // liblldb_ConstString_h_