String Class Reference

#include <String.h>

List of all members.

Public Member Functions

 String ()
 String (const String &str)
 String (const String &str, Uint32 n)
 String (const Char16 *str)
 String (const Char16 *str, Uint32 n)
 String (const char *str)
 String (const char *str, Uint32 n)
 ~String ()
Stringoperator= (const String &str)
Stringassign (const String &str)
Stringassign (const Char16 *str)
Stringassign (const Char16 *str, Uint32 n)
Stringassign (const char *str)
Stringassign (const char *str, Uint32 n)
void clear ()
void reserveCapacity (Uint32 capacity)
Uint32 size () const
const Char16getChar16Data () const
CString getCString () const
Char16operator[] (Uint32 index)
const Char16 operator[] (Uint32 index) const
Stringappend (const Char16 &c)
Stringappend (const Char16 *str, Uint32 n)
Stringappend (const String &str)
void remove (Uint32 index, Uint32 size=PEG_NOT_FOUND)
String subString (Uint32 index, Uint32 n=PEG_NOT_FOUND) const
Uint32 find (Char16 c) const
Uint32 find (Uint32 index, Char16 c) const
Uint32 find (const String &s) const
Uint32 reverseFind (Char16 c) const
void toLower ()

Static Public Member Functions

static int compare (const String &s1, const String &s2, Uint32 n)
static int compare (const String &s1, const String &s2)
static int compareNoCase (const String &s1, const String &s2)
static Boolean equal (const String &s1, const String &s2)
static Boolean equalNoCase (const String &s1, const String &s2)

Static Public Attributes

static const String EMPTY

Detailed Description

This class implements the CIM string type. The intrinsic string format is UTF-16, which is a superset of the UCS-2 characters allowed in CIM strings. Facilities are provided for converting to and from UTF-8 character strings.

Many of the method interfaces refer to a number of characters. In all cases, these characters are counted as 8- or 16-bit memory chunks rather than logical UTF-8 or UTF-16 character chains.


Constructor & Destructor Documentation

String::String (  ) 

Constructs an empty String.

String::String ( const String str  ) 

Constructs a String with the value of another String.

Parameters:
str The String from which to copy the value.
String::String ( const String str,
Uint32  n 
)

Constructs a String with a specified number of characters of the value of another String.

Parameters:
str The String from which to copy the value.
n A Uint32 specifying the number of characters to copy.
Exceptions:
IndexOutOfBoundsException If the specified String does not contain the specified number of characters.
bad_alloc If the construction fails because of a memory allocation failure.
String::String ( const Char16 str  ) 

Constructs a String with the value from a Char16 buffer.

Parameters:
str The Char16 buffer from which to copy the value.
Exceptions:
NullPointer If the buffer pointer is NULL.
bad_alloc If the construction fails because of a memory allocation failure.
String::String ( const Char16 str,
Uint32  n 
)

Constructs a String with a specified number of characters of the value from a Char16 buffer.

Parameters:
str The Char16 buffer from which to copy the value.
n A Uint32 specifying the number of characters to copy.
Exceptions:
NullPointer If the buffer pointer is NULL.
bad_alloc If the construction fails because of a memory allocation failure.
String::String ( const char *  str  ) 

Constructs a String with the value from a C string in UTF-8 format.

Parameters:
str The C string from which to copy the value.
Exceptions:
NullPointer If the C string pointer is NULL.
bad_alloc If the construction fails because of a memory allocation failure.
Exception If the C string contains invalid UTF-8.
String::String ( const char *  str,
Uint32  n 
)

Constructs a String with a specified number of characters of the value from a C string in UTF-8 format.

Parameters:
str The C string from which to copy the value.
n A Uint32 specifying the number of characters to copy.
Exceptions:
NullPointer If the C string pointer is NULL.
bad_alloc If the construction fails because of a memory allocation failure.
Exception If the C string contains invalid UTF-8.
String::~String (  ) 

Destructs a String object.


Member Function Documentation

String& String::append ( const String str  ) 

Appends a String value to the String.

Parameters:
str The String to append.
Returns:
A reference to the String object containing the newly appended characters.
Exceptions:
bad_alloc If the append fails because of a memory allocation failure.
String& String::append ( const Char16 str,
Uint32  n 
)

Appends a specified number of characters to the String from a Char16 buffer.

