contrib/llvm/tools/lldb/include/lldb/Core/ConstString.h

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