//===-- ConstString.h -------------------------------------------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef liblldb_ConstString_h_
#define liblldb_ConstString_h_

#include "llvm/ADT/StringRef.h"
#include "llvm/Support/FormatVariadic.h" // for format_provider

#include <stddef.h> // for size_t

namespace lldb_private {
class Stream;
}
namespace llvm {
class raw_ostream;
}

namespace lldb_private {

//----------------------------------------------------------------------
/// @class ConstString ConstString.h "lldb/Utility/ConstString.h"
/// @brief A uniqued constant string class.
///
/// Provides an efficient way to store strings as uniqued strings. After
/// the strings are uniqued, finding strings that are equal to one
/// another is very fast as just the pointers need to be compared. It
/// also allows for many common strings from many different sources to
/// be shared to keep the memory footprint low.
///
/// No reference counting is done on strings that are added to the
/// string pool, once strings are added they are in the string pool for
/// the life of the program.
//----------------------------------------------------------------------
class ConstString {
public:
  //------------------------------------------------------------------
  /// Default constructor
  ///
  /// Initializes the string to an empty string.
  //------------------------------------------------------------------
  ConstString() : m_string(nullptr) {}

  //------------------------------------------------------------------
  /// Copy constructor
  ///
  /// Copies the string value in \a rhs into this object.
  ///
  /// @param[in] rhs
  ///     Another string object to copy.
  //------------------------------------------------------------------
  ConstString(const ConstString &rhs) : m_string(rhs.m_string) {}

  explicit ConstString(const llvm::StringRef &s);

  //------------------------------------------------------------------
  /// Construct with C String value
  ///
  /// Constructs this object with a C string by looking to see if the
  /// C string already exists in the global string pool. If it doesn't
  /// exist, it is added to the string pool.
  ///
  /// @param[in] cstr
  ///     A NULL terminated C string to add to the string pool.
  //------------------------------------------------------------------
  explicit ConstString(const char *cstr);

  //------------------------------------------------------------------
  /// Construct with C String value with max length
  ///
  /// Constructs this object with a C string with a length. If
  /// \a max_cstr_len is greater than the actual length of the string,
  /// the string length will be truncated. This allows substrings to
  /// be created without the need to NULL terminate the string as it
  /// is passed into this function.
  ///
  /// @param[in] cstr
  ///     A pointer to the first character in the C string. The C
  ///     string can be NULL terminated in a buffer that contains
  ///     more characters than the length of the string, or the
  ///     string can be part of another string and a new substring
  ///     can be created.
  ///
  /// @param[in] max_cstr_len
  ///     The max length of \a cstr. If the string length of \a cstr
  ///     is less than \a max_cstr_len, then the string will be
  ///     truncated. If the string length of \a cstr is greater than
  ///     \a max_cstr_len, then only max_cstr_len bytes will be used
  ///     from \a cstr.
  //------------------------------------------------------------------
  explicit ConstString(const char *cstr, size_t max_cstr_len);

  //------------------------------------------------------------------
  /// Destructor
  ///
  /// Since constant string values are currently not reference counted,
  /// there isn't much to do here.
  //------------------------------------------------------------------
  ~ConstString() = default;

  //----------------------------------------------------------------------
  /// C string equality binary predicate function object for ConstString
  /// objects.
  //----------------------------------------------------------------------
  struct StringIsEqual {
    //--------------------------------------------------------------
    /// C equality test.
    ///
    /// Two C strings are equal when they are contained in ConstString
    /// objects when their pointer values are equal to each other.
    ///
    /// @return
    ///     Returns \b true if the C string in \a lhs is equal to
    ///     the C string value in \a rhs, \b false otherwise.
    //--------------------------------------------------------------
    bool operator()(const char *lhs, const char *rhs) const {
      return lhs == rhs;
    }
  };

