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 #if defined(__cplusplus)
  13
  14 #include <assert.h>
  15
  16 #include "lldb/lldb-private.h"
  17 #include "llvm/ADT/StringRef.h"
  18
  19
  20 namespace 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 //----------------------------------------------------------------------
  36 class ConstString
  37 {
  38 public:
  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 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 ()
 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     explicit 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
 492 protected:
 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 //------------------------------------------------------------------
 502 Stream& operator << (Stream& s, const ConstString& str);
 503
 504 } // namespace lldb_private
 505
 506 #endif  // #if defined(__cplusplus)
 507 #endif  // liblldb_ConstString_h_