inc/FBaseImmutableString.h

   1 //
   2 // Copyright (c) 2013 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        FBaseImmutableString.h
  19  * @brief       This is the header file for the %ImmutableString class.
  20  *
  21  * @since       3.0
  22  * @final       This class is not intended for extension.
  23  *
  24  * This header file contains the declarations of the %ImmutableString class.
  25  */
  26
  27 #ifndef _FBASE_IMMUTABLE_STRING_H_
  28 #define _FBASE_IMMUTABLE_STRING_H_
  29
  30 #include <FBaseObject.h>
  31
  32 namespace Tizen { namespace Base
  33 {
  34
  35 class _StringBuffer;
  36
  37 /**
  38  *      @class  ImmutableString
  39  *      @brief  This class represents a immutable sequence of Unicode characters.
  40  *
  41  *      @since  3.0
  42  *
  43  *      The %ImmutableString class represents a immutable sequence of Unicode characters.
  44  *      Mutation operation, such as Append(), Insert() and Remove(), do not change the current instance but return a new instance resulting from applying the operation.
  45  *
  46  *      For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/immutablestring.htm">ImmutableString</a>.
  47  *
  48  *      The following example demonstrates how to use the %ImmutableString class.
  49  *
  50  *      @code
  51  *
  52  *      #include <FBase.h>
  53  *
  54  *      using namespace Tizen::Base;
  55  *
  56  *      void
  57  *      MyClass::ImmutableStringSample(void)
  58  *      {
  59  *              ImmutableString str(L"Test");                                                   // str == L"Test"
  60  *
  61  *              ImmutableString str1 = str.Append(L"String");                   // str1 == L"TestString"
  62  *
  63  *              ImmutableString str2 = str1.Insert(L"Immutable", 4);    // str2 == L"TestImmutableString"
  64  *
  65  *              ImmutableString str3 = str2.Remove(4, 5);                               // str3 == L"TestableString"
  66  *
  67  *              ImmutableString str4 = str3.SubString(4, 4);                    // str4 == L"able"
  68  *      }
  69  *      @endcode
  70  */
  71 class _OSP_EXPORT_ ImmutableString
  72         : public Object
  73 {
  74 public:
  75         /**
  76          * Initializes %ImmutableString instance with the specified Unicode string.
  77          *
  78          * @since 3.0
  79          *
  80          * @param[in]   pStr    A pointer to an array of Unicode characters
  81          * @remarks             If whcar_t* type null pointer is entered on parameter, the empty string is set.
  82          */
  83         explicit ImmutableString(const wchar_t* pStr);
  84
  85         /**
  86          * Initializes %ImmutableString instance with the specified UTF-8 string.
  87          *
  88          * @since 3.0
  89          *
  90          * @param[in]   pStr    A pointer to an array of UTF-8 characters
  91          * @remarks             If char* type null pointer is entered on parameter, the empty string is set.
  92          */
  93         explicit ImmutableString(const char* pStr);
  94
  95         /**
  96          * Initializes %ImmutableString instance with the specified %String.
  97          *
  98          * @since 3.0
  99          *
 100          * @param[in]   value   An instance of %String
 101          */
 102         ImmutableString(const String& value);
 103
 104         /**
 105          * Copying of objects using this copy constructor is allowed.
 106          *
 107          * @since 3.0
 108          *
 109          * @param[in]   value   An instance of %ImmutableString
 110          */
 111         ImmutableString(const ImmutableString& value);
 112
 113         /**
 114          * This destructor overrides Tizen::Base::Object::~Object().
 115          *
 116          * @since 3.0
 117          */
 118         virtual ~ImmutableString(void);
 119
 120         /**
 121          * Returns a Unicode character at the specified @c index.
 122          *
 123          * @since 3.0
 124          *
 125          * @return              A Unicode character
 126          * @param[in]   index   An index within this string
 127          */
 128         wchar_t operator [](int index) const;
 129
 130         /**
 131          * Returns a new %ImmutableString instance resulting from appending the specified %ImmutableString to the end of this string.
 132          *
 133          * @since 3.0
 134          *
 135          * @return      The concatenated %ImmutableString instance
 136          * @param[in]   str     An instance of %ImmutableString to append
 137          */
 138         ImmutableString Append(const ImmutableString& str) const;
 139
 140         /**
 141          * Compares the value of the current instance to the value of the specified instance of %ImmutableString.
 142          *
 143          * @since 3.0
 144          *
 145          * @return      A @c signed integer value
 146          * @code
 147          *              <  0  if the value of the current instance is less than the value of the specified %ImmutableString instance
 148          *              == 0  if the value of the current instance is equal to the value of the specified %ImmutableString instance
 149          *              >  0  if the value of the current instance is greater than the value of the specified %ImmutableString instance
 150          * @endcode
 151          * @param[in]   str     An instance of %ImmutableString to compare
 152          * @remarks
 153          *                              - This method performs an ordinal comparison of each Unicode character. For instance,
 154          *                              L"U+xxx" is greater than L"U+XXX", but smaller than L"U+yyy".
 155          *                              - This method is not locale-dependent.
 156          */
 157         int CompareTo(const ImmutableString& str) const;
 158
 159         /**
 160          * Checks whether this instance contains the specified substring.
 161          *
 162          * @since 3.0
 163          *
 164          * @return              @c true if this instance contains the specified substring, @n
 165          *                              else @c false
 166          * @param[in]   str     The string to match
 167          * @remarks             This method returns @c true when an empty string is entered on parameter.
 168          */
 169         bool Contains(const ImmutableString& str) const;
 170
 171         /**
 172          * Checks whether the given string is present at the end of the calling instance.
 173          *
 174          * @since 3.0
 175          *
 176          * @return      @c true if this instance ends with the specified text, @n
 177          *                      else @c false
 178          * @param[in]   str     An instance to match
 179          * @exception   E_SUCCESS       The method is successful.
 180          * @exception   E_INVALID_ARG   The specified @c str is an empty string.
 181          * @remarks             The specific error code can be accessed by using GetLastResult() method.
 182          */
 183         bool EndsWith(const ImmutableString& str) const;
 184
 185         /**
 186          * Checks whether the value of the specified instance of Object is equal to the value of this string.
 187          *
 188          * @since 3.0
 189          *
 190          * @return      @c true if the value of the specified instance of Object is equal to the value of this string, @n
 191          *                      else @c false
 192          * @param[in]   obj     An instance of Object to compare
 193          * @remarks     This method returns @c false if the specified @c obj is not a string.
 194          * @see         Object::Equals()
 195          */
 196         virtual bool Equals(const Object& obj) const;
 197
 198         /**
 199          * Checks whether the value of the specified instance is equal to the value of this string. @n
 200          * Case sensitivity is ignored.
 201          *
 202          * @since 3.0
 203          *
 204          * @return      @c true if the values match, @n
 205          *                      else @c false
 206          * @param[in]   str     An instance to compare with the calling instance
 207          *
 208          * @remarks     This method performs an ordinal comparison of each Unicode
 209          *              character contained in the two given %ImmutableString instances.
 210          */
 211         bool EqualsCaseInsensitive(const ImmutableString& str) const;
 212
 213         /**
 214          * Formats the inputs as per the specified format and and returns a new %ImmutableString instance.
 215          *
 216          * @since 3.0
 217          *
 218          * @return      An error code
 219          * @param[in]   length          The maximum number of wide characters to write, including the terminating @c null character
 220          * @param[in]   pFormat         The wide character format specifier
 221          * @exception   E_SUCCESS               The method is successful.
 222          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 223          *                                                              - The specified @c length is negative.
 224          *                                                              - The specified @c pFormat is @c null.
 225          *                                                              - The specified @c pFormat includes "%n" or "%hn" which may cause format string vulnerability.
 226          * @remarks
 227          *                      - If an "l" modifier is present in @c pFormat (for example, L"@%ls"), it is a pointer to an array of wide characters.
 228          *                      - A pointer to an array of UTF-8 characters is not allowed in the Format() method (for example, Format(20, L"@%s", pUTF8Str)).
 229          *                      - This method is locale-dependent.
 230          *                      - This method returns an empty string when an exception occurs.
 231          *                      - The specific error code can be accessed by using the GetLastResult() method.
 232          * The following format specifiers are supported in this method:
 233          * @code
 234          * specifier    Output
 235          * ---------    ------
 236          * c            single byte character
 237          * d(or i)      signed decimal integer
 238          * u            unsigned decimal integer
 239          * x            unsigned hexadecimal integer
 240          * f            decimal floating point
 241          * e            scientific notation using e character
 242          * g            use the shorter of %e or %f
 243          * s            single byte character string
 244          * ls(or S)     wide-character string
 245          * lld          64-bit signed decimal integer
 246          *
 247          * @endcode
 248          *
 249          * The following example demonstrates how to use the %Format() method.
 250          * @code
 251          *
 252          *      int value = 10;
 253          *      wchar_t* testStr = L"TEST";
 254          *
 255          *      ImmutableString str = Tizen::Base::ImmutableString::Format(25, L"FORMAT %d %ls", value, testStr);       // str == L"FORMAT 10 TEST"
 256          *
 257          * @endcode
 258          */
 259         static ImmutableString Format(int length, const wchar_t* pFormat, ...);
 260
 261         /**
 262          * Gets the character at the specified position.
 263          *
 264          * @since 3.0
 265          *
 266          * @return              An error code
 267          * @param[in]   indexAt The position of the character
 268          * @param[out]  ch      The character at the specified index
 269          * @exception   E_SUCCESS       The method is successful.
 270          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 271          *                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 272          *                                                              - The specified @c indexAt is less than @c 0.
 273          * @remarks             This method does not guarantee a usable value of out-parameter when an error occurs.
 274          */
 275         result GetCharAt(int indexAt, wchar_t& ch) const;
 276
 277         /**
 278          * Gets the hash value of the current instance.
 279          *
 280          * @since 3.0
 281          *
 282          * @return      The hash value of the current instance
 283          * @remarks     Two equal instances must return the same hash value. For better performance,
 284          *                      the hash function used must generate a random distribution for all inputs.
 285          */
 286         virtual int GetHashCode(void) const;
 287
 288         /**
 289          * Gets the length of the text contained in this %ImmutableString instance.
 290          *
 291          * @since 3.0
 292          *
 293          * @return      The length of this %ImmutableString instance
 294          */
 295         int GetLength(void) const;
 296
 297         /**
 298          * Gets a pointer to the instance's internal buffer.
 299          *
 300          * @since 3.0
 301          *
 302          * @return      A Unicode pointer to the calling instance's internal buffer
 303          */
 304         const wchar_t* GetPointer(void) const;
 305
 306         /**
 307          * Searches for a character in the calling instance. @n
 308          * Gets the index of the first character that matches to the specified character in this instance.
 309          *
 310          * @since 3.0
 311          *
 312          * @return              An error code
 313          * @param[in]   ch      The Unicode character to locate
 314          * @param[in]   startIndex      The starting position of the search
 315          * @param[out]  indexOf The index of the character
 316          * @exception   E_SUCCESS       The method is successful.
 317          * @exception   E_OBJ_NOT_FOUND The specified character is not found.
 318          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 319          *                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 320          *                                                              - The specified @c startIndex is less than @c 0.
 321          * @remarks             Do not use the @c indexOf when the method returns an error.
 322          */
 323         result IndexOf(wchar_t ch, int startIndex, int& indexOf) const;
 324
 325         /**
 326          * Searches for a specified substring in the calling instance. @n
 327          * Gets the starting index of the first occurrence of the specified substring.
 328          *
 329          * @since 3.0
 330          *
 331          * @return              An error code
 332          * @param[in]   str     An instance to locate
 333          * @param[in]   startIndex      The starting position of the search
 334          * @param[out]  indexOf The index of the substring
 335          * @exception   E_SUCCESS       The method is successful.
 336          * @exception   E_OBJ_NOT_FOUND The specified string is not found.
 337          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 338          *                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 339          *                                                              - The specified @c startIndex is less than @c 0.
 340          * @remarks             Do not use the @c indexOf when the method returns an error.
 341          */
 342         result IndexOf(const ImmutableString& str, int startIndex, int& indexOf) const;
 343
 344         /**
 345          * Returns a new instance resulting from inserting the specified string at the specified position.
 346          *
 347          * @since 3.0
 348          *
 349          * @return              The new %ImmutableString instance
 350          * @param[in]   str     An instance to insert
 351          * @param[in]   indexAt The position to insert @c str
 352          * @exception   E_SUCCESS       The method is successful.
 353          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 354          *                                                              - The specified @c indexAt is greater than the length of the current instance.
 355          *                                                              - The specified @c indexAt is less than @c 0.
 356          * @remarks
 357          *                              - This method returns an empty string when an exception occurs.
 358          *                              - The specific error code can be accessed by using GetLastResult() method.
 359          */
 360         ImmutableString Insert(const ImmutableString& str, int indexAt) const;
 361
 362         /**
 363          *      Checks whether the string is empty.
 364          *
 365          *      @since 3.0
 366          *
 367          *      @return @c true if the current instance is a zero-length %ImmutableString instance L"", @n
 368          *              else @c false
 369          */
 370         bool IsEmpty(void) const;
 371
 372         /**
 373          * Searches the calling instance for the last occurrence of the specified character and returns its index. @n
 374          * The search begins at the @c startIndex position and proceeds backward towards the beginning.
 375          *
 376          * @since 3.0
 377          *
 378          * @return      An error code
 379          * @param[in]   ch              The Unicode character to locate
 380          * @param[in]   startIndex      The starting position of search
 381          * @param[out]  indexOf         The index of character
 382          * @exception   E_SUCCESS       The method is successful.
 383          * @exception   E_OBJ_NOT_FOUND The specified character is not found.
 384          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 385          *                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 386          *                                                              - The specified @c startIndex is less than @c 0.
 387          * @remarks             Do not use the @c indexOf when the method returns an error.
 388          * @code
 389          *
 390          *      int indexOf;
 391          *      wchar_t ch = L'a';
 392          *      ImmutalbeString str(L"ImmutableString");
 393          *
 394          *      str.LastIndexOf(ch, str.GetLength() - 1, indexOf); // indexOf == 5
 395          *
 396          * @endcode
 397          */
 398         result LastIndexOf(wchar_t ch, int startIndex, int& indexOf) const;
 399
 400         /**
 401          * Searches the calling instance for the last occurrence of the specified substring and returns its index. @n
 402          * The search begins at the @c startIndex position and proceeds backward towards the beginning.
 403          *
 404          * @since 3.0
 405          *
 406          * @return      An error code
 407          * @param[in]   str             An instance to locate
 408          * @param[in]   startIndex      The starting position of search
 409          * @param[out]  indexOf         The index of the substring
 410          * @exception   E_SUCCESS       The method is successful.
 411          * @exception   E_OBJ_NOT_FOUND The specified character is not found.
 412          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 413          *                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 414          *                                                              - The specified @c startIndex is less than @c 0.
 415          *
 416          * @remarks
 417          *                              - If the substring is empty, E_SUCCESS is returned and the value of @c indexOf is set to @c startIndex.
 418          *                              - Do not use the @c indexOf when the method returns an error.
 419          * @code
 420          *
 421          *      int indexOf;
 422          *      ImmutableString testStr= L"mutable";
 423          *      ImmutalbeString str(L"ImmutableString");
 424          *
 425          *      str.LastIndexOf(testStr, str.GetLength() - 1, indexOf); // indexOf == 2
 426          *
 427          * @endcode
 428          */
 429         result LastIndexOf(const ImmutableString& str, int startIndex, int& indexOf) const;
 430
 431         /**
 432          * Removes the characters within the specified range in the calling %ImmutableString instance
 433          * and returns a new %ImmutableString instance.
 434          *
 435          * @since 3.0
 436          *
 437          * @return      The new %ImmutableString instance
 438          *
 439          * @param[in]   startIndex      The position where the removal begins
 440          * @param[in]   length  The number of characters to remove
 441          * @exception   E_SUCCESS               The method is successful.
 442          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 443          *                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 444          *                                                              - The specified @c startIndex is less than @c 0.
 445          *                                                              - The specified @c length is greater than the length of the substring starting from @c startIndex.
 446          *                                                              - The specified @c length is less than @c 0.
 447          * @remarks
 448          *                              - This method returns an empty string when an exception occurs.
 449          *                              - The specific error code can be accessed by using GetLastResult() method.
 450          */
 451         ImmutableString Remove(int startIndex, int length) const;
 452
 453         /**
 454          * Replaces all occurrences of the specified character in the calling %ImmutableString instance with the character to replace
 455          * and returns a new %ImmutableString instance.
 456          *
 457          * @since 3.0
 458          *
 459          * @return      The new %ImmutableString instance
 460          *
 461          * @param[in]   original The character to replace
 462          * @param[in]   replace The character to replace all occurrences of @c original by
 463          */
 464         ImmutableString Replace(wchar_t original, wchar_t replace) const;
 465
 466         /**
 467          * Replaces all occurrences of the specified string in the calling %ImmutableString instance with string to replace
 468          * and returns a new %ImmutableString instance.
 469          *
 470          * @since 3.0
 471          *
 472          * @return      The new %ImmutableString instance
 473          *
 474          * @param[in]   original        An instance to replace
 475          * @param[in]   replace An instance to replace all occurrences of @c original by
 476          * @exception   E_SUCCESS               The method is successful.
 477          * @exception   E_INVALID_ARG   The specified @c original is an empty string.
 478          * @remarks
 479          *                              - This method returns an empty string when an exception occurs.
 480          *                              - The specific error code can be accessed by using GetLastResult() method.
 481          */
 482         ImmutableString Replace(const ImmutableString& original, const ImmutableString& replace) const;
 483
 484         /**
 485          * Replaces all occurrences of the specified string in the calling %ImmutableString instance from the specified starting position
 486          * with string to replace and returns a new %ImmutableString instance.
 487          *
 488          * @since 3.0
 489          *
 490          * @return      The new %ImmutableString instance
 491          *
 492          * @param[in]   original        An instance to replace
 493          * @param[in]   replace An instance to replace all occurrences of @c original by
 494          * @param[in]   startIndex      The starting position of the substring
 495          * @exception   E_SUCCESS               The method is successful.
 496          * @exception   E_INVALID_ARG   The specified @c original is an empty string.
 497          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 498          *                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 499          *                                                              - The specified @c startIndex is less than @c 0.
 500          *                                                              - The length of the specified @c original is greater than the length of the substring starting from @c startIndex.
 501          * @remarks
 502          *                              - This method returns an empty string when an exception occurs.
 503          *                              - The specific error code can be accessed by using GetLastResult() method.
 504          */
 505         ImmutableString Replace(const ImmutableString& original, const ImmutableString& replace, int startIndex) const;
 506
 507         /**
 508          * Reverses the sequence of characters in the calling %ImmutableString instance and returns a new %ImmutableString instance.
 509          *
 510          * @since 3.0
 511          *
 512          * @return      The new %ImmutableString instance
 513          */
 514         ImmutableString Reverse(void) const;
 515
 516         /**
 517          * Sets the character at the specified index with the given character in the calling %ImmutableString instance
 518          * and returns a new %ImmutableString instance.
 519          *
 520          * @since 3.0
 521          *
 522          * @return      The new %ImmutableString instance
 523          *
 524          * @param[in]   ch      A new character
 525          * @param[in]   indexAt The position of the character
 526          * @exception   E_SUCCESS               The method is successful.
 527          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 528          *                                                              - The specified @c indexAt is either greater than or equal to the length of the current instance.
 529          *                                                              - The specified @c indexAt is less than @c 0.
 530          * @remarks
 531          *                              - This method returns an empty string when an exception occurs.
 532          *                              - The specific error code can be accessed by using GetLastResult() method.
 533          */
 534         ImmutableString SetCharAt(wchar_t ch, int indexAt) const;
 535
 536         /**
 537          * Checks whether this instance contains the specified text from the given index.
 538          *
 539          * @since 3.0
 540          *
 541          * @return              @c true if this instance starts with the specified text, @n
 542          *                              else @c false
 543          *
 544          * @param[in]   str     The string to match
 545          * @param[in]   startIndex      The start position of the string
 546          * @exception   E_SUCCESS               The method is successful.
 547          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 548          *                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 549          *                                                              - The specified @c startIndex is less than @c 0.
 550          * @remarks
 551          *                              - The specific error code can be accessed by using GetLastResult() method.
 552          *                              - This method returns @c true when an empty string is entered on parameter.
 553          */
 554         bool StartsWith(const ImmutableString& str, int startIndex) const;
 555
 556         /**
 557          * Checks whether this instance contains the specified text.
 558          *
 559          * @since 3.0
 560          *
 561          * @return              @c true if this instance starts with the specified text, @n
 562          *                              else @c false
 563          *
 564          * @param[in]   str     The string to match
 565          */
 566         bool StartsWith(const ImmutableString& str) const;
 567
 568         /**
 569          * Finds a substring starting from the given index in the calling %ImmutableString instance
 570          * and returns a new %ImmutableString instance.
 571          *
 572          * @since 3.0
 573          *
 574          * @return      The new %ImmutableString instance containing sub string
 575          *
 576          * @param[in]   startIndex      The starting index of the substring
 577          * @exception   E_SUCCESS               The method is successful.
 578          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 579          *                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 580          *                                                              - The specified @c startIndex is less than @c 0.
 581          * @remarks
 582          *                              - This method returns an empty string when an exception occurs.
 583          *                              - The specific error code can be accessed by using GetLastResult() method.
 584          */
 585         ImmutableString SubString(int startIndex) const;
 586
 587         /**
 588          * Finds a substring of the given length starting from the specified index in the calling %ImmutableString instance
 589          * and returns a new %ImmutableString instance.
 590          *
 591          * @since 3.0
 592          *
 593          * @return      The new %ImmutableString instancecontaining sub string
 594          *
 595          * @param[in]   startIndex      The starting position of the substring
 596          * @param[in]   length  The length of the substring
 597          * @exception   E_SUCCESS               The method is successful.
 598          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 599          *                                                              - The specified @c startIndex is either greater than or equal to the length of the current instance.
 600          *                                                              - The specified @c startIndex is less than @c 0.
 601          *                                                              - The specified @c length is greater than the length of the substring starting from @c startIndex.
 602          *                                                              - The specified @c length is less than @c 0.
 603          * @remarks
 604          *                              - This method returns an empty string when an exception occurs.
 605          *                              - The specific error code can be accessed by using GetLastResult() method.
 606          */
 607         ImmutableString SubString(int startIndex, int length) const;
 608
 609         /**
 610          * Converts the unicode characters to lowercase from the calling %ImmutableString instance and
 611          * returns a new %ImmutableString instance. Unicode characters other than the English alphabets are also supported.
 612          *
 613          * @since 3.0
 614          *
 615          * @return      The new %ImmutableString instance
 616          */
 617         ImmutableString ToLowerCase(void) const;
 618
 619         /**
 620          * Converts the unicode characters to uppercase from the calling %ImmutableString instance and
 621          * returns a new %ImmutableString instance. Unicode characters other than the English alphabets are also supported.
 622          *
 623          * @since 3.0
 624          *
 625          * @return      The new %ImmutableString instance
 626          */
 627         ImmutableString ToUpperCase(void) const;
 628
 629         /**
 630          * Trims the leading and trailing whitespace characters in the calling %ImmutableString instance and
 631          * returns a new %ImmutableString instance.
 632          *
 633          * @since 3.0
 634          *
 635          * @return      The new %ImmutableString instance
 636          */
 637         ImmutableString Trim(void) const;
 638
 639 private:
 640         //
 641         // This constructor is intentionally declared as private so that only the platform can create an instance.
 642         //
 643         ImmutableString(void);
 644
 645         //
 646         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 647         //
 648         ImmutableString& operator =(const ImmutableString& rhs);
 649
 650         //
 651         // Overloaded constructor
 652         //
 653         ImmutableString(const wchar_t* pStr1, const wchar_t* pStr2);
 654
 655         //
 656         // Overloaded constructor
 657         //
 658         ImmutableString(_StringBuffer* pBuf);
 659
 660 private:
 661
 662         _StringBuffer* __pImpl;
 663         friend class _StringBuffer;
 664 };
 665
 666 /**
 667  * Checks two %ImmutableString instances for equality.
 668  *
 669  * @since 3.0
 670  *
 671  * @return              @c true if %lhs string is equal to %rhs string, @n
 672  *                              else @c false
 673  * @param[in]   lhs     An instance for the left-hand side of the operator
 674  * @param[in]   rhs     An instance for the right-hand side of the operator
 675  * @remarks
 676  *                              - The operator performs an ordinal comparison of each Unicode character.
 677  *                              - This operator is not locale-dependent.
 678  */
 679 inline bool operator ==(const ImmutableString& lhs, const ImmutableString& rhs)
 680 {
 681         return (lhs.CompareTo(rhs) == 0);
 682 }
 683
 684 /**
 685  * Checks two %ImmutableString instances for inequality.
 686  *
 687  * @since 3.0
 688  *
 689  * @return              @c true if %lhs string is not equal to %rhs string, @n
 690  *                              else @c false
 691  * @param[in]   lhs     An instance for the left-hand side of the operator
 692  * @param[in]   rhs     An instance for the right-hand side of the operator
 693  * @remarks
 694  *                              - The operator performs an ordinal comparison of each Unicode character.
 695  *                              - This operator is not locale-dependent.
 696  */
 697 inline bool operator !=(const ImmutableString& lhs, const ImmutableString& rhs)
 698 {
 699         return (lhs.CompareTo(rhs) != 0);
 700 }
 701
 702 /**
 703  * Checks the right-hand side %ImmutalbeString instance is greater than the left-hand side one.
 704  *
 705  * @since 3.0
 706  *
 707  * @return              @c true if the string of the right-hand side %ImmutableString instance is greater than the left-hand side one, @n
 708  *                              else @c false
 709  * @param[in]   lhs     An instance for the left-hand side of the operator
 710  * @param[in]   rhs     An instance for the right-hand side of the operator
 711  * @remarks
 712  *                              - The operator compares texts by ordinal comparison.
 713  *                              - This operator is not locale-dependent.
 714  */
 715 inline bool operator <(const ImmutableString& lhs, const ImmutableString& rhs)
 716 {
 717         return (lhs.CompareTo(rhs) < 0);
 718 }
 719
 720 /**
 721  * Checks the right-hand side %ImmutalbeString instance is less than the left-hand side one.
 722  *
 723  * @since 3.0
 724  *
 725  * @return              @c true if the string of the right-hand side %ImmutableString instance is less than the left-hand side one, @n
 726  *                              else @c false
 727  * @param[in]   lhs     An instance for the left-hand side of the operator
 728  * @param[in]   rhs     An instance for the right-hand side of the operator
 729  * @remarks
 730  *                              - The operator compares texts by ordinal comparison.
 731  *                              - This operator is not locale-dependent.
 732  */
 733 inline bool operator >(const ImmutableString& lhs, const ImmutableString& rhs)
 734 {
 735         return (lhs.CompareTo(rhs) > 0);
 736 }
 737
 738 /**
 739  * Checks the right-hand side %ImmutalbeString instance is greater than or equal to the left-hand side one.
 740  *
 741  * @since 3.0
 742  *
 743  * @return              @c true if the string of the right-hand side %ImmutableString instance is greater than or equal to the left-hand side one, @n
 744  *                              else @c false
 745  * @param[in]   lhs     An instance for the left-hand side of the operator
 746  * @param[in]   rhs     An instance for the right-hand side of the operator
 747  * @remarks
 748  *                              - The operator compares texts by ordinal comparison.
 749  *                              - This operator is not locale-dependent.
 750  */
 751 inline bool operator <=(const ImmutableString& lhs, const ImmutableString& rhs)
 752 {
 753         return (lhs.CompareTo(rhs) <= 0);
 754 }
 755
 756 /**
 757  * Checks the right-hand side %ImmutalbeString instance is less than or equal to the left-hand side one.
 758  *
 759  * @since 3.0
 760  *
 761  * @return              @c true if the string of the right-hand side %ImmutableString instance is less than or equal to the left-hand side one, @n
 762  *                              else @c false
 763  * @param[in]   lhs     An instance for the left-hand side of the operator
 764  * @param[in]   rhs     An instance for the right-hand side of the operator
 765  * @remarks
 766  *                              - The operator compares texts by ordinal comparison.
 767  *                              - This operator is not locale-dependent.
 768  */
 769 inline bool operator >=(const ImmutableString& lhs, const ImmutableString& rhs)
 770 {
 771         return (lhs.CompareTo(rhs) >= 0);
 772 }
 773
 774 /**
 775  * Concatenates two strings.
 776  *
 777  * @since 3.0
 778  *
 779  * @return              The concatenated %ImmutableString instance
 780  * @param[in]   lhs     An instance for the left-hand side of the operator
 781  * @param[in]   rhs     An instance for the right-hand side of the operator
 782  */
 783 inline ImmutableString operator +(const ImmutableString& lhs, const ImmutableString& rhs)
 784 {
 785         return lhs.Append(rhs);
 786 }
 787
 788 }} // Tizen::Base
 789 #endif // _FBASE_IMMUTABLE_STRING_H_