  //------------------------------------------------------------------
  /// Convert to bool operator.
  ///
  /// This allows code to check a ConstString object to see if it
  /// contains a valid string using code such as:
  ///
  /// @code
  /// ConstString str(...);
  /// if (str)
  /// { ...
  /// @endcode
  ///
  /// @return
  ///     /b True this object contains a valid non-empty C string, \b
  ///     false otherwise.
  //------------------------------------------------------------------
  explicit operator bool() const { return m_string && m_string[0]; }

  //------------------------------------------------------------------
  /// Assignment operator
  ///
  /// Assigns the string in this object with the value from \a rhs.
  ///
  /// @param[in] rhs
  ///     Another string object to copy into this object.
  ///
  /// @return
  ///     A const reference to this object.
  //------------------------------------------------------------------
  const ConstString &operator=(const ConstString &rhs) {
    m_string = rhs.m_string;
    return *this;
  }

  //------------------------------------------------------------------
  /// Equal to operator
  ///
  /// Returns true if this string is equal to the string in \a rhs.
  /// This operation is very fast as it results in a pointer
  /// comparison since all strings are in a uniqued in a global string
  /// pool.
  ///
  /// @param[in] rhs
  ///     Another string object to compare this object to.
  ///
  /// @return
  ///     @li \b true if this object is equal to \a rhs.
  ///     @li \b false if this object is not equal to \a rhs.
  //------------------------------------------------------------------
  bool operator==(const ConstString &rhs) const {
    // We can do a pointer compare to compare these strings since they
    // must come from the same pool in order to be equal.
    return m_string == rhs.m_string;
  }

  //------------------------------------------------------------------
  /// Not equal to operator
  ///
  /// Returns true if this string is not equal to the string in \a rhs.
  /// This operation is very fast as it results in a pointer
  /// comparison since all strings are in a uniqued in a global string
  /// pool.
  ///
  /// @param[in] rhs
  ///     Another string object to compare this object to.
  ///
  /// @return
  ///     @li \b true if this object is not equal to \a rhs.
  ///     @li \b false if this object is equal to \a rhs.
  //------------------------------------------------------------------
  bool operator!=(const ConstString &rhs) const {
    return m_string != rhs.m_string;
  }

  bool operator<(const ConstString &rhs) const;

  //------------------------------------------------------------------
  /// Get the string value as a C string.
  ///
  /// Get the value of the contained string as a NULL terminated C
  /// string value.
  ///
  /// If \a value_if_empty is nullptr, then nullptr will be returned.
  ///
  /// @return
  ///     Returns \a value_if_empty if the string is empty, otherwise
  ///     the C string value contained in this object.
  //------------------------------------------------------------------
  const char *AsCString(const char *value_if_empty = nullptr) const {
    return (IsEmpty() ? value_if_empty : m_string);
  }

  //------------------------------------------------------------------
  /// Get the string value as a llvm::StringRef
  ///
  /// @return
  ///     Returns a new llvm::StringRef object filled in with the
  ///     needed data.
  //------------------------------------------------------------------
  llvm::StringRef GetStringRef() const {
    return llvm::StringRef(m_string, GetLength());
  }

  //------------------------------------------------------------------
  /// Get the string value as a C string.
  ///
  /// Get the value of the contained string as a NULL terminated C
  /// string value. Similar to the ConstString::AsCString() function,
  /// yet this function will always return nullptr if the string is not
  /// valid. So this function is a direct accessor to the string
  /// pointer value.
  ///
  /// @return
  ///     Returns nullptr the string is invalid, otherwise the C string
  ///     value contained in this object.
  //------------------------------------------------------------------
  const char *GetCString() const { return m_string; }

  //------------------------------------------------------------------
  /// Get the length in bytes of string value.
  ///
  /// The string pool stores the length of the string, so we can avoid
  /// calling strlen() on the pointer value with this function.
  ///
  /// @return
  ///     Returns the number of bytes that this string occupies in
  ///     memory, not including the NULL termination byte.
  //------------------------------------------------------------------
  size_t GetLength() const;

  //------------------------------------------------------------------
  /// Clear this object's state.
  ///
  /// Clear any contained string and reset the value to the an empty
  /// string value.
  //------------------------------------------------------------------
  void Clear() { m_string = nullptr; }

