2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FTextUtf8Decoder.h
19 * @brief This is the header file for the %Utf8Decoder class.
21 * This header file contains the declarations of the %Utf8Decoder class.
24 #ifndef _FTEXT_UTF8_DECODER_H_
25 #define _FTEXT_UTF8_DECODER_H_
27 #include <FTextDecoder.h>
30 namespace Tizen { namespace Text
34 * @brief This class is an implementation of the UTF-8 decoder.
38 * @final This class is not intended for extension.
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.
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>.
47 * The following example demonstrates how to use the %Utf8Decoder class.
53 * using namespace Tizen::Base;
54 * using namespace Tizen::Text;
57 * MyClass::Utf8DecoderSample(void)
61 * // Fills a ByteBuffer with long strings to decode it into the unicode strings
62 * ByteBuffer* pBB = PrepareUtf8DecoderSample();
64 * int byteBufSize = pBB->GetCapacity();
67 * utf8De.GetCharCount(*pBB, 0, byteBufSize, charCount);
69 * WcharBuffer deChars;
70 * deChars.Construct(charCount + 1); // for L'\0'
73 * int byteCount = 100;
75 * while (byteIndex < byteBufSize)
77 * WcharBuffer* pMB = null;
79 * if (byteBufSize - byteIndex < byteCount)
81 * byteCount = byteBufSize - byteIndex;
84 * // Converts Utf8 to Unicode using Utf8Decoder
85 * pMB = utf8De.GetCharsN(*pBB, byteIndex, byteCount);
87 * deChars.CopyFrom(*pMB);
88 * byteIndex += byteCount;
102 class _OSP_EXPORT_ Utf8Decoder
107 * This is the default constructor for this class.
113 * This is the destructor for this class. @n
114 * This destructor overrides Tizen::Text::Decoder::~Decoder().
118 virtual ~Utf8Decoder(void);
121 * Gets the total number of characters that are generated by decoding an instance of Tizen::Base::ByteBuffer.
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
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.
144 virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, int& charCount, bool flush = false) const;
147 * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
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
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.
165 virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes, bool flush = false) const;
168 * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range.
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
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.
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.
196 virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
197 bool flush = false) const;
201 * The implementation of this copy constructor is intentionally blank and declared as private to
202 * prohibit copying of objects.
204 Utf8Decoder(const Utf8Decoder& utf8Decoder);
207 * The implementation of this copy assignment operator is intentionally blank and declared as private
208 * to prohibit copying of objects.
210 Utf8Decoder& operator =(const Utf8Decoder& utf8Decoder);
212 friend class _Utf8DecoderImpl;
213 class _Utf8DecoderImpl* __pUtf8DecoderImpl;
218 #endif //_FTEXT_UTF8_DECODER_H_