inc/FTextUtf8Encoding.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                FTextUtf8Encoding.h
  20  * @brief               This is the header file for the %Utf8Encoding class.
  21  *
  22  * This header file contains the declarations of the %Utf8Encoding class.
  23  * This class is derived from the Encoding class.
  24  */
  25 #ifndef _FTEXT_UTF8_ENCODING_H_
  26 #define _FTEXT_UTF8_ENCODING_H_
  27
  28 #include <FTextEncoding.h>
  29 #include <FTextUtf8Encoder.h>
  30 #include <FTextUtf8Decoder.h>
  31
  32
  33 namespace Tizen { namespace Text
  34 {
  35
  36 /**
  37  * @class       Utf8Encoding
  38  * @brief       This class is an implementation of the UTF-8 encoding.
  39  *
  40  * @since       2.0
  41  *
  42  * @final       This class is not intended for extension.
  43  *
  44  * The %Utf8Encoding class is an implementation of the UTF-8 encoding.
  45  * Universal Transformation Format-8 (UTF-8) is a translated language used on the internet. It converts Unicode to 8-bit bytes. UTF-8 encoding supports all the Unicode character values and surrogates.
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/text/converting_all_text_data.htm">Converting All Text Data at Once</a>.
  48  *
  49  * The following example demonstrates how to use the %Utf8Encoding class.
  50  *
  51  *  @code
  52  *      #include <FBase.h>
  53  *      #include <FText.h>
  54  *
  55   *     using namespace Tizen::Base;
  56  *      using namespace Tizen::Text;
  57  *
  58  *      void
  59  *      MyClass::Utf8EncodingSample(void)
  60  *      {
  61  *              Utf8Encoding utf8;
  62  *
  63  *              String str(L"(\u03a0) and (\u03a3)");
  64  *
  65  *              int byteCount;
  66  *              utf8.GetByteCount(str, byteCount);
  67  *
  68  *              // Encodes
  69  *              ByteBuffer* pBuffer = utf8.GetBytesN(str);
  70  *
  71  *              int charCount;
  72  *              utf8.GetCharCount(*pBuffer, charCount);
  73  *
  74  *              // Decodes
  75  *              String decodedStr;
  76  *              utf8.GetString(*pBuffer, decodedStr);
  77  *
  78  *              if (str.Equals(decodedStr))
  79  *              {
  80  *                      //....
  81  *              }
  82  *
  83  *              delete pBuffer;
  84  *      }
  85  * @endcode
  86  *
  87  */
  88
  89
  90 class _OSP_EXPORT_ Utf8Encoding
  91         : public Encoding
  92 {
  93 public:
  94         /**
  95          * This is the default constructor for this class.
  96          *
  97          * @since       2.0
  98          */
  99         Utf8Encoding(void);
 100
 101         /**
 102          * This is the destructor for this class. @n
 103          * This destructor overrides Tizen::Text::Encoding::~Encoding().
 104          *
 105          * @since       2.0
 106          */
 107         virtual ~Utf8Encoding(void);
 108
 109         /**
 110          * Gets the total number of bytes that are generated by encoding an instance of specified string. @n
 111          * The %GetByteCount() method determines the total number of bytes that are generated when the specified string is encoded.
 112          *
 113          * @since                       2.0
 114          *
 115          * @return              An error code
 116          * @param[in]   str                       The string to encode
 117          * @param[out]  byteCount                 The total number of bytes required to encode the string
 118          * @exception   E_SUCCESS                 The method is successful.
 119          * @exception   E_INVALID_ARG             A specified input parameter is invalid, or
 120          *                                        the specified @c str is an empty string.
 121          * @exception   E_INVALID_ENCODING_RANGE  The specified string contains code points that are outside the bounds of the character encoding scheme.
 122          * @see         GetMaxByteCount()
 123          */
 124         virtual result GetByteCount(const Tizen::Base::String& str, int& byteCount) const;
 125
 126         /**
 127          * Gets the total number of bytes that are generated by encoding an instance of specified Tizen::Base::WcharBuffer. @n
 128          * The %GetByteCount() method determines the exact number of bytes
 129          * produced if the given array of characters is encoded.
 130          *
 131          * @since                       2.0
 132          *
 133          * @return              An error code
 134          * @param[in]   chars                 An instance of Tizen::Base::WcharBuffer to encode
 135          * @param[out]  byteCount              The total number of bytes required to encode the specified range of characters
 136          * @exception   E_SUCCESS                The method is successful.
 137          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 138          *                                        the specified @c chars is empty.
 139          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 140          * @see         GetMaxByteCount()
 141          */
 142         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int& byteCount) const;
 143
 144         /**
 145          * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance. @n
 146          * The %GetByteCount() method determines the total number of bytes that are generated when the specified array of characters is encoded.
 147          *
 148          * @since                       2.0
 149          *
 150          * @return              An error code
 151          * @param[in]   chars                    An instance of Tizen::Base::WcharBuffer to encode
 152          * @param[in]   charIndex                The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 153          * @param[in]   charCount                  The total number of characters to encode
 154          * @param[out]  byteCount                 The total number of bytes required to encode the specified range of characters
 155          * @exception   E_SUCCESS                The method is successful.
 156          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 157          *                                       the specified @c chars is empty.
 158          * @exception   E_OUT_OF_RANGE               The value of an argument is outside the valid range defined by the method, or
 159          *                                                                                the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 160          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or
 161          *                                                                                 the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 162          * @exception   E_INVALID_ENCODING_RANGE  The specified string contains code points that are outside the bounds of the character encoding scheme.
 163          * @see                 GetMaxByteCount()
 164          */
 165         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount, int& byteCount) const;
 166
 167         /**
 168          * Encodes an instance of the specified Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
 169          *
 170          * @since                       2.0
 171          *
 172          * @return                                      A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 173          *                                      else @c null if an exception occurs @n
 174          *                                                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
 175          * @param[in]   chars                   An instance of Tizen::Base::WcharBuffer to encode
 176          * @exception   E_SUCCESS                   The method is successful.
 177          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 178          * @exception   E_INVALID_ARG           The specified @c chars is empty or invalid.
 179          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 180          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 181          * @see                 GetCharsN()
 182          */
 183         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars) const;
 184
 185         /**
 186          * Encodes an instance of the specified Tizen::Base::String into an instance of Tizen::Base::ByteBuffer.
 187          *
 188          * @since                       2.0
 189          *
 190          * @return                                      A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 191          *                                      else @c null if an exception occurs @n
 192          *                                                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
 193          * @param[in]   str                     A string to encode
 194          * @exception   E_SUCCESS                   The method is successful.
 195          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 196          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 197          *                                       the specified @c str is an empty string.
 198          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 199          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 200          * @see                 GetString()
 201          */
 202         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::String& str) const;
 203
 204         /**
 205          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
 206          * The position and limit of the pointer to the %Tizen::Base::ByteBuffer instance is not changed.
 207          *
 208          * @since                       2.0
 209          *
 210          * @return              An error code
 211          * @param[in]   chars                     An instance of Tizen::Base::WcharBuffer to encode
 212          * @param[in]   charIndex                 The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 213          * @param[in]   charCount                   The total number of characters to encode
 214          * @param[out]  bytes                     The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 215          * @param[in]   byteIndex                 The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 216          * @exception   E_SUCCESS                The method is successful.
 217          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 218          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 219          *                                        the specified @c chars or @c bytes is empty.
 220          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method, or
 221          *                                       the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 222          * @exception   E_UNDERFLOW                  This operation has caused the memory to underflow, or
 223          *                                         the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 224          * @exception   E_OVERFLOW               This operation has caused the memory to overflow, or
 225          *                                        the specified @c bytes does not contain sufficient space to store the encoded characters.
 226          * @exception   E_INVALID_ENCODING_RANGE  The specified string contains code points that are outside the bounds of the character encoding scheme.
 227          * @see                 GetChars()
 228          */
 229         virtual result GetBytes(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
 230                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
 231
 232         /**
 233          * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
 234          * The position and limit of the pointer to the %Tizen::Base::ByteBuffer instance is not changed.
 235          *
 236          * @since                       2.0
 237          *
 238          * @return              An error code
 239          * @param[in]   str                          A string to encode
 240          * @param[in]   charIndex                    The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 241          * @param[in]   charCount                      The total number of characters to encode
 242          * @param[out]  bytes                        The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 243          * @param[in]   byteIndex                      The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 244          * @exception   E_SUCCESS                The method is successful.
 245          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 246          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 247          *                                        the specified @c str or @c bytes is empty.
 248          * @exception   E_OUT_OF_RANGE               The value of an argument is outside the valid range defined by the method, or
 249          *                                         the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c str.
 250          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or
 251          *                                                                              the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c str.
 252          * @exception   E_OVERFLOW               This operation has caused the memory to overflow, or
 253          *                                                                                 the specified @c bytes does not contain sufficient space to store the encoded characters.
 254          * @exception   E_INVALID_ENCODING_RANGE  The specified string contains code points that are outside the bounds of the character encoding scheme.
 255          * @see                 GetString()
 256          */
 257         virtual result GetBytes(const Tizen::Base::String& str, int charIndex, int charCount,
 258                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
 259
 260         /**
 261          * Gets the total number of characters that are generated by decoding an instance of Tizen::Base::ByteBuffer. @n
 262          * The %GetCharCount() method determines the exact number of characters
 263          * produced if the given range of bytes is converted.
 264          *
 265          * @since                       2.0
 266          *
 267          * @return              An error code
 268          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 269          * @param[out]  charCount                The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
 270          * @exception   E_SUCCESS                The method is successful.
 271          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 272          *                                         the specified @c bytes is empty.
 273          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 274          * @see                 GetMaxCharCount()
 275          */
 276         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int& charCount) const;
 277
 278         /**
 279          * Gets the total number of characters that are generated by decoding a range of elements specified in the Tizen::Base::ByteBuffer instance. @n
 280          * The %GetCharCount() method determines the exact number of characters
 281          * produced if the given range of bytes is converted.
 282          *
 283          * @since                       2.0
 284          *
 285          * @return              An error code
 286          * @param[in]   bytes                         An instance of Tizen::Base::ByteBuffer to decode
 287          * @param[in]   byteIndex                    The index from where decoding begins
 288          * @param[in]   byteCount                     The total number of bytes to decode
 289          * @param[out]  charCount                 The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
 290          * @exception   E_SUCCESS                The method is successful.
 291          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 292          *                                       the specified @c bytes is empty.
 293          * @exception   E_OUT_OF_RANGE        The value of an argument is outside the valid range defined by the method, or
 294          *                                                                                 the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
 295          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or
 296          *                                                                        the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
 297          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 298          * @see                 GetMaxCharCount()
 299          */
 300         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, int& charCount) const;
 301
 302         /**
 303          * Decodes an instance of the specified Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
 304          *
 305          * @since                       2.0
 306          *
 307          * @return                            A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
 308          *                                      else @c null if an exception occurs @n
 309          *                                              The buffer limit is the position of the last decoded byte plus one and the position is zero.
 310          * @param[in]   bytes                  An instance of Tizen::Base::ByteBuffer to decode
 311          * @exception   E_SUCCESS                The method is successful.
 312          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 313          * @exception   E_INVALID_ARG            The specified @c bytes is empty or invalid.
 314          * @exception   E_INVALID_ENCODING_RANGE  The specified string contains code points that are outside the bounds of the character encoding scheme.
 315          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 316          * @see                 GetBytesN()
 317          */
 318         virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const;
 319
 320         /**
 321          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range. @n
 322          * The position and limit of the pointer to the %Tizen::Base::WcharBuffer instance is not changed.
 323          *
 324          * @since                       2.0
 325          *
 326          * @return              An error code
 327          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 328          * @param[in]   byteIndex                The index from where decoding begins
 329          * @param[in]   byteCount                The total number of bytes to decode
 330          * @param[out]  chars                    The Tizen::Base::WcharBuffer instance where the resultant decoded data is stored
 331          * @param[in]   charIndex                The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 332          * @exception   E_SUCCESS                The method is successful.
 333          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 334          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 335          *                                       the specified @c bytes or @c chars is empty.
 336          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method, or
 337          *                                                                             the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
 338          * @exception   E_UNDERFLOW                  This operation has caused the memory to underflow, or
 339          *                                                                                 the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
 340          * @exception   E_OVERFLOW                   This operation has caused the memory to overflow, or
 341          *                                                                                 the specified @c chars does not contain sufficient space to store the decoded bytes.
 342          * @exception   E_INVALID_ENCODING_RANGE  The specified string contains code points that are outside the bounds of the character encoding scheme.
 343          * @see                 GetBytes()
 344          */
 345         virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
 346                 Tizen::Base::WcharBuffer& chars, int charIndex = 0) const;
 347
 348         /**
 349          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 350          *
 351          * @since                       2.0
 352          *
 353          * @return              An error code
 354          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 355          * @param[out]  str                        A Tizen::Base::String instance @n
 356          *                                           It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 357          * @exception   E_SUCCESS                The method is successful.
 358          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 359          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 360          *                                       the specified @c bytes is empty.
 361          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 362          * @see                 GetBytesN()
 363          */
 364         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const;
 365
 366         /**
 367          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 368          *
 369          * @since                       2.0
 370          *
 371          * @return              An error code
 372          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 373          * @param[in]   index                    The index from where decoding begins
 374          * @param[in]   count                    The total number of bytes to decode
 375          * @param[out]  str                      A Tizen::Base::String instance @n
 376          *                                       It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 377          * @exception   E_SUCCESS                The method is successful.
 378          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 379          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 380          *                                        the specified @c bytes is empty.
 381          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method, or
 382          *                                                                                the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
 383          * @exception   E_UNDERFLOW                              This operation has caused the memory to underflow, or
 384          *                                                                               the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
 385          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 386          * @see                 GetBytes()
 387          */
 388         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const;
 389
 390
 391         /**
 392          * Gets the maximum number of bytes required for encoding a given number of characters.
 393          *
 394          * @since                       2.0
 395          *
 396          * @return              The maximum number of bytes required for encoding a given number of characters
 397          * @param[in]   charCount The total number of characters to encode
 398          * @remarks     This method determines an appropriate buffer size for the byte arrays passed to GetBytes() for encoding.
 399          * @see                 GetByteCount()
 400          * @see                 GetBytes()
 401          */
 402         virtual int GetMaxByteCount(int charCount) const;
 403
 404
 405         /**
 406         * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
 407         *
 408         * @since                                2.0
 409         *
 410         * @return                       The maximum number of characters generated by decoding the specified number of bytes
 411         * @param[in]            byteCount The total number of bytes to encode
 412         * @remarks     This method determines an appropriate buffer size for the character arrays passed to
 413         *                   GetChars() or a decoder for encoding.
 414         * @see                  GetCharCount()
 415         * @see                  GetChars()
 416         */
 417         virtual int GetMaxCharCount(int byteCount) const;
 418
 419         /**
 420          * Gets the encoder for the current encoding.
 421          *
 422          * @since                               2.0
 423          *
 424          * @return                      A pointer to the Encoder instance for the current encoding
 425          * @remarks     Contrary to GetBytes(), an encoder can convert partial sequences of characters into
 426          *              partial sequences of bytes by maintaining the appropriate states between the conversions.
 427          * @see                 GetBytes()
 428          */
 429         virtual Encoder* GetEncoderN(void) const;
 430
 431         /**
 432          * Gets the decoder for the current encoding.
 433          *
 434          * @since                               2.0
 435          *
 436          * @return                      A pointer to the Decoder instance for the current encoding
 437          * @remarks     Contrary to GetChars(), a decoder can convert partial sequences of bytes
 438          *              into partial sequences of characters by maintaining the appropriate states between the conversions.
 439          * @see                 GetChars()
 440          */
 441         virtual Decoder* GetDecoderN(void) const;
 442
 443         /**
 444         * Gets the encoding type of the current instance.
 445         *
 446         * @since                        2.0
 447         *
 448         * @return               An encoding type
 449         */
 450         virtual Tizen::Base::String GetEncodingType(void) const;
 451
 452 private:
 453         /**
 454          * The implementation of this copy constructor is intentionally blank and declared as private to
 455          * prohibit copying of objects.
 456          */
 457         Utf8Encoding(const Utf8Encoding& utf8Encoding);
 458
 459         /**
 460          * The implementation of this copy assignment operator is intentionally blank and declared as private
 461          * to prohibit copying of objects.
 462          */
 463         Utf8Encoding& operator =(const Utf8Encoding& utf8Encoding);
 464
 465         friend class Utf8Decoder;
 466         friend class _Utf8EncodingImpl;
 467         class _Utf8EncodingImpl* __pUtf8EncodingImpl;
 468 };
 469
 470 } } // Tizen::Text
 471 #endif //_FTEXT_UTF8_ENCODING_H_