From: Keebong Date: Tue, 29 Oct 2013 00:41:02 +0000 (+0900) Subject: Added ImmutableString class to appfw X-Git-Tag: submit/tizen/20131210.080830~8^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;ds=sidebyside;h=ed8e687b3c5c58018f01d231231cc18c07eb201c;p=platform%2Fframework%2Fnative%2Fappfw.git Added ImmutableString class to appfw Change-Id: Ie362769d4c826a5bb1e0ecf6400bc4d05a44a617 Signed-off-by: Keebong --- diff --git a/inc/FBaseImmutableString.h b/inc/FBaseImmutableString.h new file mode 100644 index 0000000..f681915 --- /dev/null +++ b/inc/FBaseImmutableString.h @@ -0,0 +1,766 @@ +// +// Copyright (c) 2013 Samsung Electronics Co., Ltd. +// +// Licensed under the Apache License, Version 2.0 (the License); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +/** + * @file FBaseImmutableString.h + * @brief This is the header file for the %ImmutableString class. + * + * @since 3.0 + * @final This class is not intended for extension. + * + * This header file contains the declarations of the %ImmutableString class. + */ + +#ifndef _FBASE_IMMUTABLE_STRING_H_ +#define _FBASE_IMMUTABLE_STRING_H_ + +#include + +namespace Tizen { namespace Base +{ +/** + * @class ImmutableString + * @brief This class represents a immutable sequence of Unicode characters. + * + * @since 3.0 + * + * The %ImmutableString class represents a immutable sequence of Unicode characters. + * Mutation operation, such as Append(), Insert() and Remove(), do not change the current instance but return a new instance resulting from applying the operation. + * + * For more information on the class features, see ImmutableString. + * + * The following example demonstrates how to use the %ImmutableString class. + * + * @code + * + * #include + * + * using namespace Tizen::Base; + * + * void + * MyClass::ImmutableStringSample(void) + * { + * ImmutableString str(L"Test"); // str == L"Test" + * + * ImmutableString str1 = str.Append(L"String"); // str1 == L"TestString" + * + * ImmutableString str2 = str1.Insert(L"Immutable", 4); // str2 == L"TestImmutableString" + * + * ImmutableString str3 = str2.Remove(4, 5); // str3 == L"TestableString" + * + * ImmutableString str4 = str3.SubString(4, 4); // str4 == L"able" + * } + * @endcode + */ +class _OSP_EXPORT_ ImmutableString + : public Object +{ +public: + /** + * Initializes %ImmutableString instance with the specified Unicode string. + * + * @since 3.0 + * + * @param[in] pStr A pointer to an array of Unicode characters + * @remark If whcar_t* type null pointer is entered on parameter, the empty string is set. + */ + explicit ImmutableString(const wchar_t* pStr); + + /** + * Initializes %ImmutableString instance with the specified UTF-8 string. + * + * @since 3.0 + * + * @param[in] pStr A pointer to an array of UTF-8 characters + * @remark If char* type null pointer is entered on parameter, the empty string is set. + */ + explicit ImmutableString(const char* pStr); + + /** + * Initializes %ImmutableString instance with the specified %String. + * + * @since 3.0 + * + * @param[in] value An instance of %String + */ + ImmutableString(const String& value); + + /** + * Copying of objects using this copy constructor is allowed. + * + * @since 3.0 + * + * @param[in] value An instance of %ImmutableString + */ + ImmutableString(const ImmutableString& value); + + /** + * This destructor overrides Tizen::Base::Object::~Object(). + * + * @since 3.0 + */ + virtual ~ImmutableString(void); + + /** + * Returns a Unicode character at the specified @c index. + * + * @since 3.0 + * + * @return A Unicode character + * @param[in] index An index within this string + */ + wchar_t operator [](int index) const; + + /** + * Returns a new %ImmutableString instance resulting from appending the specified %ImmutableString to the end of this string. + * + * @since 3.0 + * + * @return The concatenated %ImmutableString instance + * @param[in] str An instance of %ImmutableString to append + */ + ImmutableString Append(const ImmutableString& str) const; + + /** + * Compares the value of the current instance to the value of the specified instance of %ImmutableString. + * + * @since 3.0 + * + * @return A @c signed integer value + * @code + * < 0 if the value of the current instance is less than the value of the specified %ImmutableString instance + * == 0 if the value of the current instance is equal to the value of the specified %ImmutableString instance + * > 0 if the value of the current instance is greater than the value of the specified %ImmutableString instance + * @endcode + * @param[in] str An instance of %ImmutableString 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". + * - This method is not locale-dependent. + */ + int CompareTo(const ImmutableString& str) const; + + /** + * Checks whether this instance contains the specified substring. + * + * @since 3.0 + * + * @return @c true if this instance contains the specified substring, @n + * else @c false + * @param[in] str The string to match + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG The specified @c str is an empty string. + */ + bool Contains(const ImmutableString& str) const; + + /** + * Checks whether the given string is present at the end of the calling instance. + * + * @since 3.0 + * + * @return @c true if this instance ends with the specified text, @n + * else @c false + * @param[in] str An instance to match + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG The specified @c str is an empty string. + */ + bool EndsWith(const ImmutableString& str) const; + + /** + * Checks whether the value of the specified instance of Object is equal to the value of this string. + * + * @since 3.0 + * + * @return @c true if the value of the specified instance of Object is equal to the value of this string, @n + * else @c false + * @param[in] obj An instance of Object to compare + * @remarks This method returns @c false if the specified @c obj is not a string. + * @see Object::Equals() + */ + virtual bool Equals(const Object& obj) const; + + /** + * Checks whether the value of the specified instance is equal to the value of this string. @n + * Case sensitivity is ignored. + * + * @since 3.0 + * + * @return @c true if the values match, @n + * else @c false + * @param[in] str An instance to compare with the calling instance + * + * @remarks This method performs an ordinal comparison of each Unicode + * character contained in the two given %ImmutableString instances. + */ + bool EqualsCaseInsensitive(const ImmutableString& str) const; + + /** + * Formats the inputs as per the specified format and and returns a new %ImmutableString instance. + * + * @since 3.0 + * + * @return An error code + * @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 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 + * --------- ------ + * c single byte character + * d(or i) signed decimal integer + * u unsigned decimal integer + * x unsigned hexadecimal integer + * f decimal floating point + * e scientific notation using e character + * g use the shorter of %e or %f + * s single byte character string + * ls(or S) wide-character string + * lld 64-bit signed decimal integer + * + * @endcode + * + * The following example demonstrates how to use the %Format() method. + * @code + * + * int value = 10; + * wchar_t* testStr = L"TEST"; + * + * ImmutableString str = Tizen::Base::ImmutableString::Format(25, L"FORMAT %d %ls", value, testStr); // str == L"FORMAT 10 TEST" + * + * @endcode + */ + static ImmutableString Format(int length, const wchar_t* pFormat, ...) const; + + /** + * Gets the character at the specified position. + * + * @since 3.0 + * + * @return An error code + * @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 Either of the following conditions has occurred: + * - 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. + * @remark This method does not guarantee a usable value of out-parameter when an error occurs. + */ + result GetCharAt(int indexAt, wchar_t& ch) const; + + /** + * Gets the hash value of the current instance. + * + * @since 3.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. + */ + virtual int GetHashCode(void) const; + + /** + * Gets the length of the text contained in this %ImmutableString instance. + * + * @since 3.0 + * + * @return The length of this %ImmutableString instance + */ + int GetLength(void) const; + + /** + * Gets a pointer to the instance's internal buffer. + * + * @since 3.0 + * + * @return A Unicode pointer to the calling instance's internal buffer + */ + const wchar_t* GetPointer(void) const; + + /** + * Searches for a character in the calling instance. @n + * Gets the index of the first character that matches to the specified character in this instance. + * + * @since 3.0 + * + * @return An error code + * @param[in] ch The Unicode character to locate + * @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 Either of the following conditions has occurred: + * - 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. + * @remark This method does not guarantee a usable value of out-parameter when an error occurs. + */ + result IndexOf(wchar_t ch, int startIndex, int& indexOf) const; + + /** + * Searches for a specified substring in the calling instance. @n + * Gets the starting index of the first occurrence of the specified substring. + * + * @since 3.0 + * + * @return An error code + * @param[in] str An instance to locate + * @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 string is not found. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - 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. + * @remark This method does not guarantee a usable value of out-parameter when an error occurs. + */ + result IndexOf(const ImmutableString& str, int startIndex, int& indexOf) const; + + /** + * Returns a new instance resulting from inserting the specified string at the specified position. + * + * @since 3.0 + * + * @return The new %ImmutableString instance + * @param[in] str An instance to insert + * @param[in] indexAt The position to insert @c str + * @exception E_SUCCESS The method is successful. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - 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. + * @remark This method returns an empty string when an exception occurs. + */ + ImmutableString Insert(const ImmutableString& str, int indexAt) const; + + /** + * Checks whether the string is empty. + * + * @since 3.0 + * + * @return @c true if the current instance is a zero-length %ImmutableString instance L"", @n + * else @c false + */ + bool IsEmpty(void) const; + + /** + * Searches the calling instance for the last occurrence of the specified character and returns its index. @n + * The search begins at the @c startIndex position and proceeds backward towards the beginning. + * + * @since 3.0 + * + * @return An error code + * @param[in] ch The Unicode character to locate + * @param[in] startIndex The starting position of 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 Either of the following conditions has occurred: + * - 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. + * @remark This method does not guarantee a usable value of out-parameter when an error occurs. + * @code + * + * int indexOf; + * wchar_t ch = L'a'; + * ImmutalbeString str(L"ImmutableString"); + * + * str.LastIndexOf(ch, str.GetLength() - 1, indexOf); // indexOf == 5 + * + * @endcode + */ + result LastIndexOf(wchar_t ch, int startIndex, int& indexOf) const; + + /** + * Searches the calling instance for the last occurrence of the specified substring and returns its index. @n + * The search begins at the @c startIndex position and proceeds backward towards the beginning. + * + * @since 3.0 + * + * @return An error code + * @param[in] str An instance to locate + * @param[in] startIndex The starting position of 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 Either of the following conditions has occurred: + * - 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, E_SUCCESS is returned and the value of @c indexOf is set to @c startIndex. + * - This method does not guarantee a usable value of out-parameter when an error occurs. + * @code + * + * int indexOf; + * ImmutableString testStr= L"mutable"; + * ImmutalbeString str(L"ImmutableString"); + * + * str.LastIndexOf(testStr, str.GetLength() - 1, indexOf); // indexOf == 2 + * + * @endcode + */ + result LastIndexOf(const ImmutableString& str, int startIndex, int& indexOf) const; + + /** + * Removes the characters within the specified range in the calling %ImmutableString instance + * and returns a new %ImmutableString instance. + * + * @since 3.0 + * + * @return The new %ImmutableString instance + * + * @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: + * - 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 greater than the length of the substring starting from @c startIndex. + * - The specified @c length is less than @c 0. + * @remark This method returns an empty string when an exception occurs. + */ + ImmutableString Remove(int startIndex, int length) const; + + /** + * Replaces all occurrences of the specified character in the calling %ImmutableString instance with the character to replace + * and returns a new %ImmutableString instance. + * + * @since 3.0 + * + * @return The new %ImmutableString instance + * + * @param[in] original The character to replace + * @param[in] replace The character to replace all occurrences of @c original by + */ + ImmutableString Replace(wchar_t original, wchar_t replace) const; + + /** + * Replaces all occurrences of the specified string in the calling %ImmutableString instance with string to replace + * and returns a new %ImmutableString instance. + * + * @since 3.0 + * + * @return The new %ImmutableString instance + * + * @param[in] original An instance to replace + * @param[in] replace An instance to replace all occurrences of @c original by + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG The specified @c original is an empty string. + * @remark This method returns an empty string when an exception occurs. + */ + ImmutableString Replace(const ImmutableString& original, const ImmutableString& replace) const; + + /** + * Replaces all occurrences of the specified string in the calling %ImmutableString instance from the specified starting position + * with string to replace and returns a new %ImmutableString instance. + * + * @since 3.0 + * + * @return The new %ImmutableString instance + * + * @param[in] original An instance to replace + * @param[in] replace An instance to replace all occurrences of @c original by + * @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 Either of the following conditions has occurred: + * - 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. + * @remark This method returns an empty string when an exception occurs. + */ + ImmutableString Replace(const ImmutableString& original, const ImmutableString& replace, int startIndex) const; + + /** + * Reverses the sequence of characters in the calling %ImmutableString instance and returns a new %ImmutableString instance. + * + * @since 3.0 + * + * @return The new %ImmutableString instance + */ + ImmutableString Reverse(void) const; + + /** + * Sets the character at the specified index with the given character in the calling %ImmutableString instance + * and returns a new %ImmutableString instance. + * + * @since 3.0 + * + * @return The new %ImmutableString instance + * + * @param[in] ch A new character + * @param[in] indexAt The position of the character + * @exception E_SUCCESS The method is successful. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - 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. + * @remark This method returns an empty string when an exception occurs. + */ + ImmutableString SetCharAt(wchar_t ch, int indexAt) const; + + /** + * Checks whether this instance contains the specified text from the given index. + * + * @since 3.0 + * + * @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 + * @exception E_SUCCESS The method is successful. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - 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. + */ + bool StartsWith(const ImmutableString& str, int startIndex) const; + + /** + * Checks whether this instance contains the specified text. + * + * @since 3.0 + * + * @return @c true if this instance starts with the specified text, @n + * else @c false + * + * @param[in] str The string to match + */ + bool StartsWith(const ImmutableString& str) const; + + /** + * Finds a substring starting from the given index in the calling %ImmutableString instance + * and returns a new %ImmutableString instance. + * + * @since 3.0 + * + * @return The new %ImmutableString instance containing sub string + * + * @param[in] startIndex The starting index of the substring + * @exception E_SUCCESS The method is successful. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - 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. + * @remark This method returns an empty string when an exception occurs. + */ + ImmutableString SubString(int startIndex) const; + + /** + * Finds a substring of the given length starting from the specified index in the calling %ImmutableString instance + * and returns a new %ImmutableString instance. + * + * @since 3.0 + * + * @return The new %ImmutableString instancecontaining sub string + * + * @param[in] startIndex The starting position of the substring + * @param[in] length The length of the substring + * @exception E_SUCCESS The method is successful. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - 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 greater than the length of the substring starting from @c startIndex. + * - The specified @c length is less than @c 0. + * @remark This method returns an empty string when an exception occurs. + */ + ImmutableString SubString(int startIndex, int length) const; + + /** + * Converts the unicode characters to lowercase from the calling %ImmutableString instance and + * returns a new %ImmutableString instance. Unicode characters other than the English alphabets are also supported. + * + * @since 3.0 + * + * @return The new %ImmutableString instance + */ + ImmutableString ToLowerCase(void) const; + + /** + * Converts the unicode characters to uppercase from the calling %ImmutableString instance and + * returns a new %ImmutableString instance. Unicode characters other than the English alphabets are also supported. + * + * @since 3.0 + * + * @return The new %ImmutableString instance + */ + ImmutableString ToUpperCase(void) const; + + /** + * Trims the leading and trailing whitespace characters in the calling %ImmutableString instance and + * returns a new %ImmutableString instance. + * + * @since 3.0 + * + * @return The new %ImmutableString instance + */ + ImmutableString Trim(void) const; + +private: + // + // This constructor is intentionally declared as private so that only the platform can create an instance. + // + ImmutableString(void); + + // + // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects. + // + ImmutableString& operator =(const ImmutableString& rhs); + + // + // Overloaded constructor + // + ImmutableString(const wchar_t* pStr1, const wchar_t* pStr2); + + // + // Overloaded constructor + // + explicit ImmutableString(int capacity); + +private: + + class _StringBuffer* __pImpl; + friend class _StringBuffer; + + class _ImmutableStringImpl* __pImmutableStringImpl; +}; + +/** + * Checks two %ImmutableString instances for equality. + * + * @since 3.0 + * + * @return @c true if %lhs string is equal to %rhs string, @n + * else @c false + * @param[in] lhs An instance for the left-hand side of the operator + * @param[in] rhs An instance for the right-hand side of the operator + * @remarks + * - The operator performs an ordinal comparison of each Unicode character. + * - This operator is not locale-dependent. + */ +inline bool operator ==(const ImmutableString& lhs, const ImmutableString& rhs) +{ + return (lhs.CompareTo(rhs) == 0); +} + +/** + * Checks two %ImmutableString instances for inequality. + * + * @since 3.0 + * + * @return @c true if %lhs string is not equal to %rhs string, @n + * else @c false + * @param[in] lhs An instance for the left-hand side of the operator + * @param[in] rhs An instance for the right-hand side of the operator + * @remarks + * - The operator performs an ordinal comparison of each Unicode character. + * - This operator is not locale-dependent. + */ +inline bool operator !=(const ImmutableString& lhs, const ImmutableString& rhs) +{ + return (lhs.CompareTo(rhs) != 0); +} + +/** + * Checks the right-hand side %ImmutalbeString instance is greater than the left-hand side one. + * + * @since 3.0 + * + * @return @c true if the string of the right-hand side %ImmutableString instance is greater than the left-hand side one, @n + * else @c false + * @param[in] lhs An instance for the left-hand side of the operator + * @param[in] rhs An instance for the right-hand side of the operator + * @remarks + * - The operator compares texts by ordinal comparison. + * - This operator is not locale-dependent. + */ +inline bool operator <(const ImmutableString& lhs, const ImmutableString& rhs) +{ + return (lhs.CompareTo(rhs) < 0); +} + +/** + * Checks the right-hand side %ImmutalbeString instance is less than the left-hand side one. + * + * @since 3.0 + * + * @return @c true if the string of the right-hand side %ImmutableString instance is less than the left-hand side one, @n + * else @c false + * @param[in] lhs An instance for the left-hand side of the operator + * @param[in] rhs An instance for the right-hand side of the operator + * @remarks + * - The operator compares texts by ordinal comparison. + * - This operator is not locale-dependent. + */ +inline bool operator >(const ImmutableString& lhs, const ImmutableString& rhs) +{ + return (lhs.CompareTo(rhs) > 0); +} + +/** + * Checks the right-hand side %ImmutalbeString instance is greater than or equal to the left-hand side one. + * + * @since 3.0 + * + * @return @c true if the string of the right-hand side %ImmutableString instance is greater than or equal to the left-hand side one, @n + * else @c false + * @param[in] lhs An instance for the left-hand side of the operator + * @param[in] rhs An instance for the right-hand side of the operator + * @remarks + * - The operator compares texts by ordinal comparison. + * - This operator is not locale-dependent. + */ +inline bool operator <=(const ImmutableString& lhs, const ImmutableString& rhs) +{ + return (lhs.CompareTo(rhs) <= 0); +} + +/** + * Checks the right-hand side %ImmutalbeString instance is less than or equal to the left-hand side one. + * + * @since 3.0 + * + * @return @c true if the string of the right-hand side %ImmutableString instance is less than or equal to the left-hand side one, @n + * else @c false + * @param[in] lhs An instance for the left-hand side of the operator + * @param[in] rhs An instance for the right-hand side of the operator + * @remarks + * - The operator compares texts by ordinal comparison. + * - This operator is not locale-dependent. + */ +inline bool operator >=(const ImmutableString& lhs, const ImmutableString& rhs) +{ + return (lhs.CompareTo(rhs) >= 0); +} + +/** + * Concatenates two strings. + * + * @since 3.0 + * + * @return The concatenated %ImmutableString instance + * @param[in] lhs An instance for the left-hand side of the operator + * @param[in] rhs An instance for the right-hand side of the operator + */ +inline ImmutableString operator +(const ImmutableString& lhs, const ImmutableString& rhs) +{ + return lhs.Append(rhs); +} + +}} // Tizen::Base +#endif // _FBASE_IMMUTABLE_STRING_H_