2 // Copyright (c) 2013 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FBaseImmutableString.h
19 * @brief This is the header file for the %ImmutableString class.
22 * @final This class is not intended for extension.
24 * This header file contains the declarations of the %ImmutableString class.
27 #ifndef _FBASE_IMMUTABLE_STRING_H_
28 #define _FBASE_IMMUTABLE_STRING_H_
30 #include <FBaseObject.h>
32 namespace Tizen { namespace Base
35 * @class ImmutableString
36 * @brief This class represents a immutable sequence of Unicode characters.
40 * The %ImmutableString class represents a immutable sequence of Unicode characters.
41 * Mutation operation, such as Append(), Insert() and Remove(), do not change the current instance but return a new instance resulting from applying the operation.
43 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/immutablestring.htm">ImmutableString</a>.
45 * The following example demonstrates how to use the %ImmutableString class.
51 * using namespace Tizen::Base;
54 * MyClass::ImmutableStringSample(void)
56 * ImmutableString str(L"Test"); // str == L"Test"
58 * ImmutableString str1 = str.Append(L"String"); // str1 == L"TestString"
60 * ImmutableString str2 = str1.Insert(L"Immutable", 4); // str2 == L"TestImmutableString"
62 * ImmutableString str3 = str2.Remove(4, 5); // str3 == L"TestableString"
64 * ImmutableString str4 = str3.SubString(4, 4); // str4 == L"able"
68 class _OSP_EXPORT_ ImmutableString
73 * Initializes %ImmutableString instance with the specified Unicode string.
77 * @param[in] pStr A pointer to an array of Unicode characters
78 * @remark If whcar_t* type null pointer is entered on parameter, the empty string is set.
80 explicit ImmutableString(const wchar_t* pStr);
83 * Initializes %ImmutableString instance with the specified UTF-8 string.
87 * @param[in] pStr A pointer to an array of UTF-8 characters
88 * @remark If char* type null pointer is entered on parameter, the empty string is set.
90 explicit ImmutableString(const char* pStr);
93 * Initializes %ImmutableString instance with the specified %String.
97 * @param[in] value An instance of %String
99 ImmutableString(const String& value);
102 * Copying of objects using this copy constructor is allowed.
106 * @param[in] value An instance of %ImmutableString
108 ImmutableString(const ImmutableString& value);
111 * This destructor overrides Tizen::Base::Object::~Object().
115 virtual ~ImmutableString(void);
118 * Returns a Unicode character at the specified @c index.
122 * @return A Unicode character
123 * @param[in] index An index within this string
125 wchar_t operator [](int index) const;
128 * Returns a new %ImmutableString instance resulting from appending the specified %ImmutableString to the end of this string.
132 * @return The concatenated %ImmutableString instance
133 * @param[in] str An instance of %ImmutableString to append
135 ImmutableString Append(const ImmutableString& str) const;
138 * Compares the value of the current instance to the value of the specified instance of %ImmutableString.
142 * @return A @c signed integer value
144 * < 0 if the value of the current instance is less than the value of the specified %ImmutableString instance
145 * == 0 if the value of the current instance is equal to the value of the specified %ImmutableString instance
146 * > 0 if the value of the current instance is greater than the value of the specified %ImmutableString instance
148 * @param[in] str An instance of %ImmutableString to compare
150 * - This method performs an ordinal comparison of each Unicode character. For instance,
151 * L"U+xxx" is greater than L"U+XXX", but smaller than L"U+yyy".
152 * - This method is not locale-dependent.
154 int CompareTo(const ImmutableString& str) const;
157 * Checks whether this instance contains the specified substring.
161 * @return @c true if this instance contains the specified substring, @n
163 * @param[in] str The string to match
164 * @exception E_SUCCESS The method is successful.
165 * @exception E_INVALID_ARG The specified @c str is an empty string.
167 bool Contains(const ImmutableString& str) const;
170 * Checks whether the given string is present at the end of the calling instance.
174 * @return @c true if this instance ends with the specified text, @n
176 * @param[in] str An instance to match
177 * @exception E_SUCCESS The method is successful.
178 * @exception E_INVALID_ARG The specified @c str is an empty string.
180 bool EndsWith(const ImmutableString& str) const;
183 * Checks whether the value of the specified instance of Object is equal to the value of this string.
187 * @return @c true if the value of the specified instance of Object is equal to the value of this string, @n
189 * @param[in] obj An instance of Object to compare
190 * @remarks This method returns @c false if the specified @c obj is not a string.
191 * @see Object::Equals()
193 virtual bool Equals(const Object& obj) const;
196 * Checks whether the value of the specified instance is equal to the value of this string. @n
197 * Case sensitivity is ignored.
201 * @return @c true if the values match, @n
203 * @param[in] str An instance to compare with the calling instance
205 * @remarks This method performs an ordinal comparison of each Unicode
206 * character contained in the two given %ImmutableString instances.
208 bool EqualsCaseInsensitive(const ImmutableString& str) const;
211 * Formats the inputs as per the specified format and and returns a new %ImmutableString instance.
215 * @return An error code
216 * @param[in] length The maximum number of wide characters to write, including the terminating @c null character
217 * @param[in] pFormat The wide character format specifier
218 * @exception E_SUCCESS The method is successful.
219 * @exception E_INVALID_ARG Either of the following conditions has occurred:
220 * - The specified @c length is negative.
221 * - The specified @c pFormat is @c null.
223 * - If an "l" modifier is present in @c pFormat (for example, L"@%ls"), it is a pointer to an array of wide characters.
224 * - A pointer to an array of UTF-8 characters is not allowed in the Format() method (for example, Format(20, L"@%s", pUTF8Str)).
225 * The following format specifiers are supported in this method:
229 * c single byte character
230 * d(or i) signed decimal integer
231 * u unsigned decimal integer
232 * x unsigned hexadecimal integer
233 * f decimal floating point
234 * e scientific notation using e character
235 * g use the shorter of %e or %f
236 * s single byte character string
237 * ls(or S) wide-character string
238 * lld 64-bit signed decimal integer
242 * The following example demonstrates how to use the %Format() method.
246 * wchar_t* testStr = L"TEST";
248 * ImmutableString str = Tizen::Base::ImmutableString::Format(25, L"FORMAT %d %ls", value, testStr); // str == L"FORMAT 10 TEST"
252 static ImmutableString Format(int length, const wchar_t* pFormat, ...) const;
255 * Gets the character at the specified position.
259 * @return An error code
260 * @param[in] indexAt The position of the character
261 * @param[out] ch The character at the specified index
262 * @exception E_SUCCESS The method is successful.
263 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
264 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
265 * - The specified @c indexAt is less than @c 0.
266 * @remark This method does not guarantee a usable value of out-parameter when an error occurs.
268 result GetCharAt(int indexAt, wchar_t& ch) const;
271 * Gets the hash value of the current instance.
275 * @return The hash value of the current instance
276 * @remarks Two equal instances must return the same hash value. For better performance,
277 * the hash function used must generate a random distribution for all inputs.
279 virtual int GetHashCode(void) const;
282 * Gets the length of the text contained in this %ImmutableString instance.
286 * @return The length of this %ImmutableString instance
288 int GetLength(void) const;
291 * Gets a pointer to the instance's internal buffer.
295 * @return A Unicode pointer to the calling instance's internal buffer
297 const wchar_t* GetPointer(void) const;
300 * Searches for a character in the calling instance. @n
301 * Gets the index of the first character that matches to the specified character in this instance.
305 * @return An error code
306 * @param[in] ch The Unicode character to locate
307 * @param[in] startIndex The starting position of the search
308 * @param[out] indexOf The index of the character
309 * @exception E_SUCCESS The method is successful.
310 * @exception E_OBJ_NOT_FOUND The specified character is not found.
311 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
312 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
313 * - The specified @c startIndex is less than @c 0.
314 * @remark This method does not guarantee a usable value of out-parameter when an error occurs.
316 result IndexOf(wchar_t ch, int startIndex, int& indexOf) const;
319 * Searches for a specified substring in the calling instance. @n
320 * Gets the starting index of the first occurrence of the specified substring.
324 * @return An error code
325 * @param[in] str An instance to locate
326 * @param[in] startIndex The starting position of the search
327 * @param[out] indexOf The index of the substring
328 * @exception E_SUCCESS The method is successful.
329 * @exception E_OBJ_NOT_FOUND The specified string is not found.
330 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
331 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
332 * - The specified @c startIndex is less than @c 0.
333 * @remark This method does not guarantee a usable value of out-parameter when an error occurs.
335 result IndexOf(const ImmutableString& str, int startIndex, int& indexOf) const;
338 * Returns a new instance resulting from inserting the specified string at the specified position.
342 * @return The new %ImmutableString instance
343 * @param[in] str An instance to insert
344 * @param[in] indexAt The position to insert @c str
345 * @exception E_SUCCESS The method is successful.
346 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
347 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
348 * - The specified @c indexAt is less than @c 0.
349 * @remark This method returns an empty string when an exception occurs.
351 ImmutableString Insert(const ImmutableString& str, int indexAt) const;
354 * Checks whether the string is empty.
358 * @return @c true if the current instance is a zero-length %ImmutableString instance L"", @n
361 bool IsEmpty(void) const;
364 * Searches the calling instance for the last occurrence of the specified character and returns its index. @n
365 * The search begins at the @c startIndex position and proceeds backward towards the beginning.
369 * @return An error code
370 * @param[in] ch The Unicode character to locate
371 * @param[in] startIndex The starting position of search
372 * @param[out] indexOf The index of character
373 * @exception E_SUCCESS The method is successful.
374 * @exception E_OBJ_NOT_FOUND The specified character is not found.
375 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
376 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
377 * - The specified @c startIndex is less than @c 0.
378 * @remark This method does not guarantee a usable value of out-parameter when an error occurs.
383 * ImmutalbeString str(L"ImmutableString");
385 * str.LastIndexOf(ch, str.GetLength() - 1, indexOf); // indexOf == 5
389 result LastIndexOf(wchar_t ch, int startIndex, int& indexOf) const;
392 * Searches the calling instance for the last occurrence of the specified substring and returns its index. @n
393 * The search begins at the @c startIndex position and proceeds backward towards the beginning.
397 * @return An error code
398 * @param[in] str An instance to locate
399 * @param[in] startIndex The starting position of search
400 * @param[out] indexOf The index of the substring
401 * @exception E_SUCCESS The method is successful.
402 * @exception E_OBJ_NOT_FOUND The specified character is not found.
403 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
404 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
405 * - The specified @c startIndex is less than @c 0.
408 * - If the substring is empty, E_SUCCESS is returned and the value of @c indexOf is set to @c startIndex.
409 * - This method does not guarantee a usable value of out-parameter when an error occurs.
413 * ImmutableString testStr= L"mutable";
414 * ImmutalbeString str(L"ImmutableString");
416 * str.LastIndexOf(testStr, str.GetLength() - 1, indexOf); // indexOf == 2
420 result LastIndexOf(const ImmutableString& str, int startIndex, int& indexOf) const;
423 * Removes the characters within the specified range in the calling %ImmutableString instance
424 * and returns a new %ImmutableString instance.
428 * @return The new %ImmutableString instance
430 * @param[in] startIndex The position where the removal begins
431 * @param[in] length The number of characters to remove
432 * @exception E_SUCCESS The method is successful.
433 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
434 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
435 * - The specified @c startIndex is less than @c 0.
436 * - The specified @c length is greater than the length of the substring starting from @c startIndex.
437 * - The specified @c length is less than @c 0.
438 * @remark This method returns an empty string when an exception occurs.
440 ImmutableString Remove(int startIndex, int length) const;
443 * Replaces all occurrences of the specified character in the calling %ImmutableString instance with the character to replace
444 * and returns a new %ImmutableString instance.
448 * @return The new %ImmutableString instance
450 * @param[in] original The character to replace
451 * @param[in] replace The character to replace all occurrences of @c original by
453 ImmutableString Replace(wchar_t original, wchar_t replace) const;
456 * Replaces all occurrences of the specified string in the calling %ImmutableString instance with string to replace
457 * and returns a new %ImmutableString instance.
461 * @return The new %ImmutableString instance
463 * @param[in] original An instance to replace
464 * @param[in] replace An instance to replace all occurrences of @c original by
465 * @exception E_SUCCESS The method is successful.
466 * @exception E_INVALID_ARG The specified @c original is an empty string.
467 * @remark This method returns an empty string when an exception occurs.
469 ImmutableString Replace(const ImmutableString& original, const ImmutableString& replace) const;
472 * Replaces all occurrences of the specified string in the calling %ImmutableString instance from the specified starting position
473 * with string to replace and returns a new %ImmutableString instance.
477 * @return The new %ImmutableString instance
479 * @param[in] original An instance to replace
480 * @param[in] replace An instance to replace all occurrences of @c original by
481 * @param[in] startIndex The starting position of the substring
482 * @exception E_SUCCESS The method is successful.
483 * @exception E_INVALID_ARG The specified @c original is an empty string.
484 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
485 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
486 * - The specified @c startIndex is less than @c 0.
487 * @remark This method returns an empty string when an exception occurs.
489 ImmutableString Replace(const ImmutableString& original, const ImmutableString& replace, int startIndex) const;
492 * Reverses the sequence of characters in the calling %ImmutableString instance and returns a new %ImmutableString instance.
496 * @return The new %ImmutableString instance
498 ImmutableString Reverse(void) const;
501 * Sets the character at the specified index with the given character in the calling %ImmutableString instance
502 * and returns a new %ImmutableString instance.
506 * @return The new %ImmutableString instance
508 * @param[in] ch A new character
509 * @param[in] indexAt The position of the character
510 * @exception E_SUCCESS The method is successful.
511 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
512 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
513 * - The specified @c indexAt is less than @c 0.
514 * @remark This method returns an empty string when an exception occurs.
516 ImmutableString SetCharAt(wchar_t ch, int indexAt) const;
519 * Checks whether this instance contains the specified text from the given index.
523 * @return @c true if this instance starts with the specified text, @n
526 * @param[in] str The string to match
527 * @param[in] startIndex The start position of the string
528 * @exception E_SUCCESS The method is successful.
529 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
530 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
531 * - The specified @c startIndex is less than @c 0.
533 bool StartsWith(const ImmutableString& str, int startIndex) const;
536 * Checks whether this instance contains the specified text.
540 * @return @c true if this instance starts with the specified text, @n
543 * @param[in] str The string to match
545 bool StartsWith(const ImmutableString& str) const;
548 * Finds a substring starting from the given index in the calling %ImmutableString instance
549 * and returns a new %ImmutableString instance.
553 * @return The new %ImmutableString instance containing sub string
555 * @param[in] startIndex The starting index of the substring
556 * @exception E_SUCCESS The method is successful.
557 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
558 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
559 * - The specified @c startIndex is less than @c 0.
560 * @remark This method returns an empty string when an exception occurs.
562 ImmutableString SubString(int startIndex) const;
565 * Finds a substring of the given length starting from the specified index in the calling %ImmutableString instance
566 * and returns a new %ImmutableString instance.
570 * @return The new %ImmutableString instancecontaining sub string
572 * @param[in] startIndex The starting position of the substring
573 * @param[in] length The length of the substring
574 * @exception E_SUCCESS The method is successful.
575 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
576 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
577 * - The specified @c startIndex is less than @c 0.
578 * - The specified @c length is greater than the length of the substring starting from @c startIndex.
579 * - The specified @c length is less than @c 0.
580 * @remark This method returns an empty string when an exception occurs.
582 ImmutableString SubString(int startIndex, int length) const;
585 * Converts the unicode characters to lowercase from the calling %ImmutableString instance and
586 * returns a new %ImmutableString instance. Unicode characters other than the English alphabets are also supported.
590 * @return The new %ImmutableString instance
592 ImmutableString ToLowerCase(void) const;
595 * Converts the unicode characters to uppercase from the calling %ImmutableString instance and
596 * returns a new %ImmutableString instance. Unicode characters other than the English alphabets are also supported.
600 * @return The new %ImmutableString instance
602 ImmutableString ToUpperCase(void) const;
605 * Trims the leading and trailing whitespace characters in the calling %ImmutableString instance and
606 * returns a new %ImmutableString instance.
610 * @return The new %ImmutableString instance
612 ImmutableString Trim(void) const;
616 // This constructor is intentionally declared as private so that only the platform can create an instance.
618 ImmutableString(void);
621 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
623 ImmutableString& operator =(const ImmutableString& rhs);
626 // Overloaded constructor
628 ImmutableString(const wchar_t* pStr1, const wchar_t* pStr2);
631 // Overloaded constructor
633 explicit ImmutableString(int capacity);
637 class _StringBuffer* __pImpl;
638 friend class _StringBuffer;
640 class _ImmutableStringImpl* __pImmutableStringImpl;
644 * Checks two %ImmutableString instances for equality.
648 * @return @c true if %lhs string is equal to %rhs string, @n
650 * @param[in] lhs An instance for the left-hand side of the operator
651 * @param[in] rhs An instance for the right-hand side of the operator
653 * - The operator performs an ordinal comparison of each Unicode character.
654 * - This operator is not locale-dependent.
656 inline bool operator ==(const ImmutableString& lhs, const ImmutableString& rhs)
658 return (lhs.CompareTo(rhs) == 0);
662 * Checks two %ImmutableString instances for inequality.
666 * @return @c true if %lhs string is not equal to %rhs string, @n
668 * @param[in] lhs An instance for the left-hand side of the operator
669 * @param[in] rhs An instance for the right-hand side of the operator
671 * - The operator performs an ordinal comparison of each Unicode character.
672 * - This operator is not locale-dependent.
674 inline bool operator !=(const ImmutableString& lhs, const ImmutableString& rhs)
676 return (lhs.CompareTo(rhs) != 0);
680 * Checks the right-hand side %ImmutalbeString instance is greater than the left-hand side one.
684 * @return @c true if the string of the right-hand side %ImmutableString instance is greater than the left-hand side one, @n
686 * @param[in] lhs An instance for the left-hand side of the operator
687 * @param[in] rhs An instance for the right-hand side of the operator
689 * - The operator compares texts by ordinal comparison.
690 * - This operator is not locale-dependent.
692 inline bool operator <(const ImmutableString& lhs, const ImmutableString& rhs)
694 return (lhs.CompareTo(rhs) < 0);
698 * Checks the right-hand side %ImmutalbeString instance is less than the left-hand side one.
702 * @return @c true if the string of the right-hand side %ImmutableString instance is less than the left-hand side one, @n
704 * @param[in] lhs An instance for the left-hand side of the operator
705 * @param[in] rhs An instance for the right-hand side of the operator
707 * - The operator compares texts by ordinal comparison.
708 * - This operator is not locale-dependent.
710 inline bool operator >(const ImmutableString& lhs, const ImmutableString& rhs)
712 return (lhs.CompareTo(rhs) > 0);
716 * Checks the right-hand side %ImmutalbeString instance is greater than or equal to the left-hand side one.
720 * @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
722 * @param[in] lhs An instance for the left-hand side of the operator
723 * @param[in] rhs An instance for the right-hand side of the operator
725 * - The operator compares texts by ordinal comparison.
726 * - This operator is not locale-dependent.
728 inline bool operator <=(const ImmutableString& lhs, const ImmutableString& rhs)
730 return (lhs.CompareTo(rhs) <= 0);
734 * Checks the right-hand side %ImmutalbeString instance is less than or equal to the left-hand side one.
738 * @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
740 * @param[in] lhs An instance for the left-hand side of the operator
741 * @param[in] rhs An instance for the right-hand side of the operator
743 * - The operator compares texts by ordinal comparison.
744 * - This operator is not locale-dependent.
746 inline bool operator >=(const ImmutableString& lhs, const ImmutableString& rhs)
748 return (lhs.CompareTo(rhs) >= 0);
752 * Concatenates two strings.
756 * @return The concatenated %ImmutableString instance
757 * @param[in] lhs An instance for the left-hand side of the operator
758 * @param[in] rhs An instance for the right-hand side of the operator
760 inline ImmutableString operator +(const ImmutableString& lhs, const ImmutableString& rhs)
762 return lhs.Append(rhs);
766 #endif // _FBASE_IMMUTABLE_STRING_H_