ConstString.h revision 317032
1//===-- ConstString.h -------------------------------------------*- C++ -*-===// 2// 3// The LLVM Compiler Infrastructure 4// 5// This file is distributed under the University of Illinois Open Source 6// License. See LICENSE.TXT for details. 7// 8//===----------------------------------------------------------------------===// 9 10#ifndef liblldb_ConstString_h_ 11#define liblldb_ConstString_h_ 12 13#include "llvm/ADT/StringRef.h" 14#include "llvm/Support/FormatVariadic.h" // for format_provider 15 16#include <stddef.h> // for size_t 17 18namespace lldb_private { 19class Stream; 20} 21namespace llvm { 22class raw_ostream; 23} 24 25namespace lldb_private { 26 27//---------------------------------------------------------------------- 28/// @class ConstString ConstString.h "lldb/Utility/ConstString.h" 29/// @brief A uniqued constant string class. 30/// 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. 36/// 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//---------------------------------------------------------------------- 41class ConstString { 42public: 43 //------------------------------------------------------------------ 44 /// Default constructor 45 /// 46 /// Initializes the string to an empty string. 47 //------------------------------------------------------------------ 48 ConstString() : m_string(nullptr) {} 49 50 //------------------------------------------------------------------ 51 /// Copy constructor 52 /// 53 /// Copies the string value in \a rhs into this object. 54 /// 55 /// @param[in] rhs 56 /// Another string object to copy. 57 //------------------------------------------------------------------ 58 ConstString(const ConstString &rhs) : m_string(rhs.m_string) {} 59 60 explicit ConstString(const llvm::StringRef &s); 61 62 //------------------------------------------------------------------ 63 /// Construct with C String value 64 /// 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. 68 /// 69 /// @param[in] cstr 70 /// A NULL terminated C string to add to the string pool. 71 //------------------------------------------------------------------ 72 explicit ConstString(const char *cstr); 73 74 //------------------------------------------------------------------ 75 /// Construct with C String value with max length 76 /// 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. 82 /// 83 /// @param[in] cstr 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 88 /// can be created. 89 /// 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 95 /// from \a cstr. 96 //------------------------------------------------------------------ 97 explicit ConstString(const char *cstr, size_t max_cstr_len); 98 99 //------------------------------------------------------------------ 100 /// Destructor 101 /// 102 /// Since constant string values are currently not reference counted, 103 /// there isn't much to do here. 104 //------------------------------------------------------------------ 105 ~ConstString() = default; 106 107 //---------------------------------------------------------------------- 108 /// C string equality binary predicate function object for ConstString 109 /// objects. 110 //---------------------------------------------------------------------- 111 struct StringIsEqual { 112 //-------------------------------------------------------------- 113 /// C equality test. 114 /// 115 /// Two C strings are equal when they are contained in ConstString 116 /// objects when their pointer values are equal to each other. 117 /// 118 /// @return 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 { 123 return lhs == rhs; 124 } 125 }; 126 127 //------------------------------------------------------------------ 128 /// Convert to bool operator. 129 /// 130 /// This allows code to check a ConstString object to see if it 131 /// contains a valid string using code such as: 132 /// 133 /// @code 134 /// ConstString str(...); 135 /// if (str) 136 /// { ... 137 /// @endcode 138 /// 139 /// @return 140 /// /b True this object contains a valid non-empty C string, \b 141 /// false otherwise. 142 //------------------------------------------------------------------ 143 explicit operator bool() const { return m_string && m_string[0]; } 144 145 //------------------------------------------------------------------ 146 /// Assignment operator 147 /// 148 /// Assigns the string in this object with the value from \a rhs. 149 /// 150 /// @param[in] rhs 151 /// Another string object to copy into this object. 152 /// 153 /// @return 154 /// A const reference to this object. 155 //------------------------------------------------------------------ 156 const ConstString &operator=(const ConstString &rhs) { 157 m_string = rhs.m_string; 158 return *this; 159 } 160 161 //------------------------------------------------------------------ 162 /// Equal to operator 163 /// 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 167 /// pool. 168 /// 169 /// @param[in] rhs 170 /// Another string object to compare this object to. 171 /// 172 /// @return 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; 180 } 181 182 //------------------------------------------------------------------ 183 /// Not equal to operator 184 /// 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 188 /// pool. 189 /// 190 /// @param[in] rhs 191 /// Another string object to compare this object to. 192 /// 193 /// @return 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; 199 } 200 201 bool operator<(const ConstString &rhs) const; 202 203 //------------------------------------------------------------------ 204 /// Get the string value as a C string. 205 /// 206 /// Get the value of the contained string as a NULL terminated C 207 /// string value. 208 /// 209 /// If \a value_if_empty is nullptr, then nullptr will be returned. 210 /// 211 /// @return 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); 217 } 218 219 //------------------------------------------------------------------ 220 /// Get the string value as a llvm::StringRef 221 /// 222 /// @return 223 /// Returns a new llvm::StringRef object filled in with the 224 /// needed data. 225 //------------------------------------------------------------------ 226 llvm::StringRef GetStringRef() const { 227 return llvm::StringRef(m_string, GetLength()); 228 } 229 230 //------------------------------------------------------------------ 231 /// Get the string value as a C string. 232 /// 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 237 /// pointer value. 238 /// 239 /// @return 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; } 244 245 //------------------------------------------------------------------ 246 /// Get the length in bytes of string value. 247 /// 248 /// The string pool stores the length of the string, so we can avoid 249 /// calling strlen() on the pointer value with this function. 250 /// 251 /// @return 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; 256 257 //------------------------------------------------------------------ 258 /// Clear this object's state. 259 /// 260 /// Clear any contained string and reset the value to the an empty 261 /// string value. 262 //------------------------------------------------------------------ 263 void Clear() { m_string = nullptr; } 264 265 //------------------------------------------------------------------ 266 /// Equal to operator 267 /// 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. 272 /// 273 /// @param[in] rhs 274 /// The Left Hand Side const ConstString object reference. 275 /// 276 /// @param[in] rhs 277 /// The Right Hand Side const ConstString object reference. 278 /// 279 /// @param[in] case_sensitive 280 /// Case sensitivity. If true, case sensitive equality 281 /// will be tested, otherwise character case will be ignored 282 /// 283 /// @return 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); 289 290 //------------------------------------------------------------------ 291 /// Compare two string objects. 292 /// 293 /// Compares the C string values contained in \a lhs and \a rhs and 294 /// returns an integer result. 295 /// 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. 300 /// 301 /// @param[in] lhs 302 /// The Left Hand Side const ConstString object reference. 303 /// 304 /// @param[in] rhs 305 /// The Right Hand Side const ConstString object reference. 306 /// 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 310 /// 311 /// @return 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); 318 319 //------------------------------------------------------------------ 320 /// Dump the object description to a stream. 321 /// 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 325 /// stream. 326 /// 327 /// @param[in] s 328 /// The stream that will be used to dump the object description. 329 /// 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; 335 336 //------------------------------------------------------------------ 337 /// Dump the object debug description to a stream. 338 /// 339 /// @param[in] s 340 /// The stream that will be used to dump the object description. 341 //------------------------------------------------------------------ 342 void DumpDebug(Stream *s) const; 343 344 //------------------------------------------------------------------ 345 /// Test for empty string. 346 /// 347 /// @return 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'; } 352 353 //------------------------------------------------------------------ 354 /// Set the C string value. 355 /// 356 /// Set the string value in the object by uniquing the \a cstr 357 /// string value in our global string pool. 358 /// 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. 362 /// 363 /// @param[in] cstr 364 /// A NULL terminated C string to add to the string pool. 365 //------------------------------------------------------------------ 366 void SetCString(const char *cstr); 367 368 void SetString(const llvm::StringRef &s); 369 370 //------------------------------------------------------------------ 371 /// Set the C string value and its mangled counterpart. 372 /// 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. 379 /// 380 /// @param[in] demangled 381 /// The demangled C string to correlate with the \a mangled 382 /// name. 383 /// 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); 390 391 //------------------------------------------------------------------ 392 /// Retrieve the mangled or demangled counterpart for a mangled 393 /// or demangled ConstString. 394 /// 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. 401 /// 402 /// @param[in] counterpart 403 /// A reference to a ConstString object that might get filled in 404 /// with the demangled/mangled counterpart. 405 /// 406 /// @return 407 /// /b True if \a counterpart was filled in with the counterpart 408 /// /b false otherwise. 409 //------------------------------------------------------------------ 410 bool GetMangledCounterpart(ConstString &counterpart) const; 411 412 //------------------------------------------------------------------ 413 /// Set the C string value with length. 414 /// 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. 420 /// 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. 424 /// 425 /// @param[in] cstr 426 /// A NULL terminated C string to add to the string pool. 427 /// 428 /// @param[in] cstr_len 429 /// The maximum length of the C string. 430 //------------------------------------------------------------------ 431 void SetCStringWithLength(const char *cstr, size_t cstr_len); 432 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); 441 442 //------------------------------------------------------------------ 443 /// Get the memory cost of this object. 444 /// 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. 448 /// 449 /// @return 450 /// The number of bytes that this object occupies in memory. 451 /// 452 /// @see ConstString::StaticMemorySize () 453 //------------------------------------------------------------------ 454 size_t MemorySize() const { return sizeof(ConstString); } 455 456 //------------------------------------------------------------------ 457 /// Get the size in bytes of the current global string pool. 458 /// 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. 462 /// 463 /// @return 464 /// The number of bytes that the global string pool occupies 465 /// in memory. 466 //------------------------------------------------------------------ 467 static size_t StaticMemorySize(); 468 469protected: 470 //------------------------------------------------------------------ 471 // Member variables 472 //------------------------------------------------------------------ 473 const char *m_string; 474}; 475 476//------------------------------------------------------------------ 477/// Stream the string value \a str to the stream \a s 478//------------------------------------------------------------------ 479Stream &operator<<(Stream &s, const ConstString &str); 480 481} // namespace lldb_private 482 483namespace llvm { 484template <> struct format_provider<lldb_private::ConstString> { 485 static void format(const lldb_private::ConstString &CS, llvm::raw_ostream &OS, 486 llvm::StringRef Options); 487}; 488} 489 490#endif // liblldb_ConstString_h_ 491