ConstString.h revision 8de27c761a22187ef63fb60000894be163e7285f
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 18namespace lldb_private { 19 20//---------------------------------------------------------------------- 21/// @class ConstString ConstString.h "lldb/Core/ConstString.h" 22/// @brief A uniqued constant string class. 23/// 24/// Provides an efficient way to store strings as uniqued ref counted 25/// strings. Since the strings are uniqued, finding strings that are 26/// equal to one another is very fast (pointer compares). It also allows 27/// for many common strings from many different sources to be shared to 28/// keep the memory footprint low. 29//---------------------------------------------------------------------- 30class ConstString 31{ 32public: 33 //------------------------------------------------------------------ 34 /// Default constructor 35 /// 36 /// Initializes the string to an empty string. 37 //------------------------------------------------------------------ 38 ConstString (); 39 40 //------------------------------------------------------------------ 41 /// Copy constructor 42 /// 43 /// Copies the string value in \a rhs and retains an extra reference 44 /// to the string value in the string pool. 45 /// 46 /// @param[in] rhs 47 /// Another string object to copy. 48 //------------------------------------------------------------------ 49 ConstString (const ConstString& rhs); 50 51 //------------------------------------------------------------------ 52 /// Construct with C String value 53 /// 54 /// Constructs this object with a C string by looking to see if the 55 /// C string already exists in the global string pool. If it does 56 /// exist, it retains an extra reference to the string in the string 57 /// pool. If it doesn't exist, it is added to the string pool with 58 /// a reference count of 1. 59 /// 60 /// @param[in] cstr 61 /// A NULL terminated C string to add to the string pool. 62 //------------------------------------------------------------------ 63 explicit ConstString (const char *cstr); 64 65 //------------------------------------------------------------------ 66 /// Construct with C String value with max length 67 /// 68 /// Constructs this object with a C string with a length. If 69 /// \a max_cstr_len is greater than the actual length of the string, 70 /// the string length will be truncated. This allows substrings to 71 /// be created without the need to NULL terminate the string as it 72 /// is passed into this function. 73 /// 74 /// If the C string already exists in the global string pool, it 75 /// retains an extra reference to the string in the string 76 /// pool. If it doesn't exist, it is added to the string pool with 77 /// a reference count of 1. 78 /// 79 /// @param[in] cstr 80 /// A NULL terminated C string to add to the string pool. 81 /// 82 /// @param[in] max_cstr_len 83 /// The max length of \a cstr. If the string length of \a cstr 84 /// is less than \a max_cstr_len, then the string will be 85 /// truncated. If the string length of \a cstr is greater than 86 /// \a max_cstr_len, then only max_cstr_len bytes will be used 87 /// from \a cstr. 88 //------------------------------------------------------------------ 89 explicit ConstString (const char *cstr, size_t max_cstr_len); 90 91 //------------------------------------------------------------------ 92 /// Destructor 93 /// 94 /// Decrements the reference count on the contained string, and if 95 /// the resulting reference count is zero, then the string is removed 96 /// from the global string pool. If the reference count is still 97 /// greater than zero, the string will remain in the string pool 98 /// until the last reference is released by other ConstString objects. 99 //------------------------------------------------------------------ 100 ~ConstString (); 101 102 //---------------------------------------------------------------------- 103 /// C string equality function object for CStrings contains in the 104 /// same StringPool only. (binary predicate). 105 //---------------------------------------------------------------------- 106 struct StringIsEqual 107 { 108 //-------------------------------------------------------------- 109 /// C equality test. 110 /// 111 /// Two C strings are equal when they are contained in ConstString 112 /// objects when their pointer values are equal to each other. 113 /// 114 /// @return 115 /// Returns \b true if the C string in \a lhs is equal to 116 /// the C string value in \a rhs, \b false otherwise. 117 //-------------------------------------------------------------- 118 bool operator()(const char* lhs, const char* rhs) const 119 { 120 return lhs == rhs; 121 } 122 }; 123 124 //------------------------------------------------------------------ 125 /// Convert to bool operator. 126 /// 127 /// This allows code to check a ConstString object to see if it 128 /// contains a valid string using code such as: 129 /// 130 /// @code 131 /// ConstString str(...); 132 /// if (str) 133 /// { ... 134 /// @endcode 135 /// 136 /// @return 137 /// A pointer to this object if the string isn't empty, NULL 138 /// otherwise. 139 //------------------------------------------------------------------ 140 operator bool() const 141 { 142 return m_string && m_string[0]; 143 } 144 145 //------------------------------------------------------------------ 146 /// Assignment operator 147 /// 148 /// Assigns the string in this object with the value from \a rhs 149 /// and increments the reference count of that string. 150 /// 151 /// The previously contained string will be get its reference count 152 /// decremented and removed from the string pool if its reference 153 /// count reaches zero. 154 /// 155 /// @param[in] rhs 156 /// Another string object to copy into this object. 157 /// 158 /// @return 159 /// A const reference to this object. 160 //------------------------------------------------------------------ 161 const ConstString& 162 operator = (const ConstString& rhs) 163 { 164 m_string = rhs.m_string; 165 return *this; 166 } 167 168 //------------------------------------------------------------------ 169 /// Equal to operator 170 /// 171 /// Returns true if this string is equal to the string in \a rhs. 172 /// This operation is very fast as it results in a pointer 173 /// comparison since all strings are in a uniqued and reference 174 /// counted string pool. 175 /// 176 /// @param[in] rhs 177 /// Another string object to compare this object to. 178 /// 179 /// @return 180 /// @li \b true if this object is equal to \a rhs. 181 /// @li \b false if this object is not equal to \a rhs. 182 //------------------------------------------------------------------ 183 bool 184 operator == (const ConstString& rhs) const 185 { 186 // We can do a pointer compare to compare these strings since they 187 // must come from the same pool in order to be equal. 188 return m_string == rhs.m_string; 189 } 190 191 //------------------------------------------------------------------ 192 /// Not equal to operator 193 /// 194 /// Returns true if this string is not equal to the string in \a rhs. 195 /// This operation is very fast as it results in a pointer 196 /// comparison since all strings are in a uniqued and reference 197 /// counted string pool. 198 /// 199 /// @param[in] rhs 200 /// Another string object to compare this object to. 201 /// 202 /// @return 203 /// @li \b true if this object is not equal to \a rhs. 204 /// @li \b false if this object is equal to \a rhs. 205 //------------------------------------------------------------------ 206 bool 207 operator != (const ConstString& rhs) const 208 { 209 return m_string != rhs.m_string; 210 } 211 212 bool 213 operator < (const ConstString& rhs) const; 214 215 //------------------------------------------------------------------ 216 /// Get the string value as a C string. 217 /// 218 /// Get the value of the contained string as a NULL terminated C 219 /// string value. 220 /// 221 /// If \a value_if_empty is NULL, then NULL will be returned. 222 /// 223 /// @return 224 /// Returns \a value_if_empty if the string is empty, otherwise 225 /// the C string value contained in this object. 226 //------------------------------------------------------------------ 227 const char * 228 AsCString(const char *value_if_empty = NULL) const 229 { 230 if (m_string == NULL) 231 return value_if_empty; 232 return m_string; 233 } 234 235 const char * 236 GetCString () const 237 { 238 return m_string; 239 } 240 241 242 size_t 243 GetLength () const; 244 //------------------------------------------------------------------ 245 /// Clear this object's state. 246 /// 247 /// Clear any contained string and reset the value to the an empty 248 /// string value. 249 /// 250 /// The previously contained string will be get its reference count 251 /// decremented and removed from the string pool if its reference 252 /// count reaches zero. 253 //------------------------------------------------------------------ 254 void 255 Clear () 256 { 257 m_string = NULL; 258 } 259 260 //------------------------------------------------------------------ 261 /// Compare two string objects. 262 /// 263 /// Compares the C string values contained in \a lhs and \a rhs and 264 /// returns an integer result. 265 /// 266 /// @param[in] lhs 267 /// The Left Hand Side const ConstString object reference. 268 /// 269 /// @param[in] rhs 270 /// The Right Hand Side const ConstString object reference. 271 /// 272 /// @return 273 /// @li -1 if lhs < rhs 274 /// @li 0 if lhs == rhs 275 /// @li 1 if lhs > rhs 276 //------------------------------------------------------------------ 277 static int 278 Compare (const ConstString& lhs, const ConstString& rhs); 279 280 //------------------------------------------------------------------ 281 /// Dump the object description to a stream. 282 /// 283 /// Dump the string value to the stream \a s. If the contained string 284 /// is empty, print \a value_if_empty to the stream instead. If 285 /// \a value_if_empty is NULL, then nothing will be dumped to the 286 /// stream. 287 /// 288 /// @param[in] s 289 /// The stream that will be used to dump the object description. 290 /// 291 /// @param[in] value_if_empty 292 /// The value to dump if the string is empty. If NULL, nothing 293 /// will be output to the stream. 294 //------------------------------------------------------------------ 295 void 296 Dump (Stream *s, const char *value_if_empty = NULL) const; 297 298 //------------------------------------------------------------------ 299 /// Dump the object debug description to a stream. 300 /// 301 /// Dump the string value and the reference count to the stream \a 302 /// s. 303 /// 304 /// @param[in] s 305 /// The stream that will be used to dump the object description. 306 //------------------------------------------------------------------ 307 void 308 DumpDebug (Stream *s) const; 309 310 //------------------------------------------------------------------ 311 /// Test for empty string. 312 /// 313 /// @return 314 /// @li \b true if the contained string is empty. 315 /// @li \b false if the contained string is not empty. 316 //------------------------------------------------------------------ 317 bool 318 IsEmpty () const 319 { 320 return m_string == NULL || m_string[0] == '\0'; 321 } 322 323 324 //------------------------------------------------------------------ 325 /// Set the C string value. 326 /// 327 /// Set the string value in the object by uniquing the \a cstr 328 /// string value in our global string pool. 329 /// 330 /// If the C string already exists in the global string pool, it 331 /// finds the current entry and retains an extra reference to the 332 /// string in the string pool. If it doesn't exist, it is added to 333 /// the string pool with a reference count of 1. 334 /// 335 /// @param[in] cstr 336 /// A NULL terminated C string to add to the string pool. 337 //------------------------------------------------------------------ 338 void 339 SetCString (const char *cstr); 340 341 //------------------------------------------------------------------ 342 /// Set the C string value with length. 343 /// 344 /// Set the string value in the object by uniquing \a cstr_len bytes 345 /// starting at the \a cstr string value in our global string pool. 346 /// If trim is true, then \a cstr_len indicates a maximum length of 347 /// the CString and if the actual length of the string is less, then 348 /// it will be trimmed. If trim is false, then this allows strings 349 /// with NULL characters to be added to the string pool. 350 /// 351 /// If the C string already exists in the global string pool, it 352 /// retains an extra reference to the string in the string 353 /// pool. If it doesn't exist, it is added to the string pool with 354 /// a reference count of 1. 355 /// 356 /// @param[in] cstr 357 /// A NULL terminated C string to add to the string pool. 358 /// 359 /// @param[in] cstr_len 360 /// The absolute length of the C string if \a trim is false, 361 /// or the maximum length of the C string if \a trim is true. 362 /// 363 /// @param[in] trim 364 /// If \b true, trim \a cstr to it's actual length before adding 365 /// it to the string pool. If \b false then cstr_len is the 366 /// actual length of the C string to add. 367 //------------------------------------------------------------------ 368 void 369 SetCStringWithLength (const char *cstr, size_t cstr_len); 370 371 //------------------------------------------------------------------ 372 /// Set the C string value with the minimum length between 373 /// \a fixed_cstr_len and the actual length of the C string. This 374 /// can be used for data structures that have a fixed length to 375 /// store a C string where the string might not be NULL terminated 376 /// if the string takes the entire buffer. 377 //------------------------------------------------------------------ 378 void 379 SetTrimmedCStringWithLength (const char *cstr, size_t fixed_cstr_len); 380 381 //------------------------------------------------------------------ 382 /// Get the memory cost of this object. 383 /// 384 /// Return the size in bytes that this object takes in memory. This 385 /// returns the size in bytes of this object, which does not include 386 /// any the shared string values it may refer to. 387 /// 388 /// @return 389 /// The number of bytes that this object occupies in memory. 390 /// 391 /// @see ConstString::StaticMemorySize () 392 //------------------------------------------------------------------ 393 size_t 394 MemorySize () const; 395 396 //------------------------------------------------------------------ 397 /// Get the size in bytes of the current global string pool. 398 /// 399 /// Reports the the size in bytes of all shared C string values, 400 /// containers and reference count values as a byte size for the 401 /// entire string pool. 402 /// 403 /// @return 404 /// The number of bytes that the global string pool occupies 405 /// in memory. 406 //------------------------------------------------------------------ 407 static size_t 408 StaticMemorySize (); 409 410protected: 411 //------------------------------------------------------------------ 412 // Member variables 413 //------------------------------------------------------------------ 414 const char *m_string; 415}; 416 417//------------------------------------------------------------------ 418/// Stream the string value \a str to the stream \a s 419//------------------------------------------------------------------ 420Stream& operator << (Stream& s, const ConstString& str); 421 422} // namespace lldb_private 423 424#endif // #if defined(__cplusplus) 425#endif // liblldb_ConstString_h_ 426