ConstString.h revision 341825
174861Sru//===-- ConstString.h -------------------------------------------*- C++ -*-===// 29Sjkh// 3136679Sru// The LLVM Compiler Infrastructure 474861Sru// 574861Sru// This file is distributed under the University of Illinois Open Source 6113Sconklin// License. See LICENSE.TXT for details. 7113Sconklin// 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/// 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 an 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 /// Set the C string value. 350 /// 351 /// Set the string value in the object by uniquing the \a cstr string value 352 /// in our global string pool. 353 /// 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. 357 /// 358 /// @param[in] cstr 359 /// A NULL terminated C string to add to the string pool. 360 //------------------------------------------------------------------ 361 void SetCString(const char *cstr); 362 363 void SetString(const llvm::StringRef &s); 364 365 //------------------------------------------------------------------ 366 /// Set the C string value and its mangled counterpart. 367 /// 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 373 /// them. 374 /// 375 /// @param[in] demangled 376 /// The demangled C string to correlate with the \a mangled 377 /// name. 378 /// 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); 385 386 //------------------------------------------------------------------ 387 /// Retrieve the mangled or demangled counterpart for a mangled or demangled 388 /// ConstString. 389 /// 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 395 /// them. 396 /// 397 /// @param[in] counterpart 398 /// A reference to a ConstString object that might get filled in 399 /// with the demangled/mangled counterpart. 400 /// 401 /// @return 402 /// /b True if \a counterpart was filled in with the counterpart 403 /// /b false otherwise. 404 //------------------------------------------------------------------ 405 bool GetMangledCounterpart(ConstString &counterpart) const; 406 407 //------------------------------------------------------------------ 408 /// Set the C string value with length. 409 /// 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. 414 /// 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. 418 /// 419 /// @param[in] cstr 420 /// A NULL terminated C string to add to the string pool. 421 /// 422 /// @param[in] cstr_len 423 /// The maximum length of the C string. 424 //------------------------------------------------------------------ 425 void SetCStringWithLength(const char *cstr, size_t cstr_len); 426 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); 434 435 //------------------------------------------------------------------ 436 /// Get the memory cost of this object. 437 /// 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. 441 /// 442 /// @return 443 /// The number of bytes that this object occupies in memory. 444 /// 445 /// @see ConstString::StaticMemorySize () 446 //------------------------------------------------------------------ 447 size_t MemorySize() const { return sizeof(ConstString); } 448 449 //------------------------------------------------------------------ 450 /// Get the size in bytes of the current global string pool. 451 /// 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. 454 /// 455 /// @return 456 /// The number of bytes that the global string pool occupies 457 /// in memory. 458 //------------------------------------------------------------------ 459 static size_t StaticMemorySize(); 460 461protected: 462 //------------------------------------------------------------------ 463 // Member variables 464 //------------------------------------------------------------------ 465 const char *m_string; 466}; 467 468//------------------------------------------------------------------ 469/// Stream the string value \a str to the stream \a s 470//------------------------------------------------------------------ 471Stream &operator<<(Stream &s, const ConstString &str); 472 473} // namespace lldb_private 474 475namespace llvm { 476template <> struct format_provider<lldb_private::ConstString> { 477 static void format(const lldb_private::ConstString &CS, llvm::raw_ostream &OS, 478 llvm::StringRef Options); 479}; 480} 481 482#endif // liblldb_ConstString_h_ 483