1 //===-- ConstString.h -------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_ConstString_h_
11 #define liblldb_ConstString_h_
12 #if defined(__cplusplus)
16 #include "lldb/lldb-private.h"
17 #include "llvm/ADT/StringRef.h"
20 namespace lldb_private {
22 //----------------------------------------------------------------------
23 /// @class ConstString ConstString.h "lldb/Core/ConstString.h"
24 /// @brief A uniqued constant string class.
26 /// Provides an efficient way to store strings as uniqued strings. After
27 /// the strings are uniqued, finding strings that are equal to one
28 /// another is very fast as just the pointers need to be compared. It
29 /// also allows for many common strings from many different sources to
30 /// be shared to keep the memory footprint low.
32 /// No reference counting is done on strings that are added to the
33 /// string pool, once strings are added they are in the string pool for
34 /// the life of the program.
35 //----------------------------------------------------------------------
39 //------------------------------------------------------------------
40 /// Default constructor
42 /// Initializes the string to an empty string.
43 //------------------------------------------------------------------
50 //------------------------------------------------------------------
53 /// Copies the string value in \a rhs into this object.
56 /// Another string object to copy.
57 //------------------------------------------------------------------
58 ConstString (const ConstString& rhs) :
59 m_string (rhs.m_string)
63 explicit ConstString (const llvm::StringRef &s);
65 //------------------------------------------------------------------
66 /// Construct with C String value
68 /// Constructs this object with a C string by looking to see if the
69 /// C string already exists in the global string pool. If it doesn't
70 /// exist, it is added to the string pool.
73 /// A NULL terminated C string to add to the string pool.
74 //------------------------------------------------------------------
75 explicit ConstString (const char *cstr);
77 //------------------------------------------------------------------
78 /// Construct with C String value with max length
80 /// Constructs this object with a C string with a length. If
81 /// \a max_cstr_len is greater than the actual length of the string,
82 /// the string length will be truncated. This allows substrings to
83 /// be created without the need to NULL terminate the string as it
84 /// is passed into this function.
87 /// A pointer to the first character in the C string. The C
88 /// string can be NULL terminated in a buffer that contains
89 /// more characters than the length of the string, or the
90 /// string can be part of another string and a new substring
93 /// @param[in] max_cstr_len
94 /// The max length of \a cstr. If the string length of \a cstr
95 /// is less than \a max_cstr_len, then the string will be
96 /// truncated. If the string length of \a cstr is greater than
97 /// \a max_cstr_len, then only max_cstr_len bytes will be used
99 //------------------------------------------------------------------
100 explicit ConstString (const char *cstr, size_t max_cstr_len);
102 //------------------------------------------------------------------
105 /// Since constant string values are currently not reference counted,
106 /// there isn't much to do here.
107 //------------------------------------------------------------------
113 //----------------------------------------------------------------------
114 /// C string equality binary predicate function object for ConstString
116 //----------------------------------------------------------------------
119 //--------------------------------------------------------------
122 /// Two C strings are equal when they are contained in ConstString
123 /// objects when their pointer values are equal to each other.
126 /// Returns \b true if the C string in \a lhs is equal to
127 /// the C string value in \a rhs, \b false otherwise.
128 //--------------------------------------------------------------
129 bool operator()(const char* lhs, const char* rhs) const
135 //------------------------------------------------------------------
136 /// Convert to bool operator.
138 /// This allows code to check a ConstString object to see if it
139 /// contains a valid string using code such as:
142 /// ConstString str(...);
148 /// /b True this object contains a valid non-empty C string, \b
150 //------------------------------------------------------------------
151 explicit operator bool() const
153 return m_string && m_string[0];
156 //------------------------------------------------------------------
157 /// Assignment operator
159 /// Assigns the string in this object with the value from \a rhs.
162 /// Another string object to copy into this object.
165 /// A const reference to this object.
166 //------------------------------------------------------------------
168 operator = (const ConstString& rhs)
170 m_string = rhs.m_string;
174 //------------------------------------------------------------------
175 /// Equal to operator
177 /// Returns true if this string is equal to the string in \a rhs.
178 /// This operation is very fast as it results in a pointer
179 /// comparison since all strings are in a uniqued in a global string
183 /// Another string object to compare this object to.
186 /// @li \b true if this object is equal to \a rhs.
187 /// @li \b false if this object is not equal to \a rhs.
188 //------------------------------------------------------------------
190 operator == (const ConstString& rhs) const
192 // We can do a pointer compare to compare these strings since they
193 // must come from the same pool in order to be equal.
194 return m_string == rhs.m_string;
197 //------------------------------------------------------------------
198 /// Not equal to operator
200 /// Returns true if this string is not equal to the string in \a rhs.
201 /// This operation is very fast as it results in a pointer
202 /// comparison since all strings are in a uniqued in a global string
206 /// Another string object to compare this object to.
209 /// @li \b true if this object is not equal to \a rhs.
210 /// @li \b false if this object is equal to \a rhs.
211 //------------------------------------------------------------------
213 operator != (const ConstString& rhs) const
215 return m_string != rhs.m_string;
219 operator < (const ConstString& rhs) const;
221 //------------------------------------------------------------------
222 /// Get the string value as a C string.
224 /// Get the value of the contained string as a NULL terminated C
227 /// If \a value_if_empty is NULL, then NULL will be returned.
230 /// Returns \a value_if_empty if the string is empty, otherwise
231 /// the C string value contained in this object.
232 //------------------------------------------------------------------
234 AsCString(const char *value_if_empty = NULL) const
236 if (m_string == NULL)
237 return value_if_empty;
241 //------------------------------------------------------------------
242 /// Get the string value as a llvm::StringRef
245 /// Returns a new llvm::StringRef object filled in with the
247 //------------------------------------------------------------------
249 GetStringRef () const
251 return llvm::StringRef (m_string, GetLength());
254 //------------------------------------------------------------------
255 /// Get the string value as a C string.
257 /// Get the value of the contained string as a NULL terminated C
258 /// string value. Similar to the ConstString::AsCString() function,
259 /// yet this function will always return NULL if the string is not
260 /// valid. So this function is a direct accessor to the string
264 /// Returns NULL the string is invalid, otherwise the C string
265 /// value contained in this object.
266 //------------------------------------------------------------------
274 //------------------------------------------------------------------
275 /// Get the length in bytes of string value.
277 /// The string pool stores the length of the string, so we can avoid
278 /// calling strlen() on the pointer value with this function.
281 /// Returns the number of bytes that this string occupies in
282 /// memory, not including the NULL termination byte.
283 //------------------------------------------------------------------
287 //------------------------------------------------------------------
288 /// Clear this object's state.
290 /// Clear any contained string and reset the value to the an empty
292 //------------------------------------------------------------------
299 //------------------------------------------------------------------
300 /// Compare two string objects.
302 /// Compares the C string values contained in \a lhs and \a rhs and
303 /// returns an integer result.
305 /// NOTE: only call this function when you want a true string
306 /// comparision. If you want string equality use the, use the ==
307 /// operator as it is much more efficient. Also if you want string
308 /// inequality, use the != operator for the same reasons.
311 /// The Left Hand Side const ConstString object reference.
314 /// The Right Hand Side const ConstString object reference.
317 /// @li -1 if lhs < rhs
318 /// @li 0 if lhs == rhs
319 /// @li 1 if lhs > rhs
320 //------------------------------------------------------------------
322 Compare (const ConstString& lhs, const ConstString& rhs);
324 //------------------------------------------------------------------
325 /// Dump the object description to a stream.
327 /// Dump the string value to the stream \a s. If the contained string
328 /// is empty, print \a value_if_empty to the stream instead. If
329 /// \a value_if_empty is NULL, then nothing will be dumped to the
333 /// The stream that will be used to dump the object description.
335 /// @param[in] value_if_empty
336 /// The value to dump if the string is empty. If NULL, nothing
337 /// will be output to the stream.
338 //------------------------------------------------------------------
340 Dump (Stream *s, const char *value_if_empty = NULL) const;
342 //------------------------------------------------------------------
343 /// Dump the object debug description to a stream.
346 /// The stream that will be used to dump the object description.
347 //------------------------------------------------------------------
349 DumpDebug (Stream *s) const;
351 //------------------------------------------------------------------
352 /// Test for empty string.
355 /// @li \b true if the contained string is empty.
356 /// @li \b false if the contained string is not empty.
357 //------------------------------------------------------------------
361 return m_string == NULL || m_string[0] == '\0';
364 //------------------------------------------------------------------
365 /// Set the C string value.
367 /// Set the string value in the object by uniquing the \a cstr
368 /// string value in our global string pool.
370 /// If the C string already exists in the global string pool, it
371 /// finds the current entry and returns the existing value. If it
372 /// doesn't exist, it is added to the string pool.
375 /// A NULL terminated C string to add to the string pool.
376 //------------------------------------------------------------------
378 SetCString (const char *cstr);
381 SetString (const llvm::StringRef &s);
383 //------------------------------------------------------------------
384 /// Set the C string value and its mangled counterpart.
386 /// Object files and debug sybmols often use mangled string to
387 /// represent the linkage name for a symbol, function or global.
388 /// The string pool can efficiently store these values and their
389 /// counterparts so when we run into another instance of a mangled
390 /// name, we can avoid calling the name demangler over and over on
391 /// the same strings and then trying to unique them.
393 /// @param[in] demangled
394 /// The demangled C string to correlate with the \a mangled
397 /// @param[in] mangled
398 /// The already uniqued mangled ConstString to correlate the
399 /// soon to be uniqued version of \a demangled.
400 //------------------------------------------------------------------
402 SetCStringWithMangledCounterpart (const char *demangled,
403 const ConstString &mangled);
405 //------------------------------------------------------------------
406 /// Retrieve the mangled or demangled counterpart for a mangled
407 /// or demangled ConstString.
409 /// Object files and debug sybmols often use mangled string to
410 /// represent the linkage name for a symbol, function or global.
411 /// The string pool can efficiently store these values and their
412 /// counterparts so when we run into another instance of a mangled
413 /// name, we can avoid calling the name demangler over and over on
414 /// the same strings and then trying to unique them.
416 /// @param[in] counterpart
417 /// A reference to a ConstString object that might get filled in
418 /// with the demangled/mangled counterpart.
421 /// /b True if \a counterpart was filled in with the counterpart
422 /// /b false otherwise.
423 //------------------------------------------------------------------
425 GetMangledCounterpart (ConstString &counterpart) const;
427 //------------------------------------------------------------------
428 /// Set the C string value with length.
430 /// Set the string value in the object by uniquing \a cstr_len bytes
431 /// starting at the \a cstr string value in our global string pool.
432 /// If trim is true, then \a cstr_len indicates a maximum length of
433 /// the CString and if the actual length of the string is less, then
434 /// it will be trimmed.
436 /// If the C string already exists in the global string pool, it
437 /// finds the current entry and returns the existing value. If it
438 /// doesn't exist, it is added to the string pool.
441 /// A NULL terminated C string to add to the string pool.
443 /// @param[in] cstr_len
444 /// The maximum length of the C string.
445 //------------------------------------------------------------------
447 SetCStringWithLength (const char *cstr, size_t cstr_len);
449 //------------------------------------------------------------------
450 /// Set the C string value with the minimum length between
451 /// \a fixed_cstr_len and the actual length of the C string. This
452 /// can be used for data structures that have a fixed length to
453 /// store a C string where the string might not be NULL terminated
454 /// if the string takes the entire buffer.
455 //------------------------------------------------------------------
457 SetTrimmedCStringWithLength (const char *cstr, size_t fixed_cstr_len);
459 //------------------------------------------------------------------
460 /// Get the memory cost of this object.
462 /// Return the size in bytes that this object takes in memory. This
463 /// returns the size in bytes of this object, which does not include
464 /// any the shared string values it may refer to.
467 /// The number of bytes that this object occupies in memory.
469 /// @see ConstString::StaticMemorySize ()
470 //------------------------------------------------------------------
474 return sizeof(ConstString);
478 //------------------------------------------------------------------
479 /// Get the size in bytes of the current global string pool.
481 /// Reports the the size in bytes of all shared C string values,
482 /// containers and any other values as a byte size for the
483 /// entire string pool.
486 /// The number of bytes that the global string pool occupies
488 //------------------------------------------------------------------
493 //------------------------------------------------------------------
495 //------------------------------------------------------------------
496 const char *m_string;
499 //------------------------------------------------------------------
500 /// Stream the string value \a str to the stream \a s
501 //------------------------------------------------------------------
502 Stream& operator << (Stream& s, const ConstString& str);
504 } // namespace lldb_private
506 #endif // #if defined(__cplusplus)
507 #endif // liblldb_ConstString_h_