  //------------------------------------------------------------------
  /// Equal to operator
  ///
  /// Returns true if this string is equal to the string in \a rhs.
  /// If case sensitive equality is tested, this operation is very
  /// fast as it results in a pointer comparison since all strings
  /// are in a uniqued in a global string pool.
  ///
  /// @param[in] rhs
  ///     The Left Hand Side const ConstString object reference.
  ///
  /// @param[in] rhs
  ///     The Right Hand Side const ConstString object reference.
  ///
  /// @param[in] case_sensitive
  ///     Case sensitivity. If true, case sensitive equality
  ///     will be tested, otherwise character case will be ignored
  ///
  /// @return
  ///     @li \b true if this object is equal to \a rhs.
  ///     @li \b false if this object is not equal to \a rhs.
  //------------------------------------------------------------------
  static bool Equals(const ConstString &lhs, const ConstString &rhs,
                     const bool case_sensitive = true);

  //------------------------------------------------------------------
  /// Compare two string objects.
  ///
  /// Compares the C string values contained in \a lhs and \a rhs and
  /// returns an integer result.
  ///
  /// NOTE: only call this function when you want a true string
  /// comparison. If you want string equality use the, use the ==
  /// operator as it is much more efficient. Also if you want string
  /// inequality, use the != operator for the same reasons.
  ///
  /// @param[in] lhs
  ///     The Left Hand Side const ConstString object reference.
  ///
  /// @param[in] rhs
  ///     The Right Hand Side const ConstString object reference.
  ///
  /// @param[in] case_sensitive
  ///     Case sensitivity of compare. If true, case sensitive compare
  ///     will be performed, otherwise character case will be ignored
  ///
  /// @return
  ///     @li -1 if lhs < rhs
  ///     @li 0 if lhs == rhs
  ///     @li 1 if lhs > rhs
  //------------------------------------------------------------------
  static int Compare(const ConstString &lhs, const ConstString &rhs,
                     const bool case_sensitive = true);

  //------------------------------------------------------------------
  /// Dump the object description to a stream.
  ///
  /// Dump the string value to the stream \a s. If the contained string
  /// is empty, print \a value_if_empty to the stream instead. If
  /// \a value_if_empty is nullptr, then nothing will be dumped to the
  /// stream.
  ///
  /// @param[in] s
  ///     The stream that will be used to dump the object description.
  ///
  /// @param[in] value_if_empty
  ///     The value to dump if the string is empty. If nullptr, nothing
  ///     will be output to the stream.
  //------------------------------------------------------------------
  void Dump(Stream *s, const char *value_if_empty = nullptr) const;

  //------------------------------------------------------------------
  /// Dump the object debug description to a stream.
  ///
  /// @param[in] s
  ///     The stream that will be used to dump the object description.
  //------------------------------------------------------------------
  void DumpDebug(Stream *s) const;

  //------------------------------------------------------------------
  /// Test for empty string.
  ///
  /// @return
  ///     @li \b true if the contained string is empty.
  ///     @li \b false if the contained string is not empty.
  //------------------------------------------------------------------
  bool IsEmpty() const { return m_string == nullptr || m_string[0] == '\0'; }

  //------------------------------------------------------------------
  /// Set the C string value.
  ///
  /// Set the string value in the object by uniquing the \a cstr
  /// string value in our global string pool.
  ///
  /// If the C string already exists in the global string pool, it
  /// finds the current entry and returns the existing value. If it
  /// doesn't exist, it is added to the string pool.
  ///
  /// @param[in] cstr
  ///     A NULL terminated C string to add to the string pool.
  //------------------------------------------------------------------
  void SetCString(const char *cstr);

  void SetString(const llvm::StringRef &s);

