Pegasus Developers Manual

In file ../../src/Pegasus/Common/String.h:

class PEGASUS_COMMON_LINKAGE String

The Pegasus String C++ Class implements the CIM string type.

Documentation

The Pegasus String C++ Class implements the CIM string type. REVIEWERS: We need more definition here.

Inheritance:

Public Fields
Public Methods

static const String EMPTY

This member is used to represent an empty string. Using this member avoids construction of an empty string (for example, String()).

String()

Default constructor without parameters. This constructor creates a null string. For example,

        String test;


Throws:: bad_alloc Thrown if there is insufficient memory.

String(const String& str)

Copy constructor.


Throws:: bad_alloc Thrown if there is insufficient memory.
Parameters:: str - Specifies the name of the String instance.

String(const String& str, Uint32 n)

Initialize with first n characters from str.


Throws:: bad_alloc Thrown if there is insufficient memory.
Parameters:: str - Specifies the name of the String instance.
n - Specifies the Uint32 size to use for the length of the string object.

String(const Char16* str)

Initialize with str.


Throws:: NullPointer Thrown if str is NULL.
bad_alloc Thrown if there is insufficient memory.
Parameters:: str - Specifies the name of the String instance.

String(const Char16* str, Uint32 n)

Initialize with first n characters of str.


Throws:: NullPointer Thrown if str is NULL.
bad_alloc Thrown if there is insufficient memory.
Parameters:: str - Specifies the name of the String instance.
n - Specifies the Uint32 size.

String(const char* str)

Initialize from a plain C-String:


Throws:: NullPointer Thrown if str is NULL.
bad_alloc Thrown if there is insufficient memory.
Parameters:: str - Specifies the name of the String instance. API supports UTF8

String(const char* str, Uint32 n)

Initialize from the first n characters of a plain C-String:


Throws:: NullPointer Thrown if str is NULL.
bad_alloc Thrown if there is insufficient memory.
Parameters:: str - Specifies the name of the String instance.
u - Specifies the Uint32 size. API supports UTF8

~String()

String destructor

String& operator=(const String& str)

Assign this string with str. For example,

        String t1 = "abc";
        String t2 = t1;

String t2 is assigned the value of t1.


Throws:: bad_alloc Thrown if there is insufficient memory.
Parameters:: str - Specifies the name of the String to assign to another String instance.

String& assign(const String& str)

Assign this string with String str.


Throws:: bad_alloc Thrown if there is insufficient memory.
Parameters:: str - String to assign.
Returns:: Returns the String. API supports UTF8

String& assign(const Char16* str)

Assign this string with str.


Throws:: NullPointer Thrown if str is NULL.
bad_alloc Thrown if there is insufficient memory.

String& assign(const Char16* str, Uint32 n)

Assign this string with first n characters of str.


Throws:: NullPointer Thrown if str is NULL.
bad_alloc Thrown if there is insufficient memory.
Parameters:: n - REVIEWERS: Insert text here.
str - REVIEWERS: Insert text here.

String& assign(const char* str)

Assign this string with the plain C-String str.


Throws:: NullPointer Thrown if str is NULL.
bad_alloc Thrown if there is insufficient memory.
Parameters:: str - REVIEWERS: Insert text here. API supports UTF8

String& assign(const char* str, Uint32 n)

Assign this string with first n characters of the plain C-String str.


Throws:: NullPointer Thrown if str is NULL.
bad_alloc Thrown if there is insufficient memory.
Parameters:: str - REVIEWERS: Insert text here.
n - REVIEWERS: Insert text here. API supports UTF8

void clear()

Clear this string. After calling clear(), size() will return 0.

        String test = "abc";
        test.clear();

void reserveCapacity(Uint32 capacity)

Reserves memory for capacity characters. Notice that this does not change the size of the string (size() returns what it did before). If the capacity of the string is already greater or equal to the capacity argument, this method has no effect. The capacity of a String object has no bearing on its external behavior. The capacity of a String is set only for performance reasons.


Parameters:: capacity - Defines the capacity in characters to reserve.

Uint32 size() const

Returns the length of the String object.

Returns:

Length of the String in characters. For example,

String s = "abcd";
assert(s.size() == 4);

returns a value of 4 for the length.

const Char16* getChar16Data() const

Returns a pointer to the first character in the null-terminated Char16 buffer of the String object.

Returns:

Pointer to the first character of the String object. For example,

String test = "abc";
const Char16* q = test.getChar16Data();

points to the first character in the String instance named test.

CString getCString() const

Create an 8-bit representation of this String object. For example,

Throws:

bad_alloc Thrown if there is insufficient memory.

Returns:

CString object that provides access to the UTF8 String representation.

String test = "abc";
printf("test = %s\n", (const char*)test.getCString());
NOTE:  Do not do the following:
const char * p = (const char *)test.getCString();
The pointer p will be invalid.  This is because
the CString object is destructed, which deletes
the heap space for p.

Char16& operator[](Uint32 index)

Returns the specified character of the String object.

Throws:

IndexOutOfBoundsException If index is outside the bounds of the String.

String test = "abc;
Char16 c = test[1];

Parameters:

index - Index of the character to access.

