2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
20 * @brief This is the header file for the %String class.
22 * This header file contains the declarations of the %String class.
24 #ifndef _FBASE_STRING_H_
25 #define _FBASE_STRING_H_
27 #include <FBaseObject.h>
30 namespace Tizen { namespace Base
34 * @brief This class represents a mutable sequence of Unicode characters.
38 * The %String class represents a mutable sequence of Unicode characters. Operations that change the Unicode text, such as append, insert, and remove, are contained in the %String class.
40 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/string.htm">String</a>.
42 * The following example demonstrates how to use the %String class.
48 * using namespace Tizen::Base;
51 * MyClass::StringSample(void)
53 * String str; // capacity == 16, length == 0
55 * str.Append((int)100); // str == L"100"
57 * str.Insert(L"abc", 0); // str == L"abc100"
59 * String str2(L"STRING TEST");
63 * str2.SubString(7, 4, subStr); // subStr == L"TEST"
67 class _OSP_EXPORT_ String
72 * This is the default constructor for this class. @n
73 * It creates an empty %String instance with the default capacity of @c 16 bytes.
80 * Initializes this instance of %String with the specified capacity.
84 * @param[in] capacity The default capacity of this instance
89 * Initializes this instance of %String with the specified Unicode character.
93 * @param[in] ch A Unicode character
98 * Initializes this instance of %String with the specified Unicode string.
102 * @param[in] pValue A pointer to an array of Unicode characters
104 String(const wchar_t* pValue);
107 * Initializes this instance of %String with the specified character string.
111 * @param[in] pValue A pointer to an array of UTF-8 characters
113 String(const char* pValue);
116 * Copying of objects using this copy constructor is allowed.
120 * @param[in] value An instance of %String
122 String(const String& value);
125 * TThis destructor overrides Tizen::Base::Object::~Object().
129 * @remarks The internally allocated memory block is freed when the instance is destroyed.
131 virtual ~String(void);
134 * Returns the Unicode character at the specified @c index.
138 * @return A const reference to the Unicode character
139 * @param[in] index An index within the current instance of %String
141 const wchar_t& operator [](int index) const;
144 * Returns a reference to the Unicode character at the specified @c index.
148 * @return A reference to the Unicode character
149 * @param[in] index An index within the current instance of %String
151 wchar_t& operator [](int index);
154 * Copies the text from the specified
155 * Unicode string to the calling instance of %String.
159 * @return A reference to the %String instance
160 * @param[in] pRhs A pointer to an array of Unicode characters
162 String& operator =(const wchar_t* pRhs);
165 * Copying of objects using this copy assignment operator is allowed.
169 * @return A reference to the %String instance
170 * @param[in] rhs An instance of %String
172 String& operator =(const String& rhs);
175 * Appends the text from the specified array of Unicode characters
176 * to the calling instance of %String.
180 * @return A reference to the %String instance
181 * @param[in] pRhs A pointer to an array of Unicode characters
183 String& operator +=(const wchar_t* pRhs);
186 * Appends the text from the specified instance of %String
187 * to the calling instance of %String.
191 * @return A reference to the %String instance
192 * @param[in] rhs An instance of %String to copy
194 String& operator +=(const String& rhs);
197 * Concatenates the two strings.
201 * @return The concatenated %String instance
202 * @param[in] lhs A reference to the %String instance on the left-hand side of the operator
203 * @param[in] rhs A reference to the %String instance on the right-hand side of the operator
205 _OSP_EXPORT_ friend String operator +(const String& lhs, const String& rhs);
208 * Checks the two strings for equality.
212 * @return @c true if the text of the specified %String instance equals the calling instance's text, @n
214 * @param[in] rhs A reference to the %String instance on the right-hand side of the operator
215 * @remarks The operator performs an ordinal comparison of each Unicode character.
217 bool operator ==(const String& rhs) const;
220 * Checks the two strings for inequality.
224 * @return @c true if the text of the specified %String instance is not equal to the calling instance's text, @n
226 * @param[in] rhs A reference to the %String instance on the right-hand side of the operator
227 * @remarks The operator performs an ordinal comparison of each Unicode character.
229 bool operator !=(const String& rhs) const;
232 * Checks whether the string is empty.
236 * @return @c true if the current instance is a zero-length %String instance L"", @n
239 bool IsEmpty(void) const;
242 * Appends the specified @c wchar_t value to this %String instance after converting it.
246 * @return An error code
247 * @param[in] ch A @c wchar_t value to insert
248 * @exception E_SUCCESS The method is successful.
250 result Append(wchar_t ch);
253 * Appends the specified @c char value to this %String instance after converting it.
257 * @return An error code
258 * @param[in] ch A @c char value to insert
259 * @exception E_SUCCESS The method is successful.
261 result Append(char ch);
264 * Appends the string representing the specified 32-bit @c int value to this
265 * instance of %String.
269 * @return An error code
270 * @param[in] i A 32-bit integer value to insert
271 * @exception E_SUCCESS The method is successful.
273 result Append(int i);
276 * Appends the string representing the specified @c short value to this
277 * instance of %String.
281 * @return An error code
282 * @param[in] s A @c short value to insert
283 * @exception E_SUCCESS The method is successful.
285 result Append(short s);
288 * Appends the string representing the specified @c long value to this
289 * instance of %String.
293 * @return An error code
294 * @param[in] l A @c long value to insert
295 * @exception E_SUCCESS The method is successful.
297 result Append(long l);
300 * Appends the string representing the specified @c long @c long value to this
301 * instance of %String.
305 * @return An error code
306 * @param[in] ll A @c long @c long value to insert
307 * @exception E_SUCCESS The method is successful.
309 result Append(long long ll);
312 * Appends the string representing the specified @c float value to this
313 * instance of %String.
317 * @return An error code
318 * @param[in] f A @c float value to insert
319 * @exception E_SUCCESS The method is successful.
321 result Append(float f);
324 * Appends the string representing the specified @c double value to this
325 * instance of %String.
329 * @return An error code
330 * @param[in] d A @c double value to insert
331 * @exception E_SUCCESS The method is successful.
333 result Append(double d);
336 * Appends the specified null-terminated Unicode text to this instance
341 * @return An error code
342 * @param[in] p A pointer to a Unicode character array
343 * @exception E_SUCCESS The method is successful.
344 * @exception E_INVALID_ARG A @c null pointer is passed.
346 result Append(const wchar_t* p);
349 * Appends the specified instance of %String to this instance
354 * @return An error code
355 * @param[in] str An instance of %String to append
356 * @exception E_SUCCESS The method is successful.
358 result Append(const String& str);
361 * Clears the current instance and sets it to an empty %String instance. @n
362 * The capacity is set to @c 16 bytes, which is the default capacity.
369 * Compares the values of the two strings.
373 * @return A 32-bit @c signed integer value
374 * @param[in] str0 The first %String instance to compare
375 * @param[in] str1 The second %String instance to compare
376 * @remarks This method performs an ordinal comparison of each Unicode
377 * character contained in the two given %String instances.
378 * For instance, "U+xxx" is greater than "U+XXX", but smaller than "U+yyy".
381 * < 0 if the value of the first instance is less than the value of the second instance
382 * == 0 if the value of the first instance is equal to the value of the second instance
383 * > 0 if the value of the first instance is greater than the value of the second instance
386 static int Compare(const String& str0, const String& str1);
389 * Compares the value of the current instance to the value of the specified instance
394 * @return A 32-bit @c signed integer value
396 * < 0 if the value of the current instance is less than the value of the specified %String instance
397 * == 0 if the value of the current instance is equal to the value of the specified %String instance
398 * > 0 if the value of the current instance is greater than the value of the specified %String instance
400 * @param[in] str An instance of %String to compare
401 * @remarks This method performs an ordinal comparison of each Unicode character. For instance,
402 * L"U+xxx" is greater than L"U+XXX", but smaller than L"U+yyy".
404 int CompareTo(const String& str) const;
407 * Ensures that the specified length is less than or equal to the capacity of
408 * the current instance of %String. @n
409 * Otherwise, it expands the capacity of the internal buffer to a value that is greater than or equal to the specified length.
413 * @return An error code
414 * @param[in] minLength A minimum length to ensure
415 * @exception E_SUCCESS The method is successful.
416 * @exception E_INVALID_ARG The specified @c minLength is negative.
418 result EnsureCapacity(int minLength);
421 * Checks whether the value of the specified instance of Object is equal to the value of the current instance of %String.
425 * @return @c true if the value of the specified instance of Object is equal to the value of the current instance of %String, @n
427 * @param[in] obj An instance of Object to compare
428 * @remarks This method returns @c false if the specified @c obj is not a string.
429 * @see Object::Equals()
431 virtual bool Equals(const Object& obj) const;
434 * Checks whether the value of the specified instance is equal to the value of the current instance of %String. @n
435 * Case sensitivity can be controlled.
439 * @return @c true if the values match, @n
441 * @param[in] str An instance of %String to compare with the
443 * @param[in] caseSensitive Set to @c true to perform a case sensitive ordinal comparison of the strings, @n
446 * @remarks This method performs an ordinal comparison of each Unicode
447 * character contained in the two given %String instances.
449 bool Equals(const String& str, bool caseSensitive) const;
452 * Formats the inputs as per the specified format and sets the value of the calling instance to the resultant string.
456 * @return An error code
457 * @param[in] length The maximum number of wide characters to write, including the terminating @c null character
458 * @param[in] pFormat The wide character format specifier
459 * @exception E_SUCCESS The method is successful.
460 * @exception E_INVALID_ARG The specified @c length is negative or @c pFormat is @c null.
461 * @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
462 * @remarks A pointer to an array of UTF-8 characters is not allowed in the Format() method (for example, Format(20, L"@%s", pUTF8Str)).
463 * The following format specifiers are supported in this method:
467 * c single byte character
468 * d(or i) signed decimal integer
469 * u unsigned decimal integer
470 * x unsigned hexadecimal integer
471 * f decimal floating point
472 * e scientific notation using e character
473 * g use the shorter of %e or %f
474 * s single byte character string
475 * ls(or S) wide-character string
476 * lld 64-bit signed decimal integer
480 * The following example demonstrates how to use the %Format() method.
486 * wchar_t* testStr = L"TEST";
488 * str.Format(25, L"FORMAT %d %ls", value, testStr); // str == L"FORMAT 10 TEST"
492 result Format(int length, const wchar_t* pFormat, ...);
495 * Gets the hash value of the current instance.
499 * @return The hash value of the current instance
500 * @remarks Two equal instances must return the same hash value. For better performance,
501 * the hash function used must generate a random distribution
504 virtual int GetHashCode(void) const;
507 * Gets the character at the specified position.
511 * @return An error code
512 * @param[in] indexAt The position of the character
513 * @param[out] ch The character at the specified index
514 * @exception E_SUCCESS The method is successful.
515 * @exception E_OUT_OF_RANGE The specified index is out of range, or
516 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
518 result GetCharAt(int indexAt, wchar_t& ch) const;
521 * Searches for a character in the calling instance. @n
522 * Gets the index of the first character that matches to
523 * the specified character in this instance.
527 * @return An error code
528 * @param[in] ch The Unicode character to locate
529 * @param[in] startIndex The starting position of search
530 * @param[out] indexOf The index of the character
531 * @exception E_SUCCESS The method is successful.
532 * @exception E_OBJ_NOT_FOUND The specified character is not found.
533 * @exception E_OUT_OF_RANGE The specified index is out of range, or
534 * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
536 result IndexOf(wchar_t ch, int startIndex, int& indexOf) const;
539 * Searches for a specified substring in the calling instance. @n
540 * Gets the starting index of the first occurrence of the specified substring.
544 * @return An error code
545 * @param[in] str An instance of %String to locate
546 * @param[in] startIndex The starting position of the search
547 * @param[out] indexOf The index of the substring
548 * @exception E_SUCCESS The method is successful.
549 * @exception E_OBJ_NOT_FOUND The specified string is not found.
550 * @exception E_OUT_OF_RANGE The specified index is out of range, or
551 * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
553 result IndexOf(const String& str, int startIndex, int& indexOf) const;
556 * Inserts the string representing the specified Unicode character
557 * at the specified position in the calling instance.
561 * @return An error code
563 * @param[in] ch A Unicode character to insert
564 * @param[in] indexAt The position of the character
565 * @exception E_SUCCESS The method is successful.
566 * @exception E_OUT_OF_RANGE The specified index is out of range, or
567 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
569 result Insert(wchar_t ch, int indexAt);
572 * Inserts the string representing the specified @c char value
573 * at the specified position in the calling instance.
577 * @return An error code
579 * @param[in] ch A @c char value to insert
580 * @param[in] indexAt The position of the character
581 * @exception E_SUCCESS The method is successful.
582 * @exception E_OUT_OF_RANGE The specified index is out of range, or
583 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
585 result Insert(char ch, int indexAt);
588 * Inserts the string representing the specified 16-bit integer
589 * at the specified position in the calling instance.
593 * @return An error code
594 * @param[in] s A 16-bit integer value to insert
595 * @param[in] indexAt The position of the character
596 * @exception E_SUCCESS The method is successful.
597 * @exception E_OUT_OF_RANGE The specified index is out of range, or
598 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
600 result Insert(short s, int indexAt);
603 * Inserts the string representing the specified 32-bit integer
604 * at the specified position in the calling instance.
608 * @return An error code
609 * @param[in] i A 32-bit integer value to insert
610 * @param[in] indexAt The position of the character
611 * @exception E_SUCCESS The method is successful.
612 * @exception E_OUT_OF_RANGE The specified index is out of range, or
613 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
615 result Insert(int i, int indexAt);
618 * Inserts the string representing the specified @c long value
619 * at the specified position in the calling instance.
623 * @return An error code
624 * @param[in] l A @c long value to insert
625 * @param[in] indexAt The position of the character
626 * @exception E_SUCCESS The method is successful.
627 * @exception E_OUT_OF_RANGE The specified index is out of range, or
628 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
630 result Insert(long l, int indexAt);
633 * Inserts the string representing the specified @c long @c long value
634 * at the specified position in the calling instance.
638 * @return An error code
639 * @param[in] ll A @c long @c long value to insert
640 * @param[in] indexAt The position of the character
641 * @exception E_SUCCESS The method is successful.
642 * @exception E_OUT_OF_RANGE The specified index is out of range, or
643 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
645 result Insert(long long ll, int indexAt);
648 * Inserts the string representing the specified @c float value
649 * at the specified position in the calling instance.
653 * @return An error code
654 * @param[in] f A @c float value to insert
655 * @param[in] indexAt The position of the character
656 * @exception E_SUCCESS The method is successful.
657 * @exception E_OUT_OF_RANGE The specified index is out of range, or
658 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
660 result Insert(float f, int indexAt);
663 * Inserts the string representing the specified @c double value
664 * at the specified position in the calling instance.
668 * @return An error code
669 * @param[in] d A @c double value to insert
670 * @param[in] indexAt The position of the character
671 * @exception E_SUCCESS The method is successful.
672 * @exception E_OUT_OF_RANGE The specified index is out of range, or
673 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
675 result Insert(double d, int indexAt);
678 * Inserts the string representing the specified @c null-terminated
679 * string at the specified position in the calling instance.
683 * @return An error code
684 * @param[in] p An instance of %String to insert
685 * @param[in] indexAt The position of the character
686 * @exception E_SUCCESS The method is successful.
687 * @exception E_OUT_OF_RANGE The specified index is out of range, or
688 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
689 * @exception E_INVALID_ARG A @c null pointer is passed.
691 result Insert(const wchar_t* p, int indexAt);
694 * Inserts the string representing the specified instance of %String
695 * at the specified position in the calling instance.
699 * @return An error code
700 * @param[in] str An instance of %String to insert
701 * @param[in] indexAt The position of the character
702 * @exception E_SUCCESS The method is successful.
703 * @exception E_OUT_OF_RANGE The specified index is out of range, or
704 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
706 result Insert(const String& str, int indexAt);
709 * Searches the calling instance for the last occurrence of the specified character and returns its index. @n
710 * The search begins at the @c startIndex position and proceeds backward towards the beginning.
714 * @return An error code
715 * @param[in] ch The Unicode character to locate
716 * @param[in] startIndex The starting position of search
717 * @param[out] indexOf The index of character
718 * @exception E_SUCCESS The method is successful.
719 * @exception E_OBJ_NOT_FOUND The specified character is not found.
720 * @exception E_OUT_OF_RANGE The specified index is out of range, or
721 * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
723 result LastIndexOf(wchar_t ch, int startIndex, int& indexOf) const;
726 * Searches the calling instance for the last occurrence of the specified substring and returns its index. @n
727 * The search begins at the @c startIndex position and proceeds backward towards the beginning.
731 * @return An error code
732 * @param[in] str An instance of %String to locate
733 * @param[in] startIndex The starting position of search
734 * @param[out] indexOf The index of the substring
735 * @exception E_SUCCESS The method is successful.
736 * @exception E_OBJ_NOT_FOUND The specified character is not found.
737 * @exception E_OUT_OF_RANGE The specified index is out of range, or
738 * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
739 * @remarks If the substring is empty, E_SUCCESS is returned and the value of @c indexOf is set to @c startIndex.
741 result LastIndexOf(const String& str, int startIndex, int& indexOf) const;
744 * Removes the characters within the specified range.
748 * @return An error code
749 * @param[in] startIndex The position where the removal begins
750 * @param[in] length The number of characters to remove
751 * @exception E_SUCCESS The method is successful.
752 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
753 * - The specified index is out of range. @n
754 * - The specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0. @n
755 * - The specified @c count is either greater than the length of substring starting from @c startIndex or less than @c 0.
757 result Remove(int startIndex, int length);
760 * Replaces all occurrences of the specified characters.
764 * @param[in] original The character to replace
765 * @param[in] replace The character to replace all occurrences of @c original
767 void Replace(wchar_t original, wchar_t replace);
770 * Replaces all occurrences of the specified string.
774 * @return An error code
775 * @param[in] original An instance of %String to replace
776 * @param[in] replace An instance of %String to replace all occurrences of @c original
777 * @exception E_SUCCESS The method is successful.
778 * @exception E_INVALID_ARG The specified @c original is an empty string.
780 result Replace(const String& original, const String& replace);
783 * Replaces all occurrences of the specified string within the substring
784 * of this instance of %String.
788 * @return An error code
789 * @param[in] original An instance of %String to replace
790 * @param[in] replace An instance of %String to replace all occurrences of @c original
791 * @param[in] startIndex The starting position of the substring
792 * @exception E_SUCCESS The method is successful.
793 * @exception E_INVALID_ARG The specified @c original is an empty string.
794 * @exception E_OUT_OF_RANGE The specified index is out of range, or
795 * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
797 result Replace(const String& original, const String& replace, int startIndex);
800 * Reverses the sequence of characters in the calling instance.
808 * Sets the capacity of this instance of %String.
812 * @return An error code
813 * @param[in] newCapacity The new capacity
814 * @exception E_SUCCESS The method is successful.
815 * @exception E_INVALID_ARG The specified @c capacity is negative.
816 * @remarks If the new capacity is smaller than the current length, then
817 * the text contained in this instance is truncated.
819 result SetCapacity(int newCapacity);
822 * Sets the character at the specified index with the given character.
826 * @return An error code
827 * @param[in] ch A new character
828 * @param[in] indexAt The position of the character
829 * @exception E_SUCCESS The method is successful.
830 * @exception E_OUT_OF_RANGE The specified index is out of range, or
831 * the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
833 result SetCharAt(wchar_t ch, int indexAt);
836 * Sets the length of this instance of %String.
840 * @return An error code
841 * @param[in] newLength The new length
842 * @exception E_SUCCESS The method is successful.
843 * @exception E_INVALID_ARG The specified @c newLength is negative.
844 * @remarks If the new length is greater than the current length, the
845 * string is padded with spaces. On the other hand,
846 * if the new length is smaller than the current length, then
847 * the text contained in this instance is truncated.
849 result SetLength(int newLength);
852 * Gets a substring starting from the given index.
856 * @return An error code
857 * @param[in] startIndex The starting index of the substring
858 * @param[out] out The substring
859 * @exception E_SUCCESS The method is successful.
860 * @exception E_OUT_OF_RANGE The specified index is out of range, or
861 * the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
863 result SubString(int startIndex, String& out) const;
866 * Gets a substring of the given length starting from the specified index.
870 * @return An error code
871 * @param[in] startIndex The starting position of the substring
872 * @param[in] length The length of the substring
873 * @param[out] out The substring
874 * @exception E_SUCCESS The method is successful.
875 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
876 * - The specified index is out of range. @n
877 * - The specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0. @n
878 * - The specified @c length is either greater than the length of substring starting from @c startIndex or less than @c 0.
880 result SubString(int startIndex, int length, String& out) const;
883 * Checks whether this instance contains the specified text from the given index.
887 * @return @c true if this instance starts with the specified text, @n
889 * @param[in] str The string to match
890 * @param[in] startIndex The start position of the string
892 bool StartsWith(const String& str, int startIndex) const;
895 * Checks whether the given string is present at the end of the calling instance.
899 * @return @c true if this instance ends with the specified text, @n
901 * @param[in] str An instance of %String to match
903 bool EndsWith(const String& str) const;
907 * Gets the lowercase form of the string in the calling instance. @n
908 * Unicode characters other than the English alphabets are not changed.
910 * @brief <i> [Deprecated] </i>
911 * @deprecated This method is deprecated as a new method has been introduced.
912 * Instead of using this method, use the ToLowerCase(%String& out) method that supports Unicode characters other than the English alphabets.
915 * @return An error code
916 * @param[out] out An instance of %String that contains the modified value of the calling instance
917 * @exception E_SUCCESS The method is successful.
920 result ToLower(String& out) const;
923 * Gets the lowercase form of the string in the calling instance. @n
924 * Unicode characters other than the English alphabets are also supported.
928 * @return An error code
929 * @param[out] out An instance of %String that contains the modified value of the calling instance
930 * @exception E_SUCCESS The method is successful.
932 result ToLowerCase(String& out) const;
936 * Gets the uppercase form of the string in the calling instance. @n
937 * Unicode characters other than the English alphabets are not changed.
939 * @brief <i> [Deprecated] </i>
940 * @deprecated This method is deprecated as a new method has been introduced.
941 * Instead of using this method, use the ToUpperCase(%String& out) method that supports Unicode characters other than the English alphabets.
944 * @return An error code
945 * @param[out] out An instance of %String that contains the modified value of the calling instance
946 * @exception E_SUCCESS The method is successful.
949 result ToUpper(String& out) const;
952 * Gets the uppercase form of the string in the calling instance. @n
953 * Unicode characters other than the English alphabets are also supported.
957 * @return An error code
958 * @param[out] out An instance of %String that contains the modified value of the calling instance
959 * @exception E_SUCCESS The method is successful.
961 result ToUpperCase(String& out) const;
965 * Converts all the letters in this instance to lowercase. @n
966 * Unicode characters other than the English alphabets are not changed.
968 * @brief <i> [Deprecated] </i>
969 * @deprecated This method is deprecated as a new method has been introduced.
970 * Instead of using this method, use the ToLowerCase() method that supports Unicode characters other than the English alphabets.
978 * Converts all the letters in this instance to lowercase. @n
979 * Unicode characters other than the English alphabets are also supported.
983 void ToLowerCase(void);
987 * Converts all the letters in this instance to uppercase. @n
988 * Unicode characters other than the English alphabets are not changed.
990 * @brief <i> [Deprecated] </i>
991 * @deprecated This method is deprecated as a new method has been introduced.
992 * Instead of using this method, use the ToUpperCase() method that supports Unicode characters other than the English alphabets.
1000 * Converts all the letters in this instance to uppercase. @n
1001 * Unicode characters other than the English alphabets are also supported.
1005 void ToUpperCase(void);
1008 * Trims the leading and trailing whitespace characters.
1015 * Gets the current capacity of this %String instance.
1019 * @return The capacity of this %String instance
1021 int GetCapacity(void) const;
1024 * Gets the length of the text contained in this %String instance.
1028 * @return The length of this %String instance
1030 int GetLength(void) const;
1033 * Gets a pointer to the instance's internal buffer.
1037 * @return A Unicode pointer to the calling instance's internal buffer
1038 * @remarks GetPointer() does not guarantee that every call to this function returns same address.
1040 const wchar_t* GetPointer(void) const;
1043 * Checks whether this instance contains the specified substring.
1047 * @return @c true if this instance contains the specified substring, @n
1049 * @param[in] str The string to match
1051 bool Contains(const String& str) const;
1054 * A constant holding the default capacity of %String.
1058 static const unsigned long DEFAULT_CAPACITY = 16;
1062 // Allocates an internal buffer with the specified capacity.
1063 // @return An error code
1064 // @param[in] capacity The initial capacity of this instance of %String
1066 bool AllocateCapacity(int capacity);
1069 // Expands the size of the internal buffer that is greater than or equal
1070 // to the specified capacity.
1071 // @return @c true if the capacity is expanded, @n
1073 // @param[in] capacity The new capacity of this instance of %String
1075 bool ExpandCapacity(int minCapacity);
1078 // Initializes __pValue and __pRefCount
1082 result InitializeToDefault(int capacity);
1085 // Copies __pValue and subtract and initialize __pRefCount
1089 result CopyOnWrite(int capacity);
1092 // Swaps member-wisely
1096 void Swap(String& str);
1101 mutable int* __pRefCount;
1102 mutable wchar_t* __pValue;
1104 static const float GROWTH_FACTOR;
1106 class _StringImpl * __pStringImpl;
1107 friend class _StringImpl;
1111 #endif // _FBASE_STRING_H_