Parameters:
str The Char16 buffer from which to append the characters.
n A Uint32 specifying the number of characters to append from the buffer.
Returns:
A reference to the String object containing the newly appended characters.
Exceptions:
NullPointer If the buffer pointer is NULL.
bad_alloc If the append fails because of a memory allocation failure.
String& String::append ( const Char16 c  ) 

Appends a character to the String.

Parameters:
c The Char16 character to append.
Returns:
A reference to the String object containing the newly appended character.
Exceptions:
bad_alloc If the append fails because of a memory allocation failure.
String& String::assign ( const char *  str,
Uint32  n 
)

Assigns the value of a String with a specified number of characters of the value from a C string in UTF-8 format.

Parameters:
str The C string from which to copy the value.
n A Uint32 specifying the number of characters to copy.
Returns:
A reference to the target String object with its newly assigned value.
Exceptions:
NullPointer If the C string pointer is NULL.
bad_alloc If the assignment fails because of a memory allocation failure.
Exception If the C string contains invalid UTF-8.
String& String::assign ( const char *  str  ) 

Assigns the value of a String to the value from a C string in UTF-8 format.

Parameters:
str The C string from which to copy the value.
Returns:
A reference to the target String object with its newly assigned value.
Exceptions:
NullPointer If the C string pointer is NULL.
bad_alloc If the assignment fails because of a memory allocation failure.
Exception If the C string contains invalid UTF-8.
String& String::assign ( const Char16 str,
Uint32  n 
)

Assigns the value of a String with a specified number of characters of the value from a Char16 buffer.

Parameters:
str The Char16 buffer from which to copy the value.
n A Uint32 specifying the number of characters to copy.
Returns:
A reference to the target String object with its newly assigned value.
Exceptions:
NullPointer If the buffer pointer is NULL.
bad_alloc If the assignment fails because of a memory allocation failure.
String& String::assign ( const Char16 str  ) 

Assigns the value of a String to the value in a Char16 buffer.

Parameters:
str The Char16 buffer from which to copy the value.
Returns:
A reference to the target String object with its newly assigned value.
Exceptions:
NullPointer If the buffer pointer is NULL.
bad_alloc If the assignment fails because of a memory allocation failure.
String& String::assign ( const String str  ) 

Assigns the value of a String to the value of another String.

Parameters:
str The String from which to copy the value.
Returns:
A reference to the target String object with its newly assigned value.
Exceptions:
bad_alloc If the assignment fails because of a memory allocation failure.
void String::clear (  ) 

Sets a String value to the empty String.

static int String::compare ( const String s1,
const String s2 
) [static]

Compares two String objects. (Note: Use the comparison operators < <= > >= to compare String objects.)

Parameters:
s1 The first String to compare.
s2 The second String to compare.
Returns:
A negative integer if s1 is lexographically less than s2, 0 if s1 and s2 are equal, and a positive integer otherwise.
static int String::compare ( const String s1,
const String s2,
Uint32  n 
) [static]

Compares the first n characters of two String objects.

Parameters:
s1 The first String to compare.
s2 The second String to compare.
n The maximum number of characters to compare.
Returns:
A negative integer if the first n characters of s1 are lexographically less than s2, 0 if the first n characters of s1 and s2 are equal, and a positive integer otherwise.
static int String::compareNoCase ( const String s1,
const String s2 
) [static]

Compares two String objects, ignoring case differences.

Parameters:
s1 The first String to compare.
s2 The second String to compare.
Returns:
A negative integer if s1 is lexographically less than s2, 0 if s1 and s2 are equal, and a positive integer otherwise. (Case differences are ignored in all cases.)
static Boolean String::equal ( const String s1,
const String s2 
) [static]

Compares two String objects for equality. For example,

            String s1 = "Hello World";
            String s2 = s1;
            assert(String::equal(s1, s2));
        
Parameters:
s1 The first String to compare.
s2 The second String to compare.
Returns:
True if the two strings are equal, false otherwise.
static Boolean String::equalNoCase ( const String s1,
const String s2 
) [static]

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

Parameters:
s1 The first String to compare.
s2 The second String to compare.
Returns:
true if the strings are equal independent of case, false otherwise.
Uint32 String::find ( const String s  )  const

Finds the index of the first occurrence of a specified String value in the String. If the String value is not found, PEG_NOT_FOUND is returned.

Parameters:
s The String value to find in the String.
Returns:
The Uint32 index of the beginning of the String value if found, PEG_NOT_FOUND otherwise.
Uint32 String::find ( Uint32  index,
Char16  c 
) const

Finds the index of the first occurrence of a specified character in the String beginning at a specified index. If the character is not found, PEG_NOT_FOUND is returned.

