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                      The 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 the 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 the 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 to copy
 120          */
 121         String(const String& value);
 122
 123         /**
 124          * This 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          * Gets the Unicode character at the specified index.
 134          *
 135          * @since 2.0
 136          *
 137          * @return        A constant reference to the Unicode character
 138          * @param[in]    index  The index within the current instance of %String
 139          */
 140         const wchar_t& operator [](int index) const;
 141
 142         /**
 143          * Gets a reference to the Unicode character at the specified index.
 144          *
 145          * @since 2.0
 146          *
 147          * @return        A reference to the Unicode character
 148          * @param[in]    index The 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 the 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 to copy
 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 the 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                              The @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                              The @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 that represents 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                               The 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 that represents 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                               The @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 that represents 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                               The @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 that represents 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                              The @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 that represents 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                               The @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 that represents 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                               The @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 the 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         The 32-bit @c signed integer value
 373          *      @param[in]      str0    The first %String instance to compare
 374          *      @param[in]      str1    The second %String instance to compare
 375          *      @remarks        This method performs an ordinal comparison of each Unicode
 376          *                              character contained in the two given %String instances. @n
 377          *                              For instance, "U+xxx" is greater than "U+XXX", but smaller than "U+yyy".
 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              The 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. @n
 401          *                              For instance, 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               The 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   Either of the following conditions has occurred:
 460          *                                                              - The specified @c length is negative.
 461          *                                                              - The specified @c pFormat is @c null.
 462          * @remarks
 463          *                      - If an "l" modifier is present in @c pFormat (for example, L"@%ls"), it is a pointer to an array of wide characters.
 464          *                      - A pointer to an array of UTF-8 characters is not allowed in the Format() method (for example, Format(20, L"@%s", pUTF8Str)).
 465          * The following format specifiers are supported in this method:
 466          * @code
 467          * specifier    Output
 468          * ---------    ------
 469          * c            single byte character
 470          * d(or i)      signed decimal integer
 471          * u            unsigned decimal integer
 472          * x            unsigned hexadecimal integer
 473          * f            decimal floating point
 474          * e            scientific notation using e character
 475          * g            use the shorter of %e or %f
 476          * s            single byte character string
 477          * ls(or S)     wide-character string
 478          * lld          64-bit signed decimal integer
 479          *
 480          * @endcode
 481          *
 482          * The following example demonstrates how to use the %Format() method.
 483          * @code
 484          *
 485          *      String str;
 486          *
 487          *      int value = 10;
 488          *      wchar_t* testStr = L"TEST";
 489          *
 490          *      str.Format(25, L"FORMAT %d %ls", value, testStr);       // str == L"FORMAT 10 TEST"
 491          *
 492          * @endcode
 493          */
 494         result Format(int length, const wchar_t* pFormat, ...);
 495
 496         /**
 497          * Gets the hash value of the current instance.
 498          *
 499          * @since 2.0
 500          *
 501          * @return              The hash value of the current instance
 502          * @remarks     Two equal instances must return the same hash value. @n
 503          *                              For better performance, the hash function used must generate a random distribution for all the inputs.
 504          */
 505         virtual int GetHashCode(void) const;
 506
 507         /**
 508          *  Gets the character at the specified position.
 509          *
 510          *  @since 2.0
 511          *
 512          *      @return                 An error code
 513          *      @param[in]      indexAt                                 The position of the character
 514          *      @param[out]     ch                                              The character at the specified index
 515          *      @exception      E_SUCCESS                               The method is successful.
 516          *      @exception      E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 517          *                                                                              - The specified @c index is out of the valid range.
 518          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 519          *                                                                              - The specified @c indexAt is less than @c 0.
 520          */
 521         result GetCharAt(int indexAt, wchar_t& ch) const;
 522
 523         /**
 524          * Searches for a character in the calling instance. @n
 525          * Gets the index of the first character that matches
 526          * the specified character in this instance.
 527          *
 528          * @since 2.0
 529          *
 530          * @return                      An error code
 531          * @param[in]   ch                                              The Unicode character to locate
 532          * @param[in]   startIndex                              The starting position of the search
 533          * @param[out]  indexOf                                 The index of the character
 534          * @exception   E_SUCCESS                               The method is successful.
 535          * @exception   E_OBJ_NOT_FOUND                 The specified character is not found.
 536          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 537          *                                                                              - The specified @c index is out of the valid range.
 538          *                                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 539          *                                                                              - The specified @c startIndex is less than @c 0.
 540          */
 541         result IndexOf(wchar_t ch, int startIndex, int& indexOf) const;
 542
 543         /**
 544          * Searches for a specified substring in the calling instance. @n
 545          * Gets the starting index of the first occurrence of the specified substring.
 546          *
 547          * @since 2.0
 548          *
 549          * @return              An error code
 550          * @param[in]   str                                             An instance of %String to locate
 551          * @param[in]   startIndex                              The starting position of the search
 552          * @param[out]  indexOf                                 The index of the substring
 553          * @exception   E_SUCCESS                               The method is successful.
 554          * @exception   E_OBJ_NOT_FOUND                 The specified string is not found.
 555          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 556          *                                                                              - The specified @c index is out of the valid range.
 557          *                                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 558          *                                                                              - The specified @c startIndex is less than @c 0.
 559          */
 560         result IndexOf(const String& str, int startIndex, int& indexOf) const;
 561
 562         /**
 563          * Inserts the string that represents the specified Unicode character
 564          * at the specified position in the calling instance.
 565          *
 566          * @since 2.0
 567          *
 568          * @return              An error code
 569          *
 570          * @param[in]   ch                                              The Unicode character to insert
 571          * @param[in]   indexAt                                 The position of the character
 572          * @exception   E_SUCCESS                               The method is successful.
 573          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 574          *                                                                              - The specified @c index is out of the valid range.
 575          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 576          *                                                                              - The specified @c indexAt is less than @c 0.
 577          */
 578         result Insert(wchar_t ch, int indexAt);
 579
 580         /**
 581          * Inserts the string that represents the specified @c char value
 582          * at the specified position in the calling instance.
 583          *
 584          * @since 2.0
 585          *
 586          * @return              An error code
 587          *
 588          * @param[in]   ch                                              The @c char value to insert
 589          * @param[in]   indexAt                                 The position of the character
 590          * @exception   E_SUCCESS                               The method is successful.
 591          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 592          *                                                                              - The specified @c index is out of the valid range.
 593          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 594          *                                                                              - The specified @c indexAt is less than @c 0.
 595          */
 596         result Insert(char ch, int indexAt);
 597
 598         /**
 599          * Inserts the string that represents the specified 16-bit integer
 600          * at the specified position in the calling instance.
 601          *
 602          * @since 2.0
 603          *
 604          * @return              An error code
 605          * @param[in]   s                                               The 16-bit integer value to insert
 606          * @param[in]   indexAt                                 The position of the character
 607          * @exception   E_SUCCESS                               The method is successful.
 608          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 609          *                                                                              - The specified @c index is out of the valid range.
 610          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 611          *                                                                              - The specified @c indexAt is less than @c 0.
 612          */
 613         result Insert(short s, int indexAt);
 614
 615         /**
 616          * Inserts the string that represents the specified 32-bit integer
 617          * at the specified position in the calling instance.
 618          *
 619          * @since 2.0
 620          *
 621          * @return              An error code
 622          * @param[in]   i                                               The 32-bit integer value to insert
 623          * @param[in]   indexAt                                 The position of the character
 624          * @exception   E_SUCCESS                               The method is successful.
 625          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 626          *                                                                              - The specified @c index is out of the valid range.
 627          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 628          *                                                                              - The specified @c indexAt is less than @c 0.
 629          */
 630         result Insert(int i, int indexAt);
 631
 632         /**
 633          * Inserts the string that represents the specified @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]   l                                               The @c long value to insert
 640          * @param[in]   indexAt                                 The position of the character
 641          * @exception   E_SUCCESS                               The method is successful.
 642          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 643          *                                                                              - The specified @c index is out of the valid range.
 644          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 645          *                                                                              - The specified @c indexAt is less than @c 0.
 646          */
 647         result Insert(long l, int indexAt);
 648
 649         /**
 650          * Inserts the string that represents the specified @c long @c long value
 651          * at the specified position in the calling instance.
 652          *
 653          * @since 2.0
 654          *
 655          * @return              An error code
 656          * @param[in]   ll                                              The @c long @c long value to insert
 657      * @param[in]       indexAt                                 The position of the character
 658          * @exception   E_SUCCESS                               The method is successful.
 659          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 660          *                                                                              - The specified @c index is out of the valid range.
 661          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 662          *                                                                              - The specified @c indexAt is less than @c 0.
 663          */
 664         result Insert(long long ll, int indexAt);
 665
 666         /**
 667          * Inserts the string that represents the specified @c float value
 668          * at the specified position in the calling instance.
 669          *
 670          * @since 2.0
 671          *
 672          * @return              An error code
 673          * @param[in]   f                                               The @c float value to insert
 674          * @param[in]   indexAt                                 The position of the character
 675          * @exception   E_SUCCESS                               The method is successful.
 676          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 677          *                                                                              - The specified @c index is out of the valid range.
 678          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 679          *                                                                              - The specified @c indexAt is less than @c 0.
 680          */
 681         result Insert(float f, int indexAt);
 682
 683         /**
 684          * Inserts the string that represents the specified @c double value
 685          * at the specified position in the calling instance.
 686          *
 687          * @since 2.0
 688          *
 689          * @return              An error code
 690          * @param[in]   d                                               The @c double value to insert
 691          * @param[in]   indexAt                                 The position of the character
 692          * @exception   E_SUCCESS                               The method is successful.
 693          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 694          *                                                                              - The specified @c index is out of the valid range.
 695          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 696          *                                                                              - The specified @c indexAt is less than @c 0.
 697          */
 698         result Insert(double d, int indexAt);
 699
 700         /**
 701          * Inserts the string that represents the specified @c null-terminated
 702          * string at the specified position in the calling instance.
 703          *
 704          * @since 2.0
 705          *
 706          * @return              An error code
 707          * @param[in]   p                                               An instance of %String to insert
 708          * @param[in]   indexAt                                 The position of the character
 709          * @exception   E_SUCCESS                               The method is successful.
 710          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 711          *                                                                              - The specified @c index is out of the valid range.
 712          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 713      *                                                                          - The specified @c indexAt is less than @c 0.
 714          * @exception   E_INVALID_ARG                   A @c null pointer is passed.
 715          */
 716         result Insert(const wchar_t* p, int indexAt);
 717
 718         /**
 719          * Inserts the string that represents the specified instance of %String
 720          * at the specified position in the calling instance.
 721          *
 722          * @since 2.0
 723          *
 724          * @return              An error code
 725          * @param[in]   str                                             An instance of %String to insert
 726          * @param[in]   indexAt                                 The position of the character
 727          * @exception   E_SUCCESS                               The method is successful.
 728          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 729          *                                                                              - The specified @c index is out of the valid range.
 730          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 731          *                                                                              - The specified @c indexAt is less than @c 0.
 732          */
 733         result Insert(const String& str, int indexAt);
 734
 735         /**
 736          * Searches the calling instance for the last occurrence of the specified character and returns its index. @n
 737          * The search begins at the @c startIndex position and proceeds backward towards the beginning.
 738          *
 739          *  @since 2.0
 740          *
 741          *      @return                 An error code
 742          *      @param[in]      ch                                              The Unicode character to locate
 743          *      @param[in]      startIndex                              The starting position of the search
 744          *      @param[out]     indexOf                                 The index of character
 745          *      @exception      E_SUCCESS                               The method is successful.
 746          *      @exception      E_OBJ_NOT_FOUND                 The specified character is not found.
 747          *      @exception      E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 748          *                                                                              - The specified @c index is out of the valid range.
 749          *                                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 750          *                                                                              - The specified @c startIndex is less than @c 0.
 751          */
 752         result LastIndexOf(wchar_t ch, int startIndex, int& indexOf) const;
 753
 754         /**
 755          * Searches the calling instance for the last occurrence of the specified substring and returns its index. @n
 756          * The search begins at the @c startIndex position and proceeds backward towards the beginning.
 757          *
 758          * @since 2.0
 759          *
 760          * @return              An error code
 761          * @param[in]   str                                             An instance of %String to locate
 762          * @param[in]   startIndex                              The starting position of the search
 763          * @param[out]  indexOf                                 The index of the substring
 764          * @exception   E_SUCCESS                               The method is successful.
 765          * @exception   E_OBJ_NOT_FOUND                 The specified character is not found.
 766          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 767          *                                                                              - The specified @c index is out of the valid range.
 768          *                                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 769          *                                                                              - The specified @c startIndex is less than @c 0.
 770          * @remarks     If the substring is empty, @c E_SUCCESS is returned and the value of @c indexOf is set to @c startIndex.
 771          */
 772         result LastIndexOf(const String& str, int startIndex, int& indexOf) const;
 773
 774         /**
 775          * Removes the characters within the specified range.
 776          *
 777          * @since 2.0
 778          *
 779          * @return              An error code
 780          * @param[in]   startIndex                              The position where the removal begins
 781          * @param[in]   length                                  The number of characters to remove
 782          * @exception   E_SUCCESS                               The method is successful.
 783          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 784          *                                                                              - The specified @c index is out of the valid range.
 785          *                                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 786      *                                                                          - The specified @c startIndex is less than @c 0.
 787          *                                                                              - The specified @c count is either greater than the length of the substring starting from @c startIndex.
 788      *                                                                          - The specified @c count is less than @c 0.
 789          */
 790         result Remove(int startIndex, int length);
 791
 792         /**
 793          * Replaces all the occurrences of the specified characters.
 794          *
 795          * @since 2.0
 796          *
 797          * @param[in]   original        The character to replace
 798          * @param[in]   replace         The character to replace all the occurrences of @c original
 799          */
 800         void Replace(wchar_t original, wchar_t replace);
 801
 802         /**
 803          * Replaces all the occurrences of the specified string.
 804          *
 805          * @since 2.0
 806          *
 807          * @return              An error code
 808          * @param[in]   original                                An instance of %String to replace
 809          * @param[in]   replace                                 An instance of %String to replace all the occurrences of @c original
 810          * @exception   E_SUCCESS                               The method is successful.
 811          * @exception   E_INVALID_ARG                   The specified @c original is an empty string.
 812          */
 813         result Replace(const String& original, const String& replace);
 814
 815         /**
 816          * Replaces all the occurrences of the specified string within the substring
 817          * of this instance of %String.
 818          *
 819          * @since 2.0
 820          *
 821          * @return              An error code
 822          * @param[in]   original                                An instance of %String to replace
 823          * @param[in]   replace                                 An instance of %String to replace all the occurrences of @c original
 824          * @param[in]   startIndex                              The starting position of the substring
 825          * @exception   E_SUCCESS                               The method is successful.
 826          * @exception   E_INVALID_ARG                   The specified @c original is an empty string.
 827          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 828          *                                                                              - The specified @c index is out of the valid range.
 829          *                                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 830      *                                                                          - The specified @c startIndex is less than @c 0.
 831          */
 832         result Replace(const String& original, const String& replace, int startIndex);
 833
 834         /**
 835          * Reverses the sequence of the characters in the calling instance.
 836          *
 837          * @since 2.0
 838          *
 839          */
 840         void Reverse(void);
 841
 842         /**
 843          * Sets the capacity of this instance of %String.
 844          *
 845          * @since 2.0
 846          *
 847          * @return              An error code
 848          * @param[in]   newCapacity             The new capacity
 849          * @exception   E_SUCCESS               The method is successful.
 850          * @exception   E_INVALID_ARG   The specified @c capacity is negative.
 851          * @remarks             If the new capacity is smaller than the current length, then
 852          *                              the text contained in this instance is truncated.
 853          */
 854         result SetCapacity(int newCapacity);
 855
 856         /**
 857          * Sets the character at the specified index with the given character.
 858          *
 859          * @since 2.0
 860          *
 861          * @return              An error code
 862          * @param[in]   ch                                              The new character
 863          * @param[in]   indexAt                                 The position of the character
 864          * @exception   E_SUCCESS                               The method is successful.
 865          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 866          *                                                                              - The specified @c index is out of the valid range.
 867          *                                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 868      *                                                                          - The specified @c indexAt is less than @c 0.
 869          */
 870         result SetCharAt(wchar_t ch, int indexAt);
 871
 872         /**
 873          * Sets the length of this instance of %String.
 874          *
 875          * @since 2.0
 876          *
 877          * @return              An error code
 878          * @param[in]   newLength               The new length
 879          * @exception   E_SUCCESS               The method is successful.
 880          * @exception   E_INVALID_ARG   The specified @c newLength is negative.
 881          * @remarks     If the new length is greater than the current length, the
 882          *                      string is padded with spaces. @n
 883          *                      On the other hand, if the new length is smaller than the current length, then
 884          *                      the text contained in this instance is truncated.
 885          */
 886         result SetLength(int newLength);
 887
 888         /**
 889          * Gets a substring starting from the given index.
 890          *
 891          * @since 2.0
 892          *
 893          * @return              An error code
 894          * @param[in]   startIndex                              The starting index of the substring
 895          * @param[out]  out                                             The substring
 896          * @exception   E_SUCCESS                               The method is successful.
 897          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 898          *                                                                              - The specified @c index is out of the valid range.
 899          *                                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 900          *                                                                              - The specified @c startIndex is less than @c 0.
 901          */
 902         result SubString(int startIndex, String& out) const;
 903
 904         /**
 905          * Gets a substring of the given length starting from the specified index.
 906          *
 907          * @since 2.0
 908          *
 909          * @return              An error code
 910          * @param[in]   startIndex                              The starting position of the substring
 911          * @param[in]   length                                  The length of the substring
 912          * @param[out]  out                                             The substring
 913          * @exception   E_SUCCESS                               The method is successful.
 914          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 915          *                                                                              - The specified @c index is out of the valid range.
 916          *                                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 917          *                                                                              - The specified @c startIndex is less than @c 0.
 918          *                                                                              - The specified @c length is either greater than the length of the substring starting from @c startIndex.
 919          *                                                                              - The specified @c length is less than @c 0.
 920          */
 921         result SubString(int startIndex, int length, String& out) const;
 922
 923         /**
 924          *      Checks whether this instance contains the specified text from the given index.
 925          *
 926          *  @since 2.0
 927          *
 928          *      @return         @c true if this instance starts with the specified text, @n
 929          *                              else @c false
 930          *      @param[in]      str                                     The string to match
 931          *      @param[in]      startIndex                      The start position of the string
 932          */
 933         bool StartsWith(const String& str, int startIndex) const;
 934
 935         /**
 936          *      Checks whether the given string is present at the end of the calling instance.
 937          *
 938          *  @since 2.0
 939          *
 940          *      @return         @c true if this instance ends with the specified text, @n
 941          *                              else @c false
 942          *      @param[in]      str                             An instance of %String to match
 943          */
 944         bool EndsWith(const String& str) const;
 945
 946         /**
 947          *      @if OSPDEPREC
 948          *      Gets the lowercase form of the string in the calling instance. @n
 949          *  Unicode characters other than the English alphabets are not changed.
 950          *
 951          *      @brief                  <i> [Deprecated] </i>
 952          *      @deprecated     This method is deprecated as a new method has been introduced.
 953          *                                      Instead of using this method, use the ToLowerCase(%String& out) method that supports Unicode characters other than the English alphabets.
 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          *      @endif
 960          */
 961         result ToLower(String& out) const;
 962
 963         /**
 964          *      Gets the lowercase form of the string in the calling instance. @n
 965      *  Unicode characters other than the English alphabets are also supported.
 966          *
 967          *      @since 2.0
 968          *
 969          *      @return                 An error code
 970          *      @param[out]     out                                             An instance of %String that contains the modified value of the calling instance
 971          *      @exception      E_SUCCESS                               The method is successful.
 972          */
 973         result ToLowerCase(String& out) const;
 974
 975         /**
 976          *      @if OSPDEPREC
 977          *      Gets the uppercase form of the string in the calling instance. @n
 978          *  Unicode characters other than the English alphabets are not changed.
 979          *
 980          *      @brief  <i> [Deprecated] </i>
 981          *      @deprecated This method is deprecated as a new method has been introduced.
 982          *                              Instead of using this method, use the ToUpperCase(%String& out) method that supports Unicode characters other than the English alphabets.
 983          *  @since 2.0
 984          *
 985          *      @return         An error code
 986          *      @param[out]     out                                             An instance of %String that contains the modified value of the calling instance
 987          *      @exception      E_SUCCESS                               The method is successful.
 988          *      @endif
 989          */
 990         result ToUpper(String& out) const;
 991
 992         /**
 993          *      Gets the uppercase form of the string in the calling instance. @n
 994      *  Unicode characters other than the English alphabets are also supported.
 995          *
 996          *      @since 2.0
 997          *
 998          *      @return         An error code
 999          *      @param[out]     out                                             An instance of %String that contains the modified value of the calling instance
1000          *      @exception      E_SUCCESS                               The method is successful.
1001          */
1002         result ToUpperCase(String& out) const;
1003
1004         /**
1005          *      @if OSPDEPREC
1006          *      Converts all the letters in this instance to lowercase. @n
1007          *  Unicode characters other than the English alphabets are not changed.
1008          *
1009          *      @brief  <i> [Deprecated] </i>
1010          *      @deprecated This method is deprecated as a new method has been introduced.
1011          *                              Instead of using this method, use the ToLowerCase() method that supports Unicode characters other than the English alphabets.
1012          *
1013          *  @since 2.0
1014          *      @endif
1015          */
1016         void ToLower(void);
1017
1018         /**
1019          *      Converts all the letters in this instance to lowercase. @n
1020          *  Unicode characters other than the English alphabets are also supported.
1021          *
1022          *      @since 2.0
1023          */
1024         void ToLowerCase(void);
1025
1026         /**
1027          *      @if OSPDEPREC
1028          *      Converts all the letters in this instance to uppercase. @n
1029          *  Unicode characters other than the English alphabets are not changed.
1030          *
1031          *      @brief  <i> [Deprecated] </i>
1032          *      @deprecated This method is deprecated as a new method has been introduced.
1033          *                              Instead of using this method, use the ToUpperCase() method that supports Unicode characters other than the English alphabets.
1034          *
1035          *  @since 2.0
1036          *      @endif
1037          */
1038         void ToUpper(void);
1039
1040         /**
1041          *      Converts all the letters in this instance to uppercase. @n
1042      *  Unicode characters other than the English alphabets are also supported.
1043          *
1044          *      @since 2.0
1045          */
1046         void ToUpperCase(void);
1047
1048         /**
1049          *      Trims the leading and trailing whitespace characters.
1050          *
1051          *  @since 2.0
1052          */
1053         void Trim(void);
1054
1055         /**
1056          * Gets the current capacity of this %String instance.
1057          *
1058          * @since 2.0
1059          *
1060          * @return              The capacity of this %String instance
1061          */
1062         int GetCapacity(void) const;
1063
1064         /**
1065          * Gets the length of the text contained in this %String instance.
1066          *
1067          * @since 2.0
1068          *
1069          * @return              The length of this %String instance
1070          */
1071         int GetLength(void) const;
1072
1073         /**
1074          * Gets a pointer to the instance's internal buffer.
1075          *
1076          * @since 2.0
1077          *
1078          * @return              A Unicode pointer to the calling instance's internal buffer
1079          * @remarks             GetPointer() does not guarantee that every call to this method returns the same address.
1080          */
1081         const wchar_t* GetPointer(void) const;
1082
1083         /**
1084         * Checks whether this instance contains the specified substring.
1085         *
1086         *  @since 2.0
1087         *
1088         *  @return       @c true if this instance contains the specified substring, @n
1089         *                else @c false
1090         *  @param[in]    str       The string to match
1091         */
1092         bool Contains(const String& str) const;
1093
1094         /**
1095          * The constant holding the default capacity of %String.
1096          *
1097          * @since 2.0
1098          */
1099         static const unsigned long DEFAULT_CAPACITY = 16;
1100
1101 private:
1102         //
1103         // Allocates an internal buffer with the specified capacity.
1104         // @return              An error code
1105         // @param[in]   capacity The initial capacity of this instance of %String
1106         //
1107         bool AllocateCapacity(int capacity);
1108
1109         //
1110         // Expands the size of the internal buffer that is greater than or equal
1111         // to the specified capacity.
1112         // @return              @c true if the capacity is expanded, @n
1113         //              else @c false
1114         // @param[in]   capacity The new capacity of this instance of %String
1115         //
1116         bool ExpandCapacity(int minCapacity);
1117
1118         //
1119         // Initializes __pValue and __pRefCount
1120         //
1121         // @since 2.0
1122         //
1123         result InitializeToDefault(int capacity);
1124
1125         //
1126         // When the reference count is bigger than 1 and it is not UNSHAREABLE, copies__pValue and subtracts and initializes __pRefCount.
1127         // If the isUnshareable is true, this method sets the reference count to UNSHAREABLE.
1128         //
1129         // @since 2.2
1130         //
1131         result AboutToModify(int capacity, bool isUnshareable = false);
1132
1133         //
1134         // Swaps member-wisely
1135         //
1136         // @since 2.0
1137         //
1138         void Swap(String& str);
1139
1140         int __capacity;
1141         int __length;
1142         mutable int __hash;
1143         mutable volatile int* __pRefCount;
1144         mutable wchar_t* __pValue;
1145
1146         static const float GROWTH_FACTOR;
1147         static const int UNSHAREABLE;
1148
1149         class _StringImpl * __pStringImpl;
1150         friend class _StringImpl;
1151 }; // String
1152
1153 }} // Tizen::Base
1154 #endif // _FBASE_STRING_H_