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