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 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            A specified input parameter is invalid, or
 140          *                                        the specified @c chars is empty.
 141          * @exception   E_OUT_OF_RANGE                   The value of an argument is outside the valid range defined by the method, or
 142          *                                                                               the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 143          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or
 144          *                                                                               the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 145          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 146          * @see                 Utf8Decoder::GetCharCount()
 147          */
 148         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars,
 149                 int charIndex, int charCount, int& byteCount, bool flush = false) const;
 150
 151         /**
 152          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
 153          *
 154          * @since                       2.0
 155          *
 156          * @return                                 A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 157          *                                 else @c null if an exception occurs @n
 158          *                                                         The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
 159          * @param[in]   chars              An instance of Tizen::Base::WcharBuffer to encode
 160          * @param[in]   flush              Set to @c true to allow this instance to flush its state at the end of the conversion, @n
 161          *                                                 else @c false
 162          * @exception   E_SUCCESS                The method is successful.
 163          * @exception   E_OUT_OF_MEMORY      The memory is insufficient.
 164          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 165          *                                       the specified @c chars is empty.
 166          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 167          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 168          * @see         Utf8Decoder::GetCharsN()
 169          */
 170         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars, bool flush = false) const;
 171
 172         /**
 173          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range.
 174          *
 175          * @since                       2.0
 176          *
 177          * @return                                 A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 178          *                                 else @c null if an exception occurs @n
 179          *                                                          The buffer limit is the position of the last encoded byte and the starting position is zero.
 180          * @param[in]   chars               An instance of Tizen::Base::WcharBuffer to encode
 181          * @param[in]   charIndex               The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 182          * @param[in]   charCount The total number of characters to encode
 183          * @param[in]   flush                    Set to @c true to allow this instance to flush its state at the end of the conversion, @n
 184          *                                                       else @c false
 185          * @exception   E_SUCCESS                The method is successful.
 186          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 187          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 188          *                                       the specified @c chars is empty.
 189          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method, or
 190          *                                       the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 191          * @exception   E_UNDERFLOW                  This operation has caused the memory to underflow, or
 192          *                                        the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 193          * @exception   E_INVALID_ENCODING_RANGE  The specified string contains code points that are outside the bounds of the character encoding scheme.
 194          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 195          * @remarks             The pointer to the Tizen::Base::ByteBuffer instance is not terminated by a @c null character.
 196          * @see         Utf8Decoder::GetCharsN()
 197          */
 198         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
 199                 bool flush = false) const;
 200
 201 private:
 202         /**
 203          * The implementation of this copy constructor is intentionally blank and declared as private to
 204          * prohibit copying of objects.
 205          */
 206         Utf8Encoder(const Utf8Encoder& utf8Encoder);
 207
 208         /**
 209          * The implementation of this copy assignment operator is intentionally blank and declared as private
 210          * to prohibit copying of objects.
 211          */
 212         Utf8Encoder& operator =(const Utf8Encoder& utf8Encoder);
 213
 214         friend class _Utf8EncoderImpl;
 215         class _Utf8EncoderImpl* __pUtf8EncoderImpl;
 216 };
 217
 218 } } // Tizen::Text
 219 #endif //_FTEXT_UTF8_ENCODER_H_