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 FTextUcs2Encoding.h
19 * @brief This is the header file for the %Ucs2Encoding class.
21 * This header file contains the declarations of the %Ucs2Encoding class.
22 * This class is derived from the Encoding class.
24 #ifndef _FTEXT_UCS2_ENCODING_H_
25 #define _FTEXT_UCS2_ENCODING_H_
27 #include <FTextEncoding.h>
30 namespace Tizen { namespace Text
34 * @brief This class is an implementation of the UCS-2 encoding.
38 * @final This class is not intended for extension.
40 * The %Ucs2Encoding class is an implementation of the UCS-2 encoding.
41 * Universal Character Set (UCS2) is a two-octet per character encoding type with a fixed width.
42 * UCS2 prepares several characters in advance to output the needed information fast.
43 * When printing out characters, users can avail different types of character sets.
45 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/text/converting_all_text_data.htm">Converting All Text Data at Once</a>.
47 * The following example demonstrates how to use the %Ucs2Encoding class.
53 * using namespace Tizen::Base;
54 * using namespace Tizen::Text;
57 * MyClass::Ucs2EncodingSample(void)
61 * String str(L"(\u03a0) and (\u03a3)"); // sigma and pi
64 * ucs2.GetByteCount(str, byteCount);
67 * ByteBuffer* pBuffer = ucs2.GetBytesN(str);
70 * ucs2.GetCharCount(*pBuffer, charCount);
74 * ucs2.GetString(*pBuffer, decodedStr);
76 * if (str.Equals(decodedStr))
88 class _OSP_EXPORT_ Ucs2Encoding
93 * This is the default constructor for this class.
100 * This is the destructor for this class. @n
101 * This destructor overrides Tizen::Text::Encoding::~Encoding().
105 virtual ~Ucs2Encoding(void);
108 * Gets the total number of bytes that are generated by encoding an instance of Tizen::Base::String.
112 * @return An error code
113 * @param[in] str A string to encode
114 * @param[out] byteCount The total number of bytes required to encode the string
115 * @exception E_SUCCESS The method is successful.
116 * @exception E_INVALID_ARG A specified input parameter is invalid, or
117 * the specified @c str is an empty string.
118 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
119 * @remarks This method determines the exact number of bytes
120 * that are produced if the given string is encoded.
121 * @see GetMaxByteCount()
123 virtual result GetByteCount(const Tizen::Base::String& str, int& byteCount) const;
126 * Gets the total number of bytes that are generated by encoding an instance of Tizen::Base::WcharBuffer.
130 * @return An error code
131 * @param[in] chars An instance of Tizen::Base::WcharBuffer to encode
132 * @param[out] byteCount The total number of bytes required to encode the specified range of characters
133 * @exception E_SUCCESS The method is successful.
134 * @exception E_INVALID_ARG A specified input parameter is invalid, or
135 * the specified @c chars is empty.
136 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
137 * @remarks This method determines the exact number of bytes
138 * that are produced if the given array of characters is encoded.
139 * @see GetMaxByteCount()
141 virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int& byteCount) const;
144 * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance.
148 * @return An error code
149 * @param[in] chars An instance of Tizen::Base::WcharBuffer to encode
150 * @param[in] charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
151 * @param[in] charCount The total number of characters to encode
152 * @param[out] byteCount The total number of bytes required to encode the specified range of characters
153 * @exception E_SUCCESS The method is successful.
154 * @exception E_INVALID_ARG A specified input parameter is invalid, or
155 * the specified @c chars is empty.
156 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
157 * the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
158 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
159 * the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
160 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
161 * @remarks This method determines the exact number of bytes
162 * that are produced if the given array of characters is encoded.
163 * @see GetMaxByteCount()
165 virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount, int& byteCount) const;
169 * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
173 * @return A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
174 * else @c null if an exception occurs @n
175 * The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
176 * @param[in] chars An instance of Tizen::Base::WcharBuffer to encode
177 * @exception E_SUCCESS The method is successful.
178 * @exception E_OUT_OF_MEMORY The memory is insufficient.
179 * @exception E_INVALID_ARG The specified @c chars is empty or invalid.
180 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
181 * @remarks The specific error code can be accessed using the GetLastResult() method.
184 virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars) const;
187 * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer.
191 * @return A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
192 * else @c null if an exception occurs @n
193 * The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
194 * @param[in] str A string to encode
195 * @exception E_SUCCESS The method is successful.
196 * @exception E_OUT_OF_MEMORY The memory is insufficient.
197 * @exception E_INVALID_ARG The specified @c str is empty or invalid.
198 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
199 * @remarks The specific error code can be accessed using the GetLastResult() method.
202 virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::String& str) const;
205 * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
206 * The position and limit of the pointer to the %Tizen::Base::ByteBuffer instance is not changed.
210 * @return An error code
211 * @param[in] chars An instance of Tizen::Base::WcharBuffer to encode
212 * @param[in] charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
213 * @param[in] charCount The total number of characters to encode
214 * @param[out] bytes The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
215 * @param[in] byteIndex The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
216 * @exception E_SUCCESS The method is successful.
217 * @exception E_OUT_OF_MEMORY The memory is insufficient.
218 * @exception E_INVALID_ARG A specified input parameter is invalid, or
219 * the specified @c chars or @c bytes is empty.
220 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
221 * the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
222 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
223 * the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
224 * @exception E_OVERFLOW This operation has caused the memory to overflow, or
225 * the specified @c bytes does not contain sufficient space to store the encoded characters.
226 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
227 * @remarks This method encodes a range of characters in a Tizen::Base::WcharBuffer into a range of bytes in a Tizen::Base::ByteBuffer.
230 virtual result GetBytes(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
231 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
234 * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
235 * The position and limit of the pointer to the %Tizen::Base::ByteBuffer instance is not changed.
239 * @return An error code
240 * @param[in] str A string to encode
241 * @param[in] charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
242 * @param[in] charCount The total number of characters to encode
243 * @param[out] bytes The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
244 * @param[in] byteIndex The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
245 * @exception E_SUCCESS The method is successful.
246 * @exception E_OUT_OF_MEMORY The memory is insufficient.
247 * @exception E_INVALID_ARG A specified input parameter is invalid, or
248 * the specified @c str or @c bytes is empty.
249 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
250 * the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c str.
251 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
252 * the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c str.
253 * @exception E_OVERFLOW This operation has caused the memory to overflow, or
254 * the specified @c bytes does not contain sufficient space to store the encoded characters.
255 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
258 virtual result GetBytes(const Tizen::Base::String& str, int charIndex, int charCount,
259 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
262 * Gets the total number of characters that are generated by decoding an instance of Tizen::Base::ByteBuffer.
266 * @return An error code
267 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
268 * @param[out] charCount The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
269 * @exception E_SUCCESS The method is successful.
270 * @exception E_INVALID_ARG A specified input parameter is invalid, or
271 * the specified @c bytes is empty.
272 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
273 * @remarks This method determines the exact number of characters
274 * that are produced if the given range of bytes is converted.
275 * @see GetMaxCharCount()
277 virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int& charCount) const;
280 * Gets the total number of characters that are generated by decoding a range of elements specified in the Tizen::Base::ByteBuffer instance.
284 * @return An error code
285 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
286 * @param[in] byteIndex The index from where decoding begins
287 * @param[in] byteCount The total number of bytes to decode
288 * @param[out] charCount The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
289 * @exception E_SUCCESS The method is successful.
290 * @exception E_INVALID_ARG A specified input parameter is invalid, or
291 * the specified @c bytes is empty.
292 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
293 * the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
294 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
295 * the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
296 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
297 * @remarks This method determines the exact number of characters
298 * that are produced if the given range of bytes is converted.
299 * @see GetMaxCharCount()
301 virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, int& charCount) const;
304 *Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
308 * @return A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
309 * else @c null if an exception occurs @n
310 * The buffer limit is the position of the last decoded byte plus one and the starting position is zero.
311 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
312 * @exception E_SUCCESS The method is successful.
313 * @exception E_OUT_OF_MEMORY The memory is insufficient.
314 * @exception E_INVALID_ARG The specified @c bytes is empty or invalid.
315 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
316 * @remarks The specific error code can be accessed using the GetLastResult() method.
319 virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const;
322 * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range. @n
323 * The position and limit of the pointer to the %Tizen::Base::WcharBuffer instance is not changed.
327 * @return An error code
328 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
329 * @param[in] byteIndex The index from where decoding begins
330 * @param[in] byteCount The total number of bytes to decode
331 * @param[out] chars The Tizen::Base::WcharBuffer instance where the resultant decoded data is stored
332 * @param[in] charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
333 * @exception E_SUCCESS The method is successful.
334 * @exception E_OUT_OF_MEMORY The memory is insufficient.
335 * @exception E_INVALID_ARG A specified input parameter is invalid, or
336 * the specified @c bytes or @ chars is empty.
337 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
338 * the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
339 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
340 * the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
341 * @exception E_OVERFLOW This operation has caused the memory to overflow, or
342 * the specified @c chars does not contain sufficient space to store the decoded bytes.
343 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
346 virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
347 Tizen::Base::WcharBuffer& chars, int charIndex = 0) const;
350 * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
354 * @return An error code
355 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
356 * @param[out] str A Tizen::Base::String instance @n
357 * It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
358 * @exception E_SUCCESS The method is successful.
359 * @exception E_OUT_OF_MEMORY The memory is insufficient.
360 * @exception E_INVALID_ARG A specified input parameter is invalid, or
361 * the specified @c bytes is empty.
362 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
365 virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const;
368 * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
372 * @return An error code
373 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
374 * @param[in] index The index from where decoding begins
375 * @param[in] count The total number of bytes to decode
376 * @param[out] str A Tizen::Base::String instance @n
377 * It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
378 * @exception E_SUCCESS The method is successful.
379 * @exception E_OUT_OF_MEMORY The memory is insufficient.
380 * @exception E_INVALID_ARG A specified input parameter is invalid, or
381 * the specified @c bytes is empty.
382 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
383 * the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
384 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
385 * the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
386 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
389 virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const;
393 * Gets the maximum number of bytes required for encoding a given number of characters.
397 * @return The maximum number of bytes required for encoding the given number of characters
398 * @param[in] charCount The total number of characters to encode
399 * @remarks This method determines an appropriate buffer size for the byte arrays passed to GetBytes() for encoding.
400 * @see GetByteCount()
403 virtual int GetMaxByteCount(int charCount) const;
407 * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
411 * @return The maximum number of characters generated by decoding the specified number of bytes
412 * @param[in] byteCount The total number of bytes to encode
413 * @remarks This method determines an appropriate buffer size for the character arrays passed to
414 * GetChars() or a decoder for encoding.
415 * @see GetByteCount()
418 virtual int GetMaxCharCount(int byteCount) const;
422 * Gets the encoder for the current encoding.
426 * @return A pointer to the Encoder instance for the current encoding
427 * @remarks Contrary to GetBytes(), an encoder can convert partial sequences of characters into
428 * partial sequences of bytes by maintaining the appropriate state between the conversions.
429 * Currently only Utf8Encoding supports this method. Other classes return @c null.
432 virtual Encoder* GetEncoderN(void) const;
436 * Gets the decoder for the current encoding.
440 * @return A pointer to the Decoder instance for the current encoding
441 * @remarks Contrary to GetChars(), a decoder can convert partial sequences of bytes
442 * into partial sequences of characters by maintaining the appropriate state between the conversions.
443 * Currently only Utf8Encoding supports this method. Other classes return @c null.
447 virtual Decoder* GetDecoderN(void) const;
450 * Gets the encoding type of the current instance.
454 * @return An encoding type
456 virtual Tizen::Base::String GetEncodingType(void) const;
460 * The implementation of this copy constructor is intentionally blank and declared as private to
461 * prohibit copying of objects.
463 Ucs2Encoding(const Ucs2Encoding& ucs2Encoding);
466 * The implementation of this copy assignment operator is intentionally blank and declared as private
467 * to prohibit copying of objects.
469 Ucs2Encoding& operator =(const Ucs2Encoding& ucs2Encoding);
471 friend class _Ucs2EncodingImpl;
472 class _Ucs2EncodingImpl* __pUcs2EncodingImpl;
476 #endif //_FTEXT_UCS2_ENCODING_H_