2 // Copyright (c) 2012 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.
19 * @brief This is the header file for the %String class.
21 * This header file contains the declarations of the %String class.
23 #ifndef _FBASE_STRING_H_
24 #define _FBASE_STRING_H_
26 #include <FBaseObject.h>
29 namespace Tizen { namespace Base
33 * @brief This class represents a mutable sequence of Unicode characters.
37 * 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.
39 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/string.htm">String</a>.
41 * The following example demonstrates how to use the %String class.
47 * using namespace Tizen::Base;
50 * MyClass::StringSample(void)
52 * String str; // capacity == 16, length == 0
54 * str.Append((int)100); // str == L"100"
56 * str.Insert(L"abc", 0); // str == L"abc100"
58 * String str2(L"STRING TEST");
62 * str2.SubString(7, 4, subStr); // subStr == L"TEST"
66 class _OSP_EXPORT_ String
71 * This is the default constructor for this class. @n
72 * It creates an empty %String instance with the default capacity of @c 16 bytes.
79 * Initializes this instance of %String with the specified capacity.
83 * @param[in] capacity The default capacity of this instance
88 * Initializes this instance of %String with the specified Unicode character.
92 * @param[in] ch The Unicode character
97 * Initializes this instance of %String with the specified Unicode string.
101 * @param[in] pValue A pointer to the array of Unicode characters
103 String(const wchar_t* pValue);
106 * Initializes this instance of %String with the specified character string.
110 * @param[in] pValue A pointer to the array of UTF-8 characters
112 String(const char* pValue);
115 * Copying of objects using this copy constructor is allowed.
119 * @param[in] value An instance of %String to copy
121 String(const String& value);
124 * This destructor overrides Tizen::Base::Object::~Object().
128 * @remarks The internally allocated memory block is freed when the instance is destroyed.
130 virtual ~String(void);
133 * Gets the Unicode character at the specified index.
137 * @return A constant reference to the Unicode character
138 * @param[in] index The index within the current instance of %String
140 const wchar_t& operator [](int index) const;
143 * Gets a reference to the Unicode character at the specified index.
147 * @return A reference to the Unicode character
148 * @param[in] index The index within the current instance of %String
150 wchar_t& operator [](int index);
153 * Copies the text from the specified
154 * Unicode string to the calling instance of %String.
158 * @return A reference to the %String instance
159 * @param[in] pRhs A pointer to the array of Unicode characters
161 String& operator =(const wchar_t* pRhs);
164 * Copying of objects using this copy assignment operator is allowed.
168 * @return A reference to the %String instance
169 * @param[in] rhs An instance of %String to copy
171 String& operator =(const String& rhs);
174 * Appends the text from the specified array of Unicode characters
175 * to the calling instance of %String.
179 * @return A reference to the %String instance
180 * @param[in] pRhs A pointer to the array of Unicode characters
182 String& operator +=(const wchar_t* pRhs);
185 * Appends the text from the specified instance of %String
186 * to the calling instance of %String.
190 * @return A reference to the %String instance
191 * @param[in] rhs An instance of %String to copy
193 String& operator +=(const String& rhs);
196 * Concatenates the two strings.
200 * @return The concatenated %String instance
201 * @param[in] lhs A reference to the %String instance on the left-hand side of the operator
202 * @param[in] rhs A reference to the %String instance on the right-hand side of the operator
204 _OSP_EXPORT_ friend String operator +(const String& lhs, const String& rhs);
207 * Checks the two strings for equality.
211 * @return @c true if the text of the specified %String instance equals the calling instance's text, @n
213 * @param[in] rhs A reference to the %String instance on the right-hand side of the operator
214 * @remarks The operator performs an ordinal comparison of each Unicode character.
216 bool operator ==(const String& rhs) const;
219 * Checks the two strings for inequality.
223 * @return @c true if the text of the specified %String instance is not equal to the calling instance's text, @n
225 * @param[in] rhs A reference to the %String instance on the right-hand side of the operator
226 * @remarks The operator performs an ordinal comparison of each Unicode character.
228 bool operator !=(const String& rhs) const;
231 * Checks whether the string is empty.
235 * @return @c true if the current instance is a zero-length %String instance L"", @n
238 bool IsEmpty(void) const;
241 * Appends the specified @c wchar_t value to this %String instance after converting it.
245 * @return An error code
246 * @param[in] ch The @c wchar_t value to insert
247 * @exception E_SUCCESS The method is successful.
249 result Append(wchar_t ch);
252 * Appends the specified @c char value to this %String instance after converting it.
256 * @return An error code
257 * @param[in] ch The @c char value to insert
258 * @exception E_SUCCESS The method is successful.
260 result Append(char ch);
263 * Appends the string that represents the specified 32-bit @c int value to this
264 * instance of %String.
268 * @return An error code
269 * @param[in] i The 32-bit integer value to insert
270 * @exception E_SUCCESS The method is successful.
272 result Append(int i);
275 * Appends the string that represents the specified @c short value to this
276 * instance of %String.
280 * @return An error code
281 * @param[in] s The @c short value to insert
282 * @exception E_SUCCESS The method is successful.
284 result Append(short s);
287 * Appends the string that represents the specified @c long value to this
288 * instance of %String.
292 * @return An error code
293 * @param[in] l The @c long value to insert
294 * @exception E_SUCCESS The method is successful.
296 result Append(long l);
299 * Appends the string that represents the specified @c long @c long value to this
300 * instance of %String.
304 * @return An error code
305 * @param[in] ll The @c long @c long value to insert
306 * @exception E_SUCCESS The method is successful.
308 result Append(long long ll);
311 * Appends the string that represents the specified @c float value to this
312 * instance of %String.
316 * @return An error code
317 * @param[in] f The @c float value to insert
318 * @exception E_SUCCESS The method is successful.
320 result Append(float f);
323 * Appends the string that represents the specified @c double value to this
324 * instance of %String.
328 * @return An error code
329 * @param[in] d The @c double value to insert
330 * @exception E_SUCCESS The method is successful.
332 result Append(double d);
335 * Appends the specified null-terminated Unicode text to this instance
340 * @return An error code
341 * @param[in] p A pointer to the Unicode character array
342 * @exception E_SUCCESS The method is successful.
343 * @exception E_INVALID_ARG A @c null pointer is passed.
345 result Append(const wchar_t* p);
348 * Appends the specified instance of %String to this instance
353 * @return An error code
354 * @param[in] str An instance of %String to append
355 * @exception E_SUCCESS The method is successful.
357 result Append(const String& str);
360 * Clears the current instance and sets it to an empty %String instance. @n
361 * The capacity is set to @c 16 bytes, which is the default capacity.
368 * Compares the values of the two strings.
372 * @return The 32-bit @c signed integer value
373 * @param[in] str0 The first %String instance to compare
374 * @param[in] str1 The second %String instance to compare
375 * @remarks This method performs an ordinal comparison of each Unicode
376 * character contained in the two given %String instances. @n
377 * For instance, "U+xxx" is greater than "U+XXX", but smaller than "U+yyy".
380 * < 0 if the value of the first instance is less than the value of the second instance
381 * == 0 if the value of the first instance is equal to the value of the second instance
382 * > 0 if the value of the first instance is greater than the value of the second instance
385 static int Compare(const String& str0, const String& str1);
388 * Compares the value of the current instance to the value of the specified instance
393 * @return The 32-bit @c signed integer value
395 * < 0 if the value of the current instance is less than the value of the specified %String instance
396 * == 0 if the value of the current instance is equal to the value of the specified %String instance
397 * > 0 if the value of the current instance is greater than the value of the specified %String instance
399 * @param[in] str An instance of %String to compare
400 * @remarks This method performs an ordinal comparison of each Unicode character. @n
401 * For instance, L"U+xxx" is greater than L"U+XXX", but smaller than L"U+yyy".
403 int CompareTo(const String& str) const;
406 * Ensures that the specified length is less than or equal to the capacity of
407 * the current instance of %String. @n
408 * Otherwise, it expands the capacity of the internal buffer to a value that is greater than or equal to the specified length.
412 * @return An error code
413 * @param[in] minLength The minimum length to ensure
414 * @exception E_SUCCESS The method is successful.
415 * @exception E_INVALID_ARG The specified @c minLength is negative.
417 result EnsureCapacity(int minLength);
420 * Checks whether the value of the specified instance of Object is equal to the value of the current instance of %String.
424 * @return @c true if the value of the specified instance of Object is equal to the value of the current instance of %String, @n
426 * @param[in] obj An instance of Object to compare
427 * @remarks This method returns @c false if the specified @c obj is not a string.
428 * @see Object::Equals()
430 virtual bool Equals(const Object& obj) const;
433 * Checks whether the value of the specified instance is equal to the value of the current instance of %String. @n
434 * Case sensitivity can be controlled.
438 * @return @c true if the values match, @n
440 * @param[in] str An instance of %String to compare with the
442 * @param[in] caseSensitive Set to @c true to perform a case sensitive ordinal comparison of the strings, @n
445 * @remarks This method performs an ordinal comparison of each Unicode
446 * character contained in the two given %String instances.
448 bool Equals(const String& str, bool caseSensitive) const;
451 * Formats the inputs as per the specified format and sets the value of the calling instance to the resultant string.
455 * @return An error code
456 * @param[in] length The maximum number of wide characters to write, including the terminating @c null character
457 * @param[in] pFormat The wide character format specifier
458 * @exception E_SUCCESS The method is successful.
459 * @exception E_INVALID_ARG Either of the following conditions has occurred:
460 * - The specified @c length is negative.
461 * - The specified @c pFormat is @c null.
463 * - If an "l" modifier is present in @c pFormat (for example, L"@%ls"), it is a pointer to an array of wide characters.
464 * - A pointer to an array of UTF-8 characters is not allowed in the Format() method (for example, Format(20, L"@%s", pUTF8Str)).
465 * The following format specifiers are supported in this method:
469 * c single byte character
470 * d(or i) signed decimal integer
471 * u unsigned decimal integer
472 * x unsigned hexadecimal integer
473 * f decimal floating point
474 * e scientific notation using e character
475 * g use the shorter of %e or %f
476 * s single byte character string
477 * ls(or S) wide-character string
478 * lld 64-bit signed decimal integer
482 * The following example demonstrates how to use the %Format() method.
488 * wchar_t* testStr = L"TEST";
490 * str.Format(25, L"FORMAT %d %ls", value, testStr); // str == L"FORMAT 10 TEST"
494 result Format(int length, const wchar_t* pFormat, ...);
497 * Gets the hash value of the current instance.
501 * @return The hash value of the current instance
502 * @remarks Two equal instances must return the same hash value. @n
503 * For better performance, the hash function used must generate a random distribution for all the inputs.
505 virtual int GetHashCode(void) const;
508 * Gets the character at the specified position.
512 * @return An error code
513 * @param[in] indexAt The position of the character
514 * @param[out] ch The character at the specified index
515 * @exception E_SUCCESS The method is successful.
516 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
517 * - The specified @c index is out of the valid range.
518 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
519 * - The specified @c indexAt is less than @c 0.
521 result GetCharAt(int indexAt, wchar_t& ch) const;
524 * Searches for a character in the calling instance. @n
525 * Gets the index of the first character that matches
526 * the specified character in this instance.
530 * @return An error code
531 * @param[in] ch The Unicode character to locate
532 * @param[in] startIndex The starting position of the search
533 * @param[out] indexOf The index of the character
534 * @exception E_SUCCESS The method is successful.
535 * @exception E_OBJ_NOT_FOUND The specified character is not found.
536 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
537 * - The specified @c index is out of the valid range.
538 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
539 * - The specified @c startIndex is less than @c 0.
541 result IndexOf(wchar_t ch, int startIndex, int& indexOf) const;
544 * Searches for a specified substring in the calling instance. @n
545 * Gets the starting index of the first occurrence of the specified substring.
549 * @return An error code
550 * @param[in] str An instance of %String to locate
551 * @param[in] startIndex The starting position of the search
552 * @param[out] indexOf The index of the substring
553 * @exception E_SUCCESS The method is successful.
554 * @exception E_OBJ_NOT_FOUND The specified string is not found.
555 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
556 * - The specified @c index is out of the valid range.
557 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
558 * - The specified @c startIndex is less than @c 0.
560 result IndexOf(const String& str, int startIndex, int& indexOf) const;
563 * Inserts the string that represents the specified Unicode character
564 * at the specified position in the calling instance.
568 * @return An error code
570 * @param[in] ch The Unicode character to insert
571 * @param[in] indexAt The position of the character
572 * @exception E_SUCCESS The method is successful.
573 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
574 * - The specified @c index is out of the valid range.
575 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
576 * - The specified @c indexAt is less than @c 0.
578 result Insert(wchar_t ch, int indexAt);
581 * Inserts the string that represents the specified @c char value
582 * at the specified position in the calling instance.
586 * @return An error code
588 * @param[in] ch The @c char value to insert
589 * @param[in] indexAt The position of the character
590 * @exception E_SUCCESS The method is successful.
591 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
592 * - The specified @c index is out of the valid range.
593 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
594 * - The specified @c indexAt is less than @c 0.
596 result Insert(char ch, int indexAt);
599 * Inserts the string that represents the specified 16-bit integer
600 * at the specified position in the calling instance.
604 * @return An error code
605 * @param[in] s The 16-bit integer value to insert
606 * @param[in] indexAt The position of the character
607 * @exception E_SUCCESS The method is successful.
608 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
609 * - The specified @c index is out of the valid range.
610 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
611 * - The specified @c indexAt is less than @c 0.
613 result Insert(short s, int indexAt);
616 * Inserts the string that represents the specified 32-bit integer
617 * at the specified position in the calling instance.
621 * @return An error code
622 * @param[in] i The 32-bit integer value to insert
623 * @param[in] indexAt The position of the character
624 * @exception E_SUCCESS The method is successful.
625 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
626 * - The specified @c index is out of the valid range.
627 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
628 * - The specified @c indexAt is less than @c 0.
630 result Insert(int i, int indexAt);
633 * Inserts the string that represents the specified @c long value
634 * at the specified position in the calling instance.
638 * @return An error code
639 * @param[in] l The @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 Either of the following conditions has occurred:
643 * - The specified @c index is out of the valid range.
644 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
645 * - The specified @c indexAt is less than @c 0.
647 result Insert(long l, int indexAt);
650 * Inserts the string that represents the specified @c long @c long value
651 * at the specified position in the calling instance.
655 * @return An error code
656 * @param[in] ll The @c long @c long value to insert
657 * @param[in] indexAt The position of the character
658 * @exception E_SUCCESS The method is successful.
659 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
660 * - The specified @c index is out of the valid range.
661 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
662 * - The specified @c indexAt is less than @c 0.
664 result Insert(long long ll, int indexAt);
667 * Inserts the string that represents the specified @c float value
668 * at the specified position in the calling instance.
672 * @return An error code
673 * @param[in] f The @c float value to insert
674 * @param[in] indexAt The position of the character
675 * @exception E_SUCCESS The method is successful.
676 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
677 * - The specified @c index is out of the valid range.
678 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
679 * - The specified @c indexAt is less than @c 0.
681 result Insert(float f, int indexAt);
684 * Inserts the string that represents the specified @c double value
685 * at the specified position in the calling instance.
689 * @return An error code
690 * @param[in] d The @c double value to insert
691 * @param[in] indexAt The position of the character
692 * @exception E_SUCCESS The method is successful.
693 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
694 * - The specified @c index is out of the valid range.
695 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
696 * - The specified @c indexAt is less than @c 0.
698 result Insert(double d, int indexAt);
701 * Inserts the string that represents the specified @c null-terminated
702 * string at the specified position in the calling instance.
706 * @return An error code
707 * @param[in] p An instance of %String to insert
708 * @param[in] indexAt The position of the character
709 * @exception E_SUCCESS The method is successful.
710 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
711 * - The specified @c index is out of the valid range.
712 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
713 * - The specified @c indexAt is less than @c 0.
714 * @exception E_INVALID_ARG A @c null pointer is passed.
716 result Insert(const wchar_t* p, int indexAt);
719 * Inserts the string that represents the specified instance of %String
720 * at the specified position in the calling instance.
724 * @return An error code
725 * @param[in] str An instance of %String to insert
726 * @param[in] indexAt The position of the character
727 * @exception E_SUCCESS The method is successful.
728 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
729 * - The specified @c index is out of the valid range.
730 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
731 * - The specified @c indexAt is less than @c 0.
733 result Insert(const String& str, int indexAt);
736 * Searches the calling instance for the last occurrence of the specified character and returns its index. @n
737 * The search begins at the @c startIndex position and proceeds backward towards the beginning.
741 * @return An error code
742 * @param[in] ch The Unicode character to locate
743 * @param[in] startIndex The starting position of the search
744 * @param[out] indexOf The index of character
745 * @exception E_SUCCESS The method is successful.
746 * @exception E_OBJ_NOT_FOUND The specified character is not found.
747 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
748 * - The specified @c index is out of the valid range.
749 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
750 * - The specified @c startIndex is less than @c 0.
752 result LastIndexOf(wchar_t ch, int startIndex, int& indexOf) const;
755 * Searches the calling instance for the last occurrence of the specified substring and returns its index. @n
756 * The search begins at the @c startIndex position and proceeds backward towards the beginning.
760 * @return An error code
761 * @param[in] str An instance of %String to locate
762 * @param[in] startIndex The starting position of the search
763 * @param[out] indexOf The index of the substring
764 * @exception E_SUCCESS The method is successful.
765 * @exception E_OBJ_NOT_FOUND The specified character is not found.
766 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
767 * - The specified @c index is out of the valid range.
768 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
769 * - The specified @c startIndex is less than @c 0.
770 * @remarks If the substring is empty, @c E_SUCCESS is returned and the value of @c indexOf is set to @c startIndex.
772 result LastIndexOf(const String& str, int startIndex, int& indexOf) const;
775 * Removes the characters within the specified range.
779 * @return An error code
780 * @param[in] startIndex The position where the removal begins
781 * @param[in] length The number of characters to remove
782 * @exception E_SUCCESS The method is successful.
783 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
784 * - The specified @c index is out of the valid range.
785 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
786 * - The specified @c startIndex is less than @c 0.
787 * - The specified @c count is either greater than the length of the substring starting from @c startIndex.
788 * - The specified @c count is less than @c 0.
790 result Remove(int startIndex, int length);
793 * Replaces all the occurrences of the specified characters.
797 * @param[in] original The character to replace
798 * @param[in] replace The character to replace all the occurrences of @c original
800 void Replace(wchar_t original, wchar_t replace);
803 * Replaces all the occurrences of the specified string.
807 * @return An error code
808 * @param[in] original An instance of %String to replace
809 * @param[in] replace An instance of %String to replace all the occurrences of @c original
810 * @exception E_SUCCESS The method is successful.
811 * @exception E_INVALID_ARG The specified @c original is an empty string.
813 result Replace(const String& original, const String& replace);
816 * Replaces all the occurrences of the specified string within the substring
817 * of this instance of %String.
821 * @return An error code
822 * @param[in] original An instance of %String to replace
823 * @param[in] replace An instance of %String to replace all the occurrences of @c original
824 * @param[in] startIndex The starting position of the substring
825 * @exception E_SUCCESS The method is successful.
826 * @exception E_INVALID_ARG The specified @c original is an empty string.
827 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
828 * - The specified @c index is out of the valid range.
829 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
830 * - The specified @c startIndex is less than @c 0.
832 result Replace(const String& original, const String& replace, int startIndex);
835 * Reverses the sequence of the characters in the calling instance.
843 * Sets the capacity of this instance of %String.
847 * @return An error code
848 * @param[in] newCapacity The new capacity
849 * @exception E_SUCCESS The method is successful.
850 * @exception E_INVALID_ARG The specified @c capacity is negative.
851 * @remarks If the new capacity is smaller than the current length, then
852 * the text contained in this instance is truncated.
854 result SetCapacity(int newCapacity);
857 * Sets the character at the specified index with the given character.
861 * @return An error code
862 * @param[in] ch The new character
863 * @param[in] indexAt The position of the character
864 * @exception E_SUCCESS The method is successful.
865 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
866 * - The specified @c index is out of the valid range.
867 * - The specified @c indexAt is either greater than or equal to the length of the current instance.
868 * - The specified @c indexAt is less than @c 0.
870 result SetCharAt(wchar_t ch, int indexAt);
873 * Sets the length of this instance of %String.
877 * @return An error code
878 * @param[in] newLength The new length
879 * @exception E_SUCCESS The method is successful.
880 * @exception E_INVALID_ARG The specified @c newLength is negative.
881 * @remarks If the new length is greater than the current length, the
882 * string is padded with spaces. @n
883 * On the other hand, if the new length is smaller than the current length, then
884 * the text contained in this instance is truncated.
886 result SetLength(int newLength);
889 * Gets a substring starting from the given index.
893 * @return An error code
894 * @param[in] startIndex The starting index of the substring
895 * @param[out] out The substring
896 * @exception E_SUCCESS The method is successful.
897 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
898 * - The specified @c index is out of the valid range.
899 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
900 * - The specified @c startIndex is less than @c 0.
902 result SubString(int startIndex, String& out) const;
905 * Gets a substring of the given length starting from the specified index.
909 * @return An error code
910 * @param[in] startIndex The starting position of the substring
911 * @param[in] length The length of the substring
912 * @param[out] out The substring
913 * @exception E_SUCCESS The method is successful.
914 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred:
915 * - The specified @c index is out of the valid range.
916 * - The specified @c startIndex is either greater than or equal to the length of the current instance.
917 * - The specified @c startIndex is less than @c 0.
918 * - The specified @c length is either greater than the length of the substring starting from @c startIndex.
919 * - The specified @c length is less than @c 0.
921 result SubString(int startIndex, int length, String& out) const;
924 * Checks whether this instance contains the specified text from the given index.
928 * @return @c true if this instance starts with the specified text, @n
930 * @param[in] str The string to match
931 * @param[in] startIndex The start position of the string
933 bool StartsWith(const String& str, int startIndex) const;
936 * Checks whether the given string is present at the end of the calling instance.
940 * @return @c true if this instance ends with the specified text, @n
942 * @param[in] str An instance of %String to match
944 bool EndsWith(const String& str) const;
948 * Gets the lowercase form of the string in the calling instance. @n
949 * Unicode characters other than the English alphabets are not changed.
951 * @brief <i> [Deprecated] </i>
952 * @deprecated This method is deprecated as a new method has been introduced.
953 * Instead of using this method, use the ToLowerCase(%String& out) method that supports Unicode characters other than the English alphabets.
956 * @return An error code
957 * @param[out] out An instance of %String that contains the modified value of the calling instance
958 * @exception E_SUCCESS The method is successful.
961 result ToLower(String& out) const;
964 * Gets the lowercase form of the string in the calling instance. @n
965 * Unicode characters other than the English alphabets are also supported.
969 * @return An error code
970 * @param[out] out An instance of %String that contains the modified value of the calling instance
971 * @exception E_SUCCESS The method is successful.
973 result ToLowerCase(String& out) const;
977 * Gets the uppercase form of the string in the calling instance. @n
978 * Unicode characters other than the English alphabets are not changed.
980 * @brief <i> [Deprecated] </i>
981 * @deprecated This method is deprecated as a new method has been introduced.
982 * Instead of using this method, use the ToUpperCase(%String& out) method that supports Unicode characters other than the English alphabets.
985 * @return An error code
986 * @param[out] out An instance of %String that contains the modified value of the calling instance
987 * @exception E_SUCCESS The method is successful.
990 result ToUpper(String& out) const;
993 * Gets the uppercase form of the string in the calling instance. @n
994 * Unicode characters other than the English alphabets are also supported.
998 * @return An error code
999 * @param[out] out An instance of %String that contains the modified value of the calling instance
1000 * @exception E_SUCCESS The method is successful.
1002 result ToUpperCase(String& out) const;
1006 * Converts all the letters in this instance to lowercase. @n
1007 * Unicode characters other than the English alphabets are not changed.
1009 * @brief <i> [Deprecated] </i>
1010 * @deprecated This method is deprecated as a new method has been introduced.
1011 * Instead of using this method, use the ToLowerCase() method that supports Unicode characters other than the English alphabets.
1019 * Converts all the letters in this instance to lowercase. @n
1020 * Unicode characters other than the English alphabets are also supported.
1024 void ToLowerCase(void);
1028 * Converts all the letters in this instance to uppercase. @n
1029 * Unicode characters other than the English alphabets are not changed.
1031 * @brief <i> [Deprecated] </i>
1032 * @deprecated This method is deprecated as a new method has been introduced.
1033 * Instead of using this method, use the ToUpperCase() method that supports Unicode characters other than the English alphabets.
1041 * Converts all the letters in this instance to uppercase. @n
1042 * Unicode characters other than the English alphabets are also supported.
1046 void ToUpperCase(void);
1049 * Trims the leading and trailing whitespace characters.
1056 * Gets the current capacity of this %String instance.
1060 * @return The capacity of this %String instance
1062 int GetCapacity(void) const;
1065 * Gets the length of the text contained in this %String instance.
1069 * @return The length of this %String instance
1071 int GetLength(void) const;
1074 * Gets a pointer to the instance's internal buffer.
1078 * @return A Unicode pointer to the calling instance's internal buffer
1079 * @remarks GetPointer() does not guarantee that every call to this method returns the same address.
1081 const wchar_t* GetPointer(void) const;
1084 * Checks whether this instance contains the specified substring.
1088 * @return @c true if this instance contains the specified substring, @n
1090 * @param[in] str The string to match
1092 bool Contains(const String& str) const;
1095 * The constant holding the default capacity of %String.
1099 static const unsigned long DEFAULT_CAPACITY = 16;
1103 // Allocates an internal buffer with the specified capacity.
1104 // @return An error code
1105 // @param[in] capacity The initial capacity of this instance of %String
1107 bool AllocateCapacity(int capacity);
1110 // Expands the size of the internal buffer that is greater than or equal
1111 // to the specified capacity.
1112 // @return @c true if the capacity is expanded, @n
1114 // @param[in] capacity The new capacity of this instance of %String
1116 bool ExpandCapacity(int minCapacity);
1119 // Initializes __pValue and __pRefCount
1123 result InitializeToDefault(int capacity);
1126 // When the reference count is bigger than 1 and it is not UNSHAREABLE, copies__pValue and subtracts and initializes __pRefCount.
1127 // If the isUnshareable is true, this method sets the reference count to UNSHAREABLE.
1131 result AboutToModify(int capacity, bool isUnshareable = false);
1134 // Swaps member-wisely
1138 void Swap(String& str);
1143 mutable volatile int* __pRefCount;
1144 mutable wchar_t* __pValue;
1146 static const float GROWTH_FACTOR;
1147 static const int UNSHAREABLE;
1149 class _StringImpl * __pStringImpl;
1150 friend class _StringImpl;
1154 #endif // _FBASE_STRING_H_