ConstString.h revision 344779
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" 15 16#include <stddef.h> 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/// 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//---------------------------------------------------------------------- 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 \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. 81 /// 82 /// @param[in] cstr 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 87 /// can be created. 88 /// 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 94 /// from \a cstr. 95 //------------------------------------------------------------------ 96 explicit ConstString(const char *cstr, size_t max_cstr_len); 97 98 //------------------------------------------------------------------ 99 /// Destructor 100 /// 101 /// Since constant string values are currently not reference counted, there 102 /// isn't much to do here. 103 //------------------------------------------------------------------ 104 ~ConstString() = default; 105 106 //---------------------------------------------------------------------- 107 /// C string equality binary predicate function object for ConstString 108 /// objects. 109 //---------------------------------------------------------------------- 110 struct StringIsEqual { 111 //-------------------------------------------------------------- 112 /// C equality test. 113 /// 114 /// Two C strings are equal when they are contained in ConstString objects 115 /// when their pointer values are equal to each other. 116 /// 117 /// @return 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 { 122 return lhs == rhs; 123 } 124 }; 125 126 //------------------------------------------------------------------ 127 /// Convert to bool operator. 128 /// 129 /// This allows code to check a ConstString object to see if it contains a 130 /// valid string using code such as: 131 /// 132 /// @code 133 /// ConstString str(...); 134 /// if (str) 135 /// { ... 136 /// @endcode 137 /// 138 /// @return 139 /// /b True this object contains a valid non-empty C string, \b 140 /// false otherwise. 141 //------------------------------------------------------------------ 142 explicit operator bool() const { return !IsEmpty(); } 143 144 //------------------------------------------------------------------ 145 /// Assignment operator 146 /// 147 /// Assigns the string in this object with the value from \a rhs. 148 /// 149 /// @param[in] rhs 150 /// Another string object to copy into this object. 151 /// 152 /// @return 153 /// A const reference to this object. 154 //------------------------------------------------------------------ 155 const ConstString &operator=(const ConstString &rhs) { 156 m_string = rhs.m_string; 157 return *this; 158 } 159 160 //------------------------------------------------------------------ 161 /// Equal to operator 162 /// 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. 166 /// 167 /// @param[in] rhs 168 /// Another string object to compare this object to. 169 /// 170 /// @return 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; 178 } 179 180 //------------------------------------------------------------------ 181 /// Not equal to operator 182 /// 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. 186 /// 187 /// @param[in] rhs 188 /// Another string object to compare this object to. 189 /// 190 /// @return 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; 196 } 197 198 bool operator<(const ConstString &rhs) const; 199 200 //------------------------------------------------------------------ 201 /// Get the string value as a C string. 202 /// 203 /// Get the value of the contained string as a NULL terminated C string 204 /// value. 205 /// 206 /// If \a value_if_empty is nullptr, then nullptr will be returned. 207 /// 208 /// @return 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); 214 } 215 216 //------------------------------------------------------------------ 217 /// Get the string value as a llvm::StringRef 218 /// 219 /// @return 220 /// Returns a new llvm::StringRef object filled in with the 221 /// needed data. 222 //------------------------------------------------------------------ 223 llvm::StringRef GetStringRef() const { 224 return llvm::StringRef(m_string, GetLength()); 225 } 226 227 //------------------------------------------------------------------ 228 /// Get the string value as a C string. 229 /// 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. 234 /// 235 /// @return 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; } 240 241 //------------------------------------------------------------------ 242 /// Get the length in bytes of string value. 243 /// 244 /// The string pool stores the length of the string, so we can avoid calling 245 /// strlen() on the pointer value with this function. 246 /// 247 /// @return 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; 252 253 //------------------------------------------------------------------ 254 /// Clear this object's state. 255 /// 256 /// Clear any contained string and reset the value to the empty string 257 /// value. 258 //------------------------------------------------------------------ 259 void Clear() { m_string = nullptr; } 260 261 //------------------------------------------------------------------ 262 /// Equal to operator 263 /// 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 267 /// string pool. 268 /// 269 /// @param[in] rhs 270 /// The Left Hand Side const ConstString object reference. 271 /// 272 /// @param[in] rhs 273 /// The Right Hand Side const ConstString object reference. 274 /// 275 /// @param[in] case_sensitive 276 /// Case sensitivity. If true, case sensitive equality 277 /// will be tested, otherwise character case will be ignored 278 /// 279 /// @return 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); 285 286 //------------------------------------------------------------------ 287 /// Compare two string objects. 288 /// 289 /// Compares the C string values contained in \a lhs and \a rhs and returns 290 /// an integer result. 291 /// 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. 296 /// 297 /// @param[in] lhs 298 /// The Left Hand Side const ConstString object reference. 299 /// 300 /// @param[in] rhs 301 /// The Right Hand Side const ConstString object reference. 302 /// 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 306 /// 307 /// @return 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); 314 315 //------------------------------------------------------------------ 316 /// Dump the object description to a stream. 317 /// 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. 321 /// 322 /// @param[in] s 323 /// The stream that will be used to dump the object description. 324 /// 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; 330 331 //------------------------------------------------------------------ 332 /// Dump the object debug description to a stream. 333 /// 334 /// @param[in] s 335 /// The stream that will be used to dump the object description. 336 //------------------------------------------------------------------ 337 void DumpDebug(Stream *s) const; 338 339 //------------------------------------------------------------------ 340 /// Test for empty string. 341 /// 342 /// @return 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'; } 347 348 //------------------------------------------------------------------ 349 /// Test for null string. 350 /// 351 /// @return 352 /// @li \b true if there is no string associated with this instance. 353 /// @li \b false if there is a string associated with this instance. 354 //------------------------------------------------------------------ 355 bool IsNull() const { return m_string == nullptr; } 356 357 //------------------------------------------------------------------ 358 /// Set the C string value. 359 /// 360 /// Set the string value in the object by uniquing the \a cstr string value 361 /// in our global string pool. 362 /// 363 /// If the C string already exists in the global string pool, it finds the 364 /// current entry and returns the existing value. If it doesn't exist, it is 365 /// added to the string pool. 366 /// 367 /// @param[in] cstr 368 /// A NULL terminated C string to add to the string pool. 369 //------------------------------------------------------------------ 370 void SetCString(const char *cstr); 371 372 void SetString(const llvm::StringRef &s); 373 374 //------------------------------------------------------------------ 375 /// Set the C string value and its mangled counterpart. 376 /// 377 /// Object files and debug symbols often use mangled string to represent the 378 /// linkage name for a symbol, function or global. The string pool can 379 /// efficiently store these values and their counterparts so when we run 380 /// into another instance of a mangled name, we can avoid calling the name 381 /// demangler over and over on the same strings and then trying to unique 382 /// them. 383 /// 384 /// @param[in] demangled 385 /// The demangled string to correlate with the \a mangled name. 386 /// 387 /// @param[in] mangled 388 /// The already uniqued mangled ConstString to correlate the 389 /// soon to be uniqued version of \a demangled. 390 //------------------------------------------------------------------ 391 void SetStringWithMangledCounterpart(llvm::StringRef demangled, 392 const ConstString &mangled); 393 394 //------------------------------------------------------------------ 395 /// Retrieve the mangled or demangled counterpart for a mangled or demangled 396 /// ConstString. 397 /// 398 /// Object files and debug symbols often use mangled string to represent the 399 /// linkage name for a symbol, function or global. The string pool can 400 /// efficiently store these values and their counterparts so when we run 401 /// into another instance of a mangled name, we can avoid calling the name 402 /// demangler over and over on the same strings and then trying to unique 403 /// them. 404 /// 405 /// @param[in] counterpart 406 /// A reference to a ConstString object that might get filled in 407 /// with the demangled/mangled counterpart. 408 /// 409 /// @return 410 /// /b True if \a counterpart was filled in with the counterpart 411 /// /b false otherwise. 412 //------------------------------------------------------------------ 413 bool GetMangledCounterpart(ConstString &counterpart) const; 414 415 //------------------------------------------------------------------ 416 /// Set the C string value with length. 417 /// 418 /// Set the string value in the object by uniquing \a cstr_len bytes 419 /// starting at the \a cstr string value in our global string pool. If trim 420 /// is true, then \a cstr_len indicates a maximum length of the CString and 421 /// if the actual length of the string is less, then it will be trimmed. 422 /// 423 /// If the C string already exists in the global string pool, it finds the 424 /// current entry and returns the existing value. If it doesn't exist, it is 425 /// added to the string pool. 426 /// 427 /// @param[in] cstr 428 /// A NULL terminated C string to add to the string pool. 429 /// 430 /// @param[in] cstr_len 431 /// The maximum length of the C string. 432 //------------------------------------------------------------------ 433 void SetCStringWithLength(const char *cstr, size_t cstr_len); 434 435 //------------------------------------------------------------------ 436 /// Set the C string value with the minimum length between \a fixed_cstr_len 437 /// and the actual length of the C string. This can be used for data 438 /// structures that have a fixed length to store a C string where the string 439 /// might not be NULL terminated if the string takes the entire buffer. 440 //------------------------------------------------------------------ 441 void SetTrimmedCStringWithLength(const char *cstr, size_t fixed_cstr_len); 442 443 //------------------------------------------------------------------ 444 /// Get the memory cost of this object. 445 /// 446 /// Return the size in bytes that this object takes in memory. This returns 447 /// the size in bytes of this object, which does not include any the shared 448 /// string values it may refer to. 449 /// 450 /// @return 451 /// The number of bytes that this object occupies in memory. 452 /// 453 /// @see ConstString::StaticMemorySize () 454 //------------------------------------------------------------------ 455 size_t MemorySize() const { return sizeof(ConstString); } 456 457 //------------------------------------------------------------------ 458 /// Get the size in bytes of the current global string pool. 459 /// 460 /// Reports the size in bytes of all shared C string values, containers and 461 /// any other values as a byte size for the 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