inc/FTextUtf8Encoder.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                FTextUtf8Encoder.h
  19  * @brief               This is the header file for the %Utf8Encoder class.
  20  *
  21  * This header file contains the declarations of the %Utf8Encoder class.
  22  *
  23  */
  24 #ifndef _FTEXT_UTF8_ENCODER_H_
  25 #define _FTEXT_UTF8_ENCODER_H_
  26
  27 #include <FTextEncoder.h>
  28 #include <FBaseByteBuffer.h>
  29
  30
  31 namespace Tizen { namespace Text
  32 {
  33
  34 /**
  35  * @class       Utf8Encoder
  36  * @brief       This class is an implementation of the UTF-8 encoder.
  37  *
  38  * @since       2.0
  39  *
  40  * @final       This class is not intended for extension.
  41  *
  42  * The %Utf8Encoder class converts the blocks of characters into encoded blocks of bytes.
  43  * Universal Transformation Format-8 (UTF-8) is a translated language that is used on the internet. It converts the
  44  * Unicode into 8-bit bytes. @n UTF-8 encoding supports all Unicode character values and surrogates.
  45  * Note that %Utf8Encoder is not used in reality, because keeping the internal state of encoding from Unicode
  46  * to UTF-8 can be avoided if the translation unit is even.
  47  * This means that the real implementation of %Utf8Encoder is the same as that of Utf8Encoding in this state.
  48  *
  49  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/text/converting_text_data_separate_blocks.htm">Converting Text Data in Separate Blocks</a>.
  50  *
  51  * The following example demonstrates how to use the %Utf8Encoder class.
  52  *
  53  * @code
  54  *      #include <FBase.h>
  55  *      #include <FText.h>
  56  *
  57  *      using namespace Tizen::Base;
  58  *      using namespace Tizen::Text;
  59  *
  60  *      void
  61  *      MyClass::Utf8EncoderSample(void)
  62  *      {
  63  *              Utf8Encoder utf8En;
  64  *
  65  *              // Fills a WcharBuffer with the unicode strings to encode it into UTF8 format bytes.
  66  *              WcharBuffer* pMB = PrepareUtf8EncoderSample();
  67  *
  68  *              int charBufSize = pMB->GetCapacity();
  69  *
  70  *              int byteCount = 0;
  71  *              utf8En.GetByteCount(*pMB, 0, charBufSize, byteCount);
  72  *
  73  *              ByteBuffer enBytes;
  74  *              enBytes.Construct(byteCount);
  75  *
  76  *              int charIndex = 0;
  77  *              int charCount = 100;
  78  *
  79  *              while (charIndex < charBufSize)
  80  *              {
  81  *                      ByteBuffer* pBB = null;
  82  *
  83  *                      if (charBufSize - charIndex < charCount)
  84  *                      {
  85  *                              charCount = charBufSize - charIndex;
  86  *                      }
  87  *
  88  *                      // Converts Unicode to Utf8 using Utf8Encoder.
  89  *                      pBB = utf8En.GetBytesN(*pMB, charIndex, charCount); // flush is false
  90  *
  91  *                      enBytes.CopyFrom(*pBB);
  92  *                      charIndex += charCount;
  93  *
  94  *                      delete pBB;
  95  *              }
  96  *
  97  *              enBytes.SetByte('\0');
  98  *              enBytes.Rewind();
  99  *
 100  *              delete pMB;
 101  *      }
 102  * @endcode
 103  */
 104
 105
 106 class _OSP_EXPORT_ Utf8Encoder
 107         : public Encoder
 108 {
 109 public:
 110         /**
 111          * This is the default constructor for this class.
 112          *
 113          * @since       2.0
 114          *
 115          */
 116         Utf8Encoder(void);
 117
 118         /**
 119          * This is the destructor for this class. @n
 120          * This destructor overrides Tizen::Text::Encoder::~Encoder().
 121          *
 122          * @since       2.0
 123          */
 124         virtual ~Utf8Encoder(void);
 125
 126         /**
 127          * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance.
 128          *
 129          * @since                       2.0
 130          *
 131          * @return              An error code
 132          * @param[in]   chars                    An instance of Tizen::Base::WcharBuffer to encode
 133          * @param[in]   charIndex                The index from where the encoding begins in the Tizen::Base::WcharBuffer instance
 134          * @param[in]   charCount                The total number of characters to encode
 135          * @param[in]   flush                    Set to @c true to allow this instance to flush its state at the end of the conversion, @n
 136          *                                                               else @c false
 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, or
 141          *                                                              - The specified @c chars is empty.
 142          * @exception   E_OUT_OF_RANGE                   Either of the following conditions has occurred:
 143          *                                                              - A specified input parameter is outside the valid range defined by the method.
 144          *                                                              - The length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 145          * @exception   E_UNDERFLOW              Either of the following conditions has occurred:
 146          *                                                              - This operation has caused the memory to underflow.
 147          *                                                              - The sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 148          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 149          * @see                 Utf8Decoder::GetCharCount()
 150          */
 151         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars,
 152                 int charIndex, int charCount, int& byteCount, bool flush = false) const;
 153
 154         /**
 155          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
 156          *
 157          * @since                       2.0
 158          *
 159          * @return                                               A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 160          *                                               else @c null if an exception occurs @n
 161          *                                                                       The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
 162          * @param[in]   chars                            An instance of Tizen::Base::WcharBuffer to encode
 163          * @param[in]   flush                            Set to @c true to allow this instance to flush its state at the end of the conversion, @n
 164          *                                                               else @c false
 165          * @exception   E_SUCCESS                The method is successful.
 166          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 167          * @exception   E_INVALID_ARG            Either of the following conditions has occurred:
 168          *                                                              - A specified input parameter is invalid.
 169          *                                                              - The specified @c chars is empty.
 170          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 171          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 172          * @see         Utf8Decoder::GetCharsN()
 173          */
 174         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars, bool flush = false) const;
 175
 176         /**
 177          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range.
 178          *
 179          * @since                       2.0
 180          *
 181          * @return                                               A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 182          *                                               else @c null if an exception occurs @n
 183          *                                                               The buffer limit is the position of the last encoded byte and the starting position is zero.
 184          * @param[in]   chars                    An instance of Tizen::Base::WcharBuffer 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[in]   flush                    Set to @c true to allow this instance to flush its state at the end of the conversion, @n
 188          *                                                       else @c false
 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 chars is empty.
 194          * @exception   E_OUT_OF_RANGE           Either of the following conditions has occurred:
 195          *                                                              - A specified input parameter 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 chars.
 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 chars.
 200          * @exception   E_INVALID_ENCODING_RANGE  The specified string contains code points that are outside the bounds of the character encoding scheme.
 201          * @remarks
 202          *                      - The specific error code can be accessed using the GetLastResult() method.
 203          *                      - The pointer to the Tizen::Base::ByteBuffer instance is not terminated by a @c null character.
 204          * @see         Utf8Decoder::GetCharsN()
 205          */
 206         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
 207                 bool flush = false) const;
 208
 209 private:
 210         /**
 211          * The implementation of this copy constructor is intentionally blank and declared as private to
 212          * prohibit copying of objects.
 213          */
 214         Utf8Encoder(const Utf8Encoder& utf8Encoder);
 215
 216         /**
 217          * The implementation of this copy assignment operator is intentionally blank and declared as private
 218          * to prohibit copying of objects.
 219          */
 220         Utf8Encoder& operator =(const Utf8Encoder& utf8Encoder);
 221
 222         friend class _Utf8EncoderImpl;
 223         class _Utf8EncoderImpl* __pUtf8EncoderImpl;
 224 };
 225
 226 } } // Tizen::Text
 227 #endif //_FTEXT_UTF8_ENCODER_H_