X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFBaseString.h;h=22b55429051ef33b7149c57ff30d22ea38e705b2;hb=07a771d39ebf4c7f26a04aeb3e06f9d7eb1c6dc2;hp=10178ba963755da56c42b320a97e3191993deaff;hpb=84ae32fc9014edf1457554db60000885285034ff;p=platform%2Fframework%2Fnative%2Fappfw.git
diff --git a/inc/FBaseString.h b/inc/FBaseString.h
index 10178ba..22b5542 100644
--- a/inc/FBaseString.h
+++ b/inc/FBaseString.h
@@ -1,5 +1,4 @@
//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
@@ -81,7 +80,7 @@ public:
*
* @since 2.0
*
- * @param[in] capacity The default capacity of this instance
+ * @param[in] capacity The default capacity of this instance
*/
String(int capacity);
@@ -90,16 +89,16 @@ public:
*
* @since 2.0
*
- * @param[in] ch A Unicode character
+ * @param[in] ch The Unicode character
*/
- String(const wchar_t ch);
+ String(wchar_t ch);
/**
* Initializes this instance of %String with the specified Unicode string.
*
* @since 2.0
*
- * @param[in] pValue A pointer to an array of Unicode characters
+ * @param[in] pValue A pointer to the array of Unicode characters
*/
String(const wchar_t* pValue);
@@ -108,7 +107,7 @@ public:
*
* @since 2.0
*
- * @param[in] pValue A pointer to an array of UTF-8 characters
+ * @param[in] pValue A pointer to the array of UTF-8 characters
*/
String(const char* pValue);
@@ -117,36 +116,36 @@ public:
*
* @since 2.0
*
- * @param[in] value An instance of %String
+ * @param[in] value An instance of %String to copy
*/
String(const String& value);
/**
- * TThis destructor overrides Tizen::Base::Object::~Object().
+ * This destructor overrides Tizen::Base::Object::~Object().
*
* @since 2.0
*
- * @remarks The internally allocated memory block is freed when the instance is destroyed.
+ * @remarks The internally allocated memory block is freed when the instance is destroyed.
*/
virtual ~String(void);
/**
- * Returns the Unicode character at the specified @c index.
+ * Gets the Unicode character at the specified index.
*
* @since 2.0
*
- * @return A const reference to the Unicode character
- * @param[in] index An index within the current instance of %String
+ * @return A constant reference to the Unicode character
+ * @param[in] index The index within the current instance of %String
*/
const wchar_t& operator [](int index) const;
/**
- * Returns a reference to the Unicode character at the specified @c index.
+ * Gets a reference to the Unicode character at the specified index.
*
* @since 2.0
*
* @return A reference to the Unicode character
- * @param[in] index An index within the current instance of %String
+ * @param[in] index The index within the current instance of %String
*/
wchar_t& operator [](int index);
@@ -157,7 +156,7 @@ public:
* @since 2.0
*
* @return A reference to the %String instance
- * @param[in] pRhs A pointer to an array of Unicode characters
+ * @param[in] pRhs A pointer to the array of Unicode characters
*/
String& operator =(const wchar_t* pRhs);
@@ -167,7 +166,7 @@ public:
* @since 2.0
*
* @return A reference to the %String instance
- * @param[in] rhs An instance of %String
+ * @param[in] rhs An instance of %String to copy
*/
String& operator =(const String& rhs);
@@ -178,7 +177,7 @@ public:
* @since 2.0
*
* @return A reference to the %String instance
- * @param[in] pRhs A pointer to an array of Unicode characters
+ * @param[in] pRhs A pointer to the array of Unicode characters
*/
String& operator +=(const wchar_t* pRhs);
@@ -198,7 +197,7 @@ public:
*
* @since 2.0
*
- * @return The concatenated %String instance
+ * @return The concatenated %String instance
* @param[in] lhs A reference to the %String instance on the left-hand side of the operator
* @param[in] rhs A reference to the %String instance on the right-hand side of the operator
*/
@@ -209,10 +208,10 @@ public:
*
* @since 2.0
*
- * @return @c true if the text of the specified %String instance equals the calling instance's text, @n
+ * @return @c true if the text of the specified %String instance equals the calling instance's text, @n
* else @c false
- * @param[in] rhs A reference to the %String instance on the right-hand side of the operator
- * @remarks The operator performs an ordinal comparison of each Unicode character.
+ * @param[in] rhs A reference to the %String instance on the right-hand side of the operator
+ * @remarks The operator performs an ordinal comparison of each Unicode character.
*/
bool operator ==(const String& rhs) const;
@@ -221,10 +220,10 @@ public:
*
* @since 2.0
*
- * @return @c true if the text of the specified %String instance is not equal to the calling instance's text, @n
+ * @return @c true if the text of the specified %String instance is not equal to the calling instance's text, @n
* else @c false
* @param[in] rhs A reference to the %String instance on the right-hand side of the operator
- * @remarks The operator performs an ordinal comparison of each Unicode character.
+ * @remarks The operator performs an ordinal comparison of each Unicode character.
*/
bool operator !=(const String& rhs) const;
@@ -244,7 +243,7 @@ public:
* @since 2.0
*
* @return An error code
- * @param[in] ch A @c wchar_t value to insert
+ * @param[in] ch The @c wchar_t value to insert
* @exception E_SUCCESS The method is successful.
*/
result Append(wchar_t ch);
@@ -255,79 +254,79 @@ public:
* @since 2.0
*
* @return An error code
- * @param[in] ch A @c char value to insert
+ * @param[in] ch The @c char value to insert
* @exception E_SUCCESS The method is successful.
*/
result Append(char ch);
/**
- * Appends the string representing the specified 32-bit @c int value to this
+ * Appends the string that represents the specified 32-bit @c int value to this
* instance of %String.
*
* @since 2.0
*
* @return An error code
- * @param[in] i A 32-bit integer value to insert
+ * @param[in] i The 32-bit integer value to insert
* @exception E_SUCCESS The method is successful.
*/
result Append(int i);
/**
- * Appends the string representing the specified @c short value to this
+ * Appends the string that represents the specified @c short value to this
* instance of %String.
*
* @since 2.0
*
* @return An error code
- * @param[in] s A @c short value to insert
+ * @param[in] s The @c short value to insert
* @exception E_SUCCESS The method is successful.
*/
result Append(short s);
/**
- * Appends the string representing the specified @c long value to this
+ * Appends the string that represents the specified @c long value to this
* instance of %String.
*
* @since 2.0
*
* @return An error code
- * @param[in] l A @c long value to insert
+ * @param[in] l The @c long value to insert
* @exception E_SUCCESS The method is successful.
*/
result Append(long l);
/**
- * Appends the string representing the specified @c long @c long value to this
+ * Appends the string that represents the specified @c long @c long value to this
* instance of %String.
*
* @since 2.0
*
* @return An error code
- * @param[in] ll A @c long @c long value to insert
+ * @param[in] ll The @c long @c long value to insert
* @exception E_SUCCESS The method is successful.
*/
result Append(long long ll);
/**
- * Appends the string representing the specified @c float value to this
+ * Appends the string that represents the specified @c float value to this
* instance of %String.
*
* @since 2.0
*
* @return An error code
- * @param[in] f A @c float value to insert
+ * @param[in] f The @c float value to insert
* @exception E_SUCCESS The method is successful.
*/
result Append(float f);
/**
- * Appends the string representing the specified @c double value to this
+ * Appends the string that represents the specified @c double value to this
* instance of %String.
*
* @since 2.0
*
* @return An error code
- * @param[in] d A @c double value to insert
+ * @param[in] d The @c double value to insert
* @exception E_SUCCESS The method is successful.
*/
result Append(double d);
@@ -339,7 +338,7 @@ public:
* @since 2.0
*
* @return An error code
- * @param[in] p A pointer to a Unicode character array
+ * @param[in] p A pointer to the Unicode character array
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG A @c null pointer is passed.
*/
@@ -352,7 +351,7 @@ public:
* @since 2.0
*
* @return An error code
- * @param[in] str An instance of %String to append
+ * @param[in] str An instance of %String to append
* @exception E_SUCCESS The method is successful.
*/
result Append(const String& str);
@@ -370,11 +369,11 @@ public:
*
* @since 2.0
*
- * @return A 32-bit @c signed integer value
+ * @return The 32-bit @c signed integer value
* @param[in] str0 The first %String instance to compare
* @param[in] str1 The second %String instance to compare
- * @remarks This method performs an ordinal comparison of each Unicode
- * character contained in the two given %String instances.
+ * @remarks This method performs an ordinal comparison of each Unicode
+ * character contained in the two given %String instances. @n
* For instance, "U+xxx" is greater than "U+XXX", but smaller than "U+yyy".
*
* @code
@@ -391,15 +390,15 @@ public:
*
* @since 2.0
*
- * @return A 32-bit @c signed integer value
- *@code
+ * @return The 32-bit @c signed integer value
+ * @code
* < 0 if the value of the current instance is less than the value of the specified %String instance
* == 0 if the value of the current instance is equal to the value of the specified %String instance
* > 0 if the value of the current instance is greater than the value of the specified %String instance
- *@endcode
+ * @endcode
* @param[in] str An instance of %String to compare
- * @remarks This method performs an ordinal comparison of each Unicode character. For instance,
- * L"U+xxx" is greater than L"U+XXX", but smaller than L"U+yyy".
+ * @remarks This method performs an ordinal comparison of each Unicode character. @n
+ * For instance, L"U+xxx" is greater than L"U+XXX", but smaller than L"U+yyy".
*/
int CompareTo(const String& str) const;
@@ -411,7 +410,7 @@ public:
* @since 2.0
*
* @return An error code
- * @param[in] minLength A minimum length to ensure
+ * @param[in] minLength The minimum length to ensure
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG The specified @c minLength is negative.
*/
@@ -444,7 +443,7 @@ public:
* else @c false
*
* @remarks This method performs an ordinal comparison of each Unicode
- * character contained in the two given %String instances.
+ * character contained in the two given %String instances.
*/
bool Equals(const String& str, bool caseSensitive) const;
@@ -457,9 +456,12 @@ public:
* @param[in] length The maximum number of wide characters to write, including the terminating @c null character
* @param[in] pFormat The wide character format specifier
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified @c length is negative or @c pFormat is @c null.
- * @remarks If an "l" modifier is present in @c pFormat (for example, L"@%ls"), it is a pointer to an array of wide characters. @n
- * @remarks A pointer to an array of UTF-8 characters is not allowed in the Format() method (for example, Format(20, L"@%s", pUTF8Str)).
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
+ * - The specified @c length is negative.
+ * - The specified @c pFormat is @c null.
+ * @remarks
+ * - If an "l" modifier is present in @c pFormat (for example, L"@%ls"), it is a pointer to an array of wide characters.
+ * - A pointer to an array of UTF-8 characters is not allowed in the Format() method (for example, Format(20, L"@%s", pUTF8Str)).
* The following format specifiers are supported in this method:
* @code
* specifier Output
@@ -496,10 +498,9 @@ public:
*
* @since 2.0
*
- * @return The hash value of the current instance
- * @remarks Two equal instances must return the same hash value. For better performance,
- * the hash function used must generate a random distribution
- * for all inputs.
+ * @return The hash value of the current instance
+ * @remarks Two equal instances must return the same hash value. @n
+ * For better performance, the hash function used must generate a random distribution for all the inputs.
*/
virtual int GetHashCode(void) const;
@@ -512,26 +513,30 @@ public:
* @param[in] indexAt The position of the character
* @param[out] ch The character at the specified index
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result GetCharAt(int indexAt, wchar_t& ch) const;
/**
* Searches for a character in the calling instance. @n
- * Gets the index of the first character that matches to
+ * Gets the index of the first character that matches
* the specified character in this instance.
*
* @since 2.0
*
* @return An error code
* @param[in] ch The Unicode character to locate
- * @param[in] startIndex The starting position of search
+ * @param[in] startIndex The starting position of the search
* @param[out] indexOf The index of the character
- * @exception E_SUCCESS The method is successful.
- * @exception E_OBJ_NOT_FOUND The specified character is not found.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_OBJ_NOT_FOUND The specified character is not found.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c startIndex is either greater than or equal to the length of the current instance.
+ * - The specified @c startIndex is less than @c 0.
*/
result IndexOf(wchar_t ch, int startIndex, int& indexOf) const;
@@ -547,135 +552,153 @@ public:
* @param[out] indexOf The index of the substring
* @exception E_SUCCESS The method is successful.
* @exception E_OBJ_NOT_FOUND The specified string is not found.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c startIndex is either greater than or equal to the length of the current instance.
+ * - The specified @c startIndex is less than @c 0.
*/
result IndexOf(const String& str, int startIndex, int& indexOf) const;
/**
- * Inserts the string representing the specified Unicode character
+ * Inserts the string that represents the specified Unicode character
* at the specified position in the calling instance.
*
* @since 2.0
*
* @return An error code
*
- * @param[in] ch A Unicode character to insert
+ * @param[in] ch The Unicode character to insert
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result Insert(wchar_t ch, int indexAt);
/**
- * Inserts the string representing the specified @c char value
+ * Inserts the string that represents the specified @c char value
* at the specified position in the calling instance.
*
* @since 2.0
*
* @return An error code
*
- * @param[in] ch A @c char value to insert
+ * @param[in] ch The @c char value to insert
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result Insert(char ch, int indexAt);
/**
- * Inserts the string representing the specified 16-bit integer
+ * Inserts the string that represents the specified 16-bit integer
* at the specified position in the calling instance.
*
* @since 2.0
*
* @return An error code
- * @param[in] s A 16-bit integer value to insert
+ * @param[in] s The 16-bit integer value to insert
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result Insert(short s, int indexAt);
/**
- * Inserts the string representing the specified 32-bit integer
+ * Inserts the string that represents the specified 32-bit integer
* at the specified position in the calling instance.
*
* @since 2.0
*
* @return An error code
- * @param[in] i A 32-bit integer value to insert
+ * @param[in] i The 32-bit integer value to insert
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result Insert(int i, int indexAt);
/**
- * Inserts the string representing the specified @c long value
+ * Inserts the string that represents the specified @c long value
* at the specified position in the calling instance.
*
* @since 2.0
*
* @return An error code
- * @param[in] l A @c long value to insert
+ * @param[in] l The @c long value to insert
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result Insert(long l, int indexAt);
/**
- * Inserts the string representing the specified @c long @c long value
+ * Inserts the string that represents the specified @c long @c long value
* at the specified position in the calling instance.
*
* @since 2.0
*
* @return An error code
- * @param[in] ll A @c long @c long value to insert
+ * @param[in] ll The @c long @c long value to insert
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result Insert(long long ll, int indexAt);
/**
- * Inserts the string representing the specified @c float value
+ * Inserts the string that represents the specified @c float value
* at the specified position in the calling instance.
*
* @since 2.0
*
* @return An error code
- * @param[in] f A @c float value to insert
+ * @param[in] f The @c float value to insert
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result Insert(float f, int indexAt);
/**
- * Inserts the string representing the specified @c double value
+ * Inserts the string that represents the specified @c double value
* at the specified position in the calling instance.
*
* @since 2.0
*
* @return An error code
- * @param[in] d A @c double value to insert
+ * @param[in] d The @c double value to insert
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result Insert(double d, int indexAt);
/**
- * Inserts the string representing the specified @c null-terminated
+ * Inserts the string that represents the specified @c null-terminated
* string at the specified position in the calling instance.
*
* @since 2.0
@@ -684,14 +707,16 @@ public:
* @param[in] p An instance of %String to insert
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
* @exception E_INVALID_ARG A @c null pointer is passed.
*/
result Insert(const wchar_t* p, int indexAt);
/**
- * Inserts the string representing the specified instance of %String
+ * Inserts the string that represents the specified instance of %String
* at the specified position in the calling instance.
*
* @since 2.0
@@ -700,8 +725,10 @@ public:
* @param[in] str An instance of %String to insert
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result Insert(const String& str, int indexAt);
@@ -713,12 +740,14 @@ public:
*
* @return An error code
* @param[in] ch The Unicode character to locate
- * @param[in] startIndex The starting position of search
+ * @param[in] startIndex The starting position of the search
* @param[out] indexOf The index of character
* @exception E_SUCCESS The method is successful.
* @exception E_OBJ_NOT_FOUND The specified character is not found.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c startIndex is either greater than or equal to the length of the current instance.
+ * - The specified @c startIndex is less than @c 0.
*/
result LastIndexOf(wchar_t ch, int startIndex, int& indexOf) const;
@@ -730,13 +759,15 @@ public:
*
* @return An error code
* @param[in] str An instance of %String to locate
- * @param[in] startIndex The starting position of search
+ * @param[in] startIndex The starting position of the search
* @param[out] indexOf The index of the substring
* @exception E_SUCCESS The method is successful.
* @exception E_OBJ_NOT_FOUND The specified character is not found.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
- * @remarks If the substring is empty, E_SUCCESS is returned and the value of @c indexOf is set to @c startIndex.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c startIndex is either greater than or equal to the length of the current instance.
+ * - The specified @c startIndex is less than @c 0.
+ * @remarks If the substring is empty, @c E_SUCCESS is returned and the value of @c indexOf is set to @c startIndex.
*/
result LastIndexOf(const String& str, int startIndex, int& indexOf) const;
@@ -749,55 +780,59 @@ public:
* @param[in] startIndex The position where the removal begins
* @param[in] length The number of characters to remove
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
- * - The specified index is out of range. @n
- * - The specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0. @n
- * - The specified @c count is either greater than the length of substring starting from @c startIndex or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c startIndex is either greater than or equal to the length of the current instance.
+ * - The specified @c startIndex is less than @c 0.
+ * - The specified @c count is either greater than the length of the substring starting from @c startIndex.
+ * - The specified @c count is less than @c 0.
*/
result Remove(int startIndex, int length);
/**
- * Replaces all occurrences of the specified characters.
+ * Replaces all the occurrences of the specified characters.
*
* @since 2.0
*
- * @param[in] original The character to replace
- * @param[in] replace The character to replace all occurrences of @c original
+ * @param[in] original The character to replace
+ * @param[in] replace The character to replace all the occurrences of @c original
*/
void Replace(wchar_t original, wchar_t replace);
/**
- * Replaces all occurrences of the specified string.
+ * Replaces all the occurrences of the specified string.
*
* @since 2.0
*
* @return An error code
* @param[in] original An instance of %String to replace
- * @param[in] replace An instance of %String to replace all occurrences of @c original
+ * @param[in] replace An instance of %String to replace all the occurrences of @c original
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG The specified @c original is an empty string.
*/
result Replace(const String& original, const String& replace);
/**
- * Replaces all occurrences of the specified string within the substring
+ * Replaces all the occurrences of the specified string within the substring
* of this instance of %String.
*
* @since 2.0
*
* @return An error code
* @param[in] original An instance of %String to replace
- * @param[in] replace An instance of %String to replace all occurrences of @c original
+ * @param[in] replace An instance of %String to replace all the occurrences of @c original
* @param[in] startIndex The starting position of the substring
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG The specified @c original is an empty string.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c startIndex is either greater than or equal to the length of the current instance.
+ * - The specified @c startIndex is less than @c 0.
*/
result Replace(const String& original, const String& replace, int startIndex);
/**
- * Reverses the sequence of characters in the calling instance.
+ * Reverses the sequence of the characters in the calling instance.
*
* @since 2.0
*
@@ -824,11 +859,13 @@ public:
* @since 2.0
*
* @return An error code
- * @param[in] ch A new character
+ * @param[in] ch The new character
* @param[in] indexAt The position of the character
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c indexAt is either greater than or equal to the length of the current instance.
+ * - The specified @c indexAt is less than @c 0.
*/
result SetCharAt(wchar_t ch, int indexAt);
@@ -841,10 +878,10 @@ public:
* @param[in] newLength The new length
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG The specified @c newLength is negative.
- * @remarks If the new length is greater than the current length, the
- * string is padded with spaces. On the other hand,
- * if the new length is smaller than the current length, then
- * the text contained in this instance is truncated.
+ * @remarks If the new length is greater than the current length, the
+ * string is padded with spaces. @n
+ * On the other hand, if the new length is smaller than the current length, then
+ * the text contained in this instance is truncated.
*/
result SetLength(int newLength);
@@ -857,8 +894,10 @@ public:
* @param[in] startIndex The starting index of the substring
* @param[out] out The substring
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE The specified index is out of range, or
- * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c startIndex is either greater than or equal to the length of the current instance.
+ * - The specified @c startIndex is less than @c 0.
*/
result SubString(int startIndex, String& out) const;
@@ -872,10 +911,12 @@ public:
* @param[in] length The length of the substring
* @param[out] out The substring
* @exception E_SUCCESS The method is successful.
- * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
- * - The specified index is out of range. @n
- * - The specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0. @n
- * - The specified @c length is either greater than the length of substring starting from @c startIndex or less than @c 0.
+ * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
+ * - The specified @c index is out of the valid range.
+ * - The specified @c startIndex is either greater than or equal to the length of the current instance.
+ * - The specified @c startIndex is less than @c 0.
+ * - The specified @c length is either greater than the length of the substring starting from @c startIndex.
+ * - The specified @c length is less than @c 0.
*/
result SubString(int startIndex, int length, String& out) const;
@@ -884,7 +925,7 @@ public:
*
* @since 2.0
*
- * @return @c true if this instance starts with the specified text, @n
+ * @return @c true if this instance starts with the specified text, @n
* else @c false
* @param[in] str The string to match
* @param[in] startIndex The start position of the string
@@ -896,7 +937,7 @@ public:
*
* @since 2.0
*
- * @return @c true if this instance ends with the specified text, @n
+ * @return @c true if this instance ends with the specified text, @n
* else @c false
* @param[in] str An instance of %String to match
*/
@@ -907,13 +948,13 @@ public:
* Gets the lowercase form of the string in the calling instance. @n
* Unicode characters other than the English alphabets are not changed.
*
- * @brief [Deprecated]
- * @deprecated This method is deprecated as a new method has been introduced.
- * Instead of using this method, use the ToLowerCase(%String& out) method that supports Unicode characters other than the English alphabets.
- * @since 2.0
+ * @brief [Deprecated]
+ * @deprecated This method is deprecated as a new method has been introduced.
+ * Instead of using this method, use the ToLowerCase(%String& out) method that supports Unicode characters other than the English alphabets.
+ * @since 2.0
*
* @return An error code
- * @param[out] out An instance of %String that contains the modified value of the calling instance
+ * @param[out] out An instance of %String that contains the modified value of the calling instance
* @exception E_SUCCESS The method is successful.
* @endif
*/
@@ -938,10 +979,10 @@ public:
*
* @brief [Deprecated]
* @deprecated This method is deprecated as a new method has been introduced.
- * Instead of using this method, use the ToUpperCase(%String& out) method that supports Unicode characters other than the English alphabets.
+ * Instead of using this method, use the ToUpperCase(%String& out) method that supports Unicode characters other than the English alphabets.
* @since 2.0
*
- * @return An error code
+ * @return An error code
* @param[out] out An instance of %String that contains the modified value of the calling instance
* @exception E_SUCCESS The method is successful.
* @endif
@@ -954,7 +995,7 @@ public:
*
* @since 2.0
*
- * @return An error code
+ * @return An error code
* @param[out] out An instance of %String that contains the modified value of the calling instance
* @exception E_SUCCESS The method is successful.
*/
@@ -967,7 +1008,7 @@ public:
*
* @brief [Deprecated]
* @deprecated This method is deprecated as a new method has been introduced.
- * Instead of using this method, use the ToLowerCase() method that supports Unicode characters other than the English alphabets.
+ * Instead of using this method, use the ToLowerCase() method that supports Unicode characters other than the English alphabets.
*
* @since 2.0
* @endif
@@ -989,7 +1030,7 @@ public:
*
* @brief [Deprecated]
* @deprecated This method is deprecated as a new method has been introduced.
- * Instead of using this method, use the ToUpperCase() method that supports Unicode characters other than the English alphabets.
+ * Instead of using this method, use the ToUpperCase() method that supports Unicode characters other than the English alphabets.
*
* @since 2.0
* @endif
@@ -1035,7 +1076,7 @@ public:
* @since 2.0
*
* @return A Unicode pointer to the calling instance's internal buffer
- * @remarks GetPointer() does not guarantee that every call to this function returns same address.
+ * @remarks GetPointer() does not guarantee that every call to this method returns the same address.
*/
const wchar_t* GetPointer(void) const;
@@ -1044,14 +1085,14 @@ public:
*
* @since 2.0
*
- * @return @c true if this instance contains the specified substring, @n
- * else @c false
+ * @return @c true if this instance contains the specified substring, @n
+ * else @c false
* @param[in] str The string to match
*/
bool Contains(const String& str) const;
/**
- * A constant holding the default capacity of %String.
+ * The constant holding the default capacity of %String.
*
* @since 2.0
*/
@@ -1082,11 +1123,12 @@ private:
result InitializeToDefault(int capacity);
//
- // Copies __pValue and subtract and initialize __pRefCount
+ // When the reference count is bigger than 1 and it is not UNSHAREABLE, copies__pValue and subtracts and initializes __pRefCount.
+ // If the isUnshareable is true, this method sets the reference count to UNSHAREABLE.
//
- // @since 2.0
+ // @since 2.2
//
- result CopyOnWrite(int capacity);
+ result AboutToModify(int capacity, bool isUnshareable = false);
//
// Swaps member-wisely
@@ -1098,10 +1140,11 @@ private:
int __capacity;
int __length;
mutable int __hash;
- mutable int* __pRefCount;
+ mutable volatile int* __pRefCount;
mutable wchar_t* __pValue;
static const float GROWTH_FACTOR;
+ static const int UNSHAREABLE;
class _StringImpl * __pStringImpl;
friend class _StringImpl;