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 19 namespace lldb_private { 20 class Stream; 21 } 22 namespace llvm { 23 class raw_ostream; 24 } 25 26 namespace 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. 40 class ConstString { 41 public: 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. StringRef()169 operator llvm::StringRef() const { return GetStringRef(); } 170 // Implicitly convert \class ConstString instances to \calss std::string_view. 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. GetStringRef()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. GetCString()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. Clear()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. IsEmpty()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. IsNull()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. MemorySize()386 size_t MemorySize() const { return sizeof(ConstString); } 387 388 struct MemoryStats { GetBytesTotalMemoryStats389 size_t GetBytesTotal() const { return bytes_total; } GetBytesUsedMemoryStats390 size_t GetBytesUsed() const { return bytes_used; } GetBytesUnusedMemoryStats391 size_t GetBytesUnused() const { return bytes_total - bytes_used; } 392 size_t bytes_total = 0; 393 size_t bytes_used = 0; 394 }; 395 396 static MemoryStats GetMemoryStats(); 397 398 protected: 399 template <typename T, typename Enable> friend struct ::llvm::DenseMapInfo; 400 /// Only used by DenseMapInfo. FromStringPoolPointer(const char * ptr)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 411 Stream &operator<<(Stream &s, ConstString str); 412 413 } // namespace lldb_private 414 415 namespace llvm { 416 template <> 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 /// \{ 423 template <> struct DenseMapInfo<lldb_private::ConstString> { 424 static inline lldb_private::ConstString getEmptyKey() { 425 return lldb_private::ConstString::FromStringPoolPointer( 426 DenseMapInfo<const char *>::getEmptyKey()); 427 } 428 static inline lldb_private::ConstString getTombstoneKey() { 429 return lldb_private::ConstString::FromStringPoolPointer( 430 DenseMapInfo<const char *>::getTombstoneKey()); 431 } 432 static unsigned getHashValue(lldb_private::ConstString val) { 433 return DenseMapInfo<const char *>::getHashValue(val.m_string); 434 } 435 static bool isEqual(lldb_private::ConstString LHS, 436 lldb_private::ConstString RHS) { 437 return LHS == RHS; 438 } 439 }; 440 /// \} 441 442 inline 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 449