535e13164c867147af66b1f958667f3d3db64f47
[platform/framework/native/appfw.git] / inc / FTextUcs2Encoding.h
1 //
2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 //
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
8 //
9 //     http://www.apache.org/licenses/LICENSE-2.0
10 //
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.
16 //
17
18 /**
19  * @file                FTextUcs2Encoding.h
20  * @brief               This is the header file for the %Ucs2Encoding class.
21  *
22  * This header file contains the declarations of the %Ucs2Encoding class.
23  * This class is derived from the Encoding class.
24  */
25 #ifndef _FTEXT_UCS2_ENCODING_H_
26 #define _FTEXT_UCS2_ENCODING_H_
27
28 #include <FTextEncoding.h>
29
30
31 namespace Tizen { namespace Text
32 {
33 /**
34  * @class       Ucs2Encoding
35  * @brief       This class is an implementation of the UCS-2 encoding.
36  *
37  * @since       2.0
38  *
39  * @final       This class is not intended for extension.
40  *
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.
45  *
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>.
47  *
48  * The following example demonstrates how to use the %Ucs2Encoding class.
49  *
50  *  @code
51  *      #include <FBase.h>
52  *      #include <FText.h>
53  *
54  *      using namespace Tizen::Base;
55  *      using namespace Tizen::Text;
56  *
57  *      void
58  *      MyClass::Ucs2EncodingSample(void)
59  *      {
60  *              Ucs2Encoding ucs2;
61  *
62  *              String str(L"(\u03a0) and (\u03a3)"); // sigma and pi
63  *
64  *              int byteCount;
65  *              ucs2.GetByteCount(str, byteCount);
66  *
67  *              // Encodes
68  *              ByteBuffer* pBuffer = ucs2.GetBytesN(str);
69  *
70  *              int charCount;
71  *              ucs2.GetCharCount(*pBuffer, charCount);
72  *
73  *              // Decodes
74  *              String decodedStr;
75  *              ucs2.GetString(*pBuffer, decodedStr);
76  *
77  *              if (str.Equals(decodedStr))
78  *              {
79  *                      //....
80  *              }
81  *
82  *              delete pBuffer;
83  *      }
84  *
85  * @endcode
86  *
87  */
88
89 class _OSP_EXPORT_ Ucs2Encoding
90         : public Encoding
91 {
92 public:
93         /**
94          * This is the default constructor for this class.
95          *
96          * @since       2.0
97          */
98         Ucs2Encoding(void);
99
100         /**
101          * This is the destructor for this class. @n
102          * This destructor overrides Tizen::Text::Encoding::~Encoding().
103          *
104          * @since       2.0
105          */
106         virtual ~Ucs2Encoding(void);
107
108         /**
109          * Gets the total number of bytes that are generated by encoding an instance of Tizen::Base::String.
110          *
111          * @since                               2.0
112          *
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()
123          */
124         virtual result GetByteCount(const Tizen::Base::String& str, int& byteCount) const;
125
126         /**
127          * Gets the total number of bytes that are generated by encoding an instance of Tizen::Base::WcharBuffer.
128          *
129          * @since                               2.0
130          *
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()
141          */
142         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int& byteCount) const;
143
144         /**
145          * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance.
146          *
147          * @since                               2.0
148          *
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()
165          */
166         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount, int& byteCount) const;
167
168
169         /**
170          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
171          *
172          * @since                       2.0
173          *
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.
183          * @see                         GetCharsN()
184          */
185         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars) const;
186
187         /**
188          * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer.
189          *
190          * @since                       2.0
191          *
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.
201          * @see                         GetString()
202          */
203         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::String& str) const;
204
205         /**
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.
208          *
209          * @since                       2.0
210          *
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.
229          * @see                         GetChars()
230          */
231         virtual result GetBytes(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
232                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
233
234         /**
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.
237          *
238          * @since                       2.0
239          *
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.
257          * @see                         GetString()
258          */
259         virtual result GetBytes(const Tizen::Base::String& str, int charIndex, int charCount,
260                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
261
262         /**
263          * Gets the total number of characters that are generated by decoding an instance of Tizen::Base::ByteBuffer.
264          *
265          * @since                       2.0
266          *
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()
277          */
278         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int& charCount) const;
279
280         /**
281          * Gets the total number of characters that are generated by decoding a range of elements specified in the Tizen::Base::ByteBuffer instance.
282          *
283          * @since                       2.0
284          *
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()
301          */
302         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, int& charCount) const;
303
304         /**
305          *Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
306          *
307          * @since                       2.0
308          *
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.
318          * @see                         GetBytesN()
319          */
320         virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const;
321
322         /**
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.
325          *
326          * @since                       2.0
327          *
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.
345          * @see                         GetBytes()
346          */
347         virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
348                 Tizen::Base::WcharBuffer& chars, int charIndex = 0) const;
349
350         /**
351          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
352          *
353          * @since                       2.0
354          *
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.
364          * @see                         GetBytesN()
365          */
366         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const;
367
368         /**
369          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
370          *
371          * @since                       2.0
372          *
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.
388          * @see                         GetBytesN()
389          */
390         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const;
391
392
393         /**
394         * Gets the maximum number of bytes required for encoding a given number of characters.
395         *
396         * @since                        2.0
397         *
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()
402         * @see                          GetBytes()
403         */
404         virtual int GetMaxByteCount(int charCount) const;
405
406
407         /**
408         * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
409         *
410         * @since                                2.0
411         *
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()
417         * @see                                  GetChars()
418         */
419         virtual int GetMaxCharCount(int byteCount) const;
420
421
422         /**
423          * Gets the encoder for the current encoding.
424          *
425          * @since                               2.0
426          *
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.
431          * @see                                 GetBytes()
432          */
433         virtual Encoder* GetEncoderN(void) const;
434
435
436         /**
437          * Gets the decoder for the current encoding.
438          *
439          * @since                               2.0
440          *
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.
445          *
446          * @see                                 GetChars()
447          */
448         virtual Decoder* GetDecoderN(void) const;
449
450         /**
451         * Gets the encoding type of the current instance.
452         *
453         * @since                        2.0
454         *
455         * @return               An encoding type
456         */
457         virtual Tizen::Base::String GetEncodingType(void) const;
458
459 private:
460         /**
461          * The implementation of this copy constructor is intentionally blank and declared as private to
462          * prohibit copying of objects.
463          */
464         Ucs2Encoding(const Ucs2Encoding& ucs2Encoding);
465
466         /**
467          * The implementation of this copy assignment operator is intentionally blank and declared as private
468          * to prohibit copying of objects.
469          */
470         Ucs2Encoding& operator =(const Ucs2Encoding& ucs2Encoding);
471
472         friend class _Ucs2EncodingImpl;
473         class _Ucs2EncodingImpl* __pUcs2EncodingImpl;
474 };
475
476 } } // Tizen::Text
477 #endif //_FTEXT_UCS2_ENCODING_H_