inc/FTextLatin1Encoding.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                FTextLatin1Encoding.h
  19  * @brief               This is the header file for the %Latin1Encoding class.
  20  *
  21  * This header file contains the declarations of the %Latin1Encoding class.
  22  * This class is derived from the Encoding class.
  23  */
  24 #ifndef _FTEXT_LATIN1_ENCODING_H_
  25 #define _FTEXT_LATIN1_ENCODING_H_
  26
  27 #include <FTextEncoding.h>
  28
  29
  30 namespace Tizen { namespace Text
  31 {
  32 /**
  33  * @class       Latin1Encoding
  34  * @brief       This class is an implementation of the Latin1 encoding.
  35  *
  36  * @since       2.0
  37  *
  38  * @final       This class is not intended for extension.
  39  *
  40  * The %Latin1Encoding class is an implementation of the Latin1 encoding.
  41  * ISO Latin-1 is a superset of the American Standard Code for Information Interchange(ASCII) character set and is very similar to the American National Standards Institute (ANSI) character set used in Windows,
  42  * though the two are not identical.
  43  * Latin1 also serves as the basis for the ANSI character set of MS Windows.
  44  * Only the characters in ISO Latin-1 are guaranteed to be supported on an Internet website.
  45  * When a %Web browser, such as Internet Explorer or Firefox formats a Web page on a client system, such as
  46  * Windows, it maps the ISO Latin-1 characters to the default character set in the best possible way.
  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  *  The following example demonstrates how to use the %Latin1Encoding class.
  51  *
  52  *  @code
  53  *      #include <FBase.h>
  54  *      #include <FText.h>
  55  *
  56  *      using namespace Tizen::Base;
  57  *      using namespace Tizen::Text;
  58  *
  59  *      void
  60  *      MyClass::Latin1EncodingSample(void)
  61  *      {
  62  *              Latin1Encoding latin1;
  63  *
  64  *              String str(L"Latin1Test \u00A1\u00A2");
  65  *
  66  *              int byteCount;
  67  *              latin1.GetByteCount(str, byteCount);
  68  *
  69  *              // Encodes
  70  *              ByteBuffer* pBuffer = latin1.GetBytesN(str);
  71  *
  72  *              int charCount;
  73  *              latin1.GetCharCount(*pBuffer, charCount);
  74  *
  75  *              // Decodes
  76  *              String decodedStr;
  77  *              latin1.GetString(*pBuffer, decodedStr);
  78  *
  79  *              if (str.Equals(decodedStr))
  80  *              {
  81  *                      //....
  82  *              }
  83  *
  84  *              delete pBuffer;
  85  *      }
  86  *  @endcode
  87  */
  88
  89 class _OSP_EXPORT_ Latin1Encoding
  90         : public Encoding
  91 {
  92 public:
  93         /**
  94          * This is the default constructor for this class.
  95          *
  96          * @since       2.0
  97          */
  98         Latin1Encoding(void);
  99
 100         /**
 101          * This is the destructor for this class. @n
 102          * This destructor overrides Tizen::Text::Encoding::~Encoding().
 103          *
 104          * @since       2.0
 105          */
 106         virtual ~Latin1Encoding(void);
 107
 108         /**
 109          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
 110          *
 111          * @since                       2.0
 112          *
 113          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 114          *              else @c null if an exception occurs @n
 115          *                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
 116          * @param[in]   chars                    An instance of Tizen::Base::WcharBuffer to encode
 117          * @exception   E_SUCCESS                The method is successful.
 118          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 119          * @exception   E_INVALID_ARG            The specified @c chars is empty or invalid.
 120          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 121          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 122          * @see                 GetCharsN()
 123          */
 124         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars) const;
 125
 126         /**
 127          * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer.
 128          *
 129          * @since                       2.0
 130          *
 131          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 132          *              else @c null if an exception occurs @n
 133          *                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
 134          * @param[in]   str                      The string to encode
 135          * @exception   E_SUCCESS                The method is successful.
 136          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 137          * @exception   E_INVALID_ARG            The specified @c str is empty or invalid.
 138          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 139          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 140          * @see                 GetString()
 141          */
 142         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::String& str) const;
 143
 144         /**
 145          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
 146          * The position and limit of the pointer to the %Tizen::Base::ByteBuffer instance is not changed.
 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 the encoding begins in the Tizen::Base::WcharBuffer instance
 153          * @param[in]   charCount                 The total number of characters to encode
 154          * @param[out]  bytes                     The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 155          * @param[in]   byteIndex                 The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 156          * @exception   E_SUCCESS                 The method is successful.
 157          * @exception   E_OUT_OF_MEMORY           The memory is insufficient.
 158          * @exception   E_INVALID_ARG             Either of the following conditions has occurred:
 159          *                                                               - A specified input parameter is invalid.
 160          *                                                               - The specified @c chars or @c bytes is empty.
 161          * @exception   E_OUT_OF_RANGE            Either of the following conditions has occurred:
 162          *                                                               - A specified input parameter is outside the valid range defined by the method.
 163          *                                                               - The length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 164          * @exception   E_UNDERFLOW                   Either of the following conditions has occurred:
 165          *                                                               - This operation has caused the memory to underflow.
 166          *                                                               - The sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 167          * @exception   E_OVERFLOW                Either of the following conditions has occurred:
 168          *                                                               - This operation has caused the memory to overflow.
 169          *                                                               - The specified @c bytes does not contain sufficient space to store the encoded characters.
 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 encodes a range of characters in Tizen::Base::WcharBuffer into a range of bytes in Tizen::Base::ByteBuffer.
 172          * @see                 GetChars()
 173          */
 174         virtual result GetBytes(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
 175                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
 176
 177         /**
 178          * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
 179          * The position and limit of the pointer to the %Tizen::Base::ByteBuffer instance is not changed.
 180          *
 181          * @since                       2.0
 182          *
 183          * @return              An error code
 184          * @param[in]   str                      The string to encode
 185          * @param[in]   charIndex                The index from where the encoding begins in the Tizen::Base::WcharBuffer instance
 186          * @param[in]   charCount                The total number of characters to encode
 187          * @param[out]  bytes                    The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 188          * @param[in]   byteIndex                The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 189          * @exception   E_SUCCESS                The method is successful.
 190          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 191          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 192          *                                                               - A specified input parameter is invalid.
 193          *                                                               - The specified @c str or @c bytes is empty.
 194          * @exception   E_OUT_OF_RANGE               Either of the following conditions has occurred:
 195          *                                                               - A specified input parmater is outside the valid range defined by the method.
 196          *                                                               - The length of the specified @c charIndex or @c charCount is greater than the length of the specified @c str.
 197          * @exception   E_UNDERFLOW              Either of the following conditions has occurred:
 198          *                                                               - This operation has caused the memory to underflow.
 199          *                                                               - The sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c str.
 200          * @exception   E_OVERFLOW               Either of the following conditions has occurred:
 201          *                                                               - This operation has caused the memory to overflow.
 202          *                                                               - The specified @c bytes does not contain sufficient space to store the encoded characters.
 203          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 204          * @see                 GetString()
 205          */
 206         virtual result GetBytes(const Tizen::Base::String& str, int charIndex, int charCount,
 207                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
 208
 209         /**
 210          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
 211          *
 212          * @since                       2.0
 213          *
 214          * @return              A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
 215          *              else @c null if an exception occurs @n
 216          *                              The buffer limit is the position of the last decoded byte plus one and the starting position is zero.
 217          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 218          * @exception   E_SUCCESS                The method is successful.
 219          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 220          * @exception   E_INVALID_ARG            The specified @c bytes is empty.
 221          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 222          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 223          * @see                 GetBytesN()
 224          */
 225         virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const;
 226
 227         /**
 228          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range. @n
 229          * The position and limit of the pointer to the %Tizen::Base::WcharBuffer instance is not changed.
 230          *
 231          * @since                       2.0
 232          *
 233          * @return              An error code
 234          * @param[in]   bytes                       An instance of Tizen::Base::ByteBuffer to decode
 235          * @param[in]   byteIndex                   The index from where the decoding begins
 236          * @param[in]   byteCount                   The total number of bytes to decode
 237          * @param[out]  chars                       The Tizen::Base::WcharBuffer instance where the resultant decoded data is stored
 238          * @param[in]   charIndex                   The index from where the encoding begins in the Tizen::Base::WcharBuffer instance
 239          * @exception   E_SUCCESS                   The method is successful.
 240          * @exception   E_OUT_OF_MEMORY             The memory is insufficient.
 241          * @exception   E_INVALID_ARG               Either of the following conditions has occurred:
 242          *                                                               - A specified input parameter is invalid.
 243          *                                                               - The specified @c bytes or @c chars is empty.
 244          * @exception   E_OUT_OF_RANGE              Either of the following conditions has occurred:
 245          *                                                               - A specified input parameter is outside the valid range defined by the method.
 246          *                                                               - The length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
 247          * @exception   E_UNDERFLOW                     Either of the following conditions has occurred:
 248          *                                                               - This operation has caused the memory to underflow.
 249          *                                                               - The sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
 250          * @exception   E_OVERFLOW                      Either of the following conditions has occurred:
 251          *                                                               - This operation has caused the memory to overflow.
 252          *                                                               - The specified @c chars does not contain sufficient space to store the decoded bytes.
 253          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 254          * @see                 GetBytes()
 255          */
 256         virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
 257                 Tizen::Base::WcharBuffer& chars, int charIndex = 0) const;
 258
 259         /**
 260          * Gets a string that contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 261          *
 262          * @since                       2.0
 263          *
 264          * @return              An error code
 265          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 266          * @param[out]  str                      A Tizen::Base::String instance @n
 267          *                                       It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 268          * @exception   E_SUCCESS                The method is successful.
 269          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 270          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 271          *                                                               - A specified input parameter is invalid.
 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                 GetBytesN()
 275          */
 276         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const;
 277
 278         /**
 279          * Gets a string that contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 280          *
 281          * @since                       2.0
 282          *
 283          * @return              An error code
 284          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 285          * @param[in]   index                    The index from where the decoding begins
 286          * @param[in]   count                    The total number of bytes to decode
 287          * @param[out]  str                      A Tizen::Base::String instance @n
 288          *                                       It contains the decoded representation of 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_OUT_OF_RANGE           Either of the following conditions has occurred:
 295          *                                                               - A specified input parameter is outside the valid range defined by the method.
 296          *                                                               - The sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
 297          * @exception   E_UNDERFLOW                              Either of the following conditions has occurred:
 298          *                                                               - This operation has caused the memory to underflow.
 299          *                                                               - The sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
 300          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 301          * @see                 GetBytes()
 302          */
 303         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const;
 304
 305
 306         /**
 307          * Gets the maximum number of bytes required for encoding a given number of characters.
 308          *
 309          * @since                       2.0
 310          *
 311          * @return              The maximum number of bytes required for encoding the given number of characters
 312          * @param[in]   charCount The total number of characters to encode
 313          * @remarks     This method determines an appropriate buffer size for the byte arrays passed to GetBytes() for encoding.
 314          * @see         Encoding::GetByteCount()
 315          */
 316         virtual int GetMaxByteCount(int charCount) const;
 317
 318
 319         /**
 320          * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
 321          *
 322          * @since                       2.0
 323          *
 324          * @return              The maximum number of characters generated by decoding the specified number of bytes
 325          * @param[in]   byteCount The total number of bytes to encode
 326          * @remarks     This method determines an appropriate buffer size for character arrays passed to
 327          *                  GetChars() or a decoder for encoding.
 328          * @see         Encoding::GetByteCount()
 329          */
 330         virtual int GetMaxCharCount(int byteCount) const;
 331
 332
 333         /**
 334          * Gets the encoder for the current encoding.
 335          *
 336          * @since                               2.0
 337          *
 338          * @return              A pointer to the Encoder instance for the current encoding
 339          * @remarks
 340          *                              - Contrary to GetBytes(), an encoder can convert partial sequences of characters into
 341          *                              partial sequences of bytes by maintaining the appropriate state between the conversions.
 342          *                              - Currently only Utf8Encoding supports this method. Other classes return @c null.
 343          */
 344         virtual Encoder* GetEncoderN(void) const;
 345
 346         /**
 347          * Gets the decoder for the current encoding.
 348          *
 349          * @since                               2.0
 350          *
 351          * @return              A pointer to the Decoder instance for the current encoding
 352          * @remarks
 353          *                              - Contrary to GetChars(), a decoder can convert partial sequences of bytes
 354          *                              into partial sequences of characters by maintaining the appropriate state between the conversions.
 355          *                              - Currently only Utf8Encoding supports this method. Other classes return @c null.
 356          */
 357         virtual Decoder* GetDecoderN(void) const;
 358
 359         /**
 360         * Gets the encoding type of the current instance.
 361         *
 362         * @since                        2.0
 363         *
 364         * @return               The encoding type
 365         */
 366         virtual Tizen::Base::String GetEncodingType(void) const;
 367
 368 private:
 369         /**
 370          * The implementation of this copy constructor is intentionally blank and declared as private to
 371          * prohibit copying of objects.
 372          */
 373         Latin1Encoding(const Latin1Encoding& latin1Encoding);
 374
 375         /**
 376          * The implementation of this copy assignment operator is intentionally blank and declared as private
 377          * to prohibit copying of objects.
 378          */
 379         Latin1Encoding& operator =(const Latin1Encoding& latin1Encoding);
 380
 381         friend class _Latin1EncodingImpl;
 382         class _Latin1EncodingImpl* __pLatin1EncodingImpl;
 383 };
 384
 385 } } // Tizen::Text
 386 #endif //_FTEXT_LATIN1_ENCODING_H_