  //------------------------------------------------------------------
  /// Set the C string value and its mangled counterpart.
  ///
  /// Object files and debug symbols often use mangled string to
  /// represent the linkage name for a symbol, function or global.
  /// The string pool can efficiently store these values and their
  /// counterparts so when we run into another instance of a mangled
  /// name, we can avoid calling the name demangler over and over on
  /// the same strings and then trying to unique them.
  ///
  /// @param[in] demangled
  ///     The demangled C string to correlate with the \a mangled
  ///     name.
  ///
  /// @param[in] mangled
  ///     The already uniqued mangled ConstString to correlate the
  ///     soon to be uniqued version of \a demangled.
  //------------------------------------------------------------------
  void SetCStringWithMangledCounterpart(const char *demangled,
                                        const ConstString &mangled);

  //------------------------------------------------------------------
  /// Retrieve the mangled or demangled counterpart for a mangled
  /// or demangled ConstString.
  ///
  /// Object files and debug symbols often use mangled string to
  /// represent the linkage name for a symbol, function or global.
  /// The string pool can efficiently store these values and their
  /// counterparts so when we run into another instance of a mangled
  /// name, we can avoid calling the name demangler over and over on
  /// the same strings and then trying to unique them.
  ///
  /// @param[in] counterpart
  ///     A reference to a ConstString object that might get filled in
  ///     with the demangled/mangled counterpart.
  ///
  /// @return
  ///     /b True if \a counterpart was filled in with the counterpart
  ///     /b false otherwise.
  //------------------------------------------------------------------
  bool GetMangledCounterpart(ConstString &counterpart) const;

  //------------------------------------------------------------------
  /// Set the C string value with length.
  ///
  /// Set the string value in the object by uniquing \a cstr_len bytes
  /// starting at the \a cstr string value in our global string pool.
  /// If trim is true, then \a cstr_len indicates a maximum length of
  /// the CString and if the actual length of the string is less, then
  /// it will be trimmed.
  ///
  /// If the C string already exists in the global string pool, it
  /// finds the current entry and returns the existing value. If it
  /// doesn't exist, it is added to the string pool.
  ///
  /// @param[in] cstr
  ///     A NULL terminated C string to add to the string pool.
  ///
  /// @param[in] cstr_len
  ///     The maximum length of the C string.
  //------------------------------------------------------------------
  void SetCStringWithLength(const char *cstr, size_t cstr_len);

  //------------------------------------------------------------------
  /// Set the C string value with the minimum length between
  /// \a fixed_cstr_len and the actual length of the C string. This
  /// can be used for data structures that have a fixed length to
  /// store a C string where the string might not be NULL terminated
  /// if the string takes the entire buffer.
  //------------------------------------------------------------------
  void SetTrimmedCStringWithLength(const char *cstr, size_t fixed_cstr_len);

  //------------------------------------------------------------------
  /// Get the memory cost of this object.
  ///
  /// Return the size in bytes that this object takes in memory. This
  /// returns the size in bytes of this object, which does not include
  /// any the shared string values it may refer to.
  ///
  /// @return
  ///     The number of bytes that this object occupies in memory.
  ///
  /// @see ConstString::StaticMemorySize ()
  //------------------------------------------------------------------
  size_t MemorySize() const { return sizeof(ConstString); }

  //------------------------------------------------------------------
  /// Get the size in bytes of the current global string pool.
  ///
  /// Reports the size in bytes of all shared C string values,
  /// containers and any other values as a byte size for the
  /// entire string pool.
  ///
  /// @return
  ///     The number of bytes that the global string pool occupies
  ///     in memory.
  //------------------------------------------------------------------
  static size_t StaticMemorySize();

protected:
  //------------------------------------------------------------------
  // Member variables
  //------------------------------------------------------------------
  const char *m_string;
};

//------------------------------------------------------------------
/// Stream the string value \a str to the stream \a s
//------------------------------------------------------------------
Stream &operator<<(Stream &s, const ConstString &str);

} // namespace lldb_private

namespace llvm {
template <> struct format_provider<lldb_private::ConstString> {
  static void format(const lldb_private::ConstString &CS, llvm::raw_ostream &OS,
                     llvm::StringRef Options);
};
}

#endif // liblldb_ConstString_h_