Returns:

Specified character of the String object.

const Char16 operator[](Uint32 index) const

Returns the specified character of the String object (const version).


Throws:: IndexOutOfBoundsException If index is outside the bounds of the String.
Parameters:: index - Index of the character to access.
Returns:: Specified character of the String object.

String& append(const Char16& c)

Append the given character to this String.

Throws:

bad_alloc Thrown if there is insufficient memory.

Parameters:

c - Character to append.

Returns:

This String.

String test = "abc";
test.append(Char16('d'));
assert(test == "abcd");

String& append(const Char16* str, Uint32 n)

Append n characters from str to this String.


Throws:: NullPointer Thrown if str is NULL.
bad_alloc Thrown if there is insufficient memory.
Parameters:: str - REVIEWERS: Insert text here.
n - REVIEWERS: Insert text here.

String& append(const String& str)

Append the given String to this String.

Throws:

bad_alloc Thrown if there is insufficient memory.

Parameters:

str - String to append.

Returns:

This String.

String test = "abc";
test.append("def");
assert(test == "abcdef");

void remove(Uint32 index, Uint32 size = PEG_NOT_FOUND)

Remove size characters from the string starting at the given index. If size is PEG_NOT_FOUND, then all characters after index are removed.

Throws:

IndexOutOfBoundsException If size is greater than length of String plus starting index for remove.

Parameters:

index - Position in string to start remove.
- size Number of characters to remove. Default is PEG_NOT_FOUND which causes all characters after index to be removed.

String s;
s = "abc";
s.remove(0, 1);
assert(String::equal(s, "bc"));
assert(s.size() == 2);
s.remove(0);
assert(String::equal(s, ""));
assert(s.size() == 0);

String subString(Uint32 index, Uint32 length = PEG_NOT_FOUND) const

Return a new String which is initialzed with length characters from this string starting at index.


Throws:: bad_alloc Thrown if there is insufficient memory.
Parameters:: index - Specifies the index in string to start getting the substring.
length - Specifies the number of characters to get. If length is PEG_NOT_FOUND, then all characters after index are added to the new string.
Returns:: String Specifies the Sting with the defined substring.

Uint32 find(Char16 c) const

Find the index of the first occurrence of the character c. If the character is not found, PEG_NOT_FOUND is returned.


Parameters:: c - Char to be found in the String.
Returns:: Position of the character in the string or PEG_NOT_FOUND if not found.

Uint32 find(Uint32 index, Char16 c) const

Find the index of the first occurence of the character c. If the character is not found, PEG_NOT_FOUND is returned. Searching begins from the specified index.


Parameters:: c - Char to be found in the String.
Returns:: Position of the character in the string or PEG_NOT_FOUND if the character is not found.

Uint32 find(const String& s) const

Find the index of the first occurence of the string object. This function finds one string inside another. If the matching substring is not found, PEG_NOT_FOUND is returned.


Parameters:: s - String object to be found in the String.
Returns:: Position of the substring in the String or PEG_NOT_FOUND if the substring is not found.

Uint32 reverseFind(Char16 c) const

Same as find() but start looking in reverse (last character first).


Parameters:: c - Char16 character to find in String.
Returns:: Position of the character in the string or PEG_NOT_FOUND if the character is not found.

void toLower()

Converts all characters in this string to lowercase characters,

void toUpper()

Experimental Interface
Converts all characters in this string to uppercase characters

static int compare(const String& s1, const String& s2, Uint32 n)

Compare the first n characters of the two strings.


Parameters:: s1 - First null-terminated string for the comparison.
s2 - Second null-terminated string for the comparison.
n - Number of characters to compare.
Returns:: Return -1 If s1 is lexographically less than s2; if they are equivalent return 0; otherwise return 1.

static int compare(const String& s1, const String& s2)

Compare two null-terminated strings.


Parameters:: s1 - First null-terminated string for the comparison.
s2 - Second null-terminated string for the comparison.
Returns:: Return -1 if s1 is less than s2; if equal return 0; otherwise return 1. NOTE: Use the comparison operators <,<= > >= to compare String objects.

static int compareNoCase(const String& s1, const String& s2)

Compare two null-terminated strings but ignore case.


Parameters:: s1 - First null-terminated string for the comparison.
s2 - Second null-terminated string for the comparison.
Returns:: Return -1 if s1 is less than s2; if equal return 0; otherwise return 1. NOTE: Use the comparison operators <,<= > >= to compare String objects.

static Boolean equal(const String& str1, const String& str2)

Compare two String objects for equality.

Parameters:

s1 - First String for comparison.
s2 - Second String for comparison.

Returns:

true If the two strings are equal; otherwise, false. For example,

String s1 = "Hello World";
String s2 = s1;
String s3(s2);
assert(String::equal(s1, s3));

static Boolean equalNoCase(const String& str1, const String& str2)

Compares two strings and returns true if they are equal indepedent of case of the characters.


Parameters:: str1 - First String parameter.
str2 - Second String parameter.
Returns:: true If strings are equal independent of case, flase otherwise.

This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java

class PEGASUS_COMMON_LINKAGE String

Documentation

Inheritance:

Public Fields

Public Methods