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