inc/FBaseString.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   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
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  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.
  15 //
  16
  17 /**
  18  * @file                FBaseString.h
  19  * @brief               This is the header file for the %String class.
  20  *
  21  * This header file contains the declarations of the %String class.
  22  */
  23 #ifndef _FBASE_STRING_H_
  24 #define _FBASE_STRING_H_
  25
  26 #include <FBaseObject.h>
  27
  28
  29 namespace Tizen { namespace Base
  30 {
  31 /**
  32  *      @class  String
  33  *      @brief  This class represents a mutable sequence of Unicode characters.
  34  *
  35  *      @since 2.0
  36  *
  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.
  38  *
  39  *      For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/string.htm">String</a>.
  40  *
  41  * The following example demonstrates how to use the %String class.
  42  *
  43  *      @code
  44  *
  45  *      #include <FBase.h>
  46  *
  47  *      using namespace Tizen::Base;
  48  *
  49  *      void
  50  *      MyClass::StringSample(void)
  51  *      {
  52  *              String str;                         // capacity == 16, length == 0
  53  *
  54  *              str.Append((int)100);   // str == L"100"
  55  *
  56  *              str.Insert(L"abc", 0);  // str == L"abc100"
  57  *
  58  *              String str2(L"STRING TEST");
  59  *
  60  *              String subStr;
  61  *
  62  *              str2.SubString(7, 4, subStr);  // subStr == L"TEST"
  63  *      }
  64  *      @endcode
  65  */
  66 class _OSP_EXPORT_ String
  67         : public Object
  68 {
  69 public:
  70         /**
  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.
  73          *
  74          *      @since 2.0
  75          */
  76         String(void);
  77
  78         /**
  79          *      Initializes this instance of %String with the specified capacity.
  80          *
  81          * @since 2.0
  82          *
  83          * @param[in]   capacity The default capacity of this instance
  84          */
  85         String(int capacity);
  86
  87         /**
  88          * Initializes this instance of %String with the specified Unicode character.
  89          *
  90          * @since 2.0
  91          *
  92          * @param[in]   ch                      A Unicode character
  93          */
  94         String(wchar_t ch);
  95
  96         /**
  97          * Initializes this instance of %String with the specified Unicode string.
  98          *
  99          * @since 2.0
 100          *
 101          * @param[in]   pValue          A pointer to an array of Unicode characters
 102          */
 103         String(const wchar_t* pValue);
 104
 105         /**
 106          * Initializes this instance of %String with the specified character string.
 107          *
 108          * @since 2.0
 109          *
 110          * @param[in]   pValue          A pointer to an array of UTF-8 characters
 111          */
 112         String(const char* pValue);
 113
 114         /**
 115          *      Copying of objects using this copy constructor is allowed.
 116          *
 117          * @since 2.0
 118          *
 119          * @param[in]   value   An instance of %String
 120          */
 121         String(const String& value);
 122
 123         /**
 124          * TThis destructor overrides Tizen::Base::Object::~Object().
 125          *
 126          * @since 2.0
 127          *
 128          *      @remarks                The internally allocated memory block is freed when the instance is destroyed.
 129          */
 130         virtual ~String(void);
 131
 132         /**
 133          * Returns the Unicode character at the specified @c index.
 134          *
 135          * @since 2.0
 136          *
 137          * @return        A const reference to the Unicode character
 138          * @param[in]    index An index within the current instance of %String
 139          */
 140         const wchar_t& operator [](int index) const;
 141
 142         /**
 143          * Returns a reference to the Unicode character at the specified @c index.
 144          *
 145          * @since 2.0
 146          *
 147          * @return        A reference to the Unicode character
 148          * @param[in]    index An index within the current instance of %String
 149          */
 150         wchar_t& operator [](int index);
 151
 152         /**
 153          *      Copies the text from the specified
 154          *      Unicode string to the calling instance of %String.
 155          *
 156          *      @since 2.0
 157          *
 158          *      @return                 A reference to the %String instance
 159          *      @param[in]      pRhs A pointer to an array of Unicode characters
 160          */
 161         String& operator =(const wchar_t* pRhs);
 162
 163         /**
 164          *      Copying of objects using this copy assignment operator is allowed.
 165          *
 166          *      @since 2.0
 167          *
 168          *      @return                 A reference to the %String instance
 169          *      @param[in]      rhs An instance of %String
 170          */
 171         String& operator =(const String& rhs);
 172
 173         /**
 174          *      Appends the text from the specified array of Unicode characters
 175          *      to the calling instance of %String.
 176          *
 177          *      @since 2.0
 178          *
 179          *      @return                 A reference to the %String instance
 180          *      @param[in]      pRhs    A pointer to an array of Unicode characters
 181          */
 182         String& operator +=(const wchar_t* pRhs);
 183
 184         /**
 185          *      Appends the text from the specified instance of %String
 186          *      to the calling instance of %String.
 187          *
 188          *      @since 2.0
 189          *
 190          *      @return                 A reference to the %String instance
 191          *      @param[in]      rhs An instance of %String to copy
 192          */
 193         String& operator +=(const String& rhs);
 194
 195         /**
 196          * Concatenates the two strings.
 197          *
 198          * @since 2.0
 199          *
 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
 203          */
 204         _OSP_EXPORT_ friend String operator +(const String& lhs, const String& rhs);
 205
 206         /**
 207          *      Checks the two strings for equality.
 208          *
 209          *      @since 2.0
 210          *
 211          *      @return                 @c true if the text of the specified %String instance equals the calling instance's text, @n
 212          *                              else @c false
 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.
 215          */
 216         bool operator ==(const String& rhs) const;
 217
 218         /**
 219          *      Checks the two strings for inequality.
 220          *
 221          *      @since 2.0
 222          *
 223          *      @return                 @c true if the text of the specified %String instance is not equal to the calling instance's text, @n
 224          *                              else @c false
 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.
 227          */
 228         bool operator !=(const String& rhs) const;
 229
 230         /**
 231          *      Checks whether the string is empty.
 232          *
 233          *      @since 2.0
 234          *
 235          *      @return         @c true if the current instance is a zero-length %String instance L"", @n
 236          *                              else @c false
 237          */
 238         bool IsEmpty(void) const;
 239
 240         /**
 241          * Appends the specified @c wchar_t value to this %String instance after converting it.
 242          *
 243          * @since 2.0
 244          *
 245          * @return              An error code
 246          * @param[in]   ch A @c wchar_t value to insert
 247          * @exception   E_SUCCESS               The method is successful.
 248          */
 249         result Append(wchar_t ch);
 250
 251         /**
 252          * Appends the specified @c char value to this %String instance after converting it.
 253          *
 254          * @since 2.0
 255          *
 256          * @return              An error code
 257          * @param[in]   ch A @c char value to insert
 258          * @exception   E_SUCCESS               The method is successful.
 259          */
 260         result Append(char ch);
 261
 262         /**
 263          * Appends the string representing the specified 32-bit @c int value to this
 264          * instance of %String.
 265          *
 266          * @since 2.0
 267          *
 268          * @return              An error code
 269          * @param[in]   i A 32-bit integer value to insert
 270          * @exception   E_SUCCESS               The method is successful.
 271          */
 272         result Append(int i);
 273
 274         /**
 275          * Appends the string representing the specified @c short value to this
 276          * instance of %String.
 277          *
 278          * @since 2.0
 279          *
 280          * @return              An error code
 281          * @param[in]   s A @c short value to insert
 282          * @exception   E_SUCCESS               The method is successful.
 283          */
 284         result Append(short s);
 285
 286         /**
 287          * Appends the string representing the specified @c long value to this
 288          * instance of %String.
 289          *
 290          * @since 2.0
 291          *
 292          * @return              An error code
 293          * @param[in]   l A @c long value to insert
 294          * @exception   E_SUCCESS               The method is successful.
 295          */
 296         result Append(long l);
 297
 298         /**
 299          * Appends the string representing the specified @c long @c long value to this
 300          * instance of %String.
 301          *
 302          * @since 2.0
 303          *
 304          * @return              An error code
 305          * @param[in]   ll A @c long @c long value to insert
 306          * @exception   E_SUCCESS               The method is successful.
 307          */
 308         result Append(long long ll);
 309
 310         /**
 311          * Appends the string representing the specified @c float value to this
 312          * instance of %String.
 313          *
 314          * @since 2.0
 315          *
 316          * @return              An error code
 317          * @param[in]   f A @c float value to insert
 318          * @exception   E_SUCCESS               The method is successful.
 319          */
 320         result Append(float f);
 321
 322         /**
 323          * Appends the string representing the specified @c double value to this
 324          * instance of %String.
 325          *
 326          * @since 2.0
 327          *
 328          * @return              An error code
 329          * @param[in]   d A @c double value to insert
 330          * @exception   E_SUCCESS               The method is successful.
 331          */
 332         result Append(double d);
 333
 334         /**
 335          * Appends the specified null-terminated Unicode text to this instance
 336          * of %String.
 337          *
 338          * @since 2.0
 339          *
 340          * @return              An error code
 341          * @param[in]   p A pointer to a Unicode character array
 342          * @exception   E_SUCCESS               The method is successful.
 343          * @exception   E_INVALID_ARG   A @c null pointer is passed.
 344          */
 345         result Append(const wchar_t* p);
 346
 347         /**
 348          * Appends the specified instance of %String to this instance
 349          * of %String.
 350          *
 351          * @since 2.0
 352          *
 353          * @return              An error code
 354          * @param[in]   str An instance of %String to append
 355          * @exception   E_SUCCESS               The method is successful.
 356          */
 357         result Append(const String& str);
 358
 359         /**
 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.
 362          *
 363          * @since 2.0
 364          */
 365         void Clear(void);
 366
 367         /**
 368          * Compares the values of the two strings.
 369          *
 370          *  @since 2.0
 371          *
 372          *      @return                 A 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.
 377          *                              For instance, "U+xxx" is greater than "U+XXX", but smaller than "U+yyy".
 378          *
 379          *      @code
 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
 383          *      @endcode
 384          */
 385         static int Compare(const String& str0, const String& str1);
 386
 387         /**
 388          * Compares the value of the current instance to the value of the specified instance
 389          * of %String.
 390          *
 391          * @since 2.0
 392          *
 393          * @return              A 32-bit @c signed integer value
 394          *@code
 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
 398          *@endcode
 399          * @param[in]   str             An instance of %String to compare
 400          * @remarks             This method performs an ordinal comparison of each Unicode character. For instance,
 401          *                              L"U+xxx" is greater than L"U+XXX", but smaller than L"U+yyy".
 402          */
 403         int CompareTo(const String& str) const;
 404
 405         /**
 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.
 409          *
 410          * @since 2.0
 411          *
 412          * @return              An error code
 413          * @param[in]   minLength               A minimum length to ensure
 414          * @exception   E_SUCCESS               The method is successful.
 415          * @exception   E_INVALID_ARG   The specified @c minLength is negative.
 416          */
 417         result EnsureCapacity(int minLength);
 418
 419         /**
 420          * Checks whether the value of the specified instance of Object is equal to the value of the current instance of %String.
 421          *
 422          * @since 2.0
 423          *
 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
 425          *                              else @c false
 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()
 429          */
 430         virtual bool Equals(const Object& obj) const;
 431
 432         /**
 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.
 435          *
 436          * @since 2.0
 437          *
 438          * @return              @c true if the values match, @n
 439          *                              else @c false
 440          * @param[in]   str                             An instance of %String to compare with the
 441          *                                                              calling instance
 442          * @param[in]   caseSensitive   Set to @c true to perform a case sensitive ordinal comparison of the strings, @n
 443          *                                                              else @c false
 444          *
 445          * @remarks             This method performs an ordinal comparison of each Unicode
 446          *                      character contained in the two given %String instances.
 447          */
 448         bool Equals(const String& str, bool caseSensitive) const;
 449
 450         /**
 451          * Formats the inputs as per the specified format and sets the value of the calling instance to the resultant string.
 452          *
 453          * @since 2.0
 454          *
 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   The specified @c length is negative or @c pFormat is @c null.
 460          * @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
 461          * @remarks             A pointer to an array of UTF-8 characters is not allowed in the Format() method (for example, Format(20, L"@%s", pUTF8Str)).
 462          * The following format specifiers are supported in this method:
 463          * @code
 464          * specifier    Output
 465          * ---------    ------
 466          * c            single byte character
 467          * d(or i)      signed decimal integer
 468          * u            unsigned decimal integer
 469          * x            unsigned hexadecimal integer
 470          * f            decimal floating point
 471          * e            scientific notation using e character
 472          * g            use the shorter of %e or %f
 473          * s            single byte character string
 474          * ls(or S)     wide-character string
 475          * lld          64-bit signed decimal integer
 476          *
 477          * @endcode
 478          *
 479          * The following example demonstrates how to use the %Format() method.
 480          * @code
 481          *
 482          *      String str;
 483          *
 484          *      int value = 10;
 485          *      wchar_t* testStr = L"TEST";
 486          *
 487          *      str.Format(25, L"FORMAT %d %ls", value, testStr);       // str == L"FORMAT 10 TEST"
 488          *
 489          * @endcode
 490          */
 491         result Format(int length, const wchar_t* pFormat, ...);
 492
 493         /**
 494          * Gets the hash value of the current instance.
 495          *
 496          * @since 2.0
 497          *
 498          *      @return         The hash value of the current instance
 499          * @remarks     Two equal instances must return the same hash value. For better performance,
 500          *                              the hash function used must generate a random distribution
 501          *                              for all inputs.
 502          */
 503         virtual int GetHashCode(void) const;
 504
 505         /**
 506          *  Gets the character at the specified position.
 507          *
 508          *  @since 2.0
 509          *
 510          *      @return                 An error code
 511          *      @param[in]      indexAt                                 The position of the character
 512          *      @param[out]     ch                                              The character at the specified index
 513          *      @exception      E_SUCCESS                               The method is successful.
 514          *      @exception      E_OUT_OF_RANGE                  The specified index is out of range, or
 515          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 516          */
 517         result GetCharAt(int indexAt, wchar_t& ch) const;
 518
 519         /**
 520          * Searches for a character in the calling instance. @n
 521          * Gets the index of the first character that matches to
 522          * the specified character in this instance.
 523          *
 524          * @since 2.0
 525          *
 526          * @return                      An error code
 527          * @param[in]   ch                                              The Unicode character to locate
 528          * @param[in]   startIndex                              The starting position of search
 529          * @param[out]  indexOf                                 The index of the character
 530          *      @exception      E_SUCCESS                               The method is successful.
 531          *      @exception      E_OBJ_NOT_FOUND                 The specified character is not found.
 532          *      @exception      E_OUT_OF_RANGE                  The specified index is out of range, or
 533          *                                                                              the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
 534          */
 535         result IndexOf(wchar_t ch, int startIndex, int& indexOf) const;
 536
 537         /**
 538          * Searches for a specified substring in the calling instance. @n
 539          * Gets the starting index of the first occurrence of the specified substring.
 540          *
 541          * @since 2.0
 542          *
 543          * @return              An error code
 544          * @param[in]   str                                             An instance of %String to locate
 545          * @param[in]   startIndex                              The starting position of the search
 546          * @param[out]  indexOf                                 The index of the substring
 547          * @exception   E_SUCCESS                               The method is successful.
 548          * @exception   E_OBJ_NOT_FOUND                 The specified string is not found.
 549          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 550          *                                                                              the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
 551          */
 552         result IndexOf(const String& str, int startIndex, int& indexOf) const;
 553
 554         /**
 555          * Inserts the string representing the specified Unicode character
 556          * at the specified position in the calling instance.
 557          *
 558          * @since 2.0
 559          *
 560          * @return              An error code
 561          *
 562          * @param[in]   ch                                              A Unicode character to insert
 563          * @param[in]   indexAt                                 The position of the character
 564          * @exception   E_SUCCESS                               The method is successful.
 565          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 566          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 567          */
 568         result Insert(wchar_t ch, int indexAt);
 569
 570         /**
 571          * Inserts the string representing the specified @c char value
 572          * at the specified position in the calling instance.
 573          *
 574          * @since 2.0
 575          *
 576          * @return              An error code
 577          *
 578          * @param[in]   ch                                              A @c char value to insert
 579          * @param[in]   indexAt                                 The position of the character
 580          * @exception   E_SUCCESS                               The method is successful.
 581          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 582          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 583          */
 584         result Insert(char ch, int indexAt);
 585
 586         /**
 587          * Inserts the string representing the specified 16-bit integer
 588          * at the specified position in the calling instance.
 589          *
 590          * @since 2.0
 591          *
 592          * @return              An error code
 593          * @param[in]   s                                               A 16-bit integer value to insert
 594          * @param[in]   indexAt                                 The position of the character
 595          * @exception   E_SUCCESS                               The method is successful.
 596          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 597          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 598          */
 599         result Insert(short s, int indexAt);
 600
 601         /**
 602          * Inserts the string representing the specified 32-bit integer
 603          * at the specified position in the calling instance.
 604          *
 605          * @since 2.0
 606          *
 607          * @return              An error code
 608          * @param[in]   i                                               A 32-bit integer value to insert
 609          * @param[in]   indexAt                                 The position of the character
 610          * @exception   E_SUCCESS                               The method is successful.
 611          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 612          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 613          */
 614         result Insert(int i, int indexAt);
 615
 616         /**
 617          * Inserts the string representing the specified @c long value
 618          * at the specified position in the calling instance.
 619          *
 620          * @since 2.0
 621          *
 622          * @return              An error code
 623          * @param[in]   l                                               A @c long value to insert
 624          * @param[in]   indexAt                                 The position of the character
 625          * @exception   E_SUCCESS                               The method is successful.
 626          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 627          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 628          */
 629         result Insert(long l, int indexAt);
 630
 631         /**
 632          * Inserts the string representing the specified @c long @c long value
 633          * at the specified position in the calling instance.
 634          *
 635          * @since 2.0
 636          *
 637          * @return              An error code
 638          * @param[in]   ll                                              A @c long @c long value to insert
 639      * @param[in]       indexAt                                 The position of the character
 640          * @exception   E_SUCCESS                               The method is successful.
 641          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 642          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 643          */
 644         result Insert(long long ll, int indexAt);
 645
 646         /**
 647          * Inserts the string representing the specified @c float value
 648          * at the specified position in the calling instance.
 649          *
 650          * @since 2.0
 651          *
 652          * @return              An error code
 653          * @param[in]   f                                               A @c float value to insert
 654          * @param[in]   indexAt                                 The position of the character
 655          * @exception   E_SUCCESS                               The method is successful.
 656          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 657          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 658          */
 659         result Insert(float f, int indexAt);
 660
 661         /**
 662          * Inserts the string representing the specified @c double value
 663          * at the specified position in the calling instance.
 664          *
 665          * @since 2.0
 666          *
 667          * @return              An error code
 668          * @param[in]   d                                               A @c double value to insert
 669          * @param[in]   indexAt                                 The position of the character
 670          * @exception   E_SUCCESS                               The method is successful.
 671          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 672          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 673          */
 674         result Insert(double d, int indexAt);
 675
 676         /**
 677          * Inserts the string representing the specified @c null-terminated
 678          * string at the specified position in the calling instance.
 679          *
 680          * @since 2.0
 681          *
 682          * @return              An error code
 683          * @param[in]   p                                               An instance of %String to insert
 684          * @param[in]   indexAt                                 The position of the character
 685          * @exception   E_SUCCESS                               The method is successful.
 686          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 687          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 688          * @exception   E_INVALID_ARG                   A @c null pointer is passed.
 689          */
 690         result Insert(const wchar_t* p, int indexAt);
 691
 692         /**
 693          * Inserts the string representing the specified instance of %String
 694          * at the specified position in the calling instance.
 695          *
 696          * @since 2.0
 697          *
 698          * @return              An error code
 699          * @param[in]   str                                             An instance of %String to insert
 700          * @param[in]   indexAt                                 The position of the character
 701          * @exception   E_SUCCESS                               The method is successful.
 702          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 703          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 704          */
 705         result Insert(const String& str, int indexAt);
 706
 707         /**
 708          * Searches the calling instance for the last occurrence of the specified character and returns its index. @n
 709          * The search begins at the @c startIndex position and proceeds backward towards the beginning.
 710          *
 711          *  @since 2.0
 712          *
 713          *      @return                 An error code
 714          *      @param[in]      ch                                              The Unicode character to locate
 715          *      @param[in]      startIndex                              The starting position of search
 716          *      @param[out]     indexOf                                 The index of character
 717          *      @exception      E_SUCCESS                               The method is successful.
 718          *      @exception      E_OBJ_NOT_FOUND                 The specified character is not found.
 719          *      @exception      E_OUT_OF_RANGE                  The specified index is out of range, or
 720          *                                                                              the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
 721          */
 722         result LastIndexOf(wchar_t ch, int startIndex, int& indexOf) const;
 723
 724         /**
 725          * Searches the calling instance for the last occurrence of the specified substring and returns its index. @n
 726          * The search begins at the @c startIndex position and proceeds backward towards the beginning.
 727          *
 728          * @since 2.0
 729          *
 730          * @return              An error code
 731          * @param[in]   str                                             An instance of %String to locate
 732          * @param[in]   startIndex                              The starting position of search
 733          * @param[out]  indexOf                                 The index of the substring
 734          * @exception   E_SUCCESS                               The method is successful.
 735          * @exception   E_OBJ_NOT_FOUND                 The specified character is not found.
 736          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 737          *                                                                              the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
 738          * @remarks     If the substring is empty, E_SUCCESS is returned and the value of @c indexOf is set to @c startIndex.
 739          */
 740         result LastIndexOf(const String& str, int startIndex, int& indexOf) const;
 741
 742         /**
 743          * Removes the characters within the specified range.
 744          *
 745          * @since 2.0
 746          *
 747          * @return              An error code
 748          * @param[in]   startIndex                              The position where the removal begins
 749          * @param[in]   length                                  The number of characters to remove
 750          * @exception   E_SUCCESS                               The method is successful.
 751          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred: @n
 752          *                                                                              - The specified index is out of range. @n
 753          *                                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0. @n
 754          *                                                                              - The specified @c count is either greater than the length of substring starting from @c startIndex or less than @c 0.
 755          */
 756         result Remove(int startIndex, int length);
 757
 758         /**
 759          * Replaces all occurrences of the specified characters.
 760          *
 761          * @since 2.0
 762          *
 763          * @param[in]   original The character to replace
 764          * @param[in]   replace The character to replace all occurrences of @c original
 765          */
 766         void Replace(wchar_t original, wchar_t replace);
 767
 768         /**
 769          * Replaces all occurrences of the specified string.
 770          *
 771          * @since 2.0
 772          *
 773          * @return              An error code
 774          * @param[in]   original                                An instance of %String to replace
 775          * @param[in]   replace                                 An instance of %String to replace all occurrences of @c original
 776          * @exception   E_SUCCESS                               The method is successful.
 777          * @exception   E_INVALID_ARG                   The specified @c original is an empty string.
 778          */
 779         result Replace(const String& original, const String& replace);
 780
 781         /**
 782          * Replaces all occurrences of the specified string within the substring
 783          * of this instance of %String.
 784          *
 785          * @since 2.0
 786          *
 787          * @return              An error code
 788          * @param[in]   original                                An instance of %String to replace
 789          * @param[in]   replace                                 An instance of %String to replace all occurrences of @c original
 790          * @param[in]   startIndex                              The starting position of the substring
 791          * @exception   E_SUCCESS                               The method is successful.
 792          * @exception   E_INVALID_ARG                   The specified @c original is an empty string.
 793          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 794          *                                                                              the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
 795          */
 796         result Replace(const String& original, const String& replace, int startIndex);
 797
 798         /**
 799          * Reverses the sequence of characters in the calling instance.
 800          *
 801          * @since 2.0
 802          *
 803          */
 804         void Reverse(void);
 805
 806         /**
 807          * Sets the capacity of this instance of %String.
 808          *
 809          * @since 2.0
 810          *
 811          * @return              An error code
 812          * @param[in]   newCapacity             The new capacity
 813          * @exception   E_SUCCESS               The method is successful.
 814          * @exception   E_INVALID_ARG   The specified @c capacity is negative.
 815          * @remarks             If the new capacity is smaller than the current length, then
 816          *                              the text contained in this instance is truncated.
 817          */
 818         result SetCapacity(int newCapacity);
 819
 820         /**
 821          * Sets the character at the specified index with the given character.
 822          *
 823          * @since 2.0
 824          *
 825          * @return              An error code
 826          * @param[in]   ch                                              A new character
 827          * @param[in]   indexAt                                 The position of the character
 828          * @exception   E_SUCCESS                               The method is successful.
 829          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 830          *                                                                              the specified @c indexAt is either greater than or equal to the length of the current instance or less than @c 0.
 831          */
 832         result SetCharAt(wchar_t ch, int indexAt);
 833
 834         /**
 835          * Sets the length of this instance of %String.
 836          *
 837          * @since 2.0
 838          *
 839          * @return              An error code
 840          * @param[in]   newLength               The new length
 841          * @exception   E_SUCCESS               The method is successful.
 842          * @exception   E_INVALID_ARG   The specified @c newLength is negative.
 843          * @remarks             If the new length is greater than the current length, the
 844          *                              string is padded with spaces. On the other hand,
 845          *                              if the new length is smaller than the current length, then
 846          *                              the text contained in this instance is truncated.
 847          */
 848         result SetLength(int newLength);
 849
 850         /**
 851          * Gets a substring starting from the given index.
 852          *
 853          * @since 2.0
 854          *
 855          * @return              An error code
 856          * @param[in]   startIndex                              The starting index of the substring
 857          * @param[out]  out                                             The substring
 858          * @exception   E_SUCCESS                               The method is successful.
 859          * @exception   E_OUT_OF_RANGE                  The specified index is out of range, or
 860          *                                                                              the specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0.
 861          */
 862         result SubString(int startIndex, String& out) const;
 863
 864         /**
 865          * Gets a substring of the given length starting from the specified index.
 866          *
 867          * @since 2.0
 868          *
 869          * @return              An error code
 870          * @param[in]   startIndex                              The starting position of the substring
 871          * @param[in]   length                                  The length of the substring
 872          * @param[out]  out                                             The substring
 873          * @exception   E_SUCCESS                               The method is successful.
 874          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred: @n
 875          *                                                                              - The specified index is out of range. @n
 876          *                                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance or less than @c 0. @n
 877          *                                                                              - The specified @c length is either greater than the length of substring starting from @c startIndex or less than @c 0.
 878          */
 879         result SubString(int startIndex, int length, String& out) const;
 880
 881         /**
 882          *      Checks whether this instance contains the specified text from the given index.
 883          *
 884          *  @since 2.0
 885          *
 886          *      @return                 @c true if this instance starts with the specified text, @n
 887          *                              else @c false
 888          *      @param[in]      str                                     The string to match
 889          *      @param[in]      startIndex                      The start position of the string
 890          */
 891         bool StartsWith(const String& str, int startIndex) const;
 892
 893         /**
 894          *      Checks whether the given string is present at the end of the calling instance.
 895          *
 896          *  @since 2.0
 897          *
 898          *      @return                 @c true if this instance ends with the specified text, @n
 899          *                              else @c false
 900          *      @param[in]      str                             An instance of %String to match
 901          */
 902         bool EndsWith(const String& str) const;
 903
 904         /**
 905          *      @if OSPDEPREC
 906          *      Gets the lowercase form of the string in the calling instance. @n
 907          *  Unicode characters other than the English alphabets are not changed.
 908          *
 909          *      @brief  <i> [Deprecated] </i>
 910          *      @deprecated This method is deprecated as a new method has been introduced.
 911          *      Instead of using this method, use the ToLowerCase(%String& out) method that supports Unicode characters other than the English alphabets.
 912          *  @since 2.0
 913          *
 914          *      @return                 An error code
 915          *      @param[out]     out                                             An instance of %String that contains the modified value of the calling instance
 916          *      @exception      E_SUCCESS                               The method is successful.
 917          *      @endif
 918          */
 919         result ToLower(String& out) const;
 920
 921         /**
 922          *      Gets the lowercase form of the string in the calling instance. @n
 923      *  Unicode characters other than the English alphabets are also supported.
 924          *
 925          *      @since 2.0
 926          *
 927          *      @return                 An error code
 928          *      @param[out]     out                                             An instance of %String that contains the modified value of the calling instance
 929          *      @exception      E_SUCCESS                               The method is successful.
 930          */
 931         result ToLowerCase(String& out) const;
 932
 933         /**
 934          *      @if OSPDEPREC
 935          *      Gets the uppercase form of the string in the calling instance. @n
 936          *  Unicode characters other than the English alphabets are not changed.
 937          *
 938          *      @brief  <i> [Deprecated] </i>
 939          *      @deprecated This method is deprecated as a new method has been introduced.
 940          *      Instead of using this method, use the ToUpperCase(%String& out) method that supports Unicode characters other than the English alphabets.
 941          *  @since 2.0
 942          *
 943          *      @return                 An error code
 944          *      @param[out]     out                                             An instance of %String that contains the modified value of the calling instance
 945          *      @exception      E_SUCCESS                               The method is successful.
 946          *      @endif
 947          */
 948         result ToUpper(String& out) const;
 949
 950         /**
 951          *      Gets the uppercase form of the string in the calling instance. @n
 952      *  Unicode characters other than the English alphabets are also supported.
 953          *
 954          *      @since 2.0
 955          *
 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.
 959          */
 960         result ToUpperCase(String& out) const;
 961
 962         /**
 963          *      @if OSPDEPREC
 964          *      Converts all the letters in this instance to lowercase. @n
 965          *  Unicode characters other than the English alphabets are not changed.
 966          *
 967          *      @brief  <i> [Deprecated] </i>
 968          *      @deprecated This method is deprecated as a new method has been introduced.
 969          *      Instead of using this method, use the ToLowerCase() method that supports Unicode characters other than the English alphabets.
 970          *
 971          *  @since 2.0
 972          *      @endif
 973          */
 974         void ToLower(void);
 975
 976         /**
 977          *      Converts all the letters in this instance to lowercase. @n
 978          *  Unicode characters other than the English alphabets are also supported.
 979          *
 980          *      @since 2.0
 981          */
 982         void ToLowerCase(void);
 983
 984         /**
 985          *      @if OSPDEPREC
 986          *      Converts all the letters in this instance to uppercase. @n
 987          *  Unicode characters other than the English alphabets are not changed.
 988          *
 989          *      @brief  <i> [Deprecated] </i>
 990          *      @deprecated This method is deprecated as a new method has been introduced.
 991          *      Instead of using this method, use the ToUpperCase() method that supports Unicode characters other than the English alphabets.
 992          *
 993          *  @since 2.0
 994          *      @endif
 995          */
 996         void ToUpper(void);
 997
 998         /**
 999          *      Converts all the letters in this instance to uppercase. @n
1000      *  Unicode characters other than the English alphabets are also supported.
1001          *
1002          *      @since 2.0
1003          */
1004         void ToUpperCase(void);
1005
1006         /**
1007          *      Trims the leading and trailing whitespace characters.
1008          *
1009          *  @since 2.0
1010          */
1011         void Trim(void);
1012
1013         /**
1014          * Gets the current capacity of this %String instance.
1015          *
1016          * @since 2.0
1017          *
1018          * @return              The capacity of this %String instance
1019          */
1020         int GetCapacity(void) const;
1021
1022         /**
1023          * Gets the length of the text contained in this %String instance.
1024          *
1025          * @since 2.0
1026          *
1027          * @return              The length of this %String instance
1028          */
1029         int GetLength(void) const;
1030
1031         /**
1032          * Gets a pointer to the instance's internal buffer.
1033          *
1034          * @since 2.0
1035          *
1036          * @return              A Unicode pointer to the calling instance's internal buffer
1037          * @remarks             GetPointer() does not guarantee that every call to this function returns same address.
1038          */
1039         const wchar_t* GetPointer(void) const;
1040
1041         /**
1042         * Checks whether this instance contains the specified substring.
1043         *
1044         *  @since 2.0
1045         *
1046         *  @return                 @c true if this instance contains the specified substring, @n
1047         *                              else @c false
1048         *  @param[in]    str       The string to match
1049         */
1050         bool Contains(const String& str) const;
1051
1052         /**
1053          * A constant holding the default capacity of %String.
1054          *
1055          * @since 2.0
1056          */
1057         static const unsigned long DEFAULT_CAPACITY = 16;
1058
1059 private:
1060         //
1061         // Allocates an internal buffer with the specified capacity.
1062         // @return              An error code
1063         // @param[in]   capacity The initial capacity of this instance of %String
1064         //
1065         bool AllocateCapacity(int capacity);
1066
1067         //
1068         // Expands the size of the internal buffer that is greater than or equal
1069         // to the specified capacity.
1070         // @return              @c true if the capacity is expanded, @n
1071         //              else @c false
1072         // @param[in]   capacity The new capacity of this instance of %String
1073         //
1074         bool ExpandCapacity(int minCapacity);
1075
1076         //
1077         // Initializes __pValue and __pRefCount
1078         //
1079         // @since 2.0
1080         //
1081         result InitializeToDefault(int capacity);
1082
1083         //
1084         // When the reference count is bigger than 1 and it is not UNSHAREABLE, copies__pValue and subtracts and initializes __pRefCount.
1085         // If the isUnshareable is true, this method sets the reference count to UNSHAREABLE.
1086         //
1087         // @since 2.2
1088         //
1089         result AboutToModify(int capacity, bool isUnshareable = false);
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 volatile int* __pRefCount;
1102         mutable wchar_t* __pValue;
1103
1104         static const float GROWTH_FACTOR;
1105         static const int UNSHAREABLE;
1106
1107         class _StringImpl * __pStringImpl;
1108         friend class _StringImpl;
1109 }; // String
1110
1111 }} // Tizen::Base
1112 #endif // _FBASE_STRING_H_