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