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#if defined(__cplusplus) 13 14#include <assert.h> 15 16#include "lldb/lldb-private.h" 17#include "llvm/ADT/StringRef.h" 18 19 20namespace lldb_private { 21 22//---------------------------------------------------------------------- 23/// @class ConstString ConstString.h "lldb/Core/ConstString.h" 24/// @brief A uniqued constant string class. 25/// 26/// Provides an efficient way to store strings as uniqued strings. After 27/// the strings are uniqued, finding strings that are equal to one 28/// another is very fast as just the pointers need to be compared. It 29/// also allows for many common strings from many different sources to 30/// be shared to keep the memory footprint low. 31/// 32/// No reference counting is done on strings that are added to the 33/// string pool, once strings are added they are in the string pool for 34/// the life of the program. 35//---------------------------------------------------------------------- 36class ConstString 37{ 38public: 39 //------------------------------------------------------------------ 40 /// Default constructor 41 /// 42 /// Initializes the string to an empty string. 43 //------------------------------------------------------------------ 44 ConstString (): 45 m_string (NULL) 46 { 47 } 48 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) : 59 m_string (rhs.m_string) 60 { 61 } 62 63 explicit ConstString (const llvm::StringRef &s); 64 65 //------------------------------------------------------------------ 66 /// Construct with C String value 67 /// 68 /// Constructs this object with a C string by looking to see if the 69 /// C string already exists in the global string pool. If it doesn't 70 /// exist, it is added to the string pool. 71 /// 72 /// @param[in] cstr 73 /// A NULL terminated C string to add to the string pool. 74 //------------------------------------------------------------------ 75 explicit ConstString (const char *cstr); 76 77 //------------------------------------------------------------------ 78 /// Construct with C String value with max length 79 /// 80 /// Constructs this object with a C string with a length. If 81 /// \a max_cstr_len is greater than the actual length of the string, 82 /// the string length will be truncated. This allows substrings to 83 /// be created without the need to NULL terminate the string as it 84 /// is passed into this function. 85 /// 86 /// @param[in] cstr 87 /// A pointer to the first character in the C string. The C 88 /// string can be NULL terminated in a buffer that contains 89 /// more characters than the length of the stirng, or the 90 /// string can be part of another string and a new substring 91 /// can be created. 92 /// 93 /// @param[in] max_cstr_len 94 /// The max length of \a cstr. If the string length of \a cstr 95 /// is less than \a max_cstr_len, then the string will be 96 /// truncated. If the string length of \a cstr is greater than 97 /// \a max_cstr_len, then only max_cstr_len bytes will be used 98 /// from \a cstr. 99 //------------------------------------------------------------------ 100 explicit ConstString (const char *cstr, size_t max_cstr_len); 101 102 //------------------------------------------------------------------ 103 /// Destructor 104 /// 105 /// Since constant string values are currently not reference counted, 106 /// there isn't much to do here. 107 //------------------------------------------------------------------ 108 ~ConstString () 109 { 110 } 111 112 113 //---------------------------------------------------------------------- 114 /// C string equality binary predicate function object for ConstString 115 /// objects. 116 //---------------------------------------------------------------------- 117 struct StringIsEqual 118 { 119 //-------------------------------------------------------------- 120 /// C equality test. 121 /// 122 /// Two C strings are equal when they are contained in ConstString 123 /// objects when their pointer values are equal to each other. 124 /// 125 /// @return 126 /// Returns \b true if the C string in \a lhs is equal to 127 /// the C string value in \a rhs, \b false otherwise. 128 //-------------------------------------------------------------- 129 bool operator()(const char* lhs, const char* rhs) const 130 { 131 return lhs == rhs; 132 } 133 }; 134 135 //------------------------------------------------------------------ 136 /// Convert to bool operator. 137 /// 138 /// This allows code to check a ConstString object to see if it 139 /// contains a valid string using code such as: 140 /// 141 /// @code 142 /// ConstString str(...); 143 /// if (str) 144 /// { ... 145 /// @endcode 146 /// 147 /// @return 148 /// /b True this object contains a valid non-empty C string, \b 149 /// false otherwise. 150 //------------------------------------------------------------------ 151 operator bool() const 152 { 153 return m_string && m_string[0]; 154 } 155 156 //------------------------------------------------------------------ 157 /// Assignment operator 158 /// 159 /// Assigns the string in this object with the value from \a rhs. 160 /// 161 /// @param[in] rhs 162 /// Another string object to copy into this object. 163 /// 164 /// @return 165 /// A const reference to this object. 166 //------------------------------------------------------------------ 167 const ConstString& 168 operator = (const ConstString& rhs) 169 { 170 m_string = rhs.m_string; 171 return *this; 172 } 173 174 //------------------------------------------------------------------ 175 /// Equal to operator 176 /// 177 /// Returns true if this string is equal to the string in \a rhs. 178 /// This operation is very fast as it results in a pointer 179 /// comparison since all strings are in a uniqued in a global string 180 /// pool. 181 /// 182 /// @param[in] rhs 183 /// Another string object to compare this object to. 184 /// 185 /// @return 186 /// @li \b true if this object is equal to \a rhs. 187 /// @li \b false if this object is not equal to \a rhs. 188 //------------------------------------------------------------------ 189 bool 190 operator == (const ConstString& rhs) const 191 { 192 // We can do a pointer compare to compare these strings since they 193 // must come from the same pool in order to be equal. 194 return m_string == rhs.m_string; 195 } 196 197 //------------------------------------------------------------------ 198 /// Not equal to operator 199 /// 200 /// Returns true if this string is not equal to the string in \a rhs. 201 /// This operation is very fast as it results in a pointer 202 /// comparison since all strings are in a uniqued in a global string 203 /// pool. 204 /// 205 /// @param[in] rhs 206 /// Another string object to compare this object to. 207 /// 208 /// @return 209 /// @li \b true if this object is not equal to \a rhs. 210 /// @li \b false if this object is equal to \a rhs. 211 //------------------------------------------------------------------ 212 bool 213 operator != (const ConstString& rhs) const 214 { 215 return m_string != rhs.m_string; 216 } 217 218 bool 219 operator < (const ConstString& rhs) const; 220 221 //------------------------------------------------------------------ 222 /// Get the string value as a C string. 223 /// 224 /// Get the value of the contained string as a NULL terminated C 225 /// string value. 226 /// 227 /// If \a value_if_empty is NULL, then NULL will be returned. 228 /// 229 /// @return 230 /// Returns \a value_if_empty if the string is empty, otherwise 231 /// the C string value contained in this object. 232 //------------------------------------------------------------------ 233 const char * 234 AsCString(const char *value_if_empty = NULL) const 235 { 236 if (m_string == NULL) 237 return value_if_empty; 238 return m_string; 239 } 240 241 //------------------------------------------------------------------ 242 /// Get the string value as a llvm::StringRef 243 /// 244 /// @return 245 /// Returns a new llvm::StringRef object filled in with the 246 /// needed data. 247 //------------------------------------------------------------------ 248 llvm::StringRef 249 GetStringRef () const 250 { 251 return llvm::StringRef (m_string, GetLength()); 252 } 253 254 //------------------------------------------------------------------ 255 /// Get the string value as a C string. 256 /// 257 /// Get the value of the contained string as a NULL terminated C 258 /// string value. Similar to the ConstString::AsCString() function, 259 /// yet this function will always return NULL if the string is not 260 /// valid. So this function is a direct accessor to the string 261 /// pointer value. 262 /// 263 /// @return 264 /// Returns NULL the string is invalid, otherwise the C string 265 /// value contained in this object. 266 //------------------------------------------------------------------ 267 const char * 268 GetCString () const 269 { 270 return m_string; 271 } 272 273 274 //------------------------------------------------------------------ 275 /// Get the length in bytes of string value. 276 /// 277 /// The string pool stores the length of the string, so we can avoid 278 /// calling strlen() on the pointer value with this function. 279 /// 280 /// @return 281 /// Returns the number of bytes that this string occupies in 282 /// memory, not including the NULL termination byte. 283 //------------------------------------------------------------------ 284 size_t 285 GetLength () const; 286 287 //------------------------------------------------------------------ 288 /// Clear this object's state. 289 /// 290 /// Clear any contained string and reset the value to the an empty 291 /// string value. 292 //------------------------------------------------------------------ 293 void 294 Clear () 295 { 296 m_string = NULL; 297 } 298 299 //------------------------------------------------------------------ 300 /// Compare two string objects. 301 /// 302 /// Compares the C string values contained in \a lhs and \a rhs and 303 /// returns an integer result. 304 /// 305 /// NOTE: only call this function when you want a true string 306 /// comparision. If you want string equality use the, use the == 307 /// operator as it is much more efficient. Also if you want string 308 /// inequality, use the != operator for the same reasons. 309 /// 310 /// @param[in] lhs 311 /// The Left Hand Side const ConstString object reference. 312 /// 313 /// @param[in] rhs 314 /// The Right Hand Side const ConstString object reference. 315 /// 316 /// @return 317 /// @li -1 if lhs < rhs 318 /// @li 0 if lhs == rhs 319 /// @li 1 if lhs > rhs 320 //------------------------------------------------------------------ 321 static int 322 Compare (const ConstString& lhs, const ConstString& rhs); 323 324 //------------------------------------------------------------------ 325 /// Dump the object description to a stream. 326 /// 327 /// Dump the string value to the stream \a s. If the contained string 328 /// is empty, print \a value_if_empty to the stream instead. If 329 /// \a value_if_empty is NULL, then nothing will be dumped to the 330 /// stream. 331 /// 332 /// @param[in] s 333 /// The stream that will be used to dump the object description. 334 /// 335 /// @param[in] value_if_empty 336 /// The value to dump if the string is empty. If NULL, nothing 337 /// will be output to the stream. 338 //------------------------------------------------------------------ 339 void 340 Dump (Stream *s, const char *value_if_empty = NULL) const; 341 342 //------------------------------------------------------------------ 343 /// Dump the object debug description to a stream. 344 /// 345 /// @param[in] s 346 /// The stream that will be used to dump the object description. 347 //------------------------------------------------------------------ 348 void 349 DumpDebug (Stream *s) const; 350 351 //------------------------------------------------------------------ 352 /// Test for empty string. 353 /// 354 /// @return 355 /// @li \b true if the contained string is empty. 356 /// @li \b false if the contained string is not empty. 357 //------------------------------------------------------------------ 358 bool 359 IsEmpty () const 360 { 361 return m_string == NULL || m_string[0] == '\0'; 362 } 363 364 //------------------------------------------------------------------ 365 /// Set the C string value. 366 /// 367 /// Set the string value in the object by uniquing the \a cstr 368 /// string value in our global string pool. 369 /// 370 /// If the C string already exists in the global string pool, it 371 /// finds the current entry and returns the existing value. If it 372 /// doesn't exist, it is added to the string pool. 373 /// 374 /// @param[in] cstr 375 /// A NULL terminated C string to add to the string pool. 376 //------------------------------------------------------------------ 377 void 378 SetCString (const char *cstr); 379 380 void 381 SetString (const llvm::StringRef &s); 382 383 //------------------------------------------------------------------ 384 /// Set the C string value and its mangled counterpart. 385 /// 386 /// Object files and debug sybmols often use mangled string to 387 /// represent the linkage name for a symbol, function or global. 388 /// The string pool can efficiently store these values and their 389 /// counterparts so when we run into another instance of a mangled 390 /// name, we can avoid calling the name demangler over and over on 391 /// the same strings and then trying to unique them. 392 /// 393 /// @param[in] demangled 394 /// The demangled C string to correlate with the \a mangled 395 /// name. 396 /// 397 /// @param[in] mangled 398 /// The already uniqued mangled ConstString to correlate the 399 /// soon to be uniqued version of \a demangled. 400 //------------------------------------------------------------------ 401 void 402 SetCStringWithMangledCounterpart (const char *demangled, 403 const ConstString &mangled); 404 405 //------------------------------------------------------------------ 406 /// Retrieve the mangled or demangled counterpart for a mangled 407 /// or demangled ConstString. 408 /// 409 /// Object files and debug sybmols often use mangled string to 410 /// represent the linkage name for a symbol, function or global. 411 /// The string pool can efficiently store these values and their 412 /// counterparts so when we run into another instance of a mangled 413 /// name, we can avoid calling the name demangler over and over on 414 /// the same strings and then trying to unique them. 415 /// 416 /// @param[in] counterpart 417 /// A reference to a ConstString object that might get filled in 418 /// with the demangled/mangled counterpart. 419 /// 420 /// @return 421 /// /b True if \a counterpart was filled in with the counterpart 422 /// /b false otherwise. 423 //------------------------------------------------------------------ 424 bool 425 GetMangledCounterpart (ConstString &counterpart) const; 426 427 //------------------------------------------------------------------ 428 /// Set the C string value with length. 429 /// 430 /// Set the string value in the object by uniquing \a cstr_len bytes 431 /// starting at the \a cstr string value in our global string pool. 432 /// If trim is true, then \a cstr_len indicates a maximum length of 433 /// the CString and if the actual length of the string is less, then 434 /// it will be trimmed. 435 /// 436 /// If the C string already exists in the global string pool, it 437 /// finds the current entry and returns the existing value. If it 438 /// doesn't exist, it is added to the string pool. 439 /// 440 /// @param[in] cstr 441 /// A NULL terminated C string to add to the string pool. 442 /// 443 /// @param[in] cstr_len 444 /// The maximum length of the C string. 445 //------------------------------------------------------------------ 446 void 447 SetCStringWithLength (const char *cstr, size_t cstr_len); 448 449 //------------------------------------------------------------------ 450 /// Set the C string value with the minimum length between 451 /// \a fixed_cstr_len and the actual length of the C string. This 452 /// can be used for data structures that have a fixed length to 453 /// store a C string where the string might not be NULL terminated 454 /// if the string takes the entire buffer. 455 //------------------------------------------------------------------ 456 void 457 SetTrimmedCStringWithLength (const char *cstr, size_t fixed_cstr_len); 458 459 //------------------------------------------------------------------ 460 /// Get the memory cost of this object. 461 /// 462 /// Return the size in bytes that this object takes in memory. This 463 /// returns the size in bytes of this object, which does not include 464 /// any the shared string values it may refer to. 465 /// 466 /// @return 467 /// The number of bytes that this object occupies in memory. 468 /// 469 /// @see ConstString::StaticMemorySize () 470 //------------------------------------------------------------------ 471 size_t 472 MemorySize () const 473 { 474 return sizeof(ConstString); 475 } 476 477 478 //------------------------------------------------------------------ 479 /// Get the size in bytes of the current global string pool. 480 /// 481 /// Reports the the size in bytes of all shared C string values, 482 /// containers and any other values as a byte size for the 483 /// entire string pool. 484 /// 485 /// @return 486 /// The number of bytes that the global string pool occupies 487 /// in memory. 488 //------------------------------------------------------------------ 489 static size_t 490 StaticMemorySize (); 491 492protected: 493 //------------------------------------------------------------------ 494 // Member variables 495 //------------------------------------------------------------------ 496 const char *m_string; 497}; 498 499//------------------------------------------------------------------ 500/// Stream the string value \a str to the stream \a s 501//------------------------------------------------------------------ 502Stream& operator << (Stream& s, const ConstString& str); 503 504} // namespace lldb_private 505 506#endif // #if defined(__cplusplus) 507#endif // liblldb_ConstString_h_ 508