Public Functions
operator+(const String & a, const String & b)
operator+(const String & a, const StringChar * b)
operator+(const String & a, StringChar c)
operator+(const StringChar * a, const String & b)
operator+(StringChar c, const String & a)
1
2//-----------------------------------------------------------------------------
3// Copyright (c) 2012 GarageGames, LLC
4//
5// Permission is hereby granted, free of charge, to any person obtaining a copy
6// of this software and associated documentation files (the "Software"), to
7// deal in the Software without restriction, including without limitation the
8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
9// sell copies of the Software, and to permit persons to whom the Software is
10// furnished to do so, subject to the following conditions:
11//
12// The above copyright notice and this permission notice shall be included in
13// all copies or substantial portions of the Software.
14//
15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
21// IN THE SOFTWARE.
22//-----------------------------------------------------------------------------
23
24#ifndef _TORQUE_STRING_H_
25#define _TORQUE_STRING_H_
26
27#include <cstdarg>
28
29#ifndef _TORQUE_TYPES_H_
30#include "platform/types.h"
31#endif
32
33#include <string.h>
34
35template< class T > class Vector;
36
37
38typedef UTF8 StringChar;
39
40
41/// The String class represents a 0-terminated array of characters.
42class String
43{
44public:
45 class StringData;
46
47 /// Default mode is case sensitive starting from the left
48 enum Mode
49 {
50 Case = 0, ///< Case sensitive
51 NoCase = 1, ///< Case insensitive
52 Left = 0, ///< Start at left end of string
53 Right = 2, ///< Start at right end of string
54 };
55
56 typedef U32 SizeType;
57 typedef StringChar ValueType;
58
59 static const SizeType NPos; ///< Indicates 'not found' when using find() functions
60
61 /// A predefined empty string.
62 static const String EmptyString;
63
64 String();
65 String(const String &str);
66 String(const StringChar *str);
67 String(const StringChar *str, SizeType size); ///< Copy from raw data
68 String(const UTF16 *str);
69 ~String();
70
71 const UTF8 *c_str() const; ///< Return the string as a native type
72 const UTF16 *utf16() const;
73 const UTF8* utf8() const { return c_str(); }
74
75 SizeType length() const; ///< Returns the length of the string in bytes.
76 SizeType size() const; ///< Returns the length of the string in bytes including the NULL terminator.
77 SizeType numChars() const; ///< Returns the length of the string in characters.
78 bool isEmpty() const; ///< Is this an empty string [""]?
79 static bool isEmpty(const char*); // is the input empty?
80 bool isNotEmpty() const { return !isEmpty(); } ///< Is this not an empty string [""]?
81
82 /// Erases all characters in a string.
83 void clear() { *this = EmptyString; }
84
85 bool isShared() const; ///< Is this string's reference count greater than 1?
86 bool isSame( const String& str ) const; ///< Return true if both strings refer to the same shared data.
87
88 U32 getHashCaseSensitive() const; ///< Get the case-sensitive hash of the string [only calculates the hash as necessary]
89 U32 getHashCaseInsensitive() const; ///< Get the case-insensitive hash of the string [only calculates the hash as necessary]
90
91 String& operator=(StringChar);
92 String& operator+=(StringChar);
93 String& operator=(const StringChar*);
94 String& operator+=(const StringChar*);
95 String& operator=(const String&);
96 String& operator+=(const String&);
97
98 /**
99 Compare this string with another.
100 @param str The string to compare against.
101 @param len If len is non-zero, then at most len characters are compared.
102 @param mode Comparison mode.
103 @return Difference between the first two characters that don't match.
104 */
105 S32 compare(const StringChar *str, SizeType len = 0, U32 mode = Case</a>|<a href="/coding/class/classstring/#classstring_1ad23530ba3c445d964722346a3c80771da84aa4530ee3fa8bfa8e0c2305744bff8">Left) const;
106 S32 compare(const String &str, SizeType len = 0, U32 mode = Case</a>|<a href="/coding/class/classstring/#classstring_1ad23530ba3c445d964722346a3c80771da84aa4530ee3fa8bfa8e0c2305744bff8">Left) const; ///< @see compare(const StringChar *, SizeType, U32) const
107 static S32 compare(const char *str1, const char *str2);
108 static S32 compare(const UTF16 *str1, const UTF16 *str2);
109
110 /**
111 Compare two strings for equality.
112 It will use the string hashes to determine inequality.
113 @param str The string to compare against.
114 @param mode Comparison mode - case sensitive or not.
115 */
116 bool equal(const String &str, U32 mode = Case) const;
117
118 SizeType find(StringChar c, SizeType pos = 0, U32 mode = Case</a>|<a href="/coding/class/classstring/#classstring_1ad23530ba3c445d964722346a3c80771da84aa4530ee3fa8bfa8e0c2305744bff8">Left) const;
119 SizeType find(const StringChar *str, SizeType pos = 0, U32 mode = Case</a>|<a href="/coding/class/classstring/#classstring_1ad23530ba3c445d964722346a3c80771da84aa4530ee3fa8bfa8e0c2305744bff8">Left) const;
120 SizeType find(const String &str, SizeType pos = 0, U32 mode = Case</a>|<a href="/coding/class/classstring/#classstring_1ad23530ba3c445d964722346a3c80771da84aa4530ee3fa8bfa8e0c2305744bff8">Left) const;
121
122 String &insert(SizeType pos, const StringChar c) { return insert(pos,&c,1); }
123 String &insert(SizeType pos, const StringChar *str);
124 String &insert(SizeType pos, const String &str);
125 String &insert(SizeType pos, const StringChar *str, SizeType len);
126
127 String &erase(SizeType pos, SizeType len);
128
129 String &replace(SizeType pos, SizeType len, const StringChar *str);
130 String &replace(SizeType pos, SizeType len, const String &str);
131
132 /// Replace all occurrences of character 'c1' with 'c2'
133 String &replace( StringChar c1, StringChar c2 );
134
135 /// Replace all occurrences of StringData 's1' with StringData 's2'
136 String &replace(const String &s1, const String &s2);
137
138 String substr( SizeType pos, SizeType len = -1 ) const;
139
140 /// Remove leading and trailing whitespace.
141 String trim() const;
142
143 /// Replace all characters that need to be escaped for the string to be a valid string literal with their
144 /// respective escape sequences.
145 String expandEscapes() const;
146
147 /// Replace all escape sequences in with their respective character codes.
148 String collapseEscapes() const;
149
150 /// Split the string into its components separated by the given delimiter.
151 void split( const char* delimiter, Vector< String>& outElements ) const;
152
153 /// Return true if the string starts with the given text.
154 bool startsWith( const char* text ) const;
155
156 /// Return true if the string ends with the given text.
157 bool endsWith( const char* text ) const;
158
159 operator const StringChar*() const { return c_str(); }
160
161 StringChar operator []( U32 i ) const { return c_str()[i]; }
162 StringChar operator []( S32 i ) const { return c_str()[i]; }
163
164 bool operator==(const String &str) const;
165 bool operator!=(const String &str) const { return !(*this == str); }
166 bool operator==( StringChar c ) const;
167 bool operator!=( StringChar c ) const { return !(*this == c); }
168 bool operator<(const String &str) const;
169 bool operator>(const String &str) const;
170 bool operator<=(const String &str) const;
171 bool operator>=(const String &str) const;
172
173 friend String operator+(const String &a, StringChar c);
174 friend String operator+(StringChar c, const String &a);
175 friend String operator+(const String &a, const StringChar *b);
176 friend String operator+(const String &a, const String &b);
177 friend String operator+(const StringChar *a, const String &b);
178
179public:
180 /// @name String Utility routines
181 /// @{
182
183 static String ToString(const char *format, ...);
184 static String VToString(const char* format, va_list args);
185
186 static String ToString( bool v );
187 static inline String ToString( U32 v ) { return ToString( "%u", v ); }
188 static inline String ToString( S32 v ) { return ToString( "%d", v ); }
189 static inline String ToString( F32 v ) { return ToString( "%g", v ); }
190 static inline String ToString( F64 v ) { return ToString( "%Lg", v ); }
191
192 static String SpanToString(const char* start, const char* end);
193
194 static String ToLower(const String &string);
195 static String ToUpper(const String &string);
196
197 static String GetTrailingNumber(const char* str, S32& number);
198 static String GetFirstNumber(const char* str, U32& startPos, U32& endPos);
199
200 /// @}
201
202 /// @name Interning
203 ///
204 /// Interning maps identical strings to unique instances so that equality
205 /// amounts to simple pointer comparisons.
206 ///
207 /// Note that using interned strings within global destructors is not safe
208 /// as table destruction runs within this phase as well. Uses o interned
209 /// strings in global destructors is thus dependent on object file ordering.
210 ///
211 /// Also, interned strings are not reference-counted. Once interned, a
212 /// string will persist until shutdown. This is to avoid costly concurrent
213 /// reference counting that would otherwise be necessary.
214 ///
215 /// @{
216
217 /// Return the interned version of the string.
218 /// @note Interning is case-sensitive.
219 String intern() const;
220
221 /// Return true if this string is interned.
222 bool isInterned() const;
223
224 /// @}
225
226 /** An internal support class for ToString().
227 StrFormat manages the formatting of arbitrary length strings.
228 The class starts with a default internal fixed size buffer and
229 moves to dynamic allocation from the heap when that is exceeded.
230 Constructing the class on the stack will result in its most
231 efficient use. This class is meant to be used as a helper class,
232 and not for the permanent storage of string data.
233 @code
234 char* indexString(U32 index)
235 {
236 StrFormat format("Index: %d",index);
237 char* str = new char[format.size()];
238 format.copy(str);
239 return str;
240 }
241 @endcode
242 */
243 class StrFormat
244 {
245 public:
246 StrFormat()
247 : _dynamicBuffer( NULL ),
248 _dynamicSize( 0 ),
249 _len( 0 )
250 {
251 strncpy(_fixedBuffer, "", 2048);
252 }
253
254 StrFormat(const char *formatStr, va_list args)
255 : _dynamicBuffer( NULL ),
256 _dynamicSize( 0 ),
257 _len( 0 )
258 {
259 format(formatStr, args);
260 }
261
262 ~StrFormat();
263
264 S32 format( const char *format, va_list args );
265 S32 formatAppend( const char *format, va_list args );
266 S32 append(const char * str, S32 len);
267 S32 append(const char * str);
268
269 String getString() { return String(c_str(),_len); }
270
271 const char * c_str() const { return _dynamicBuffer ? _dynamicBuffer : _fixedBuffer; }
272
273 void reset()
274 {
275 _len = 0;
276 strncpy(_fixedBuffer, "", 2048);
277 }
278
279 /// Copy the formatted string into the output buffer which must be at least size() characters.
280 char *copy(char* buffer) const;
281
282 /// Return the length of the formated string (does not include the terminating 0)
283 U32 length() const { return _len; };
284
285 public:
286 char _fixedBuffer[2048]; //< Fixed size buffer
287 char *_dynamicBuffer; //< Temporary format buffer
288 U32 _dynamicSize; //< Dynamic buffer size
289 U32 _len; //< Len of the formatted string
290 };
291
292private:
293 String(StringData *str)
294 : _string( str ) {}
295
296 // Generate compile error if operator bool is used. Without this we use
297 // operator const char *, which is always true...including operator bool
298 // causes an ambiguous cast compile error. Making it private is simply
299 // more insurance that it isn't used on different compilers.
300 // NOTE: disable on GCC since it causes hyper casting to U32 on gcc.
301#if !defined(TORQUE_COMPILER_GCC) && !defined(__clang__)
302 operator const bool() const { return false; }
303#endif
304
305 static void copy(StringChar *dst, const StringChar *src, U32 size);
306
307 StringData *_string;
308};
309
310// Utility class for formatting strings.
311class StringBuilder
312{
313 protected:
314
315 ///
316 String::StrFormat mFormat;
317
318 public:
319
320 StringBuilder() {}
321
322 U32 length() const
323 {
324 return mFormat.length();
325 }
326
327 void copy( char* buffer ) const
328 {
329 mFormat.copy( buffer );
330 }
331
332 const char* data() const
333 {
334 return mFormat.c_str();
335 }
336
337 String end()
338 {
339 return mFormat.getString();
340 }
341
342 S32 append( char ch )
343 {
344 char str[2];
345 str[0]=ch;
346 str[1]='\0';
347 return mFormat.append(str);
348 }
349 S32 append( const char* str )
350 {
351 return mFormat.append(str);
352 }
353 S32 append( const String& str )
354 {
355 return mFormat.append( str.c_str(), str.length() );
356 }
357 S32 append( const char* str, U32 length )
358 {
359 return mFormat.append(str,length);
360 }
361 S32 format( const char* fmt, ... )
362 {
363 va_list args;
364 va_start(args, fmt);
365 return mFormat.formatAppend(fmt, args);
366 }
367};
368
369// For use in hash tables and the like for explicitly requesting case sensitive hashing.
370// Meant to only appear in hash table definition (casting will take care of the rest).
371class StringCase : public String
372{
373public:
374 StringCase() : String() {}
375 StringCase(const String & s) : String(s) {}
376};
377
378// For use in hash tables and the like for explicitly requesting case insensitive hashing.
379// Meant to only appear in hash table definition (casting will take care of the rest).
380class StringNoCase : public String
381{
382public:
383 StringNoCase() : String() {}
384 StringNoCase(const String & s) : String(s) {}
385};
386
387class FileName : public String
388{
389public:
390 FileName() : String() {}
391 FileName(const String & s) : String(s) {}
392 FileName & operator=(const String & s) { String::operator=(s); return *this; }
393};
394
395//-----------------------------------------------------------------------------
396
397extern String operator+(const String &a, StringChar c);
398extern String operator+(StringChar c, const String &a);
399extern String operator+(const String &a, const StringChar *b);
400extern String operator+(const String &a, const String &b);
401extern String operator+(const StringChar *a, const String &b);
402
403#endif
404
405
