mirror of
https://github.com/opnsense/src.git
synced 2026-02-28 04:10:49 -05:00
499 lines
19 KiB
C++
499 lines
19 KiB
C++
//===-- 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_
|
|
|
|
// C Includes
|
|
// C++ Includes
|
|
// Other libraries and framework includes
|
|
#include "llvm/ADT/StringRef.h"
|
|
|
|
// Project includes
|
|
#include "lldb/lldb-private.h"
|
|
|
|
namespace lldb_private {
|
|
|
|
//----------------------------------------------------------------------
|
|
/// @class ConstString ConstString.h "lldb/Core/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;
|
|
}
|
|
|
|
//------------------------------------------------------------------
|
|
/// 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.
|
|
///
|
|
/// @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);
|
|
|
|
//------------------------------------------------------------------
|
|
/// 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
|
|
|
|
#endif // liblldb_ConstString_h_
|