String
Functions
void * |
|
const void * |
|
class T_As |
|
class T_As |
|
String & |
|
String & |
|
bool |
|
void |
|
unsigned int |
|
int |
|
const char * |
|
int |
|
int |
|
char * |
|
void |
|
void |
|
unsigned short * |
|
unsigned int * |
|
unsigned int |
|
int |
|
int |
|
int |
|
int |
|
int |
|
int |
|
int |
|
unsigned int |
|
bool |
|
bool |
|
String & |
|
String & |
|
String & |
|
String & |
|
String & |
Detailed Description
-
class String : public RED::Object
Unicode string class
@related Displaying Texts
The String class encapsulates all usual string functions in an unicode version. Unicode allows any language string to be encoded. The string internally uses the UTF-8 encoding.
UTF-8 stands for “UCS Transformation Format”. The way a String is accessed is done either using UTF-8 strings or UCS-2 unicode formats or through (char *) pointers, in which case the rough byte array with the string contents is returned.
According on unicode value (left column), the UTF-8 encoded value is described on the right column of the following table:
U-00000000 - U-0000007F:
0xxxxxxx
U-00000080 - U-000007FF:
110xxxxx 10xxxxxx
U-00000800 - U-0000FFFF:
1110xxxx 10xxxxxx 10xxxxxx
U-00010000 - U-001FFFFF:
11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
U-00200000 - U-03FFFFFF:
111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
U-04000000 - U-7FFFFFFF:
1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
“xxxx” represents bits of the value to be encoded in the UTF-8 string. Bits are filled from right to left. Therefore, the beta greek sign (0xE1 Ascii value - 11100001 binary) is represented as 110xxxxx 10xxxxxx => 11000011 10100001.
A key advantage with UTF-8 is that standard Ascii strings using western characters (unicode 0-127) are encoded “as is” in the string, without the need for any encoding on a single byte per character.
Subclassed by RED::ShaderString
Public Functions
-
virtual void *As(const RED::CID &iCID)
Converts the object to an instance of the given type.
- Parameters
iCID – Requested class.
- Returns
An object pointer of the given class on success, NULL otherwise.
-
virtual const void *As(const RED::CID &iCID) const
Converts the object to an instance of the given type.
- Parameters
iCID – Requested class.
- Returns
An object pointer of the given class on success, NULL otherwise.
-
String()
String construction method.
Builds an empty string. The string exists and is ‘\0’ terminated (using a terminating ‘\0’ byte, which is the valid UTF-8 string termination character).
-
String(const RED::String &iInputString)
String copy construction method.
This method duplicates iInputString contents inside This.
- Parameters
iInputString – Input string object to copy in This.
-
String(const char *iInputString, unsigned int iLength = 0)
String construction method from an Ascii formatted character chain.
If the buffer length is 0, a terminal zero is inserted marking the end of the buffer, otherwise the iLength number of bytes is read from the buffer and a terminal zero is added.
- Parameters
iInputString – Input Ascii formatted string. Must be ‘\0’ terminated.
iLength – Optional length of the input buffer.
-
String(char iChar)
String construction method from a single Ascii character.
- Parameters
iChar – Input Ascii character.
-
String(const wchar_t *iInputString)
String construction from a wchar_t buffer.
The input buffer must be zero terminated.
- Parameters
iInputString – Source string to copy in ‘this’.
-
String(unsigned int iLength)
String construction filled with with ‘iLength’ spaces.
Creates a string with an allocated string of ‘iLength’ bytes plus one for the termination character.
- Parameters
iLength – The number of spaces to set into the string.
-
RED_RC operator=(const RED::String &iInputString)
Assigns string content using right operand ‘=’ string.
This method replaces any old string content with the one provided as right hand argument to the ‘=’ operator in the assignment.
- Parameters
iInputString – String to set equal to This.
- Returns
RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed.
-
RED_RC operator=(const char *iInputString)
Assigns string content using right operand ‘=’ UTF8 string.
This method replaces any old string content with the one provided as right hand argument to the ‘=’ operator in the assignment.
- Parameters
iInputString – String to set equal to This.
- Returns
RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed.
-
RED_RC operator=(const wchar_t *iInputString)
Assigns string content using right operand ‘=’ UCS2 string.
This method replaces any old string content with the one provided as right hand argument to the ‘=’ operator in the assignment.
- Parameters
iInputString – String to set equal to This.
- Returns
RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed.
-
RED::String &Add(const RED::String &iAddedString)
Concatenates the provided string with the object content. ‘\0’ terminated result.
This method concatenates iAddedString at the end of this. The resulting string is ‘\0’ terminated.
- Parameters
iAddedString – String being concatenated to This.
- Returns
A reference to this.
-
RED::String &AddAscii(const char *iAscii, int iLength)
Concatenates the provided ASCII string with the object contents. ‘\0’ terminated result.
This method concatenates iAscii at the end of this. The resulting string is ‘\0’ terminated.
- Parameters
iAscii – String being concatenated to this.
iLength – Number of bytes to concatenate in iAscii. Does not include the termination character. The method does nothing if iLength is <= 0.
- Returns
A reference to this.
-
RED_RC operator+=(const RED::String &iAddedString)
Concatenates two strings.
Same as method RED::String::Add.
- Parameters
iAddedString – Reference to the string to concatenate to this.
- Returns
RED_OK if the operation has succeeded
RED_ALLOC_FAILURE if an internal memory allocation has failed.
-
RED::String operator+(const RED::String &iString) const
Gets the concatenation of two strings.
- Parameters
iString – String to be concatenated to this.
- Returns
the concatenation of two strings.
-
bool IsEmpty() const
Returns true if the string is empty.
- Returns
true if the string is empty, false otherwise.
-
void Clear()
Clears the string content, and resets it to an UTF-8 ‘\0’ termination sequence.
This methods clears the string content, and sets a ‘\0’ termination character.
-
unsigned int MemorySize() const
Returns the memory size of the internal string buffer.
- Returns
The memory size of the stored string. Note that this value is 1 byte greater than the string length, due to the termination character at the end.
-
int Length() const
Counts the number of characters.
- Returns
the number of characters in the string.
-
const char *Buffer() const
Returns the untranslated string buffer.
This method returns the untranslated content of the string. The encoding of the returned string is UTF-8.
- Returns
The string content buffer. Note that this buffer is never NULL and contains at least one ‘\0’ termination character.
-
int GetCharBytes(const char *iInputUTF8Char) const
Returns the number of bytes an UTF-8 encoded char is made of.
This method returns the number of bytes composing the UTF-8 character iInputUTF8Char is made of. iInputUTF8Char points to the leading byte of the character.
- Parameters
iInputUTF8Char – UTF-8 encoded character for which we want to know the number of bytes it’s encoded with.
- Returns
The number of bytes of iInputUTF8Char. If the provided address is not valid, the method returns 0.
-
int GetStringBytes() const
Returns the number of bytes composing the provided string.
This method returns the number of bytes composing the UTF-8 encoded string buffer that is provided to the routine. The count occurs until an ‘\0’ termination character is found.
- Returns
The number of bytes the string is made of. The termination character of the string is not included in the returned length.
-
char *GetChar(int iIndex, char *iPreviousChar = NULL) const
Gets a pointer to the leading byte of the n-th string UTF-8 encoded character.
- Parameters
iIndex – Index of the character to access.
iPreviousChar – The position of the previous character in the string. If the provided value is not the previous character of the string, the routine may produce wrong results.
- Returns
The leading byte of the searched character, or NULL if the request was out of bounds.
-
void SetChar(int iPosition, char iChar)
Sets an Ascii character at a given position.
Note that if the character at iPosition is not an Ascii character (0-127 unicode range) then the string contents may become incorrect, as only one byte is replaced using this method, at the first byte of iPosition-th character.
- Parameters
iPosition – Number of the character to set.
iChar – New character to set.
-
void Replace(char iChar1, char iChar2, int iOffset = 0)
Replaces all occurrences of an Ascii character by another.
- Parameters
iChar1 – Character to look for.
iChar2 – Character to replace with.
iOffset – Optional offset to start from (default is 0).
-
RED_RC Replace(const RED::String &iString1, const RED::String &iString2, int iOffset = 0)
Replaces all occurences of a string by another.
-
unsigned short *ToUCS2() const
Converts the string to UCS2 (UTF16) format.
This method converts the content of the string to the UCS-2 “Universal
Character Set” format. A termination character is added at the string’s end (a double 0). All characters are now 16 bits wide.
The buffer in which the string is dumped is dynamically allocated by the call using an internal ‘rmalloc’. The caller must ensure that the created buffer is released using ‘rfree’ after usage.
- Returns
A pointer to the UCS2 converted string (note that the user has to delete the returned string when he doesn’t need it anymore).
-
unsigned int *ToUCS4() const
Converts the string to UCS4 (UTF32) format.
This method converts the content of the string to the UCS-4 “Universal
Character Set” format. A termination character is added at the string’s end (four 0). All characters are now 32 bits wide.
The buffer in which the string is dumped is dynamically allocated by the call using an internal ‘rmalloc’. The caller must ensure that the created buffer is released using ‘rfree’ after usage.
- Returns
A pointer to the UCS4 converted string (note that the user has to delete the returned string when he doesn’t need it anymore).
-
operator wchar_t*() const
Converts the string to native wchar_t format.
This method converts the content of the string to the UCS-2 for windows and UCS-4 for linux and mac.
A termination character is added at the string’s end.
The buffer in which the string is dumped is dynamically allocated by the call using an internal ‘rmalloc’. The caller must ensure that the created buffer is released using ‘rfree’ after usage.
- Returns
A pointer to the UCS2 or UCS4 converted string (note that the user has to delete the returned string when he doesn’t need it anymore).
-
RED_RC SetUTF8Buffer(const char *iUTF8Buffer)
Directly assigns the string UTF-8 encoded buffer.
This method directly overrides the string contents with the provided UTF-8 buffer.
- Parameters
iUTF8Buffer – UTF-8 encoded buffer, that must be NULL terminated.
-
inline unsigned int ToID() const
Converts the string to an hash key using the RED::Object::GetIDFromString method.
- Returns
the ID (hash key) computed from the string.
-
int operator==(const RED::String &iTestedString) const
Tests equality of This with the right hand operator string.
This operator checks at the byte level that the string contents are identical. If they are not, the operator returns 0, and if they are identical, it returns 1.
- Parameters
iTestedString – Right hand string operator compared with this.
-
int operator!=(const RED::String &iTestedString) const
Tests difference of This with the right hand operator string.
This operator checks at the byte level that the string contents are different. If they are not, the operator returns 0, and if they are different, it returns 1.
- Parameters
iTestedString – Right hand string operator compared with this.
-
int Find(const RED::String &iSearchedString, int iOffset = 0) const
Looks for the first occurrence of a string.
- Parameters
iSearchedString – String to look for.
iOffset – offset (in characters) to start the search from (Default is 0).
- Returns
the index of the first char of the searched string on success,
-1 otherwise.
-
int IndexOf(const RED::String &iChar, int iOffset = 0) const
Gets the first occurrence of a character.
- Parameters
iChar – Character to look for.
iOffset – Optional offset to start the search from.
- Returns
the index of the character in the string if found,
-1 otherwise.
-
int LastIndexOf(const RED::String &iChar, int iOffset = 0) const
Gets the first occurrence of a character from the end of the string.
- Parameters
iChar – Character to look for.
iOffset – Optional offset that should be negative. It is added to the position of the last character in the string to compute that search starting offset.
- Returns
the index of the character in the string if found,
-1 otherwise.
-
int Compare(const RED::String &iOther, int iCount = -1) const
Case sensitive comparison of two strings.
- Parameters
iOther – String to compare with.
iCount – Optional number of characters to compare (Default is -1 for the whole string).
- Returns
0 if the strings are identical,
-1 if the first string is less than the second,
+1 if the first string is greater than the second.
-
int CompareNoCase(const RED::String &iOther, int iCount = -1) const
Case insensitive comparison of two strings.
- Parameters
iOther – String to compare with.
iCount – Optional number of characters to compare (Default is -1 for the whole string).
- Returns
0 if the strings are identical,
-1 if the first string is less than the second,
+1 if the first string is greater than the second.
-
unsigned int GetIDFromString() const
Gets a unique id from a string.
Converts the contents of ‘this’ into an unique id that is returned by the call. This id can be used as the identifier on all REDObjects.
- Returns
The unique key computed from the string.
-
bool operator>(const RED::String &iOther) const
Sorting operator.
Compares two strings and returns true if the first is “more” than the second. “More” means longer and/or using characters with Ascii codes superior to those of the other string.
- Returns
true if the string can be sorted after the given one, false otherwise.
-
RED::String Left(int iPosition) const
Gets the substring made of the leftmost characters of the string.
This method returns a string built starting from the first string character and terminated by the character before the one indicated by iPosition.
If iPosition is negative, the method returns the full string. If iPosition is greater or equal to the string length, the full string is returned.
- Parameters
iPosition – position of the first character not included into the sub-string.
- Returns
the sub-string from 0 to (iPosition - 1).
-
RED::String Right(int iPosition) const
Gets the substring made of the rightmost characters of the string.
This method returns a string built starting from the character indicated by iPosition and ends at the string’s end.
If iPosition is negative, the method returns the full string. If iPosition is greater or equal to the string length, an empty string is returned.
- Parameters
iPosition – position of the last character not included into the sub-string.
- Returns
the sub-string from (iPosition + 1) to (string length - 1).
-
RED::String Mid(int iPosition, int iLength = -1) const
Extracts a substring of a given length from a given position.
This method returns the substring of length iLength that starts at position iPosition in the string.
If iPosition is negative, the full string is returned.
If iPosition is greater or equal to the string length, an empty string is returned.
If iPosition + iLength is greater than the string length, the returned string ends at the string’s end.- Parameters
iPosition – Position to start extraction from.
iLength – Length of the extracted string; if iLength is < 0 or bigger than the count of characters left from iPosition, the full sub-string starting at iPosition is returned.
- Returns
the sub-string starting at iPosition of length iLength.
-
bool operator<(const RED::String &iOther) const
Sorting operator.
Compares two strings and returns true if the first is “less” than the second. “Less” means shorter and/or using characters with Ascii codes inferior to those of the other string.
- Returns
true if the string can be sorted before the given one, false otherwise.
-
RED::String &Arg(const RED::String &iArg)
Replaces the lowest occurence of %1, %2, … n by the provided string.
example:
RED::String( "Red %1 Development %2" ).arg( "Software" ).arg( "Kit" );
will return
"Red Software Development Kit"- Parameters
iArg – the string to insert.
- Returns
a reference to the modified string.
-
RED::String &Arg(RED::int64 iArg)
Replaces the lowest occurence of %1, %2, … n by the provided integer.
example:
RED::String( "1 = %1 - %2" ).arg( 4 ).arg( 3 );
will return
"1 = 4 - 3"- Parameters
iArg – the integer to insert.
- Returns
a reference to the modified string.
-
RED::String &Arg(RED::uint64 iArg)
Replaces the lowest occurence of %1, %2, … n by the provided unsigned integer.
example:
RED::String( "1 = %1 - %2" ).arg( 4 ).arg( 3 );
will return
"1 = 4 - 3"- Parameters
iArg – the unsigned integer to insert.
- Returns
a reference to the modified string.
-
virtual void *As(const RED::CID &iCID)
