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

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