Util::String Class Reference
#include <string.h>
Detailed Description
Nebula3's universal string class. An empty string object is always 32 bytes big. The string class tries to avoid costly heap allocations with the following tactics:
- a local embedded buffer is used if the string is short enough
- if a heap buffer must be allocated, care is taken to reuse an existing buffer instead of allocating a new buffer if possible (usually if an assigned string fits into the existing buffer, the buffer is reused and not re-allocated)
Heap allocations are performed through a local heap which should be faster then going through the process heap.
Besides the usual string manipulation methods, the String class also offers methods to convert basic Nebula3 datatypes from and to string, and a group of methods which manipulate filename strings.
(C) 2006 RadonLabs GmbH
Public Member Functions | |
| void * | operator new (size_t s) |
| override new operator | |
| void | operator delete (void *ptr) |
| override delete operator | |
| String () | |
| constructor | |
| String (const String &rhs) | |
| copy constructor | |
| String (const char *cStr) | |
| construct from C string | |
| ~String () | |
| destructor | |
| void | operator= (const String &rhs) |
| assignment operator | |
| void | operator= (const char *cStr) |
| assign from const char* | |
| void | operator+= (const String &rhs) |
| += operator | |
| char | operator[] (IndexT i) const |
| read-only index operator | |
| char & | operator[] (IndexT i) |
| read/write index operator | |
| void | Reserve (SizeT newSize) |
| reserve internal buffer size to prevent heap allocs | |
| SizeT | Length () const |
| return length of string | |
| void | Clear () |
| clear the string | |
| bool | IsEmpty () const |
| return true if string object is empty | |
| bool | IsValid () const |
| return true if string object is not empty | |
| bool | CopyToBuffer (char *buf, SizeT bufSize) const |
| copy to char buffer (return false if buffer is too small) | |
| void | Append (const String &str) |
| append string | |
| void | Append (const char *str) |
| append c-string | |
| void | AppendRange (const char *str, SizeT numChars) |
| append a range of characters | |
| void | ToLower () |
| convert string to lower case | |
| void | ToUpper () |
| convert string to upper case | |
| void | FirstCharToUpper () |
| convert first char of string to upper case | |
| SizeT | Tokenize (const String &whiteSpace, Array< String > &outTokens) const |
| tokenize string into a provided String array (faster if tokens array can be reused) | |
| Array< String > | Tokenize (const String &whiteSpace) const |
| tokenize string into a provided String array, SLOW since new array will be constructed | |
| SizeT | Tokenize (const String &whiteSpace, char fence, Array< String > &outTokens) const |
| tokenize string, keep strings within fence characters intact (faster if tokens array can be reused) | |
| Array< String > | Tokenize (const String &whiteSpace, char fence) const |
| tokenize string, keep strings within fence characters intact, SLOW since new array will be constructed | |
| String | ExtractRange (IndexT fromIndex, SizeT numChars) const |
| extract substring | |
| String | ExtractToEnd (IndexT fromIndex) const |
| extract substring to end of this string | |
| void | Strip (const String &charSet) |
| terminate string at first occurence of character in set | |
| IndexT | FindStringIndex (const String &s, IndexT startIndex=0) const |
| return start index of substring, or InvalidIndex if not found | |
| IndexT | FindCharIndex (char c, IndexT startIndex=0) const |
| return index of character in string, or InvalidIndex if not found | |
| void | TerminateAtIndex (IndexT index) |
| terminate string at given index | |
| bool | ContainsCharFromSet (const String &charSet) const |
| returns true if string contains any character from set | |
| void | TrimLeft (const String &charSet) |
| delete characters from charset at left side of string | |
| void | TrimRight (const String &charSet) |
| delete characters from charset at right side of string | |
| void | Trim (const String &charSet) |
| trim characters from charset at both sides of string | |
| void | SubstituteString (const String &str, const String &substStr) |
| substitute every occurance of a string with another string | |
| void | SubstituteChar (char c, char subst) |
| substiture every occurance of a character with another character | |
| void __cdecl | Format (const char *fmtString,...) |
| format string printf-style | |
| void __cdecl | FormatArgList (const char *fmtString, va_list argList) |
| format string printf-style with varargs list | |
| bool | CheckValidCharSet (const String &charSet) const |
| return true if string only contains characters from charSet argument | |
| void | ReplaceChars (const String &charSet, char replacement) |
| replace any char set character within a srtring with the replacement character | |
| IndexT | HashCode () const |
| return a 32-bit hash code for the string | |
| void | SetCharPtr (const char *s) |
| set content to char ptr | |
| void | Set (const char *ptr, SizeT length) |
| set as char ptr, with explicit length | |
| void | SetInt (int val) |
| set as int value | |
| void | SetFloat (float val) |
| set as float value | |
| void | SetBool (bool val) |
| set as bool value | |
| void | SetFloat2 (const Math::float2 &v) |
| set as float2 value | |
| void | SetFloat4 (const Math::float4 &v) |
| set as float4 value | |
| void | SetMatrix44 (const Math::matrix44 &v) |
| set as matrix44 value | |
| template<typename T> | |
| void | Set (const T &t) |
| generic setter | |
| void | AppendInt (int val) |
| append int value | |
| void | AppendFloat (float val) |
| append float value | |
| void | AppendBool (bool val) |
| append bool value | |
| void | AppendFloat2 (const Math::float2 &v) |
| append float2 value | |
| void | AppendFloat4 (const Math::float4 &v) |
| append float4 value | |
| void | AppendMatrix44 (const Math::matrix44 &v) |
| append matrix44 value | |
| template<typename T> | |
| void | Append (const T &t) |
| generic append | |
| const char * | AsCharPtr () const |
| return contents as character pointer | |
| const char * | Get () const |
| *** OBSOLETE *** only Nebula2 compatibility | |
| int | AsInt () const |
| return contents as integer | |
| float | AsFloat () const |
| return contents as float | |
| bool | AsBool () const |
| return contents as bool | |
| Math::float2 | AsFloat2 () const |
| return contents as float2 | |
| Math::float4 | AsFloat4 () const |
| return contents as float4 | |
| Math::matrix44 | AsMatrix44 () const |
| return contents as matrix44 | |
| template<typename T> | |
| T | As () const |
| convert to "anything" | |
| bool | IsValidInt () const |
| return true if the content is a valid integer | |
| bool | IsValidFloat () const |
| return true if the content is a valid float | |
| bool | IsValidBool () const |
| return true if the content is a valid bool | |
| bool | IsValidFloat2 () const |
| return true if the content is a valid float2 | |
| bool | IsValidFloat4 () const |
| return true if the content is a valid float4 | |
| bool | IsValidMatrix44 () const |
| return true if content is a valid matrix44 | |
| template<typename T> | |
| bool | IsValid () const |
| generic valid checker | |
| String | GetFileExtension () const |
| get filename extension without dot | |
| bool | CheckFileExtension (const String &ext) const |
| check file extension | |
| void | ConvertBackslashes () |
| convert backslashes to slashes | |
| void | StripFileExtension () |
| remove file extension | |
| void | ChangeFileExtension (const Util::String &newExt) |
| change file extension | |
| String | ExtractFileName () const |
| extract the part after the last directory separator | |
| String | ExtractLastDirName () const |
| extract the last directory of the path | |
| String | ExtractDirName () const |
| extract the part before the last directory separator | |
| String | ExtractToLastSlash () const |
| extract path until last slash | |
| void | ReplaceIllegalFilenameChars (char replacement) |
| replace illegal filename characters | |
Static Public Member Functions | |
| static String | Concatenate (const Array< String > &strArray, const String &whiteSpace) |
| concatenate array of strings into new string | |
| static bool | MatchPattern (const String &str, const String &pattern) |
| pattern matching | |
| static String | FromInt (int i) |
| construct a string from an int | |
| static String | FromFloat (float f) |
| construct a string from a float | |
| static String | FromBool (bool b) |
| construct a string from a bool | |
| static String | FromFloat2 (const Math::float2 &v) |
| construct a string from float2 | |
| static String | FromFloat4 (const Math::float4 &v) |
| construct a string from float4 | |
| static String | FromMatrix44 (const Math::matrix44 &m) |
| construct a string from matrix44 | |
| template<typename T> | |
| static String | From (const T &t) |
| convert from "anything" | |
| static bool | IsDigit (char c) |
| test if provided character is a digit (0..9) | |
| static bool | IsAlpha (char c) |
| test if provided character is an alphabet character (A..Z, a..z) | |
| static bool | IsAlNum (char c) |
| test if provided character is an alpha-numeric character (A..Z,a..z,0..9) | |
| static bool | IsLower (char c) |
| test if provided character is a lower case character | |
| static bool | IsUpper (char c) |
| test if provided character is an upper-case character | |
| static int | StrCmp (const char *str0, const char *str1) |
| lowlevel string compare wrapper function | |
| static int | StrLen (const char *str) |
| lowlevel string length function | |
| static const char * | StrChr (const char *str, int c) |
| find character in string | |
|
static Dictionary< String, String > | ParseKeyValuePairs (const String &str) |
| parse key/value pair string ("key0=value0 key1=value1") | |
Friends | |
| bool | operator== (const String &a, const String &b) |
| equality operator | |
| bool | operator== (const String &a, const char *cStr) |
| shortcut equality operator | |
| bool | operator== (const char *cStr, const String &a) |
| shortcut equality operator | |
| bool | operator!= (const String &a, const String &b) |
| inequality operator | |
| bool | operator< (const String &a, const String &b) |
| less-then operator | |
| bool | operator> (const String &a, const String &b) |
| greater-then operator | |
| bool | operator<= (const String &a, const String &b) |
| less-or-equal operator | |
| bool | operator>= (const String &a, const String &b) |
| greater-then operator | |
Member Function Documentation
| char & Util::String::operator[] | ( | IndexT | i | ) | [inline] |
read/write index operator
NOTE: unlike the read-only indexer, the terminating 0 is NOT a valid part of the string because it may not be overwritten!!!
| void Util::String::Reserve | ( | SizeT | newSize | ) | [inline] |
reserve internal buffer size to prevent heap allocs
Reserves internal space to prevent excessive heap re-allocations. If you plan to do many Append() operations this may help alot.
tokenize string into a provided String array, SLOW since new array will be constructed
This is the slow-but-convenient Tokenize() method. Slow since the returned string array will be constructed anew with every method call. Consider the Tokenize() method which takes a string array as input, since this may allow reusing of the array, reducing heap allocations.
| SizeT Util::String::Tokenize | ( | const String & | whiteSpace, | |
| char | fence, | |||
| Array< String > & | outTokens | |||
| ) | const |
tokenize string, keep strings within fence characters intact (faster if tokens array can be reused)
Tokenize a string, but keeps the string within the fence-character intact. For instance for the sentence:
He said: "I don't know."
A Tokenize(" ", '"', tokens) would return:
token 0: He token 1: said: token 2: I don't know.
tokenize string, keep strings within fence characters intact, SLOW since new array will be constructed
Slow version of Tokenize() with fence character. See above Tokenize() for details.
| String Util::String::ExtractRange | ( | IndexT | from, | |
| SizeT | numChars | |||
| ) | const |
extract substring
Extract a substring range.
| String Util::String::ExtractToEnd | ( | IndexT | fromIndex | ) | const |
extract substring to end of this string
Extract a substring until the end of the original string.
| void Util::String::Strip | ( | const String & | charSet | ) |
terminate string at first occurence of character in set
Terminates the string at the first occurance of one of the characters in charSet.
| IndexT Util::String::FindStringIndex | ( | const String & | s, | |
| IndexT | startIndex = 0 | |||
| ) | const |
return start index of substring, or InvalidIndex if not found
Return the index of a substring, or InvalidIndex if not found.
| IndexT Util::String::FindCharIndex | ( | char | c, | |
| IndexT | startIndex = 0 | |||
| ) | const |
return index of character in string, or InvalidIndex if not found
Return index of character in string, or InvalidIndex if not found.
| void Util::String::TerminateAtIndex | ( | IndexT | index | ) |
terminate string at given index
Terminates the string at the given index.
| bool Util::String::ContainsCharFromSet | ( | const String & | charSet | ) | const |
returns true if string contains any character from set
Returns true if string contains one of the characters from charset.
| void Util::String::TrimLeft | ( | const String & | charSet | ) |
delete characters from charset at left side of string
Removes all characters in charSet from the left side of the string.
| void Util::String::TrimRight | ( | const String & | charSet | ) |
delete characters from charset at right side of string
Removes all characters in charSet from the right side of the string.
| void Util::String::Trim | ( | const String & | charSet | ) |
trim characters from charset at both sides of string
Trim both sides of a string.
substitute every occurance of a string with another string
Substitute every occurance of origStr with substStr.
| void Util::String::SubstituteChar | ( | char | c, | |
| char | subst | |||
| ) | [inline] |
substiture every occurance of a character with another character
Replace character with another.
| bool Util::String::CheckValidCharSet | ( | const String & | charSet | ) | const [inline] |
return true if string only contains characters from charSet argument
Return true if the string only contains characters which are in the defined character set.
pattern matching
Pattern-matching, TCL-style.
| IndexT Util::String::HashCode | ( | ) | const [inline] |
return a 32-bit hash code for the string
This method computes a hash code for the string. The method is compatible with the Util::HashTable class.
| void Util::String::Set | ( | const char * | str, | |
| SizeT | length | |||
| ) |
set as char ptr, with explicit length
Sets a new string content. This will handle all special cases and try to minimize heap allocations as much as possible.
| int Util::String::AsInt | ( | ) | const |
return contents as integer
Returns content as integer. Note: this method doesn't check whether the contents is actually a valid integer. Use the IsValidInteger() method for this!
| float Util::String::AsFloat | ( | ) | const |
return contents as float
Returns content as float. Note: this method doesn't check whether the contents is actually a valid float. Use the IsValidInt() method for this!
| Math::float2 Util::String::AsFloat2 | ( | ) | const [inline] |
return contents as float2
Returns content as float2. Note: this method doesn't check whether the contents is actually a valid float4. Use the IsValidFloat2() method for this!
| Math::float4 Util::String::AsFloat4 | ( | ) | const [inline] |
return contents as float4
Returns content as float4. Note: this method doesn't check whether the contents is actually a valid float4. Use the IsValidFloat4() method for this!
| Math::matrix44 Util::String::AsMatrix44 | ( | ) | const |
return contents as matrix44
Returns content as matrix44. Note: this method doesn't check whether the contents is actually a valid matrix44. Use the IsValidMatrix44() method for this!
| bool Util::String::IsValidFloat | ( | ) | const [inline] |
return true if the content is a valid float
Note: this method is not 100% correct, it just checks for invalid characters.
| bool Util::String::IsValidFloat2 | ( | ) | const [inline] |
return true if the content is a valid float2
Note: this method is not 100% correct, it just checks for invalid characters.
| bool Util::String::IsValidFloat4 | ( | ) | const [inline] |
return true if the content is a valid float4
Note: this method is not 100% correct, it just checks for invalid characters.
| bool Util::String::IsValidMatrix44 | ( | ) | const [inline] |
return true if content is a valid matrix44
Note: this method is not 100% correct, it just checks for invalid characters.
| String Util::String::GetFileExtension | ( | ) | const |
get filename extension without dot
- Returns:
- string representing the filename extension (maybe empty)
| void Util::String::ConvertBackslashes | ( | ) | [inline] |
convert backslashes to slashes
Converts backslashes to slashes.
| void Util::String::StripFileExtension | ( | ) |
remove file extension
Remove the file extension.
| String Util::String::ExtractFileName | ( | ) | const [inline] |
extract the part after the last directory separator
Return a String object containing the part after the last path separator.
| String Util::String::ExtractLastDirName | ( | ) | const |
extract the last directory of the path
Return a String object containing the last directory of the path, i.e. a category.
- 17-Feb-04 floh fixed a bug when the path ended with a slash
| String Util::String::ExtractDirName | ( | ) | const |
extract the part before the last directory separator
Return a String object containing the part before the last directory separator.
NOTE: I left my fix in that returns the last slash (or colon), this was necessary to tell if a dirname is a normal directory or an assign.
- 17-Feb-04 floh fixed a bug when the path ended with a slash
| String Util::String::ExtractToLastSlash | ( | ) | const [inline] |
extract path until last slash
Return a path string object which contains of the complete path up to the last slash. Returns an empty string if there is no slash in the path.