string.h

Pegasus is an open-source implementationof the DMTF CIM and WBEM standards. It is designed to be por

	</pre>
    */
    String& append(const Char16& c);

    /** Append n characters from str to this String.
    @param str REVIEWERS: Insert text here.
    @param n REVIEWERS: Insert text here.
    */
    String& append(const Char16* str, Uint32 n);

    /** Append the given String to this String.
	@param str String to append.
	@return This String.
	<pre>
	String test = "abc";
	test.append("def");
	assert(test == "abcdef");
	</pre>
    */
    String& append(const String& str);

    /** Remove size characters from the string starting at the given
	index. If size is PEG_NOT_FOUND, then all characters after index are
	removed.
	@param index Position in string to start remove.
	@param size Number of characters to remove. Default is PEG_NOT_FOUND
	which causes all characters after index to be removed.
	<pre>
	    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);
	</pre>
	@exception IndexOutOfBoundsException If size is greater than
	length of String plus starting index for remove.
    */
    void remove(Uint32 index, Uint32 size = PEG_NOT_FOUND);

    /** Return a new String which is initialzed with <TT>length</TT>
	characters from this string starting at <TT>index</TT>.
	@param index Specifies the index in string to start getting the
	substring.
	@param 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.
	@return String Specifies the Sting with the defined substring.
    */
    String subString(Uint32 index, Uint32 length = PEG_NOT_FOUND) const;

    /** Find the index of the first occurrence of the character c.
	If the character is not found, PEG_NOT_FOUND is returned.
	@param c Char to be found in the String.
	@return Position of the character in the string or PEG_NOT_FOUND if not
	found.
    */
    Uint32 find(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.
        This begins searching from the given index. 
	@param c Char to be found in the String.
	@return 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 string object.
	This function finds one string inside another.
	If the matching substring is not found, PEG_NOT_FOUND is returned.
	@param s String object to be found in the String.
	@return Position of the substring in the String or PEG_NOT_FOUND if not
	found.
    */
    Uint32 find(const String& s) const;

    /** Same as find() but start looking in reverse (last character first).
    	@param c Char16 character to find in String.
	@return Position of the character in the string or PEG_NOT_FOUND if not
	found.
    */
    Uint32 reverseFind(Char16 c) const;

    /** Converts all characters in this string to lowercase characters,
        ICU    : Operation will use default locale or the locale provided
        NON ICU: Operattion will use c runtime function
    */
    void toLower();
#ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
    /** <I><B>Experimental Interface</B></I><BR>
        @param strLocale const char * is the locale to use for the operation.
               If NULL will use the default locale for the process.
        Refer to Locale constants for formating.
    */
    void toLower(const char * strLocale);
#endif

#ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
    /** <I><B>Experimental Interface</B></I><BR>
        Converts all characters in this string to uppercase characters.
        @param strLocale const char * is the locale to use for the operation.
               If NULL will use the default locale for the process.
        ICU    : Operation will use default locale or the locale provided
        NON ICU: Operattion will use c runtime function 
        Refer to Locale constants for formating.   
    */
    void toUpper(const char * strLocale = NULL);
#endif

    /** Compare the first n characters of the two strings.
    	@param s1 First null-terminated string for the comparison.
	@param s2 Second null-terminated string for the comparison.
	@param n Number of characters to compare.
	@return 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, Uint32 n);

    /** Compare two null-terminated strings.
    	@param s1 First null-terminated string for the comparison.
	@param s2 Second null-terminated string for the comparison.
	@return 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 compare(const String& s1, const String& s2);

    /** Compare two null-terminated strings but ignore case.
        @param s1 First null-terminated string for the comparison.
	@param s2 Second null-terminated string for the comparison.
	@return Return -1 if s1 is less than s2; if equal return 0;
	otherwise return 1.

	NOTE: Use the comparison operators <,<= > >= to compare
	String objects.
        ICU    : Operation will use default locale or the locale provided
        NON ICU: Operattion will use c runtime function
    */
    static int compareNoCase(const String& s1, const String& s2);
#ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
    /** <I><B>Experimental Interface</B></I><BR>
        @param strLocale const char * is the locale to use for the operation.
               If NULL will use the default locale for the process.
        Refer to Locale constants for formating.
    */
    static int compareNoCase(const String& s1, const String& s2, const char * strLocale);
#endif

    /** Compare two String objects for equality.
	@param s1 First <TT>String</TT> for comparison.
	@param s2 Second <TT>String</TT> for comparison.

	@return true If the two strings are equal; otherwise, false. For example, 
	<pre>
	    String s1 = "Hello World";
	    String s2 = s1;
	    String s3(s2);
	    assert(String::equal(s1, s3));
	</pre>
    */
    static Boolean equal(const String& str1, const String& str2);

    /** Compares two strings and returns true if they
	are equal indepedent of case of the characters.
	@param str1 First String parameter.
	@param str2 Second String parameter.
	@return true If strings are equal independent of case, flase
        otherwise.

        ICU    : Operation will use default locale or the locale provided
        NON ICU: Operation will use c runtime function
    */
    static Boolean equalNoCase(const String& str1, const String& str2);
#ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
    /** <I><B>Experimental Interface</B></I><BR>
        @param strLocale const char * is the locale to use for the operation.
               If NULL will use the default locale for the process.
        Refer to Locale constants for formating.
    */
    static Boolean equalNoCase(const String& str1, const String& str2, const char * strLocale);
#endif

private:

    StringRep* _rep;
};