Parameters:
c The Char16 value to find in the String.
index The Uint32 index at which to start the search.
Returns:
The Uint32 index of the character in the String if found, PEG_NOT_FOUND otherwise.
Uint32 String::find ( Char16  c  )  const

Finds the index of the first occurrence of a specified character in the String. If the character is not found, PEG_NOT_FOUND is returned.

Parameters:
c The Char16 value to find in the String.
Returns:
The Uint32 index of the character in the String if found, PEG_NOT_FOUND otherwise.
const Char16* String::getChar16Data (  )  const

Gets a null-terminated Char16 buffer containing the String value. The buffer is valid until the original String object is modified or destructed.

Returns:
A pointer to a null-terminated Char16 buffer containing the String value.
CString String::getCString (  )  const

Gets a CString object containing the String value in UTF-8 format. Important: A character pointer extracted from a CString object is only valid while the CString object exists and is unmodified. (See the CString documentation.) Thus, in the following example, the variable p holds a dangling (invalid) pointer:

              const char * p = (const char *)test.getCString();
        

This situation can be corrected by declaring a CString variable in the same scope.

Returns:
A CString object containing the String value in UTF-8 format.
Exceptions:
bad_alloc If the operation fails because of a memory allocation failure.
String& String::operator= ( const String str  ) 

Assigns the value of a String to the value of another String.

Parameters:
str The String from which to copy the value.
Returns:
A reference to the target String object with its newly assigned value.
Exceptions:
bad_alloc If the assignment fails because of a memory allocation failure.
const Char16 String::operator[] ( Uint32  index  )  const

Gets a specified character from the String value.

Parameters:
index Index of the character to access.
Returns:
The Char16 character at the specified index.
Exceptions:
IndexOutOfBoundsException If the String does not contain a character at the specified index.
Char16& String::operator[] ( Uint32  index  ) 

Gets a specified character from the String value.

Parameters:
index Index of the character to access.
Returns:
The Char16 character at the specified index.
Exceptions:
IndexOutOfBoundsException If the String does not contain a character at the specified index.
void String::remove ( Uint32  index,
Uint32  size = PEG_NOT_FOUND 
)

Removes a specified number of characters from the String starting at a given index. If the number of characters to remove is specified as PEG_NOT_FOUND, then all characters from the index to the end of the String are removed.

Parameters:
index Uint32 position in String from which to remove characters.
size A Uint32 specifying the number of characters to remove. The default value is PEG_NOT_FOUND, which means all characters from the index to the end of the String are to be removed.
Exceptions:
IndexOutOfBoundsException If the index plus the size (if not PEG_NOT_FOUND) is greater than the number of characters in the String.
void String::reserveCapacity ( Uint32  capacity  ) 

Reserves memory for a specified number of (16-bit) characters. This method does not change the size() of the string or any other external behavior. If the capacity of the string is already greater than or equal to the specified size, this method has no effect. The capacity of a String is set only for performance reasons.

Parameters:
capacity A Uint32 specifying the number of characters the String should be prepared to hold.
Uint32 String::reverseFind ( Char16  c  )  const

Finds the index of the last occurrence of a specified character in the String. If the character is not found, PEG_NOT_FOUND is returned.

Parameters:
c The Char16 value to find in the String.
Returns:
The Uint32 index of the character in the String if found, PEG_NOT_FOUND otherwise.
Uint32 String::size (  )  const

Returns the number of characters in a String value. No termination character is included in the count. For example, String("abcd").size() returns 4.

String String::subString ( Uint32  index,
Uint32  n = PEG_NOT_FOUND 
) const

Creates a new String containing up to the specified number of characters from the specified index in the String.

Parameters:
index A Uint32 specifying the index at which to copy characters into the new String.
n A Uint32 specifying the maximum number of characters to copy into the new String. If the value is PEG_NOT_FOUND or is greater than the number of characters from the index to the end of the String, the new String contains all characters from the index to the end of the String.
Returns:
A new String containing up to the specified number of characters from the specified index in the String.
Exceptions:
bad_alloc If the operation fails because of a memory allocation failure.
void String::toLower (  ) 

Converts all characters in the String to lower case.


Member Data Documentation

const String String::EMPTY [static]

Represents an empty string. This value may be used as a convenience to avoid construction of an empty String object.


The documentation for this class was generated from the following file:
  • /root/rpmbuild/BUILD/pegasus/src/Pegasus/Common/String.h