inc/FTextEncoding.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                FTextEncoding.h
  19  * @brief               This is the header file for the %Encoding class.
  20  *
  21  * This header file contains the declarations of the %Encoding class. @n
  22  * This class is the base class for all character encoding classes.
  23  */
  24 #ifndef _FTEXT_ENCODING_H_
  25 #define _FTEXT_ENCODING_H_
  26
  27 // Include
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseBuffer.h>
  31 #include <FBaseColIList.h>
  32 #include <FBaseString.h>
  33 #include <FTextEncoder.h>
  34 #include <FTextDecoder.h>
  35
  36
  37 namespace Tizen { namespace Text
  38 {
  39
  40 /**
  41  * @class       Encoding
  42  * @brief       This class implements character encoding.
  43  *
  44  * @since       2.0
  45  *
  46  * The %Encoding class is the base class for all classes that implement character encoding.
  47  *
  48  * 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>.
  49  *
  50  * For more information on the supported encoding types, see <a href="../org.tizen.native.appprogramming/html/guide/text/text.htm">Encoding standards in %Tizen</a>.
  51  *
  52  * The following example demonstrates how to use the %Encoding class.
  53  *
  54  *      @code
  55  *      #include <FBase.h>
  56  *      #include <FText.h>
  57  *
  58  *      using namespace Tizen::Base;
  59  *      using namespace Tizen::Text;
  60  *
  61  *      void
  62  *      MyClass::EncodingSample(void)
  63  *      {
  64  *              Encoding* pEnc = Encoding::GetEncodingN(L"ISO-8859-2");
  65  *
  66  *              String str(L"Encoding Test \u0104\u02D8");
  67  *
  68  *              int byteCount;
  69  *              pEnc->GetByteCount(str, byteCount);
  70  *
  71  *              // Encodes
  72  *              ByteBuffer* pBuffer = pEnc->GetBytesN(str);
  73  *
  74  *              int charCount;
  75  *              pEnc->GetCharCount(*pBuffer, charCount);
  76  *
  77  *              // Decodes
  78  *              String decodedStr;
  79  *              pEnc->GetString(*pBuffer, decodedStr);
  80  *
  81  *              if (str.Equals(decodedStr))
  82  *              {
  83  *                      //....
  84  *              }
  85  *
  86  *              delete pBuffer;
  87  *
  88  *              delete pEnc;
  89  *      }
  90  *  @endcode
  91  */
  92
  93 class AsciiEncoding;
  94 class Utf8Encoding;
  95 class Ucs2Encoding;
  96 class Latin1Encoding;
  97 class GsmEncoding;
  98
  99 class _OSP_EXPORT_ Encoding
 100         : public Tizen::Base::Object
 101 {
 102 public:
 103         /**
 104          * This is the destructor for this class. @n
 105          * This destructor overrides Tizen::Base::Object::~Object().
 106          *
 107          * @since       2.0
 108          */
 109         virtual ~Encoding(void);
 110
 111         /**
 112          * Gets the total number of bytes that are required to encode the specified string.
 113          *
 114          * @since                       2.0
 115          *
 116          * @return              An error code
 117          * @param[in]   str                      The string to encode
 118          * @param[out]  byteCount                The total number of bytes that are required to encode the specified string
 119          * @exception   E_SUCCESS                The method is successful.
 120          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 121          *                                                      - A specified input parameter is invalid.
 122          *                                                      - The specified @c str is an empty string.
 123          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 124          * @remarks     This method determines the total number of bytes
 125          *              that are generated when the specified string is encoded.
 126          * @see         GetMaxByteCount()
 127          */
 128         virtual result GetByteCount(const Tizen::Base::String& str, int& byteCount) const;
 129
 130         /**
 131          * Gets the total number of bytes that are required to encode the specified characters.
 132          *
 133          * @since                       2.0
 134          *
 135          * @return              An error code
 136          * @param[in]   chars                           An instance of Tizen::Base::WcharBuffer to encode
 137          * @param[out]  byteCount                       The total number of bytes required to encode the specified range of characters
 138          * @exception   E_SUCCESS                       The method is successful.
 139          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred:
 140          *                                                                                      - A specified input parameter is invalid.
 141          *                                                                                      - The specified @c chars is empty.
 142          * @exception   E_INVALID_ENCODING_RANGE    The specified string contains code points that are outside the bounds of the character encoding scheme.
 143          * @remarks     This method determines the total number of bytes
 144          *              that are generated when the specified array of characters are encoded.
 145          * @see         GetMaxByteCount()
 146          * @see         GetByteCount()
 147          */
 148         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int& byteCount) const;
 149
 150         /**
 151          * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance.
 152          *
 153          * @since                       2.0
 154          *
 155          * @return              An error code
 156          * @param[in]   chars                An instance of Tizen::Base::WcharBuffer to encode
 157          * @param[in]   charIndex            The index from where the encoding begins in the Tizen::Base::WcharBuffer instance
 158          * @param[in]   charCount            The total number of characters to encode
 159          * @param[out]  byteCount            The total number of bytes that are required to encode the specified range of characters
 160          * @exception   E_SUCCESS            The method is successful.
 161          * @exception   E_INVALID_ARG        Either of the following conditions has occurred:
 162          *                                                                       - A specified input parameter is invalid.
 163          *                                                                       - The specified @c chars is empty.
 164          * @exception   E_OUT_OF_RANGE           Either of the following conditions has occurred:
 165          *                                                                       - A specified input parameter is outside the valid range defined by the method.
 166          *                                                                       - The length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 167          * @exception   E_UNDERFLOW          Either of the following conditions has occurred:
 168          *                                                                       - This operation has caused the memory to underflow.
 169          *                                                                       - The sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 170          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 171          * @remarks     This method determines the total number of bytes
 172          *              that are generated when the specified array of characters are encoded.
 173          * @see                 GetMaxByteCount()
 174          * @see                 GetByteCount()
 175          */
 176         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
 177                 int& byteCount) const;
 178
 179         /**
 180          * Encodes an instance of specified Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
 181          *
 182          * @since                       2.0
 183          *
 184          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 185          *                              else @c null if an exception occurs @n
 186          *                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
 187          * @param[in]   chars                    An instance of Tizen::Base::WcharBuffer to encode
 188          * @exception   E_SUCCESS                The method is successful.
 189          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 190          * @exception   E_INVALID_ARG            The specified @c chars is invalid or empty.
 191          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 192          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 193          * @see                 GetCharsN()
 194          * @see                 GetBytesN()
 195          */
 196         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars) const = 0;
 197
 198         /**
 199          * Encodes the specified string of type Tizen::Base::String to Tizen::Base::ByteBuffer.
 200          *
 201          * @since                       2.0
 202          *
 203          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 204          *                              else @c null if an exception occurs @n
 205          *                              The buffer limit is the position of the last encoded byte plus one and the position is zero.
 206          * @param[in]   str                      The string to encode
 207          * @exception   E_SUCCESS                The method is successful.
 208          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 209          * @exception   E_INVALID_ARG            The specified @c str is invalid or is an empty string.
 210          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 211          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 212          * @see                 GetString()
 213          */
 214         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::String& str) const = 0;
 215
 216         /**
 217          * Encodes an instance of the specified Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
 218          * The position and limit of the %Tizen::Base::ByteBuffer instance is not changed.
 219          *
 220          * @since                       2.0
 221          *
 222          * @return              An error code
 223          * @param[in]   chars                                           The buffer that contains the character array to encode
 224          * @param[in]   charIndex                                       The index from where the encoding begins in the Tizen::Base::WcharBuffer instance
 225          * @param[in]   charCount                                       The total number of characters to encode
 226          * @param[out]  bytes                                           The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 227          * @param[in]   byteIndex                                       The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 228          * @exception   E_SUCCESS                                       The method is successful.
 229          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 230          * @exception   E_INVALID_ARG                           Either of the following conditions has occurred:
 231          *                                                                                      - A specified input parameter is invalid.
 232          *                                                                                      - The specified @c chars or @c bytes is empty.
 233          * @exception   E_OUT_OF_RANGE                          Either of the following conditions has occurred:
 234          *                                                                                      - A specified input paramter is outside the valid range defined by the method.
 235          *                                                                                      - The length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 236          * @exception   E_UNDERFLOW                                     Either of the following conditions has occurred:
 237          *                                                                                      - This operation has caused the memory to underflow.
 238          *                                                                                      - The sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 239          * @exception   E_OVERFLOW                                      Either of the following conditions has occurred:
 240          *                                                                                      - This operation has caused the memory to overflow.
 241          *                                                                                      - The specified @c bytes does not contain sufficient space to store the encoded characters.
 242          * @exception   E_INVALID_ENCODING_RANGE        The specified string contains code points that are outside the bounds of the character encoding scheme.
 243          * @remarks             This method encodes a range of characters in Tizen::Base::WcharBuffer into a range of bytes in Tizen::Base::ByteBuffer.
 244          * @see                 GetChars()
 245          */
 246         virtual result GetBytes(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
 247                 Tizen::Base::ByteBuffer& bytes, int byteIndex) const = 0;
 248
 249         /**
 250          * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
 251          * The position and limit of the %Tizen::Base::ByteBuffer instance is not changed.
 252          *
 253          * @since                       2.0
 254          *
 255          * @return              An error code
 256          * @param[in]   str                      The string to encode
 257          * @param[in]   charIndex                The index from where the encoding begins in the Tizen::Base::WcharBuffer instance
 258          * @param[in]   charCount                The total number of characters to encode
 259          * @param[out]  bytes                    The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 260          * @param[in]   byteIndex                The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 261          * @exception   E_SUCCESS                The method is successful.
 262          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 263          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 264          *                                                                               - A specified input parameter is invalid.
 265          *                                                                               - The specified @c str or @c bytes is empty.
 266          * @exception   E_OUT_OF_RANGE                   Either of the following conditions has occurred:
 267          *                                                                               - A specified input parameter is outside the valid range defined by the method.
 268          *                                                                               - The length of the specified @c charIndex or @c charCount is greater than the length of the specified @c str.
 269          * @exception   E_UNDERFLOW              Either of the following conditions has occurred:
 270          *                                                                               - This operation has caused the memory to underflow.
 271          *                                                                               - The sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c str.
 272          * @exception   E_OVERFLOW               Either of the following conditions has occurred:
 273          *                                                                               - This operation has caused the memory to overflow.
 274          *                                                                               - The specified @c bytes does not contain sufficient space to store the encoded characters.
 275          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 276          * @see                 GetString()
 277          */
 278         virtual result GetBytes(const Tizen::Base::String& str, int charIndex, int charCount,
 279                 Tizen::Base::ByteBuffer& bytes, int byteIndex) const = 0;
 280
 281         /**
 282          * Gets the total number of characters that are generated by decoding an instance of Tizen::Base::ByteBuffer.
 283          *
 284          * @since                       2.0
 285          *
 286          * @return              An error code
 287          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 288          * @param[out]  charCount                The total number of characters that are generated by decoding a range of bytes in the specified Tizen::Base::ByteBuffer instance
 289          * @exception   E_SUCCESS                The method is successful.
 290          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 291          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 292          *                                                                               - A specified input parameter is invalid.
 293          *                                                                               - The specified @c bytes is empty.
 294          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 295          * @remarks     This method determines the total number of characters
 296          *              that are generated when the specified range of bytes are encoded.
 297          * @see                 GetMaxCharCount()
 298          * @see                 GetCharCount()
 299          */
 300         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int& charCount) const;
 301
 302         /**
 303          * Gets the total number of characters that are generated by decoding a range of elements specified in the Tizen::Base::ByteBuffer instance.
 304          *
 305          * @since                       2.0
 306          *
 307          * @return              An error code
 308          * @param[in]   bytes                 An instance of Tizen::Base::ByteBuffer to decode
 309          * @param[in]   byteIndex             The index from where the decoding begins
 310          * @param[in]   byteCount             The total number of bytes to decode
 311          * @param[out]  charCount             The total number of characters that are generated by decoding a range of bytes in the specified Tizen::Base::ByteBuffer instance
 312          * @exception   E_SUCCESS             The method is successful.
 313          * @exception   E_OUT_OF_MEMORY       The memory is insufficient.
 314          * @exception   E_INVALID_ARG         Either of the following conditions has occurred:
 315          *                                                                        - A specified input parameter is invalid.
 316          *                                                                        - The specified @c bytes is empty.
 317          * @exception   E_OUT_OF_RANGE        Either of the following conditions has occurred:
 318          *                                                                        - A specified input parameter is outside the valid range defined by the method.
 319          *                                                                        - The length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
 320          * @exception   E_UNDERFLOW           Either of the following conditions has occurred:
 321          *                                                                        - This operation has caused the memory to underflow.
 322          *                                                                        - The sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
 323          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 324          * @remarks     This method determines the total number of characters
 325          *              that are generated when the specified range of bytes are encoded.
 326          * @see                 GetMaxCharCount()
 327          * @see                 GetCharCount()
 328          */
 329         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, int& charCount) const;
 330
 331         /**
 332          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
 333          *
 334          * @since                       2.0
 335          *
 336          * @return              A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
 337          *                              else @c null if an exception occurs @n
 338          *                              The buffer limit is the position of the last decoded byte plus one and the starting position is zero.
 339          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 340          * @exception   E_SUCCESS                The method is successful.
 341          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 342          * @exception   E_INVALID_ARG            The specified @c bytes is invalid or empty.
 343          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 344          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 345          * @see                 GetBytesN()
 346          */
 347         virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const = 0;
 348
 349         /**
 350          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range. @n
 351          * The position and limit of the %Tizen::Base::WcharBuffer instance is not changed.
 352          *
 353          * @since                       2.0
 354          *
 355          * @return              An error code
 356          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 357          * @param[in]   byteIndex                The index from where the decoding begins
 358          * @param[in]   byteCount                The total number of bytes to decode
 359          * @param[out]  chars                    The Tizen::Base::WcharBuffer instance where the resultant decoded data is stored
 360          * @param[in]   charIndex                The index from where the encoding begins in the Tizen::Base::WcharBuffer instance
 361          * @exception   E_SUCCESS                The method is successful.
 362          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 363          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 364          *                                                                               - A specified input parameter is invalid.
 365          *                                                                               - The specified @c bytes is empty.
 366          * @exception   E_OUT_OF_RANGE           Either of the following conditions has occurred:
 367          *                                                                               - A specified input parameter is outside the valid range defined by the method.
 368          *                                                                               - The length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
 369          * @exception   E_UNDERFLOW                  Either of the following conditions has occurred:
 370          *                                                                               - This operation has caused the memory to underflow.
 371          *                                                                               - The sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
 372          * @exception   E_OVERFLOW                   Either of the following conditions has occurred:
 373          *                                                                               - This operation has caused the memory to overflow.
 374          *                                                                               - The specified @c chars does not contain sufficient space to store the decoded bytes.
 375          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 376          * @see                 GetBytes()
 377          */
 378         virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
 379                 Tizen::Base::WcharBuffer& chars, int charIndex) const = 0;
 380
 381         /**
 382          * Gets a string that contains the decoded representation of a range of bytes in the specified Tizen::Base::ByteBuffer instance.
 383          *
 384          * @since                       2.0
 385          *
 386          * @return              An error code
 387          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 388          * @param[out]  str                      A Tizen::Base::String instance @n
 389          *                                       It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 390          * @exception   E_SUCCESS                The method is successful.
 391          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 392          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 393          *                                                                               - A specified input parameter is invalid.
 394          *                                                                               - The specified @c bytes is empty.
 395          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 396          *
 397          * @see                 GetBytesN()
 398          * @see                 GetString()
 399          */
 400         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const = 0;
 401
 402         /**
 403          * Gets a string that contains the decoded representation of a range of bytes in the specified Tizen::Base::ByteBuffer instance.
 404          *
 405          * @since                       2.0
 406          *
 407          * @return              An error code
 408          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 409          * @param[in]   index                    The index from where the decoding begins
 410          * @param[in]   count                    The total number of bytes to decode
 411          * @param[out]  str                      A Tizen::Base::String instance @n
 412          *                                       It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 413          * @exception   E_SUCCESS                The method is successful.
 414          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 415          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 416          *                                                                               - A specified input parameter is invalid.
 417          *                                                                               - The specified @c bytes is empty.
 418          * @exception   E_OUT_OF_RANGE           Either of the following conditions has occurred:
 419          *                                                                               - A specified input parameter is outside the valid range defined by the method.
 420          *                                                                               - The sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
 421          * @exception   E_UNDERFLOW                              Either of the following conditions has occurred:
 422          *                                                                               - This operation has caused the memory to underflow.
 423          *                                                                               - The sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
 424          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 425          * @see                 GetBytes()
 426          * @see                 GetString()
 427          */
 428         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const = 0;
 429
 430         /**
 431          * Gets the maximum number of bytes that are required to encode the specified number of characters.
 432          *
 433          * @since                       2.0
 434          *
 435          * @return              The maximum number of bytes that are required to encode the specified number of characters
 436          * @param[in]   charCount     The total number of characters to encode
 437          * @remarks     This method determines an appropriate buffer size for the byte arrays passed to GetBytes() for encoding.
 438          * @see                 GetByteCount()
 439          */
 440         virtual int GetMaxByteCount(int charCount) const = 0;
 441
 442         /**
 443          * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
 444          *
 445          * @since               2.0
 446          *
 447          * @return              The maximum number of characters that are generated by decoding the specified number of bytes
 448          * @param[in]   byteCount The total number of bytes to encode
 449          * @remarks      This method determines an appropriate buffer size for character arrays passed to
 450          *                  GetChars() or a decoder for encoding.
 451          * @see                 GetCharCount()
 452          */
 453         virtual int GetMaxCharCount(int byteCount) const = 0;
 454
 455         /**
 456          * Gets the encoder for the current encoding.
 457          *
 458          * @since                       2.0
 459          *
 460          * @return              A pointer to the Encoder instance for the current encoding
 461          * @remarks
 462          *                              - Contrary to GetBytes(), an encoder can convert partial sequences of characters into
 463          *                              partial sequences of bytes by maintaining an appropriate state between the conversions.
 464          *                              - Currently, only UTF-8 encoding supports this method. The other classes return a @c null value.
 465          */
 466         virtual Encoder* GetEncoderN(void) const = 0;
 467
 468         /**
 469          * Gets the decoder for the current encoding.
 470          *
 471          * @since                       2.0
 472          *
 473          * @return              A pointer to the Decoder instance for the current encoding
 474          * @remarks
 475          *                              - Contrary to GetChars(), a decoder can convert partial sequences of bytes
 476          *                              into partial sequences of characters by maintaining an appropriate state between the conversions.
 477          *                              - Currently, only UTF-8 encoding supports this method. The other classes return a @c null value.
 478          */
 479         virtual Decoder* GetDecoderN(void) const = 0;
 480
 481         /**
 482          * Gets the encoding type of the current instance.
 483          *
 484          * @since                       2.0
 485          *
 486          * @return              The encoding type
 487          */
 488         virtual Tizen::Base::String GetEncodingType(void) const = 0;
 489
 490         /**
 491         * Gets the encoding for the UTF-8 format.
 492         *
 493         * @since                        2.0
 494         *
 495         * @return               The encoding for the UTF-8 format
 496         *
 497         */
 498         static Utf8Encoding& GetUtf8Encoding(void);
 499
 500         /**
 501         * Gets the encoding for the UCS-2 format.
 502         *
 503         * @since                        2.0
 504         *
 505         * @return               The encoding for the UCS-2 format
 506         -*
 507         */
 508         static Ucs2Encoding& GetUcs2Encoding(void);
 509
 510         /**
 511         * Gets the encoding for the GSM format.
 512         *
 513         * @since                        2.0
 514         *
 515         * @return               The encoding for the GSM format
 516         *
 517         */
 518         static GsmEncoding& GetGsmEncoding(void);
 519
 520         /**
 521         * Gets the encoding for the Latin1 format.
 522         *
 523         * @since                        2.0
 524         *
 525         * @return               The encoding for the Latin1 format
 526         *
 527         */
 528         static Latin1Encoding& GetLatin1Encoding(void);
 529
 530         /**
 531         * Gets the encoding for the ASCII format.
 532         *
 533         * @since                        2.0
 534         *
 535         * @return               The encoding for the ASCII format
 536         *
 537         */
 538         static AsciiEncoding& GetAsciiEncoding(void);
 539
 540         /**
 541          * Gets an %Encoding instance from the specified encoding type.
 542          *
 543          * @since                       2.0
 544          *
 545          * @return      An instance of %Encoding, @n
 546          *              else @c null if it fails
 547          * @param[in]   encodingType                    The encoding type
 548          * @exception   E_SUCCESS                               The method is successful.
 549          * @exception   E_UNSUPPORTED_TYPE      The specified encoding type is not supported.
 550          * @remarks
 551          *                              - The specific error code can be accessed using the GetLastResult() method.
 552          *                              - The supported encoding types are ASCII, GSM, UCS-2, UCS-2LE, UCS-2BE, UCS-4, UCS-4LE, UCS-4BE, UTF-8, UTF-16, UTF-16LE, UTF-16BE, @n
 553          *                              UTF-32, UTF-32LE, UTF-32BE, ISO-8859-1~16 (except ISO-8859-12), Windows-874, Windows-1250 ~ Windows-1258, @n
 554          *                              KSC5601, BIG5, GB2312, Shift-JIS and ISO-2022-JP. @n
 555          *                              For more information on the supported encoding types, see
 556          *                              <a href="../org.tizen.native.appprogramming/html/guide/text/text.htm">Encoding standards in %Tizen</a>.
 557          * @see                 Tizen::Text::Encoding::GetAvailableEncodingsN()
 558          */
 559         static Encoding* GetEncodingN(const Tizen::Base::String& encodingType);
 560
 561         /**
 562         * Gets the encoding type of the specified %Encoding instance.
 563         *
 564         * @since                        2.0
 565         *
 566         * @return               The encoding type
 567         * @param[in] encoding An instance of %Encoding
 568         */
 569         static Tizen::Base::String GetEncodingType(const Encoding& encoding);
 570
 571         /**
 572          * Gets a list of all the available encodings.
 573          *
 574          * @since                       2.0
 575          *
 576          * @return              The list of Tizen::Base::String instances (ASCII, UTF-8, ISO-8859-1, ISO-8859-2, Windows-1254, and so on), @n
 577          *              else @c null if it fails
 578          * @exception   E_SUCCESS                               The method is successful.
 579          * @exception   E_SYSTEM                                A system error has occurred.
 580          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 581          */
 582         static Tizen::Base::Collection::IList* GetAvailableEncodingsN(void);
 583
 584         /**
 585          * Converts an instance of Tizen::Base::ByteBuffer from one encoding format to another.
 586          *
 587          * @since                       2.0
 588          *
 589          * @return              The new buffer for storing the result of the conversion, @n
 590          *                              else @c null if an exception occurs @n
 591          *                              The buffer limit is the position of the last converted byte plus one and the starting position is zero.
 592          * @param[in]   src                      The source of the encoding
 593          * @param[in]   dst                      The destination of the encoding
 594          * @param[in]   srcBytes                 The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 595          * @exception   E_SUCCESS                The method is successful.
 596          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 597          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 598          *                                                                               - A specified input parameter is invalid.
 599          *                                                                               - The specified @c srcBytes is empty.
 600          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 601          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 602          * @see                 GetBytes()
 603          * @see                 GetChars()
 604          */
 605         static Tizen::Base::ByteBuffer* ConvertN(const Encoding& src, const Encoding& dst,
 606                 const Tizen::Base::ByteBuffer& srcBytes);
 607
 608         /**
 609          * Converts a range of bytes in the Tizen::Base::ByteBuffer instance from one encoding format to another.
 610          *
 611          * @since                       2.0
 612          *
 613          * @return              A new buffer for storing result of the conversion, @n
 614          *                              else @c null if an exception occurs @n
 615          *                              The buffer limit is the position of the last converted byte plus one and the starting position is zero.
 616          * @param[in]   src                      The source of the encoding
 617          * @param[in]   dst                      The destination of the encoding
 618          * @param[in]   srcBytes                 The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 619          * @param[in]   index                    The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 620          * @param[in]   count                    The total number of bytes to convert
 621          * @exception   E_SUCCESS                The method is successful.
 622          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 623          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 624          *                                                                               - A specified input parameter is invalid.
 625          *                                                                               - The specified @c srcBytes is empty.
 626          * @exception   E_OUT_OF_RANGE           Either of the following conditions has occurred:
 627          *                                                                               - A specified input parameter is outside the valid range defined by the method.
 628          *                                                                               - The specified @c index or @c count is greater than the length of the specified @c srcBytes.
 629          * @exception   E_UNDERFLOW              Either of the following conditions has occurred:
 630          *                                                                               - This operation has caused the memory to underflow.
 631          *                                                                               - The sum of the length of the specified @c index and @c count is greater than the length of the specified @c srcBytes.
 632          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 633          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 634          * @see                 GetBytes()
 635          * @see                 GetChars()
 636          */
 637         static Tizen::Base::ByteBuffer* ConvertN(const Encoding& src, const Encoding& dst, const Tizen::Base::ByteBuffer& srcBytes,
 638                 int index, int count);
 639
 640 protected:
 641         Encoding(void);
 642
 643         //
 644         // This method is for internal use only. Using this method can cause behavioral, security-related,
 645         // and consistency-related issues in the application.
 646         //
 647         // This method is reserved and may change its name at any time without prior notice.
 648         //
 649         // @since       2.0
 650         //
 651         virtual void Encoding_Reserved1(void) { }
 652
 653         //
 654         // This method is for internal use only. Using this method can cause behavioral, security-related,
 655         // and consistency-related issues in the application.
 656         //
 657         // This method is reserved and may change its name at any time without prior notice.
 658         //
 659         // @since       2.0
 660         //
 661         virtual void Encoding_Reserved2(void) { }
 662
 663         //
 664         // This method is for internal use only. Using this method can cause behavioral, security-related,
 665         // and consistency-related issues in the application.
 666         //
 667         // This method is reserved and may change its name at any time without prior notice.
 668         //
 669         // @since       2.0
 670         //
 671         virtual void Encoding_Reserved3(void) { }
 672
 673         //
 674         // This method is for internal use only. Using this method can cause behavioral, security-related,
 675         // and consistency-related issues in the application.
 676         //
 677         // This method is reserved and may change its name at any time without prior notice.
 678         //
 679         // @since       2.0
 680         //
 681         virtual void Encoding_Reserved4(void) { }
 682
 683         //
 684         // This method is for internal use only. Using this method can cause behavioral, security-related,
 685         // and consistency-related issues in the application.
 686         //
 687         // This method is reserved and may change its name at any time without prior notice.
 688         //
 689         // @since       2.0
 690         //
 691         virtual void Encoding_Reserved5(void) { }
 692
 693         friend class _EncodingImpl;
 694         class _EncodingImpl* _pEncodingImpl;
 695
 696 private:
 697         /**
 698          * The implementation of this copy constructor is intentionally blank and declared as private to
 699          * prohibit copying of objects.
 700          */
 701         Encoding(const Encoding& encoding);
 702
 703         /**
 704          * The implementation of this copy assignment operator is intentionally blank and declared as private
 705          * to prohibit copying of objects.
 706          */
 707         Encoding& operator =(const Encoding& encoding);
 708
 709 }; // Encoding
 710
 711 } } // Tizen::Text
 712
 713 #endif //_FTEXT_ENCODING_H_