/** String operator == tests for equality between two strings of any of the
    types String or char*.
    @return true If the strings are equal; otherwise, false.
    @param str1 REVIEWERS: Insert description here.
    @param str2 REVIEWERS: Insert description here.
*/
PEGASUS_COMMON_LINKAGE Boolean operator==(
    const String& str1,
    const String& str2);

/** String operator ==. Test for equality between two strings.
    @param str1 REVIEWERS: Insert description here.
    @param str2 REVIEWERS: Insert description here.
*/
PEGASUS_COMMON_LINKAGE Boolean operator==(const String& str1, const char* str2);

/** String operator ==. Test for equality between two strings.
    @param str1 REVIEWERS: Insert description here.
    @param str2 REVIEWERS: Insert description here.
*/
PEGASUS_COMMON_LINKAGE Boolean operator==(const char* str1, const String& str2);

/** String operator ==. Test for equality between two strings.
    @param str1 REVIEWERS: Insert description here.
    @param str2 REVIEWERS: Insert description here.
*/
PEGASUS_COMMON_LINKAGE Boolean operator!=(
    const String& str1,
    const String& str2);

/** REVIEWERS: Insert description here.
    @param str REVIEWERS: Insert description here.
    @param os REVIEWERS: Insert description here.
*/
PEGASUS_COMMON_LINKAGE PEGASUS_STD(ostream)& operator<<(
    PEGASUS_STD(ostream)& os,
    const String& str);

/** This overload operator (+) concatenates String objects. For example, 
    <pre>
	String t1 = "abc";
	String t2;
	t2 = t1 + "def"
	assert(t2 == "abcdef");
    </pre>
*/
PEGASUS_COMMON_LINKAGE String operator+(const String& str1, const String& str2);

/** The overload operator (<) compares String obects.
    <pre>
	String t1 = "def";
	String t2 = "a";
	assert (t2 < t1);
    </pre>
    @param str1 REVIEWERS: Insert description here.
    @param str2 REVIEWERS: Insert description here.
*/
PEGASUS_COMMON_LINKAGE Boolean operator<(
    const String& str1,
    const String& str2);

/** The overload operator (<=) compares String objects.
    @param str1 REVIEWERS: Insert description here.
    @param str2 REVIEWERS: Insert description here.
*/
PEGASUS_COMMON_LINKAGE Boolean operator<=(
    const String& str1,
    const String& str2);

/** The overload operator (>) compares String objects.
    @param str1 REVIEWERS: Insert description here.
    @param str2 REVIEWERS: Insert description here.
*/
PEGASUS_COMMON_LINKAGE Boolean operator>(
    const String& str1,
    const String& str2);

/** The overload operator (>=) compares String objects.
    @param str1 REVIEWERS: Insert description here.
    @param str2 REVIEWERS: Insert description here.
*/
PEGASUS_COMMON_LINKAGE Boolean operator>=(
    const String& str1,
    const String& str2);

PEGASUS_NAMESPACE_END

#endif /* Pegasus_String_h */