diff options
Diffstat (limited to 'include/lldb/Utility/ConstString.h')
| -rw-r--r-- | include/lldb/Utility/ConstString.h | 176 |
1 files changed, 84 insertions, 92 deletions
diff --git a/include/lldb/Utility/ConstString.h b/include/lldb/Utility/ConstString.h index fbf1a9bf536e..98b3447abe3e 100644 --- a/include/lldb/Utility/ConstString.h +++ b/include/lldb/Utility/ConstString.h @@ -26,17 +26,17 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ConstString ConstString.h "lldb/Utility/ConstString.h" -/// @brief A uniqued constant string class. +/// 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. +/// 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. +/// 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: @@ -74,11 +74,10 @@ public: //------------------------------------------------------------------ /// 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. + /// 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 @@ -99,8 +98,8 @@ public: //------------------------------------------------------------------ /// Destructor /// - /// Since constant string values are currently not reference counted, - /// there isn't much to do here. + /// Since constant string values are currently not reference counted, there + /// isn't much to do here. //------------------------------------------------------------------ ~ConstString() = default; @@ -112,8 +111,8 @@ public: //-------------------------------------------------------------- /// C equality test. /// - /// Two C strings are equal when they are contained in ConstString - /// objects when their pointer values are equal to each other. + /// 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 @@ -127,8 +126,8 @@ public: //------------------------------------------------------------------ /// Convert to bool operator. /// - /// This allows code to check a ConstString object to see if it - /// contains a valid string using code such as: + /// This allows code to check a ConstString object to see if it contains a + /// valid string using code such as: /// /// @code /// ConstString str(...); @@ -140,7 +139,7 @@ public: /// /b True this object contains a valid non-empty C string, \b /// false otherwise. //------------------------------------------------------------------ - explicit operator bool() const { return m_string && m_string[0]; } + explicit operator bool() const { return !IsEmpty(); } //------------------------------------------------------------------ /// Assignment operator @@ -161,10 +160,9 @@ public: //------------------------------------------------------------------ /// 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. + /// 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. @@ -174,18 +172,17 @@ public: /// @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. + // 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. + /// 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. @@ -203,8 +200,8 @@ public: //------------------------------------------------------------------ /// Get the string value as a C string. /// - /// Get the value of the contained string as a NULL terminated C - /// string value. + /// 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. /// @@ -230,11 +227,10 @@ public: //------------------------------------------------------------------ /// 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. + /// 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 @@ -245,8 +241,8 @@ public: //------------------------------------------------------------------ /// 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. + /// 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 @@ -257,18 +253,18 @@ public: //------------------------------------------------------------------ /// Clear this object's state. /// - /// Clear any contained string and reset the value to the an empty - /// string value. + /// 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. + /// 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. @@ -290,13 +286,13 @@ public: //------------------------------------------------------------------ /// Compare two string objects. /// - /// Compares the C string values contained in \a lhs and \a rhs and - /// returns an integer result. + /// 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. + /// 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. @@ -319,10 +315,9 @@ public: //------------------------------------------------------------------ /// 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. + /// 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. @@ -353,12 +348,12 @@ public: //------------------------------------------------------------------ /// Set the C string value. /// - /// Set the string value in the object by uniquing the \a cstr - /// string value in our global string pool. + /// 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. + /// 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. @@ -370,12 +365,12 @@ public: //------------------------------------------------------------------ /// 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. + /// 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 @@ -389,15 +384,15 @@ public: const ConstString &mangled); //------------------------------------------------------------------ - /// Retrieve the mangled or demangled counterpart for a mangled - /// or demangled ConstString. + /// 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. + /// 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 @@ -413,14 +408,13 @@ public: /// 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. + /// 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. + /// 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. @@ -431,20 +425,19 @@ public: 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. + /// 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 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. @@ -456,9 +449,8 @@ public: //------------------------------------------------------------------ /// 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. + /// 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 |