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