aboutsummaryrefslogtreecommitdiff
path: root/include/lldb/Core/ConstString.h
blob: 684cc8f921ed8565f22fba06be47818a1a3c4dcb (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
//===-- 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_
#if defined(__cplusplus)

#include <assert.h>

#include "lldb/lldb-private.h"
#include "llvm/ADT/StringRef.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 (NULL)
    {
    }


    //------------------------------------------------------------------
    /// 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 ()
    {
    }


    //----------------------------------------------------------------------
    /// 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 NULL, then NULL 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 = NULL) const
    {
        if (m_string == NULL)
            return value_if_empty;
        return 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 NULL if the string is not
    /// valid. So this function is a direct accessor to the string 
    /// pointer value.
    ///
    /// @return
    ///     Returns NULL 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 = NULL;
    }

    //------------------------------------------------------------------
    /// 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 
    /// comparision. 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 NULL, 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 NULL, nothing
    ///     will be output to the stream.
    //------------------------------------------------------------------
    void
    Dump (Stream *s, const char *value_if_empty = NULL) 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 == NULL || 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 sybmols 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 sybmols 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 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  // #if defined(__cplusplus)
#endif  // liblldb_ConstString_h_