2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @file FTextUcs2Encoding.h
20 * @brief This is the header file for the %Ucs2Encoding class.
22 * This header file contains the declarations of the %Ucs2Encoding class.
23 * This class is derived from the Encoding class.
25 #ifndef _FTEXT_UCS2_ENCODING_H_
26 #define _FTEXT_UCS2_ENCODING_H_
28 #include <FTextEncoding.h>
31 namespace Tizen { namespace Text
35 * @brief This class is an implementation of the UCS-2 encoding.
39 * @final This class is not intended for extension.
41 * The %Ucs2Encoding class is an implementation of the UCS-2 encoding.
42 * Universal Character Set (UCS2) is a two-octet per character encoding type with a fixed width.
43 * UCS2 prepares several characters in advance to output the needed information fast.
44 * When printing out characters, users can avail different types of character sets.
46 * 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>.
48 * The following example demonstrates how to use the %Ucs2Encoding class.
54 * using namespace Tizen::Base;
55 * using namespace Tizen::Text;
58 * MyClass::Ucs2EncodingSample(void)
62 * String str(L"(\u03a0) and (\u03a3)"); // sigma and pi
65 * ucs2.GetByteCount(str, byteCount);
68 * ByteBuffer* pBuffer = ucs2.GetBytesN(str);
71 * ucs2.GetCharCount(*pBuffer, charCount);
75 * ucs2.GetString(*pBuffer, decodedStr);
77 * if (str.Equals(decodedStr))
89 class _OSP_EXPORT_ Ucs2Encoding
94 * This is the default constructor for this class.
101 * This is the destructor for this class. @n
102 * This destructor overrides Tizen::Text::Encoding::~Encoding().
106 virtual ~Ucs2Encoding(void);
109 * Gets the total number of bytes that are generated by encoding an instance of Tizen::Base::String.
113 * @return An error code
114 * @param[in] str A string to encode
115 * @param[out] byteCount The total number of bytes required to encode the string
116 * @exception E_SUCCESS The method is successful.
117 * @exception E_INVALID_ARG A specified input parameter is invalid, or
118 * the specified @c str is an empty string.
119 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
120 * @remarks This method determines the exact number of bytes
121 * that are produced if the given string is encoded.
122 * @see GetMaxByteCount()
124 virtual result GetByteCount(const Tizen::Base::String& str, int& byteCount) const;
127 * Gets the total number of bytes that are generated by encoding an instance of Tizen::Base::WcharBuffer.
131 * @return An error code
132 * @param[in] chars An instance of Tizen::Base::WcharBuffer to encode
133 * @param[out] byteCount The total number of bytes required to encode the specified range of characters
134 * @exception E_SUCCESS The method is successful.
135 * @exception E_INVALID_ARG A specified input parameter is invalid, or
136 * the specified @c chars is empty.
137 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
138 * @remarks This method determines the exact number of bytes
139 * that are produced if the given array of characters is encoded.
140 * @see GetMaxByteCount()
142 virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int& byteCount) const;
145 * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance.
149 * @return An error code
150 * @param[in] chars An instance of Tizen::Base::WcharBuffer to encode
151 * @param[in] charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
152 * @param[in] charCount The total number of characters to encode
153 * @param[out] byteCount The total number of bytes required to encode the specified range of characters
154 * @exception E_SUCCESS The method is successful.
155 * @exception E_INVALID_ARG A specified input parameter is invalid, or
156 * the specified @c chars is empty.
157 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
158 * the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
159 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
160 * the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
161 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
162 * @remarks This method determines the exact number of bytes
163 * that are produced if the given array of characters is encoded.
164 * @see GetMaxByteCount()
166 virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount, int& byteCount) const;
170 * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
174 * @return A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
175 * else @c null if an exception occurs @n
176 * The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
177 * @param[in] chars An instance of Tizen::Base::WcharBuffer to encode
178 * @exception E_SUCCESS The method is successful.
179 * @exception E_OUT_OF_MEMORY The memory is insufficient.
180 * @exception E_INVALID_ARG The specified @c chars is empty or invalid.
181 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
182 * @remarks The specific error code can be accessed using the GetLastResult() method.
185 virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars) const;
188 * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer.
192 * @return A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
193 * else @c null if an exception occurs @n
194 * The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
195 * @param[in] str A string to encode
196 * @exception E_SUCCESS The method is successful.
197 * @exception E_OUT_OF_MEMORY The memory is insufficient.
198 * @exception E_INVALID_ARG The specified @c str is empty or invalid.
199 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
200 * @remarks The specific error code can be accessed using the GetLastResult() method.
203 virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::String& str) const;
206 * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
207 * The position and limit of the pointer to the %Tizen::Base::ByteBuffer instance is not changed.
211 * @return An error code
212 * @param[in] chars An instance of Tizen::Base::WcharBuffer to encode
213 * @param[in] charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
214 * @param[in] charCount The total number of characters to encode
215 * @param[out] bytes The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
216 * @param[in] byteIndex The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
217 * @exception E_SUCCESS The method is successful.
218 * @exception E_OUT_OF_MEMORY The memory is insufficient.
219 * @exception E_INVALID_ARG A specified input parameter is invalid, or
220 * the specified @c chars or @c bytes is empty.
221 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
222 * the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
223 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
224 * the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
225 * @exception E_OVERFLOW This operation has caused the memory to overflow, or
226 * the specified @c bytes does not contain sufficient space to store the encoded characters.
227 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
228 * @remarks This method encodes a range of characters in a Tizen::Base::WcharBuffer into a range of bytes in a Tizen::Base::ByteBuffer.
231 virtual result GetBytes(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
232 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
235 * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
236 * The position and limit of the pointer to the %Tizen::Base::ByteBuffer instance is not changed.
240 * @return An error code
241 * @param[in] str A string to encode
242 * @param[in] charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
243 * @param[in] charCount The total number of characters to encode
244 * @param[out] bytes The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
245 * @param[in] byteIndex The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
246 * @exception E_SUCCESS The method is successful.
247 * @exception E_OUT_OF_MEMORY The memory is insufficient.
248 * @exception E_INVALID_ARG A specified input parameter is invalid, or
249 * the specified @c str or @c bytes is empty.
250 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
251 * the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c str.
252 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
253 * the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c str.
254 * @exception E_OVERFLOW This operation has caused the memory to overflow, or
255 * the specified @c bytes does not contain sufficient space to store the encoded characters.
256 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
259 virtual result GetBytes(const Tizen::Base::String& str, int charIndex, int charCount,
260 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
263 * Gets the total number of characters that are generated by decoding an instance of Tizen::Base::ByteBuffer.
267 * @return An error code
268 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
269 * @param[out] charCount The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
270 * @exception E_SUCCESS The method is successful.
271 * @exception E_INVALID_ARG A specified input parameter is invalid, or
272 * the specified @c bytes is empty.
273 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
274 * @remarks This method determines the exact number of characters
275 * that are produced if the given range of bytes is converted.
276 * @see GetMaxCharCount()
278 virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int& charCount) const;
281 * Gets the total number of characters that are generated by decoding a range of elements specified in the Tizen::Base::ByteBuffer instance.
285 * @return An error code
286 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
287 * @param[in] byteIndex The index from where decoding begins
288 * @param[in] byteCount The total number of bytes to decode
289 * @param[out] charCount The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
290 * @exception E_SUCCESS The method is successful.
291 * @exception E_INVALID_ARG A specified input parameter is invalid, or
292 * the specified @c bytes is empty.
293 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
294 * the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
295 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
296 * the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
297 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
298 * @remarks This method determines the exact number of characters
299 * that are produced if the given range of bytes is converted.
300 * @see GetMaxCharCount()
302 virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, int& charCount) const;
305 *Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
309 * @return A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
310 * else @c null if an exception occurs @n
311 * The buffer limit is the position of the last decoded byte plus one and the starting position is zero.
312 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
313 * @exception E_SUCCESS The method is successful.
314 * @exception E_OUT_OF_MEMORY The memory is insufficient.
315 * @exception E_INVALID_ARG The specified @c bytes is empty or invalid.
316 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
317 * @remarks The specific error code can be accessed using the GetLastResult() method.
320 virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const;
323 * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range. @n
324 * The position and limit of the pointer to the %Tizen::Base::WcharBuffer instance is not changed.
328 * @return An error code
329 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
330 * @param[in] byteIndex The index from where decoding begins
331 * @param[in] byteCount The total number of bytes to decode
332 * @param[out] chars The Tizen::Base::WcharBuffer instance where the resultant decoded data is stored
333 * @param[in] charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
334 * @exception E_SUCCESS The method is successful.
335 * @exception E_OUT_OF_MEMORY The memory is insufficient.
336 * @exception E_INVALID_ARG A specified input parameter is invalid, or
337 * the specified @c bytes or @ chars is empty.
338 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
339 * the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
340 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
341 * the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
342 * @exception E_OVERFLOW This operation has caused the memory to overflow, or
343 * the specified @c chars does not contain sufficient space to store the decoded bytes.
344 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
347 virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
348 Tizen::Base::WcharBuffer& chars, int charIndex = 0) const;
351 * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
355 * @return An error code
356 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
357 * @param[out] str A Tizen::Base::String instance @n
358 * It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
359 * @exception E_SUCCESS The method is successful.
360 * @exception E_OUT_OF_MEMORY The memory is insufficient.
361 * @exception E_INVALID_ARG A specified input parameter is invalid, or
362 * the specified @c bytes is empty.
363 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
366 virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const;
369 * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
373 * @return An error code
374 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
375 * @param[in] index The index from where decoding begins
376 * @param[in] count The total number of bytes to decode
377 * @param[out] str A Tizen::Base::String instance @n
378 * It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
379 * @exception E_SUCCESS The method is successful.
380 * @exception E_OUT_OF_MEMORY The memory is insufficient.
381 * @exception E_INVALID_ARG A specified input parameter is invalid, or
382 * the specified @c bytes is empty.
383 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
384 * the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
385 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
386 * the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
387 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
390 virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const;
394 * Gets the maximum number of bytes required for encoding a given number of characters.
398 * @return The maximum number of bytes required for encoding the given number of characters
399 * @param[in] charCount The total number of characters to encode
400 * @remarks This method determines an appropriate buffer size for the byte arrays passed to GetBytes() for encoding.
401 * @see GetByteCount()
404 virtual int GetMaxByteCount(int charCount) const;
408 * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
412 * @return The maximum number of characters generated by decoding the specified number of bytes
413 * @param[in] byteCount The total number of bytes to encode
414 * @remarks This method determines an appropriate buffer size for the character arrays passed to
415 * GetChars() or a decoder for encoding.
416 * @see GetByteCount()
419 virtual int GetMaxCharCount(int byteCount) const;
423 * Gets the encoder for the current encoding.
427 * @return A pointer to the Encoder instance for the current encoding
428 * @remarks Contrary to GetBytes(), an encoder can convert partial sequences of characters into
429 * partial sequences of bytes by maintaining the appropriate state between the conversions.
430 * Currently only Utf8Encoding supports this method. Other classes return @c null.
433 virtual Encoder* GetEncoderN(void) const;
437 * Gets the decoder for the current encoding.
441 * @return A pointer to the Decoder instance for the current encoding
442 * @remarks Contrary to GetChars(), a decoder can convert partial sequences of bytes
443 * into partial sequences of characters by maintaining the appropriate state between the conversions.
444 * Currently only Utf8Encoding supports this method. Other classes return @c null.
448 virtual Decoder* GetDecoderN(void) const;
451 * Gets the encoding type of the current instance.
455 * @return An encoding type
457 virtual Tizen::Base::String GetEncodingType(void) const;
461 * The implementation of this copy constructor is intentionally blank and declared as private to
462 * prohibit copying of objects.
464 Ucs2Encoding(const Ucs2Encoding& ucs2Encoding);
467 * The implementation of this copy assignment operator is intentionally blank and declared as private
468 * to prohibit copying of objects.
470 Ucs2Encoding& operator =(const Ucs2Encoding& ucs2Encoding);
472 friend class _Ucs2EncodingImpl;
473 class _Ucs2EncodingImpl* __pUcs2EncodingImpl;
477 #endif //_FTEXT_UCS2_ENCODING_H_