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
38 * @class ImmutableString
39 * @brief This class represents a immutable sequence of Unicode characters.
43 * The %ImmutableString class represents a immutable sequence of Unicode characters.
44 * Mutation operation, such as Append(), Insert() and Remove(), do not change the current instance but return a new instance resulting from applying the operation.
46 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/immutablestring.htm">ImmutableString</a>.
48 * The following example demonstrates how to use the %ImmutableString class.
54 * using namespace Tizen::Base;
57 * MyClass::ImmutableStringSample(void)
59 * ImmutableString str(L"Test"); // str == L"Test"
61 * ImmutableString str1 = str.Append(L"String"); // str1 == L"TestString"
63 * ImmutableString str2 = str1.Insert(L"Immutable", 4); // str2 == L"TestImmutableString"
65 * ImmutableString str3 = str2.Remove(4, 5); // str3 == L"TestableString"
67 * ImmutableString str4 = str3.SubString(4, 4); // str4 == L"able"
71 class _OSP_EXPORT_ ImmutableString
76 * Initializes %ImmutableString instance with the specified Unicode string.
80 * @param[in] pStr A pointer to an array of Unicode characters
81 * @remarks If whcar_t* type null pointer is entered on parameter, the empty string is set.
83 explicit ImmutableString(const wchar_t* pStr);
86 * Initializes %ImmutableString instance with the specified UTF-8 string.
90 * @param[in] pStr A pointer to an array of UTF-8 characters
91 * @remarks If char* type null pointer is entered on parameter, the empty string is set.
93 explicit ImmutableString(const char* pStr);
96 * Initializes %ImmutableString instance with the specified %String.
100 * @param[in] value An instance of %String
102 ImmutableString(const String& value);
105 * Copying of objects using this copy constructor is allowed.
109 * @param[in] value An instance of %ImmutableString
111 ImmutableString(const ImmutableString& value);
114 * This destructor overrides Tizen::Base::Object::~Object().
118 virtual ~ImmutableString(void);
121 * Returns a Unicode character at the specified @c index.
125 * @return A Unicode character
126 * @param[in] index An index within this string
128 wchar_t operator [](int index) const;
131 * Returns a new %ImmutableString instance resulting from appending the specified %ImmutableString to the end of this string.
135 * @return The concatenated %ImmutableString instance
136 * @param[in] str An instance of %ImmutableString to append
138 ImmutableString Append(const ImmutableString& str) const;
141 * Compares the value of the current instance to the value of the specified instance of %ImmutableString.
145 * @return A @c signed integer value
147 * < 0 if the value of the current instance is less than the value of the specified %ImmutableString instance
148 * == 0 if the value of the current instance is equal to the value of the specified %ImmutableString instance
149 * > 0 if the value of the current instance is greater than the value of the specified %ImmutableString instance
151 * @param[in] str An instance of %ImmutableString to compare
153 * - This method performs an ordinal comparison of each Unicode character. For instance,
154 * L"U+xxx" is greater than L"U+XXX", but smaller than L"U+yyy".
155 * - This method is not locale-dependent.
157 int CompareTo(const ImmutableString& str) const;
160 * Checks whether this instance contains the specified substring.
164 * @return @c true if this instance contains the specified substring, @n
166 * @param[in] str The string to match
167 * @remarks This method returns @c true when an empty string is entered on parameter.
169 bool Contains(const ImmutableString& str) const;
172 * Checks whether the given string is present at the end of the calling instance.
176 * @return @c true if this instance ends with the specified text, @n
178 * @param[in] str An instance to match
179 * @exception E_SUCCESS The method is successful.
180 * @exception E_INVALID_ARG The specified @c str is an empty string.
181 * @remarks The specific error code can be accessed by using GetLastResult() method.
183 bool EndsWith(const ImmutableString& str) const;
186 * Checks whether the value of the specified instance of Object is equal to the value of this string.
190 * @return @c true if the value of the specified instance of Object is equal to the value of this string, @n
192 * @param[in] obj An instance of Object to compare
193 * @remarks This method returns @c false if the specified @c obj is not a string.
194 * @see Object::Equals()
196 virtual bool Equals(const Object& obj) const;
199 * Checks whether the value of the specified instance is equal to the value of this string. @n
200 * Case sensitivity is ignored.
204 * @return @c true if the values match, @n
206 * @param[in] str An instance to compare with the calling instance
208 * @remarks This method performs an ordinal comparison of each Unicode
209 * character contained in the two given %ImmutableString instances.
211 bool EqualsCaseInsensitive(const ImmutableString& str) const;
214 * Formats the inputs as per the specified format and and returns a new %ImmutableString instance.
218 * @return An error code
219 * @param[in] length The maximum number of wide characters to write, including the terminating @c null character
220 * @param[in] pFormat The wide character format specifier
221 * @exception E_SUCCESS The method is successful.
222 * @exception E_INVALID_ARG Either of the following conditions has occurred:
223 * - The specified @c length is negative.
224 * - The specified @c pFormat is @c null.
225 * - The specified @c pFormat includes "%n" or "%hn" which may cause format string vulnerability.
227 * - If an "l" modifier is present in @c pFormat (for example, L"@%ls"), it is a pointer to an array of wide characters.
228 * - A pointer to an array of UTF-8 characters is not allowed in the Format() method (for example, Format(20, L"@%s", pUTF8Str)).
229 * - This method is locale-dependent.
230 * - This method returns an empty string when an exception occurs.
231 * - The specific error code can be accessed by using the GetLastResult() method.
232 * The following format specifiers are supported in this method:
236 * c single byte character
237 * d(or i) signed decimal integer
238 * u unsigned decimal integer
239 * x unsigned hexadecimal integer
240 * f decimal floating point
241 * e scientific notation using e character
242 * g use the shorter of %e or %f
243 * s single byte character string
244 * ls(or S) wide-character string
245 * lld 64-bit signed decimal integer
249 * The following example demonstrates how to use the %Format() method.
253 * wchar_t* testStr = L"TEST";
255 * ImmutableString str = Tizen::Base::ImmutableString::Format(25, L"FORMAT %d %ls", value, testStr); // str == L"FORMAT 10 TEST"
259 static ImmutableString Format(int length, const wchar_t* pFormat, ...);
262 * Gets the character at the specified position.
266 * @return An error code
267 * @param[in] indexAt The position of the character
268 * @param[out] ch The character at the specified index
269 * @exception E_SUCCESS The method is successful.
270 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
271 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
272 * - The specified @c indexAt is less than @c 0.
273 * @remarks This method does not guarantee a usable value of out-parameter when an error occurs.
275 result GetCharAt(int indexAt, wchar_t& ch) const;
278 * Gets the hash value of the current instance.
282 * @return The hash value of the current instance
283 * @remarks Two equal instances must return the same hash value. For better performance,
284 * the hash function used must generate a random distribution for all inputs.
286 virtual int GetHashCode(void) const;
289 * Gets the length of the text contained in this %ImmutableString instance.
293 * @return The length of this %ImmutableString instance
295 int GetLength(void) const;
298 * Gets a pointer to the instance's internal buffer.
302 * @return A Unicode pointer to the calling instance's internal buffer
304 const wchar_t* GetPointer(void) const;
307 * Searches for a character in the calling instance. @n
308 * Gets the index of the first character that matches to the specified character in this instance.
312 * @return An error code
313 * @param[in] ch The Unicode character to locate
314 * @param[in] startIndex The starting position of the search
315 * @param[out] indexOf The index of the character
316 * @exception E_SUCCESS The method is successful.
317 * @exception E_OBJ_NOT_FOUND The specified character is not found.
318 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
319 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
320 * - The specified @c startIndex is less than @c 0.
321 * @remarks Do not use the @c indexOf when the method returns an error.
323 result IndexOf(wchar_t ch, int startIndex, int& indexOf) const;
326 * Searches for a specified substring in the calling instance. @n
327 * Gets the starting index of the first occurrence of the specified substring.
331 * @return An error code
332 * @param[in] str An instance to locate
333 * @param[in] startIndex The starting position of the search
334 * @param[out] indexOf The index of the substring
335 * @exception E_SUCCESS The method is successful.
336 * @exception E_OBJ_NOT_FOUND The specified string is not found.
337 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
338 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
339 * - The specified @c startIndex is less than @c 0.
340 * @remarks Do not use the @c indexOf when the method returns an error.
342 result IndexOf(const ImmutableString& str, int startIndex, int& indexOf) const;
345 * Returns a new instance resulting from inserting the specified string at the specified position.
349 * @return The new %ImmutableString instance
350 * @param[in] str An instance to insert
351 * @param[in] indexAt The position to insert @c str
352 * @exception E_SUCCESS The method is successful.
353 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
354 * - The specified @c indexAt is greater than the length of the current instance.
355 * - The specified @c indexAt is less than @c 0.
357 * - This method returns an empty string when an exception occurs.
358 * - The specific error code can be accessed by using GetLastResult() method.
360 ImmutableString Insert(const ImmutableString& str, int indexAt) const;
363 * Checks whether the string is empty.
367 * @return @c true if the current instance is a zero-length %ImmutableString instance L"", @n
370 bool IsEmpty(void) const;
373 * Searches the calling instance for the last occurrence of the specified character and returns its index. @n
374 * The search begins at the @c startIndex position and proceeds backward towards the beginning.
378 * @return An error code
379 * @param[in] ch The Unicode character to locate
380 * @param[in] startIndex The starting position of search
381 * @param[out] indexOf The index of character
382 * @exception E_SUCCESS The method is successful.
383 * @exception E_OBJ_NOT_FOUND The specified character is not found.
384 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
385 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
386 * - The specified @c startIndex is less than @c 0.
387 * @remarks Do not use the @c indexOf when the method returns an error.
392 * ImmutalbeString str(L"ImmutableString");
394 * str.LastIndexOf(ch, str.GetLength() - 1, indexOf); // indexOf == 5
398 result LastIndexOf(wchar_t ch, int startIndex, int& indexOf) const;
401 * Searches the calling instance for the last occurrence of the specified substring and returns its index. @n
402 * The search begins at the @c startIndex position and proceeds backward towards the beginning.
406 * @return An error code
407 * @param[in] str An instance to locate
408 * @param[in] startIndex The starting position of search
409 * @param[out] indexOf The index of the substring
410 * @exception E_SUCCESS The method is successful.
411 * @exception E_OBJ_NOT_FOUND The specified character is not found.
412 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
413 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
414 * - The specified @c startIndex is less than @c 0.
417 * - If the substring is empty, E_SUCCESS is returned and the value of @c indexOf is set to @c startIndex.
418 * - Do not use the @c indexOf when the method returns an error.
422 * ImmutableString testStr= L"mutable";
423 * ImmutalbeString str(L"ImmutableString");
425 * str.LastIndexOf(testStr, str.GetLength() - 1, indexOf); // indexOf == 2
429 result LastIndexOf(const ImmutableString& str, int startIndex, int& indexOf) const;
432 * Removes the characters within the specified range in the calling %ImmutableString instance
433 * and returns a new %ImmutableString instance.
437 * @return The new %ImmutableString instance
439 * @param[in] startIndex The position where the removal begins
440 * @param[in] length The number of characters to remove
441 * @exception E_SUCCESS The method is successful.
442 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
443 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
444 * - The specified @c startIndex is less than @c 0.
445 * - The specified @c length is greater than the length of the substring starting from @c startIndex.
446 * - The specified @c length is less than @c 0.
448 * - This method returns an empty string when an exception occurs.
449 * - The specific error code can be accessed by using GetLastResult() method.
451 ImmutableString Remove(int startIndex, int length) const;
454 * Replaces all occurrences of the specified character in the calling %ImmutableString instance with the character to replace
455 * and returns a new %ImmutableString instance.
459 * @return The new %ImmutableString instance
461 * @param[in] original The character to replace
462 * @param[in] replace The character to replace all occurrences of @c original by
464 ImmutableString Replace(wchar_t original, wchar_t replace) const;
467 * Replaces all occurrences of the specified string in the calling %ImmutableString instance with string to replace
468 * and returns a new %ImmutableString instance.
472 * @return The new %ImmutableString instance
474 * @param[in] original An instance to replace
475 * @param[in] replace An instance to replace all occurrences of @c original by
476 * @exception E_SUCCESS The method is successful.
477 * @exception E_INVALID_ARG The specified @c original is an empty string.
479 * - This method returns an empty string when an exception occurs.
480 * - The specific error code can be accessed by using GetLastResult() method.
482 ImmutableString Replace(const ImmutableString& original, const ImmutableString& replace) const;
485 * Replaces all occurrences of the specified string in the calling %ImmutableString instance from the specified starting position
486 * with string to replace and returns a new %ImmutableString instance.
490 * @return The new %ImmutableString instance
492 * @param[in] original An instance to replace
493 * @param[in] replace An instance to replace all occurrences of @c original by
494 * @param[in] startIndex The starting position of the substring
495 * @exception E_SUCCESS The method is successful.
496 * @exception E_INVALID_ARG The specified @c original is an empty string.
497 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
498 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
499 * - The specified @c startIndex is less than @c 0.
500 * - The length of the specified @c original is greater than the length of the substring starting from @c startIndex.
502 * - This method returns an empty string when an exception occurs.
503 * - The specific error code can be accessed by using GetLastResult() method.
505 ImmutableString Replace(const ImmutableString& original, const ImmutableString& replace, int startIndex) const;
508 * Reverses the sequence of characters in the calling %ImmutableString instance and returns a new %ImmutableString instance.
512 * @return The new %ImmutableString instance
514 ImmutableString Reverse(void) const;
517 * Sets the character at the specified index with the given character in the calling %ImmutableString instance
518 * and returns a new %ImmutableString instance.
522 * @return The new %ImmutableString instance
524 * @param[in] ch A new character
525 * @param[in] indexAt The position of the character
526 * @exception E_SUCCESS The method is successful.
527 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
528 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
529 * - The specified @c indexAt is less than @c 0.
531 * - This method returns an empty string when an exception occurs.
532 * - The specific error code can be accessed by using GetLastResult() method.
534 ImmutableString SetCharAt(wchar_t ch, int indexAt) const;
537 * Checks whether this instance contains the specified text from the given index.
541 * @return @c true if this instance starts with the specified text, @n
544 * @param[in] str The string to match
545 * @param[in] startIndex The start position of the string
546 * @exception E_SUCCESS The method is successful.
547 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
548 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
549 * - The specified @c startIndex is less than @c 0.
551 * - The specific error code can be accessed by using GetLastResult() method.
552 * - This method returns @c true when an empty string is entered on parameter.
554 bool StartsWith(const ImmutableString& str, int startIndex) const;
557 * Checks whether this instance contains the specified text.
561 * @return @c true if this instance starts with the specified text, @n
564 * @param[in] str The string to match
566 bool StartsWith(const ImmutableString& str) const;
569 * Finds a substring starting from the given index in the calling %ImmutableString instance
570 * and returns a new %ImmutableString instance.
574 * @return The new %ImmutableString instance containing sub string
576 * @param[in] startIndex The starting index of the substring
577 * @exception E_SUCCESS The method is successful.
578 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
579 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
580 * - The specified @c startIndex is less than @c 0.
582 * - This method returns an empty string when an exception occurs.
583 * - The specific error code can be accessed by using GetLastResult() method.
585 ImmutableString SubString(int startIndex) const;
588 * Finds a substring of the given length starting from the specified index in the calling %ImmutableString instance
589 * and returns a new %ImmutableString instance.
593 * @return The new %ImmutableString instancecontaining sub string
595 * @param[in] startIndex The starting position of the substring
596 * @param[in] length The length of the substring
597 * @exception E_SUCCESS The method is successful.
598 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
599 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
600 * - The specified @c startIndex is less than @c 0.
601 * - The specified @c length is greater than the length of the substring starting from @c startIndex.
602 * - The specified @c length is less than @c 0.
604 * - This method returns an empty string when an exception occurs.
605 * - The specific error code can be accessed by using GetLastResult() method.
607 ImmutableString SubString(int startIndex, int length) const;
610 * Converts the unicode characters to lowercase from the calling %ImmutableString instance and
611 * returns a new %ImmutableString instance. Unicode characters other than the English alphabets are also supported.
615 * @return The new %ImmutableString instance
617 ImmutableString ToLowerCase(void) const;
620 * Converts the unicode characters to uppercase from the calling %ImmutableString instance and
621 * returns a new %ImmutableString instance. Unicode characters other than the English alphabets are also supported.
625 * @return The new %ImmutableString instance
627 ImmutableString ToUpperCase(void) const;
630 * Trims the leading and trailing whitespace characters in the calling %ImmutableString instance and
631 * returns a new %ImmutableString instance.
635 * @return The new %ImmutableString instance
637 ImmutableString Trim(void) const;
641 // This constructor is intentionally declared as private so that only the platform can create an instance.
643 ImmutableString(void);
646 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
648 ImmutableString& operator =(const ImmutableString& rhs);
651 // Overloaded constructor
653 ImmutableString(const wchar_t* pStr1, const wchar_t* pStr2);
656 // Overloaded constructor
658 ImmutableString(_StringBuffer* pBuf);
662 _StringBuffer* __pImpl;
663 friend class _StringBuffer;
667 * Checks two %ImmutableString instances for equality.
671 * @return @c true if %lhs string is equal to %rhs string, @n
673 * @param[in] lhs An instance for the left-hand side of the operator
674 * @param[in] rhs An instance for the right-hand side of the operator
676 * - The operator performs an ordinal comparison of each Unicode character.
677 * - This operator is not locale-dependent.
679 inline bool operator ==(const ImmutableString& lhs, const ImmutableString& rhs)
681 return (lhs.CompareTo(rhs) == 0);
685 * Checks two %ImmutableString instances for inequality.
689 * @return @c true if %lhs string is not equal to %rhs string, @n
691 * @param[in] lhs An instance for the left-hand side of the operator
692 * @param[in] rhs An instance for the right-hand side of the operator
694 * - The operator performs an ordinal comparison of each Unicode character.
695 * - This operator is not locale-dependent.
697 inline bool operator !=(const ImmutableString& lhs, const ImmutableString& rhs)
699 return (lhs.CompareTo(rhs) != 0);
703 * Checks the right-hand side %ImmutalbeString instance is greater than the left-hand side one.
707 * @return @c true if the string of the right-hand side %ImmutableString instance is greater than the left-hand side one, @n
709 * @param[in] lhs An instance for the left-hand side of the operator
710 * @param[in] rhs An instance for the right-hand side of the operator
712 * - The operator compares texts by ordinal comparison.
713 * - This operator is not locale-dependent.
715 inline bool operator <(const ImmutableString& lhs, const ImmutableString& rhs)
717 return (lhs.CompareTo(rhs) < 0);
721 * Checks the right-hand side %ImmutalbeString instance is less than the left-hand side one.
725 * @return @c true if the string of the right-hand side %ImmutableString instance is less than the left-hand side one, @n
727 * @param[in] lhs An instance for the left-hand side of the operator
728 * @param[in] rhs An instance for the right-hand side of the operator
730 * - The operator compares texts by ordinal comparison.
731 * - This operator is not locale-dependent.
733 inline bool operator >(const ImmutableString& lhs, const ImmutableString& rhs)
735 return (lhs.CompareTo(rhs) > 0);
739 * Checks the right-hand side %ImmutalbeString instance is greater than or equal to the left-hand side one.
743 * @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
745 * @param[in] lhs An instance for the left-hand side of the operator
746 * @param[in] rhs An instance for the right-hand side of the operator
748 * - The operator compares texts by ordinal comparison.
749 * - This operator is not locale-dependent.
751 inline bool operator <=(const ImmutableString& lhs, const ImmutableString& rhs)
753 return (lhs.CompareTo(rhs) <= 0);
757 * Checks the right-hand side %ImmutalbeString instance is less than or equal to the left-hand side one.
761 * @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
763 * @param[in] lhs An instance for the left-hand side of the operator
764 * @param[in] rhs An instance for the right-hand side of the operator
766 * - The operator compares texts by ordinal comparison.
767 * - This operator is not locale-dependent.
769 inline bool operator >=(const ImmutableString& lhs, const ImmutableString& rhs)
771 return (lhs.CompareTo(rhs) >= 0);
775 * Concatenates two strings.
779 * @return The concatenated %ImmutableString instance
780 * @param[in] lhs An instance for the left-hand side of the operator
781 * @param[in] rhs An instance for the right-hand side of the operator
783 inline ImmutableString operator +(const ImmutableString& lhs, const ImmutableString& rhs)
785 return lhs.Append(rhs);
789 #endif // _FBASE_IMMUTABLE_STRING_H_