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