inc/FBaseUtilStringUtil.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FBaseUtilStringUtil.h
  20  * @brief               This is the header file for the %StringUtil class.
  21  *
  22  * This header file contains the declarations of the %StringUtil class.
  23  */
  24 #ifndef _FBASE_UTIL_STRING_UTIL_H_
  25 #define _FBASE_UTIL_STRING_UTIL_H_
  26
  27 #include <FBaseString.h>
  28 #include <FBaseByteBuffer.h>
  29 #include <FBaseBuffer.h>
  30 #include <FBaseResult.h>
  31
  32
  33 namespace Tizen { namespace Base { namespace Utility
  34 {
  35 /**
  36  * @class       StringUtil
  37  * @brief       This class provides various utility methods for String.
  38  *
  39  * @since 2.0
  40  *
  41  * The %StringUtil class provides various utility methods for String.
  42  *
  43  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/utility_namespace.htm">Utility</a>.
  44  *
  45  * The following example demonstrates how to use the %StringUtil class.
  46  *
  47  * @code
  48  *      #include <FBase.h>
  49  *
  50  *      using namespace Tizen::Base;
  51  *      using namespace Tizen::Base::Utility;
  52  *
  53  *      void
  54  *      MyClass::StringUtilSample(void)
  55  *      {
  56  *              String str1(L"Sigma and Pi : \u03A0 and \u03A3");
  57  *              String str2;
  58  *
  59  *              // String to McharBuffer
  60  *              McharBuffer* pMb = StringUtil::StringToMbN(str1);
  61  *
  62  *              // Gets a length of string in McharBuffer
  63  *              int length = StringUtil::GetStringLengthInMb(*pMb);
  64  *
  65  *              // McharBuffer to String
  66  *              StringUtil::MbToString(*pMb, str2);
  67  *
  68  *              if (str1.Equals(str2))
  69  *              {
  70  *                      // ...
  71  *              }
  72  *
  73  *              delete pMb;
  74  *      }
  75  * @endcode
  76  */
  77 class _OSP_EXPORT_ StringUtil
  78 {
  79 public:
  80         /**
  81          * @if OSPDEPREC
  82          * Converts an McharBuffer to a null-terminated string. @n
  83          * The position of the buffer is not changed.
  84          *
  85          * @brief       <i> [Deprecated] </i>
  86          * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
  87          * Instead of using this method, use the WcharBufferToString(const WcharBuffer& mb, String& str) method.
  88          * @since 2.0
  89          *
  90          * @return                      An error code
  91          * @param[in]           mb              An instance of McharBuffer
  92          * @param[out]          str             The current position
  93          * @exception           E_SUCCESS               The method is successful.
  94          * @exception           E_INVALID_ARG   A specified input parameter is invalid, or
  95          *                                                                      @c null does not exist between the position and limit of buffer.
  96          * @endif
  97          */
  98         static result MbToString(const McharBuffer& mb, String& str);
  99
 100         /**
 101          * Converts an WcharBuffer to a null-terminated string. @n
 102          * The position of the buffer is not changed.
 103          *
 104          * @since 2.0
 105          *
 106          * @return                      An error code
 107          * @param[in]           wb              An instance of WcharBuffer
 108          * @param[out]          str             The current position
 109          * @exception           E_SUCCESS               The method is successful.
 110          * @exception           E_INVALID_ARG   A specified input parameter is invalid, or
 111          *                                                                      @c null does not exist between the position and limit of buffer.
 112          */
 113         static result WcharBufferToString(const WcharBuffer& wb, String& str);
 114
 115         /**
 116          * @if OSPDEPREC
 117          * Gets a new McharBuffer from the specified string. @n
 118          * The buffer's limit is the length of the string plus one and the starting position is @c 0.
 119          *
 120          * @brief       <i> [Deprecated] </i>
 121          * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
 122          * Instead of using this method, use the StringToWcharBufferN(const String& str) method.
 123          * @since 2.0
 124          *
 125          * @return                      A pointer to the McharBuffer instance from the specified string, @n
 126          *                                      else @c null if an exception occurs
 127          * @param[in]           str             The string to read
 128          * @exception           E_SUCCESS                       The method is successful.
 129          * @exception           E_INVALID_ARG           The specified @c str is an empty string.
 130          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 131          * @endif
 132          */
 133         static McharBuffer* StringToMbN(const String& str);
 134
 135         /**
 136          * Gets a new WcharBuffer from the specified string. @n
 137          * The buffer's limit is the length of the string plus one and the starting position is @c 0.
 138          *
 139          * @since 2.0
 140          *
 141          * @return                      A pointer to the WcharBuffer instance from the specified string, @n
 142          *                                      else @c null if an exception occurs
 143          * @param[in]           str             The string to read
 144          * @exception           E_SUCCESS                       The method is successful.
 145          * @exception           E_INVALID_ARG           The specified @c str is an empty string.
 146          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 147          */
 148         static WcharBuffer* StringToWcharBufferN(const String& str);
 149
 150         /**
 151          * @if OSPDEPREC
 152          * Gets a new McharBuffer from a substring of the specified string. @n
 153          * The buffer's limit is the length of the string plus one and the starting position is @c 0.
 154          *
 155          * @brief       <i> [Deprecated] </i>
 156          * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
 157          * Instead of using this method, use the StringToWcharBufferN(const String& str, int index, int length) method.
 158          * @since 2.0
 159          *
 160          * @return                      A pointer to the McharBuffer instance from the substring of the specified string, @n
 161          *                                      else @c null if an exception occurs
 162          * @param[in]           str             The string to read
 163          * @param[in]           index   The starting index for the substring in the string @n
 164          *                                                      It must not be longer than the length of the string.
 165          * @param[in]           length  The length of the substring @n
 166          *                                                      It must not be longer than the length of the given string minus the specified @c index.
 167          * @exception           E_SUCCESS                       The method is successful.
 168          * @exception           E_INVALID_ARG           The specified @c str is an empty string.
 169          * @exception           E_OUT_OF_RANGE          The @c index and @c length are outside the bounds of the data structure.
 170          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 171          * @endif
 172          */
 173         static McharBuffer* StringToMbN(const String& str, int index, int length);
 174
 175         /**
 176          * Gets a new WcharBuffer from a substring of the specified string. @n
 177          * The buffer's limit is the length of the string plus one and the starting position is @c 0.
 178          *
 179          * @since 2.0
 180          *
 181          * @return                      A pointer to the WcharBuffer instance from the substring of the specified string, @n
 182          *                                      else @c null if an exception occurs
 183          * @param[in]           str             The string to read
 184          * @param[in]           index   The starting index for the substring in the string @n
 185          *                                                      It must not be longer than the length of the string.
 186          * @param[in]           length  The length of the substring @n
 187          *                                                      It must not be longer than the length of the given string minus the specified @c index.
 188          * @exception           E_SUCCESS                       The method is successful.
 189          * @exception           E_INVALID_ARG           The specified @c str is an empty string.
 190          * @exception           E_OUT_OF_RANGE          The @c index and @c length are outside the bounds of the data structure.
 191          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 192          */
 193         static WcharBuffer* StringToWcharBufferN(const String& str, int index, int length);
 194
 195         /**
 196          * @if OSPDEPREC
 197          * Gets the string length in the McharBuffer. @n
 198          * The string length is the length from the current position of the %McharBuffer to the @c null character.
 199          * The position of the buffer is not changed.
 200          *
 201          * @brief       <i> [Deprecated] </i>
 202          * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
 203          * Instead of using this method, use the GetStringLengthInWcharBuffer(const WcharBuffer& wb) method.
 204          *
 205          * @since 2.0
 206          *
 207          * @return                      The length of the McharBuffer instance, @n
 208          *                                      else @c -1 if the %McharBuffer instance is not terminated with the @c null character
 209          * @param[in]           mb              An instance of McharBuffer
 210          * @remarks                     If @c null does not exist between the position and the limit of the buffer, the method returns @c -1.
 211          * @endif
 212          */
 213         static int GetStringLengthInMb(const McharBuffer& mb);
 214
 215         /**
 216          * Gets the string length in the WcharBuffer. @n
 217          * The string length is the length from the current position of the %WcharBuffer to the @c null character.
 218          * The position of the buffer is not changed.
 219          *
 220          * @since 2.0
 221          *
 222          * @return                      The length of the WcharBuffer instance, @n
 223          *                                      else @c -1 if the %WcharBuffer instance is not terminated with the @c null character
 224          * @param[in]           wb              An instance of WcharBuffer
 225          * @remarks                     If @c null does not exist between the position and the limit of the buffer, the method returns @c -1.
 226          */
 227         static int GetStringLengthInWcharBuffer(const WcharBuffer& wb);
 228
 229         /**
 230          * Gets a new ByteBuffer encoded from the specified string. @n
 231          * The buffer's limit is the length of the string plus one and the starting position is @c 0.
 232          *
 233          * @since 2.0
 234          *
 235          * @return                      A pointer to the ByteBuffer instance encoded from the specified string, @n
 236          *                                      else @c null if an exception occurs
 237          * @param[in]           unicodeString   A string to encode
 238          * @exception           E_SUCCESS               The method is successful.
 239          * @exception           E_INVALID_ARG   The specified input parameter is invalid.
 240          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 241          * @see                         Tizen::Base::ByteBuffer
 242          * @see                         Tizen::Base::String
 243          */
 244         static ByteBuffer* StringToUtf8N(const String& unicodeString);
 245
 246         /**
 247          * Decodes a null-terminated UTF-8 string into a Unicode string. @n
 248          * The position of the buffer is not changed.
 249          *
 250          * @since 2.0
 251          *
 252          * @return                      An error code
 253          * @param[in]           pUtf8String             A pointer to a String instance containing UTF-8 codes
 254          * @param[out]          unicodeString   A string containing Unicode characters
 255          * @exception           E_SUCCESS                                       The method is successful.
 256          * @exception           E_INVALID_ARG                           The specified @c pUtf8String is a @c null reference.
 257          * @exception           E_INVALID_ENCODING_RANGE        The indicated string contains UTF-8 code that is outside the bounds specified by the character encoding scheme.
 258          *
 259          * The following example demonstrates how to use the %Utf8ToString() method.
 260          *
 261          * @code
 262          *
 263          *       const char* pUtf8String = "Utf8ToString";
 264          *
 265          *       String str;
 266          *
 267          *       // Decodes a UTF-8 string into a Unicode string
 268          *       StringUtil::Utf8ToString(pUtf8String, str);
 269          *
 270          * @endcode
 271          */
 272         static result Utf8ToString(const char* pUtf8String, String& unicodeString);
 273
 274         /**
 275          * Decodes a string consisting of base 64 digits to a ByteBuffer. @n
 276          * The buffer's limit is the length of the string plus one and the starting position is @c 0.
 277          *
 278          * @since 2.0
 279          *
 280          * @return                      A pointer to the ByteBuffer instance decoded from the specified string, @n
 281          *                                      else @c null if an exception occurs
 282          * @param[in]           base64String    A string to decode
 283          * @exception           E_SUCCESS                       The method is successful.
 284          * @exception           E_INVALID_ARG           The specified input parameter is invalid. @n
 285          *                                                                              The specified @c base64String is not a valid Base64 string.
 286          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 287          *
 288          * The following example demonstrates how to use the %DecodeBase64StringN() method.
 289          *
 290          * @code
 291          *
 292          *      const char* pChar = "abcdefg123456";
 293          *      int size = strlen(pChar);
 294          *
 295          *      String encodedStr;
 296          *      ByteBuffer buffer;
 297          *      buffer.Construct(size + 1);
 298          *
 299          *      buffer.SetArray((byte*)pChar, 0, size);
 300          *      buffer.SetByte('\0');
 301          *      buffer.Flip();
 302          *
 303          *      StringUtil::EncodeToBase64String(buffer, encodedStr);
 304          *
 305          *      // Decodes a String consisting of base 64 digits to a ByteBuffer
 306          *      ByteBuffer* pDecodedBuffer = StringUtil::DecodeBase64StringN(encodedStr);
 307          *
 308          * @endcode
 309          */
 310         static ByteBuffer* DecodeBase64StringN(const String& base64String);
 311
 312         /**
 313          * Encodes a ByteBuffer into a string consisting of base 64 characters. @n
 314          * The position of the buffer is not changed.
 315          *
 316          * @since 2.0
 317          *
 318          * @return                      An error code
 319          * @param[in]           buffer                  An instance of ByteBuffer to encode
 320          * @param[out]          encodedString   An instance of String consisting of base 64 characters
 321          * @exception           E_SUCCESS                       The method is successful.
 322          * @exception           E_INVALID_ARG           A specified input parameter is invalid, or
 323          *                                                                              the @c buffer is empty.
 324          *
 325          * The following example demonstrates how to use the %EncodeToBase64String() method.
 326          *
 327          * @code
 328          *
 329          *      const char* pChar = "abcdefg123456";
 330          *      int size = strlen(pChar);
 331          *
 332          *      String encodedStr;
 333          *      ByteBuffer buffer;
 334          *      buffer.Construct(size + 1);
 335          *
 336          *      buffer.SetArray((byte*)pChar, 0, size);
 337          *      buffer.SetByte('\0');
 338          *      buffer.Flip();
 339          *
 340          *      // Encodes a ByteBuffer into a String consisting of base 64 characters
 341          *      StringUtil::EncodeToBase64String(buffer, encodedStr);
 342          *
 343          * @endcode
 344          */
 345         static result EncodeToBase64String(const ByteBuffer& buffer, String& encodedString);
 346
 347 private:
 348         /**
 349          * This default constructor is intentionally declared as private because this class cannot be constructed.
 350          */
 351         StringUtil(void);
 352
 353         /**
 354          * This destructor is intentionally declared as private because this class cannot be constructed.
 355          */
 356         ~StringUtil(void);
 357
 358         /**
 359          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 360          *
 361          * @param[in]   rhs     The instance of the StringUtil
 362          */
 363         StringUtil(const StringUtil& rhs);
 364
 365         /**
 366          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 367          *
 368          * @param[in]   rhs     An instance of %StringUtil
 369          */
 370         StringUtil& operator =(const StringUtil& rhs);
 371 }; // StringUtil
 372
 373 }}} // Tizen::Base::Utility
 374
 375 #endif // _FBASE_UTIL_STRING_UTIL_H_