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