inc/FBaseString.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file                FBaseString.h
  20  * @brief               This is the header file for the %String class.
  21  *
  22  * This header file contains the declarations of the %String class.
  23  */
  24 #ifndef _FBASE_STRING_H_
  25 #define _FBASE_STRING_H_
  26
  27 #include <FBaseObject.h>
  28
  29
  30 namespace Tizen { namespace Base
  31 {
  32 /**
  33  *      @class  String
  34  *      @brief  This class represents a mutable sequence of Unicode characters.
  35  *
  36  *      @since 2.0
  37  *
  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.
  39  *
  40  *      For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/string.htm">String</a>.
  41  *
  42  * The following example demonstrates how to use the %String class.
  43  *
  44  *      @code
  45  *
  46  *      #include <FBase.h>
  47  *
  48  *      using namespace Tizen::Base;
  49  *
  50  *      void
  51  *      MyClass::StringSample(void)
  52  *      {
  53  *              String str;                         // capacity == 16, length == 0
  54  *
  55  *              str.Append((int)100);   // str == L"100"
  56  *
  57  *              str.Insert(L"abc", 0);  // str == L"abc100"
  58  *
  59  *              String str2(L"STRING TEST");
  60  *
  61  *              String subStr;
  62  *
  63  *              str2.SubString(7, 4, subStr);  // subStr == L"TEST"
  64  *      }
  65  *      @endcode
  66  */
  67 class _OSP_EXPORT_ String
  68         : public Object
  69 {
  70 public:
  71         /**
  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.
  74          *
  75          *      @since 2.0
  76          */
  77         String(void);
  78
  79         /**
  80          *      Initializes this instance of %String with the specified capacity.
  81          *
  82          * @since 2.0
  83          *
  84          * @param[in]   capacity The default capacity of this instance
  85          */
  86         String(int capacity);
  87
  88         /**
  89          * Initializes this instance of %String with the specified Unicode character.
  90          *
  91          * @since 2.0
  92          *
  93          * @param[in]   ch                      A Unicode character
  94          */
  95         String(const wchar_t ch);
  96
  97         /**
  98          * Initializes this instance of %String with the specified Unicode string.
  99          *
 100          * @since 2.0
 101          *
 102          * @param[in]   pValue          A pointer to an array of Unicode characters
 103          */
 104         String(const wchar_t* pValue);
 105
 106         /**
 107          * Initializes this instance of %String with the specified character string.
 108          *
 109          * @since 2.0
 110          *
 111          * @param[in]   pValue          A pointer to an array of UTF-8 characters
 112          */
 113         String(const char* pValue);
 114
 115         /**
 116          *      Copying of objects using this copy constructor is allowed.
 117          *
 118          * @since 2.0
 119          *
 120          * @param[in]   value   An instance of %String
 121          */
 122         String(const String& value);
 123
 124         /**
 125          * TThis destructor overrides Tizen::Base::Object::~Object().
 126          *
 127          * @since 2.0
 128          *
 129          *      @remarks                The internally allocated memory block is freed when the instance is destroyed.
 130          */
 131         virtual ~String(void);
 132
 133         /**
 134          * Returns the Unicode character at the specified @c index.
 135          *
 136          * @since 2.0
 137          *
 138          * @return        A const reference to the Unicode character
 139          * @param[in]    index An index within the current instance of %String
 140          */
 141         const wchar_t& operator [](int index) const;
 142
 143         /**
 144          * Returns a reference to the Unicode character at the specified @c index.
 145          *
 146          * @since 2.0
 147          *
 148          * @return        A reference to the Unicode character
 149          * @param[in]    index An index within the current instance of %String
 150          */
 151         wchar_t& operator [](int index);
 152
 153         /**
 154          *      Copies the text from the specified
 155          *      Unicode string to the calling instance of %String.
 156          *
 157          *      @since 2.0
 158          *
 159          *      @return                 A reference to the %String instance
 160          *      @param[in]      pRhs A pointer to an array of Unicode characters
 161          */
 162         String& operator =(const wchar_t* pRhs);
 163
 164         /**
 165          *      Copying of objects using this copy assignment operator is allowed.
 166          *
 167          *      @since 2.0
 168          *
 169          *      @return                 A reference to the %String instance
 170          *      @param[in]      rhs An instance of %String
 171          */
 172         String& operator =(const String& rhs);
 173
 174         /**
 175          *      Appends the text from the specified array of Unicode characters
 176          *      to the calling instance of %String.
 177          *
 178          *      @since 2.0
 179          *
 180          *      @return                 A reference to the %String instance
 181          *      @param[in]      pRhs    A pointer to an array of Unicode characters
 182          */
 183         String& operator +=(const wchar_t* pRhs);
 184
 185         /**
 186          *      Appends the text from the specified instance of %String
 187          *      to the calling instance of %String.
 188          *
 189          *      @since 2.0
 190          *
 191          *      @return                 A reference to the %String instance
 192          *      @param[in]      rhs An instance of %String to copy
 193          */
 194         String& operator +=(const String& rhs);
 195
 196         /**
 197          * Concatenates the two strings.
 198          *
 199          * @since 2.0
 200          *
 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
 204          */
 205         _OSP_EXPORT_ friend String operator +(const String& lhs, const String& rhs);
 206
 207         /**
 208          *      Checks the two strings for equality.
 209          *
 210          *      @since 2.0
 211          *
 212          *      @return                 @c true if the text of the specified %String instance equals the calling instance's text, @n
 213          *                              else @c false
 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.
 216          */
 217         bool operator ==(const String& rhs) const;
 218
 219         /**
 220          *      Checks the two strings for inequality.
 221          *
 222          *      @since 2.0
 223          *
 224          *      @return                 @c true if the text of the specified %String instance is not equal to the calling instance's text, @n
 225          *                              else @c false
 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.
 228          */
 229         bool operator !=(const String& rhs) const;
 230
 231         /**
 232          *      Checks whether the string is empty.
 233          *
 234          *      @since 2.0
 235          *
 236          *      @return         @c true if the current instance is a zero-length %String instance L"", @n
 237          *                              else @c false
 238          */
 239         bool IsEmpty(void) const;
 240
 241         /**
 242          * Appends the specified @c wchar_t value to this %String instance after converting it.
 243          *
 244          * @since 2.0
 245          *
 246          * @return              An error code
 247          * @param[in]   ch A @c wchar_t value to insert
 248          * @exception   E_SUCCESS               The method is successful.
 249          */
 250         result Append(wchar_t ch);
 251
 252         /**
 253          * Appends the specified @c char value to this %String instance after converting it.
 254          *
 255          * @since 2.0
 256          *
 257          * @return              An error code
 258          * @param[in]   ch A @c char value to insert
 259          * @exception   E_SUCCESS               The method is successful.
 260          */
 261         result Append(char ch);
 262
 263         /**
 264          * Appends the string representing the specified 32-bit @c int value to this
 265          * instance of %String.
 266          *
 267          * @since 2.0
 268          *
 269          * @return              An error code
 270          * @param[in]   i A 32-bit integer value to insert
 271          * @exception   E_SUCCESS               The method is successful.
 272          */
 273         result Append(int i);
 274
 275         /**
 276          * Appends the string representing the specified @c short value to this
 277          * instance of %String.
 278          *
 279          * @since 2.0
 280          *
 281          * @return              An error code
 282          * @param[in]   s A @c short value to insert
 283          * @exception   E_SUCCESS               The method is successful.
 284          */
 285         result Append(short s);
 286
 287         /**
 288          * Appends the string representing the specified @c long value to this
 289          * instance of %String.
 290          *
 291          * @since 2.0
 292          *
 293          * @return              An error code
 294          * @param[in]   l A @c long value to insert
 295          * @exception   E_SUCCESS               The method is successful.
 296          */
 297         result Append(long l);
 298
 299         /**
 300          * Appends the string representing the specified @c long @c long value to this
 301          * instance of %String.
 302          *
 303          * @since 2.0
 304          *
 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.
 308          */
 309         result Append(long long ll);
 310
 311         /**
 312          * Appends the string representing the specified @c float value to this
 313          * instance of %String.
 314          *
 315          * @since 2.0
 316          *
 317          * @return              An error code
 318          * @param[in]   f A @c float value to insert
 319          * @exception   E_SUCCESS               The method is successful.
 320          */
 321         result Append(float f);
 322
 323         /**
 324          * Appends the string representing the specified @c double value to this
 325          * instance of %String.
 326          *
 327          * @since 2.0
 328          *
 329          * @return              An error code
 330          * @param[in]   d A @c double value to insert
 331          * @exception   E_SUCCESS               The method is successful.
 332          */
 333         result Append(double d);
 334
 335         /**
 336          * Appends the specified null-terminated Unicode text to this instance
 337          * of %String.
 338          *
 339          * @since 2.0
 340          *
 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.
 345          */
 346         result Append(const wchar_t* p);
 347
 348         /**
 349          * Appends the specified instance of %String to this instance
 350          * of %String.
 351          *
 352          * @since 2.0
 353          *
 354          * @return              An error code
 355          * @param[in]   str An instance of %String to append
 356          * @exception   E_SUCCESS               The method is successful.
 357          */
 358         result Append(const String& str);
 359
 360         /**
 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.
 363          *
 364          * @since 2.0
 365          */
 366         void Clear(void);
 367
 368         /**
 369          * Compares the values of the two strings.
 370          *
 371          *  @since 2.0
 372          *
 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".
 379          *
 380          *      @code
 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
 384          *      @endcode
 385          */
 386         static int Compare(const String& str0, const String& str1);
 387
 388         /**
 389          * Compares the value of the current instance to the value of the specified instance
 390          * of %String.
 391          *
 392          * @since 2.0
 393          *
 394          * @return              A 32-bit @c signed integer value
 395          *@code
 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
 399          *@endcode
 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".
 403          */
 404         int CompareTo(const String& str) const;
 405
 406         /**
 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.
 410          *
 411          * @since 2.0
 412          *
 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.
 417          */
 418         result EnsureCapacity(int minLength);
 419
 420         /**
 421          * Checks whether the value of the specified instance of Object is equal to the value of the current instance of %String.
 422          *
 423          * @since 2.0
 424          *
 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
 426          *                              else @c false
 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()
 430          */
 431         virtual bool Equals(const Object& obj) const;
 432
 433         /**
 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.
 436          *
 437          * @since 2.0
 438          *
 439          * @return              @c true if the values match, @n
 440          *                              else @c false
 441          * @param[in]   str                             An instance of %String to compare with the
 442          *                                                              calling instance
 443          * @param[in]   caseSensitive   Set to @c true to perform a case sensitive ordinal comparison of the strings, @n
 444          *                                                              else @c false
 445          *
 446          * @remarks             This method performs an ordinal comparison of each Unicode
 447          *                      character contained in the two given %String instances.
 448          */
 449         bool Equals(const String& str, bool caseSensitive) const;
 450
 451         /**
 452          * Formats the inputs as per the specified format and sets the value of the calling instance to the resultant string.
 453          *
 454          * @since 2.0
 455          *
 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:
 464          * @code
 465          * specifier    Output
 466          * ---------    ------
 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
 477          *
 478          * @endcode
 479          *
 480          * The following example demonstrates how to use the %Format() method.
 481          * @code
 482          *
 483          *      String str;
 484          *
 485          *      int value = 10;
 486          *      wchar_t* testStr = L"TEST";
 487          *
 488          *      str.Format(25, L"FORMAT %d %ls", value, testStr);       // str == L"FORMAT 10 TEST"
 489          *
 490          * @endcode
 491          */
 492         result Format(int length, const wchar_t* pFormat, ...);
 493
 494         /**
 495          * Gets the hash value of the current instance.
 496          *
 497          * @since 2.0
 498          *
 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
 502          *                              for all inputs.
 503          */
 504         virtual int GetHashCode(void) const;
 505
 506         /**
 507          *  Gets the character at the specified position.
 508          *
 509          *  @since 2.0
 510          *
 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.
 517          */
 518         result GetCharAt(int indexAt, wchar_t& ch) const;
 519
 520         /**
 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.
 524          *
 525          * @since 2.0
 526          *
 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.
 535          */
 536         result IndexOf(wchar_t ch, int startIndex, int& indexOf) const;
 537
 538         /**
 539          * Searches for a specified substring in the calling instance. @n
 540          * Gets the starting index of the first occurrence of the specified substring.
 541          *
 542          * @since 2.0
 543          *
 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.
 552          */
 553         result IndexOf(const String& str, int startIndex, int& indexOf) const;
 554
 555         /**
 556          * Inserts the string representing the specified Unicode character
 557          * at the specified position in the calling instance.
 558          *
 559          * @since 2.0
 560          *
 561          * @return              An error code
 562          *
 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.
 568          */
 569         result Insert(wchar_t ch, int indexAt);
 570
 571         /**
 572          * Inserts the string representing the specified @c char value
 573          * at the specified position in the calling instance.
 574          *
 575          * @since 2.0
 576          *
 577          * @return              An error code
 578          *
 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.
 584          */
 585         result Insert(char ch, int indexAt);
 586
 587         /**
 588          * Inserts the string representing the specified 16-bit integer
 589          * at the specified position in the calling instance.
 590          *
 591          * @since 2.0
 592          *
 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.
 599          */
 600         result Insert(short s, int indexAt);
 601
 602         /**
 603          * Inserts the string representing the specified 32-bit integer
 604          * at the specified position in the calling instance.
 605          *
 606          * @since 2.0
 607          *
 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.
 614          */
 615         result Insert(int i, int indexAt);
 616
 617         /**
 618          * Inserts the string representing the specified @c long value
 619          * at the specified position in the calling instance.
 620          *
 621          * @since 2.0
 622          *
 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.
 629          */
 630         result Insert(long l, int indexAt);
 631
 632         /**
 633          * Inserts the string representing the specified @c long @c long value
 634          * at the specified position in the calling instance.
 635          *
 636          * @since 2.0
 637          *
 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.
 644          */
 645         result Insert(long long ll, int indexAt);
 646
 647         /**
 648          * Inserts the string representing the specified @c float value
 649          * at the specified position in the calling instance.
 650          *
 651          * @since 2.0
 652          *
 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.
 659          */
 660         result Insert(float f, int indexAt);
 661
 662         /**
 663          * Inserts the string representing the specified @c double value
 664          * at the specified position in the calling instance.
 665          *
 666          * @since 2.0
 667          *
 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.
 674          */
 675         result Insert(double d, int indexAt);
 676
 677         /**
 678          * Inserts the string representing the specified @c null-terminated
 679          * string at the specified position in the calling instance.
 680          *
 681          * @since 2.0
 682          *
 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.
 690          */
 691         result Insert(const wchar_t* p, int indexAt);
 692
 693         /**
 694          * Inserts the string representing the specified instance of %String
 695          * at the specified position in the calling instance.
 696          *
 697          * @since 2.0
 698          *
 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.
 705          */
 706         result Insert(const String& str, int indexAt);
 707
 708         /**
 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.
 711          *
 712          *  @since 2.0
 713          *
 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.
 722          */
 723         result LastIndexOf(wchar_t ch, int startIndex, int& indexOf) const;
 724
 725         /**
 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.
 728          *
 729          * @since 2.0
 730          *
 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.
 740          */
 741         result LastIndexOf(const String& str, int startIndex, int& indexOf) const;
 742
 743         /**
 744          * Removes the characters within the specified range.
 745          *
 746          * @since 2.0
 747          *
 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.
 756          */
 757         result Remove(int startIndex, int length);
 758
 759         /**
 760          * Replaces all occurrences of the specified characters.
 761          *
 762          * @since 2.0
 763          *
 764          * @param[in]   original The character to replace
 765          * @param[in]   replace The character to replace all occurrences of @c original
 766          */
 767         void Replace(wchar_t original, wchar_t replace);
 768
 769         /**
 770          * Replaces all occurrences of the specified string.
 771          *
 772          * @since 2.0
 773          *
 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.
 779          */
 780         result Replace(const String& original, const String& replace);
 781
 782         /**
 783          * Replaces all occurrences of the specified string within the substring
 784          * of this instance of %String.
 785          *
 786          * @since 2.0
 787          *
 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.
 796          */
 797         result Replace(const String& original, const String& replace, int startIndex);
 798
 799         /**
 800          * Reverses the sequence of characters in the calling instance.
 801          *
 802          * @since 2.0
 803          *
 804          */
 805         void Reverse(void);
 806
 807         /**
 808          * Sets the capacity of this instance of %String.
 809          *
 810          * @since 2.0
 811          *
 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.
 818          */
 819         result SetCapacity(int newCapacity);
 820
 821         /**
 822          * Sets the character at the specified index with the given character.
 823          *
 824          * @since 2.0
 825          *
 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.
 832          */
 833         result SetCharAt(wchar_t ch, int indexAt);
 834
 835         /**
 836          * Sets the length of this instance of %String.
 837          *
 838          * @since 2.0
 839          *
 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.
 848          */
 849         result SetLength(int newLength);
 850
 851         /**
 852          * Gets a substring starting from the given index.
 853          *
 854          * @since 2.0
 855          *
 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.
 862          */
 863         result SubString(int startIndex, String& out) const;
 864
 865         /**
 866          * Gets a substring of the given length starting from the specified index.
 867          *
 868          * @since 2.0
 869          *
 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.
 879          */
 880         result SubString(int startIndex, int length, String& out) const;
 881
 882         /**
 883          *      Checks whether this instance contains the specified text from the given index.
 884          *
 885          *  @since 2.0
 886          *
 887          *      @return                 @c true if this instance starts with the specified text, @n
 888          *                              else @c false
 889          *      @param[in]      str                                     The string to match
 890          *      @param[in]      startIndex                      The start position of the string
 891          */
 892         bool StartsWith(const String& str, int startIndex) const;
 893
 894         /**
 895          *      Checks whether the given string is present at the end of the calling instance.
 896          *
 897          *  @since 2.0
 898          *
 899          *      @return                 @c true if this instance ends with the specified text, @n
 900          *                              else @c false
 901          *      @param[in]      str                             An instance of %String to match
 902          */
 903         bool EndsWith(const String& str) const;
 904
 905         /**
 906          *      @if OSPDEPREC
 907          *      Gets the lowercase form of the string in the calling instance. @n
 908          *  Unicode characters other than the English alphabets are not changed.
 909          *
 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.
 913          *  @since 2.0
 914          *
 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.
 918          *      @endif
 919          */
 920         result ToLower(String& out) const;
 921
 922         /**
 923          *      Gets the lowercase form of the string in the calling instance. @n
 924      *  Unicode characters other than the English alphabets are also supported.
 925          *
 926          *      @since 2.0
 927          *
 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.
 931          */
 932         result ToLowerCase(String& out) const;
 933
 934         /**
 935          *      @if OSPDEPREC
 936          *      Gets the uppercase form of the string in the calling instance. @n
 937          *  Unicode characters other than the English alphabets are not changed.
 938          *
 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.
 942          *  @since 2.0
 943          *
 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.
 947          *      @endif
 948          */
 949         result ToUpper(String& out) const;
 950
 951         /**
 952          *      Gets the uppercase form of the string in the calling instance. @n
 953      *  Unicode characters other than the English alphabets are also supported.
 954          *
 955          *      @since 2.0
 956          *
 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.
 960          */
 961         result ToUpperCase(String& out) const;
 962
 963         /**
 964          *      @if OSPDEPREC
 965          *      Converts all the letters in this instance to lowercase. @n
 966          *  Unicode characters other than the English alphabets are not changed.
 967          *
 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.
 971          *
 972          *  @since 2.0
 973          *      @endif
 974          */
 975         void ToLower(void);
 976
 977         /**
 978          *      Converts all the letters in this instance to lowercase. @n
 979          *  Unicode characters other than the English alphabets are also supported.
 980          *
 981          *      @since 2.0
 982          */
 983         void ToLowerCase(void);
 984
 985         /**
 986          *      @if OSPDEPREC
 987          *      Converts all the letters in this instance to uppercase. @n
 988          *  Unicode characters other than the English alphabets are not changed.
 989          *
 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.
 993          *
 994          *  @since 2.0
 995          *      @endif
 996          */
 997         void ToUpper(void);
 998
 999         /**
1000          *      Converts all the letters in this instance to uppercase. @n
1001      *  Unicode characters other than the English alphabets are also supported.
1002          *
1003          *      @since 2.0
1004          */
1005         void ToUpperCase(void);
1006
1007         /**
1008          *      Trims the leading and trailing whitespace characters.
1009          *
1010          *  @since 2.0
1011          */
1012         void Trim(void);
1013
1014         /**
1015          * Gets the current capacity of this %String instance.
1016          *
1017          * @since 2.0
1018          *
1019          * @return              The capacity of this %String instance
1020          */
1021         int GetCapacity(void) const;
1022
1023         /**
1024          * Gets the length of the text contained in this %String instance.
1025          *
1026          * @since 2.0
1027          *
1028          * @return              The length of this %String instance
1029          */
1030         int GetLength(void) const;
1031
1032         /**
1033          * Gets a pointer to the instance's internal buffer.
1034          *
1035          * @since 2.0
1036          *
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.
1039          */
1040         const wchar_t* GetPointer(void) const;
1041
1042         /**
1043         * Checks whether this instance contains the specified substring.
1044         *
1045         *  @since 2.0
1046         *
1047         *  @return                 @c true if this instance contains the specified substring, @n
1048         *                              else @c false
1049         *  @param[in]    str       The string to match
1050         */
1051         bool Contains(const String& str) const;
1052
1053         /**
1054          * A constant holding the default capacity of %String.
1055          *
1056          * @since 2.0
1057          */
1058         static const unsigned long DEFAULT_CAPACITY = 16;
1059
1060 private:
1061         //
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
1065         //
1066         bool AllocateCapacity(int capacity);
1067
1068         //
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
1072         //              else @c false
1073         // @param[in]   capacity The new capacity of this instance of %String
1074         //
1075         bool ExpandCapacity(int minCapacity);
1076
1077         //
1078         // Initializes __pValue and __pRefCount
1079         //
1080         // @since 2.0
1081         //
1082         result InitializeToDefault(int capacity);
1083
1084         //
1085         // Copies __pValue and subtract and initialize __pRefCount
1086         //
1087         // @since 2.0
1088         //
1089         result CopyOnWrite(int capacity);
1090
1091         //
1092         // Swaps member-wisely
1093         //
1094         // @since 2.0
1095         //
1096         void Swap(String& str);
1097
1098         int __capacity;
1099         int __length;
1100         mutable int __hash;
1101         mutable int* __pRefCount;
1102         mutable wchar_t* __pValue;
1103
1104         static const float GROWTH_FACTOR;
1105
1106         class _StringImpl * __pStringImpl;
1107         friend class _StringImpl;
1108 }; // String
1109
1110 }} // Tizen::Base
1111 #endif // _FBASE_STRING_H_